wiki:WikiStart

Version 21 (modified by jtv, 13 years ago) (diff)

--

libpqxx is the official C++ API for writing client programs that talk to the PostgreSQL database management system. (If that's too verbose, call it by its shorter name, postgres).

This project has only moved here recently, from its old location at http://gborg.postgresql.org/project/libpqxx/ so don't be surprised if some things are still missing.

Finding Everything

If you want to know why this library should interest you, read the SalesPitch.

See UsingThisSite for more details on various ways to access the source code etc., and the development projects overview page for other development projects hosted on this site.

Complete source tarballs are available on the DownloadPage. No binaries are available on this site; if you need one, either find a ready-made libpqxx package for your operating system environment, or build it yourself from the source code.

Documentation can be read online, but is also included in the source tarballs.

The two mailing lists, libpqxx-general and libpqxx-announce, are still on the old site.

Current bug tickets and feature requests are in the bug tracker (see also the View Tickets and New Ticket options; they should be in the top button bar of this page.

For issues not suitable for the mailing list or bug tickets, contact the author at jtv@…

Technical Overview

This library works on top of the C-level API library, libpq. You will need libpq in order to use libpqxx.

The first thing you're likely to notice in programming with libpqxx is that unlike other libraries, it revolves entirely around transactions. Transactions are a central concept in database management systems, but they are widely underappreciated among application developers. Another well-known open source database system, MySQL, never even got around to implementing them at all in their own engine, relying on a third-party replacement engine (now owned by Oracle) to provide this functionality instead. It may sometimes be possible to build limited applications reliably without serious use of transactions, but applications that don't use them are usually written that way because the developers aren't fully aware of the risks they are taking, and any data loss is rare or small enough not to be noticed. That kind of design was not considered acceptable for libpqxx.

With conventional database APIs, you issue commands and queries to a database session or connection, and optionally create the occasional transaction. In libpqxx you start a transaction inside the connection first, do your SQL work using that transaction, then commit it when it's complete. There are several types of transactions with various "quality of service" properties; if you don't really want to use transactions at all, one of the available transaction types is called nontransaction and provides classic, nontransactional behaviour.

Every command or query issues a result object, which is really a smart pointer so it can be copied around without incurring much cost in terms of performance. No need to write special code to check these for success; error conditions are converted to regular C++ exceptions. Result objects can be kept around for as long as they are needed, completely separate from the connections and transactions that originated them.