Version 160 (modified by jtv, 8 years ago) (diff)


C++ connector for PostgreSQL

libpqxx is the official C++ client API for PostgreSQL, the enterprise-strength open-source relational database. (If "PostgreSQL" is too verbose, call it by its shorter name, postgres).

If you are writing software in C++ that needs to access databases managed by postgres—on just about any platform—then libpqxx is the library you use. It is the standard C++ language binding for the postgres RDBMS.

The source code for libpqxx is available under the BSD license, so you're free to download it, pass it on to others, change it, sell it, include it in your own code, and share your changes with anyone you choose. No charge, no catch. In most cases you'll want a pre-built package provided by a package maintainer for your platform, and distributed through your normal package management infrastructure.


2011-11-27: libpqxx 4.0 released

We just released libpqxx 4.0, perfectly on schedule but with a few last-minute fixes — mostly from contributors. Thanks to all who found things that needed fixing, and especially to those who sent in patches or example programs!

The theme for this release is simplicity. No, things didn't become simple overnight. But hopefully we made some steps in the right direction. We've also got some massive compatibility improvements: the Visual C++ build is viable at last. All this comes at the cost of support for postgres 7.x, and a few esoteric APIs.

See NEWS for details; get it from the download page.

2011-11-24: announcing 4.0

The release of libpqxx 4.0 is scheduled for Sunday, 2011-11-27. This is a major new release; you may need to change your application code to compile with it.

A quick rundown of changes you need to take into account:

  • No more noticers. Use the new errorhandler instead.
  • The tablereader and tablewriter classes are now deprecated. They're going to disappear.
  • notify_listener is deprecated. Use the new notification_receiver instead (it accepts a payload).
  • pqxx::result::field and pqxx::result::tuple are now pqxx::field and pqxx::tuple.
  • Thread-safety metadata field have_strerror_r is now have_safe_strerror.
  • Prepared statements work a little differently; they're simpler now.
  • You'll need libpq version 8.0 or better.

That's the bad news. There's lots of good news as well. :)

2011-11-13: tablestreams are deprecated

The tablereader and tablewriter classes will be deprecated in 4.0. They cause problems (and even security risks) with some multibyte encodings.

Finding Everything

Where What
Sales Pitch Why this library should interest you
Using This Site The various services offered by this development site
Download Page Source archives (no binaries; those depend on your individual platform)
FAQ Frequently Asked Questions, and their answers
Online Documentation Wiki and copies of packaged documentation
Packagers Page Information for maintainers of libpqxx packages
Consulting? Where can I get professional development help?
Bug Tracker Known bugs and requests (as in View Tickets option in top button bar)
Reporting Bugs How to report a problem or request a new feature
Mailing Lists Hosted on pgFoundry site
Database Notes Notes and tips about postgres
Performance Tips Figure out and solve performance problems
Other Projects Other open-source development projects hosted here
libpqxx Elsewhere Sites where libpqxx is registered as a project
Author and Contributors Who made all this?

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

Also, you may want to have a look at the other open source projects hosted on this site.

Technical Overview

This library works on top of the C-level API library, libpq. It comes with postgres. You will link your program with both libpqxx and libpq, in that order.

Coding with libpqxx revolves around transactions. Transactions are a central concept in database management systems, but they are widely under-appreciated among application developers. In libpqxx, they're fundamental.

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 with a connection, but you do all your SQL work in transactions that you open in your connection. You commit each transaction when it's complete; if you don't, all changes made inside the transaction get rolled back.

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. This transaction type provides basic non-transactional behaviour. (This is sometimes called "autocommit": it commits every command right away).

Every command or query returns a result. Your query fetches its result data immediately when you execute it, and stores it in the result. Don't check your result for errors; failures show up as 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. You can access the rows in a result using standard iterators, or more like an array using numerical indexes. Inside each row you can access the fields by standard iterators, numerical indexes, or using column names.


Can't have a database example without an Employee table. Here's a simple program: find an employee by name, and raise their salary by 1 whatever-it-is-they-get-paid-in.

This example is so simple that anything that goes wrong crashes the program. You won't need to do that much more to fix that, but we'll get to it later.

#include <iostream>
#include <pqxx/pqxx>

int main(int, char *argv[])
  pqxx::connection c("dbname=company user=accounting");
  pqxx::work txn(c);

  pqxx::result r = txn.exec(
    "SELECT id "
    "FROM Employee "
    "WHERE name =" + txn.quote(argv[1]));

  if (r.size() != 1)
      << "Expected 1 employee with name " << argv[1] << ", "
      << "but found " << r.size() << std::endl;
    return 1;

  int employee_id = r[0][0].as<int>();
  std::cout << "Updating employee #" << employee_id << std::endl;

    "SET salary = salary + 1 "
    "WHERE id = " + txn.quote(employee_id));


For more realistic examples with detailed explanations, see CodeExamples. Also, see the API reference for details about what everything does.

Building your libpqxx program

The details depend on your system and compiler. On a typical Unix-like system, you might do:

c++ add_employee.cxx -I/usr/local/include/ -lpqxx -lpq

Remember to keep the -lpqxx and -lpq in that order! Otherwise the linker will complain bitterly about missing functions with names starting with "PQ."

The -I/usr/local/include/ tells the compiler where the directory with header files for libpqxx is. So in this example, the header files would be in /usr/local/include/pqxx/.

This should work on most GNU/Linux systems (Debian, Fedora, Gentoo, Red Hat, Slax, Ubuntu, etc.), BSD systems (FreeBSD, NetBSD, OpenBSD), vaguely Unix-like systems such as Apple OS X, and so on—as long as you have libpqxx, libpq, and a C++ compiler installed. If your C++ compiler has a different name on the command line, use that instead of "c++"). It works differently on Microsoft Windows, though there are development environments out there that behave more like a Unix system.

Ohloh Metrics GTF Contributor