Chapter 1. libpq - C Library

Table of Contents
1.1. Database Connection Functions
1.2. Query Execution Functions
1.2.1. Main Routines
1.2.2. Retrieving SELECT Result Information
1.2.3. Retrieving SELECT Result Values
1.2.4. Retrieving Non-SELECT Result Information
1.3. Asynchronous Query Processing
1.4. Fast Path
1.5. Asynchronous Notification
1.6. Functions Associated with the COPY Command
1.7. libpq Tracing Functions
1.8. libpq Control Functions
1.9. Environment Variables
1.10. Threading Behavior
1.11. Example Programs

libpq is the C application programmer's interface to Postgres. libpq is a set of library routines that allow client programs to pass queries to the Postgres backend server and to receive the results of these queries. libpq is also the underlying engine for several other Postgres application interfaces, including libpq++ (C++), libpgtcl (Tcl), Perl, and ecpg. So some aspects of libpq's behavior will be important to you if you use one of those packages.

Three short programs are included at the end of this section to show how to write programs that use libpq. There are several complete examples of libpq applications in the following directories:

../src/test/regress
../src/test/examples
../src/bin/psql
   

Frontend programs that use libpq must include the header file libpq-fe.h and must link with the libpq library.

1.1. Database Connection Functions

The following routines deal with making a connection to a Postgres backend server. The application program can have several backend connections open at one time. (One reason to do that is to access more than one database.) Each connection is represented by a PGconn object which is obtained from PQconnectdb or PQsetdbLogin. Note that these functions will always return a non-null object pointer, unless perhaps there is too little memory even to allocate the PGconn object. The PQstatus function should be called to check whether a connection was successfully made before queries are sent via the connection object.

libpq application programmers should be careful to maintain the PGconn abstraction. Use the accessor functions below to get at the contents of PGconn. Avoid directly referencing the fields of the PGconn structure because they are subject to change in the future. (Beginning in Postgres release 6.4, the definition of struct PGconn is not even provided in libpq-fe.h. If you have old code that accesses PGconn fields directly, you can keep using it by including libpq-int.h too, but you are encouraged to fix the code soon.)