libpqtypes

libpqtypes is a libpq extension that offers a new way of handling parameterized queries and getting result field values. Both putting parameters and getting values use a printf/scanf style interface, with consistent specifiers for both.

Portability

libpqtypes has been tested on many platforms. It will most likely work on many others. Below is a list of the platforms libpqtypes has been tested on.

Example of libpqtypes in action:

#include <libpqtypes.h>

/* Always call first on any conn that is to be used with libpqtypes */
PQinitTypes(conn);

/* Instead of using PQexecParams and friends .... */
int resultFormat = 1;
PGparam *param = PQparamCreate(conn);

/* Pack one or more parameters into a PGparam. */
PQputf(param, "%int4 %text", 654321, "some text");

/* Execute a parameterized query. */
PGresult *res = PQparamExec(conn, param, 
  "INSERT INTO t VALUES ($1, $2)", resultFormat);
PQclear(res);

/* Release all resources used by `param'. */
PQparamClear(param);

/* Or, do all of the above in a single statement!  This will put an 
 * int4 and text into a temporary PGparam and execute 
 * "INSERT INTO t VALUES ($1, $2)".
 */
PGresult *res = PQexecf(conn, 
  "INSERT INTO t VALUES (%int4, %text)", 654321, "some text");
PQclear(res);

/* Let's get a composite.
 * CREATE TYPE simple AS (a int4, t text);
 */
PGint4 i4;
PGtext text;
PGresult *simple;
PGregisterType composites[] = {
  {"simple", NULL, NULL}
};

/* Your composites need to be registered */
PQregisterTypes(conn, PQT_COMPOSITE, composites, 1, 0);

/* 2nd arg, PGparam, can be NULL if there are no query params.
 * Composites require binary results, so we can't use PQexec().
 */
res = PQparamExec(conn, NULL, "SELECT my_simple FROM t", resultFormat);
if(!res)
  fprintf(stderr, "ERROR: %s\n", PQgeterror());

/* Get the simple composite, which is exposed as a PGresult. */
PQgetf(res, 0, "%simple", 0, &simple);
PQclear(res); /* no longer needed */

/* Get the simple composite attributes from the simple result.
 * Reference fields by name by using a '#' rather than a '%'.
 * The field names are the composite attribute names.
 */
PQgetf(simple, 0, "#int4 #text", "a", &i4, "t", &text);
PQclear(simple);
NOTE:

This requires using postgresql 8.4 or a patched version of 8.3.x. libpqtypes requires a new 8.4 feature called libpq-events. To learn more about this feature, see the 8.4 docs. The 8.3 patch can be found here: libpq 8.3 patch.

pgFoundry

libpqtypes is a pgFoundry project, which is where the lastest releases can be found. This site is for online documentation.

Source Code

The source code to libpqtypes can be browsed online. Or, you can checkout/browse the CVS repository.

Documentation

libpqtypes man documentation can be browsed online or at the shell. Below are the links to every man page and any other relevant documents.

Package Documents
Overview Documents
Managing PGparam
Putting Parameters
Executing Commands
Getting Result Values
Type Management and Registration
* Deprecated
Error System
Prepared Specifier Management
Misc. Functions
* Deprecated

Contact

To report bugs, feature requests or general questions goto the libpqtypes pgFoundry Forum or send an email to libpqtypes (at) esilo (dot) com>.