wiki:WikiStart

Version 41 (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).

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-06-01: Expect 2.6.7 release soon

Well, it turns out the 2.6.6 "stable" release got a lot of testing that we didn't get with development releases. People have run into several build problems that will be fixed in 2.6.7:

  • Missing symbols in the include/pqxx/config-internal-libpq.h configuration header. If the configure script produced a version for you that is only a line or two long, it's because of this bug. Paweł Sikora at PLD and "crazy" Gabriel C. at Frugalware are helping us sort this out; for now it looks like a problem with the grep program. We've been bitten by such problems before when Fedora Core 4 was just released.
  • Compile errors in connection_base.cxx lines 837 and 853. This is workaround code for when the available libpq version does not offer the PQprepare() function. There are two ways to get around this:
    1. Make the "a" in line 837 an int (i.e. "for (int a; [...]") and replace the one in line 853 with "n", then continue compiling.
    2. Upgrade to a libpq version from PostgreSQL 8.1--including the libpq headers!--and rebuild libpqxx, starting with the configure script run. Make sure that your compiler options are not too strict (specifically, don't let it treat warnings as errors and don't enable maintainer mode) or the script in its 2.6.6 version will fail to detect PQprepare().
  • Incomplete Visual C++ makefile. This was due to a small "slash-vs-backslash" bug in a template file.

2006-06-03: Call to action for package maintainers

Several people maintaining libpqxx packages for various free operating system distributions have picked up the 2.6.6 release vary quickly, and some have run into problems with it that didn't occur in the upstream test environment. In effect, the meaning of "stable" and "development" releases ended up being inverted because it's the stable releases that receive wide testing, and the development releases that receive the subsequent fixes.

I'm not convinced that a more fine-grained version numbering scheme would fix the problem. How about this instead:

  1. We set up a new mailing list with a name like libpqxx-packagers, meant for package maintainers.
  2. Whenever a new stable release is imminent, an announcement will be posted there. The announcement will state a target date for the release.
  3. Where possible, we a new development release is prepared to serve as a "preview" for the upcoming stable version.
  4. Maintainers on the list test the latest version in their own environments, and post any problems they have on the list. If there are no problems, a simple acknowledgment would be nice as an indicator of confidence.
  5. Any problems brought up are fixed, insofar that looks feasible before the target date.
  6. To avoid endless touchup cycles, and save your time, we try to avoid going through another test release.
  7. The fixes are applied and a stable upgrade is announced.

Maintainers, please let me know if you have any problems with this.

2006-05-27: Release 2.6.6 introduces new string-escaping API

Important note to existing users: a bug has been discovered in the string-escaping functions of libpq, the C-level library underlying libpqxx, that can cause trouble with non-ASCII characters. This can cause applications to fail on some non-ASCII inputs (and depending on their locale settings). This is also a security hole.

To deal with the problem, the sqlesc() functions have been replaced with a set of similar new functions, called simply "esc()," in the transaction classes. So please, where previously you wrote

X = T.exec("SELECT title FROM books WHERE author='" + sqlesc(writer) + "'");

...to prevent accidents, you should now write:

X = T.exec("SELECT title FROM books WHERE author='" + T.esc(writer) + "'");

A similar change will soon be made with the escape_binary() functions. Please update your libpq as soon as possible, and rebuild libpqxx if necessary!

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
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
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, transactions 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