Version 16 (modified by jtv, 14 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 so don't be surprised if some things are still missing.

Finding Everything

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.

Sales Pitch

I hope you will find libpqxx flexible but easy to use. Not everything about it is easy, but at least there is a tendency to stick to the kinds of complexity that you are used to as a C++ programmer. Query results do not have their own "get next row" interfaces and so on; instead, they provide iterator classes that let you treat the result as a standard C++ container, just like the ones defined by the STL. Streams are also supported where it makes sense, and fields can be read into variables using conversion functions that are implemented as templates.

Also, simple libpqxx programs tend to be less complex than equivalent Java code while having more flexibility.

Many similar libraries have preceded libpqxx and perhaps many will follow. Below are some reasons why I believe libpqxx is worth your while.

  1. Language conformance. It tries to make sensible use of modern C++ features such as templates, standard exceptions, and various kinds of iterators to integrate more comfortably with the language. Where possible, libpqxx blends in with the standard library and the STL in particular.
  2. Structure. It also tries to make it easier for you to write robust, correct code that deals elegantly with various kinds of error conditions. This helps the library detect many problems at compile time instead of at runtime, or during a normal test instead of just in rare corner cases.
  3. Power. Built-in features such as automatic connection restoration and transaction management free you from the low-level chores that tend to take up too much time and go wrong just when you need them most.
  4. Flexibility. Despite the above, this is not an application framework. You won't be forced to squeeze your code into a poorly matched, poorly documented event loop. There are no home-grown string or exception classes. The library lives in its own namespace and completely hides all symbols of the underlying C API library, so it's less likely to clash with other libraries.
  5. Generic programming. Object-orientation is a fine thing, but let's not get obsessed. Functions are used where they make more sense than classes. Inheritance is used internally, but you are not expected to derive your own classes from libpqxx classes except in one or two specific and useful design patterns. Even then, your own code will be isolated in a well-understood environment.

If your impression is that libpqxx is nothing special, that everything about it is obvious or unsurprising, then that means it does its job.

More about libpqxx

It's not very recent, but Poul Höcherl has written a nice article on OSDN about libpqxx. Around the same time, Markus Jais published a particularly good German article for Linux Enterprise--but unfortunately it is not available in the online edition. The source code to his examples is available, but note that libpqxx programming has gotten even easier since then!

If you want to see how simple everything was back in the days of the 1.x API, you may also want to look at the attached slides for a presentation I gave at the FOSDEM conference in Brussels, February 2003. These slides are not very verbose, however. I prefer to avoid long texts and endless lists of bullet points in presentations. Bullet points are there only to remind me where I'm going, and to help people in the audience orient themselves if they happen to wake up in the middle of the presentation; there's no point in giving a presentation if the slides spell it all out.

Users' Comments

Here are just some flattering comments from developers using libpqxx:

  • I love the job you've done on libpqxx - the class layouts just make perfect sense to me. I've also learned a lot about writing STL-compatible classes by looking at your code, thanks. -- Murphy Pope
  • I started playing around with the pqxx library last night and I'm quite impressed by how easy it is to perform simple db tasks (The test programs helps a whole lot too). -- Hannes Wagener
  • I must say I'm really impressed with the clean, good-looking code for a simple test program and with the STL container approach.
  • Congrats on your library, it is a pleasure to work with well done, open code.

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.