libpqtypes

• Full support for binary and text format (parameter and result)
• Full support for composites, arrays and composite arrays. (binary format only)
• printf style interface to libpq's binary parameterized API. (PQputf)
• scanf style interface for getting values: PQgetvalue extension. (PQgetf)
• Ability to register user-defined types, aliases and data type sub-classes for use with printf style interfaces: ex. "%mytype". (PQregisterTypeHandler)
• Per-thread global error message: (PQgeterror)
• Online docs as well as man pages.

#include <libpqtypes.h>

/* 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);

/* Let's get a composite.
 * CREATE TYPE simple AS (a int4, t text);
 */
PGint4 i4;
PGtext text;
PGresult *simple;

/* Your composites need to be registered */
PQregisterTypeHandler(conn, "simple", NULL, NULL);

/* 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:
To use libpqtypes you must apply a patch to libpq. libpqtypes requires receiving notifications about certain libpq events. The patch we submitted to -patches is called libpq Object Hooks. It makes PGconn and PGresult notify registered Object Hooks about object construction and destruction (PQresets as well). The Object Hooks patch is in the 2008 May commit fest queue, so we are hoping for the best. The pgFoundry downloads section contains the patch under the name "objhooks.patch".

pgFoundry

Source Code

Documentation

Package Documents
README
INSTALL
LICENSE
AUTHORS
ChangeLog

Overview Documents
How to Put and Get data types
Describes every structure used by libpqtypes: like PGtimestamp or PGpolygon.
How to handle Composites
Detailed examples for simple, nested and arrays of composites.
Writing Data Type Handlers
Documents structures used by type handlers; includes examples.

Managing PGparam
PQparamCreate
PQparamReset
PQparamClear

Putting Parameters
PQputf
PQputvf

Executing Commands
PQparamExec
PQparamExecPrepared
PQparamSendQuery
PQparamSendQueryPrepared

Getting Result Values
PQgetf

Registering Types
PQregisterTypeHandler

Error System
PQgeterror
PQseterror

Misc. Functions
PQtypesObjectHooks
PQlocalTZInfo

Contact