wiki:WikiStart

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

--

Welcome! libpqxx is the official C++ client API for PostgreSQL, the enterprise-strength open-source database software. (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, libpqxx is the library you use.

For those who arrived at this page through http://pqxx.tk/: that domain name may disappear at some point in the future. Please use http://pqxx.org/ instead, or bookmark this page.

2006-09-12: Visual C++ build error

If you are using Visual C++ and you're getting a link error about a missing libpqxx library while building libpqxx, try creating the lib directory in the main libpqxx source tree and building again.

This should be fixed in the current source repository.

2006-09-07: Mailing Lists Back!

The old development site hosting our mailing lists has recovered from its recent double disk failure. If you posted to libpqxx-general over the past few weeks but your post did not appear, please send it again.

2006-09-06: libpqxx 2.6.8 released

It was planned for this Monday, but life got in the way: libpqxx 2.6.8 is out. This fixes a number of problems, so upgrading should be well worth your while:

  • Binary arguments to prepared statements were previously truncated at the first zero byte.
  • Parts of the reference documentation were missing or generated in the wrong place.
  • Some versions of mktemp (BSD versions and very old GNU versions) did not agree with the way we used the utility.
  • Builds on Windows would fail for various reasons, including failure to find the socket library.
  • pqxx-config has been replaced with pkg-config usage.
  • On GNU/Linux, poll() is used to get around file descriptor limits (and speed up programs with lots of file descriptors).

Then there are a few interesting new features:

  • More specific exception types to help tell different kinds of errors apart.
  • A new absolute_cursor class implements a cursor that "knows where it is" and supports random access to its result set.
  • Connections can provide version numbers for the server and communications protocol being used.

Get it now from the download page!

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 tarballs (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
Bug Tracker Known bugs and requests (as in View Tickets option in top button bar)
Bugs by Milestone Bugs and feature requests, but ordered by milestone
Reporting Bugs How to report a problem or request a new feature
Mailing Lists libpqxx-general and libpqxx-announce (Still hosted on the old libpqxx site)
Other Projects Other open-source development projects hosted on thaiopensource.org
Old Site Old home page for libpqxx development (now used only for the mailing lists)
Author and Contributors Who made all this?

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

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. 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. More usually, however, applications are designed without transactions simply because the developers aren't 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 the transaction 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. This transaction type 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.


GTF Contributor