libpq++ is the C++ API to PostgreSQL. libpq++ is a set of classes that allow client programs to connect to the PostgreSQL backend server. These connections come in two forms: a Database Class and a Large Object class. The Database Class is intended for manipulating a database. You can send all sorts of SQL queries to the PostgreSQL backend server and retrieve the responses of the server. The Large Object Class is intended for manipulating a large object in a database. Although a Large Object instance can send normal queries to the PostgreSQL backend server it is only intended for simple queries that do not return any data. A large object should be seen as a file stream. In the future it should behave much like the C++ file streams cin, cout and cerr. This chapter is based on the documentation for the libpq C library. Three short programs are listed at the end of this section as examples of libpq++ programming (though not necessarily of good programming). There are several examples of libpq++ applications in src/libpq++/examples, including the source code for the three examples in this chapter. The following environment variables can be used to set up default values for an environment and to avoid hard-coding database names into an application program: Refer to for a complete list of available connection options. The following environment variables can be used to select default connection parameter values, which will be used by PQconnectdb or PQsetdbLogin if no value is directly specified by the calling code. These are useful to avoid hard-coding database names into simple application programs. libpq++ uses only environment variables or libpq's PQconnectdb conninfo style strings. PGHOST sets the default server name. If this begins with a slash, it specifies Unix-domain communication rather than TCP/IP communication; the value is the name of the directory in which the socket file is stored (default /tmp). PGPORT sets the default TCP port number or Unix-domain socket file extension for communicating with the PostgreSQL backend. PGDATABASE sets the default PostgreSQL database name. PGUSER sets the user name used to connect to the database and for authentication. PGPASSWORD sets the password used if the backend demands password authentication. This is not recommended because the password can be read by others using the ps command with special options on some platforms. PGREALM sets the Kerberos realm to use with PostgreSQL, if it is different from the local realm. If PGREALM is set, PostgreSQL applications will attempt authentication with servers for this realm and use separate ticket files to avoid conflicts with local ticket files. This environment variable is only used if Kerberos authentication is selected by the backend. PGOPTIONS sets additional runtime options for the PostgreSQL backend. PGTTY sets the file or tty on which debugging messages from the backend server are displayed. The following environment variables can be used to specify user-level default behavior for every PostgreSQL session: PGDATESTYLE sets the default style of date/time representation. PGTZ sets the default time zone. The following environment variables can be used to specify default internal behavior for every PostgreSQL session: PGGEQO sets the default mode for the genetic optimizer. Refer to the SET SQL command for information on correct values for these environment variables. The connection class makes the actual connection to the database and is inherited by all of the access classes. The database class provides C++ objects that have a connection to a backend server. To create such an object one first needs the appropriate environment for the backend to access. The following constructors deal with making a connection to a backend server from a C++ program. PgConnection makes a new connection to a backend database server. PgConnection::PgConnection(const char *conninfo) The conninfo string is the same as for the underlying libpq PQconnectdb function. Although typically called from one of the access classes, a connection to a backend server is possible by creating a PgConnection object. ConnectionBad returns whether or not the connection to the backend server succeeded or failed. bool PgConnection::ConnectionBad() const Returns true if the connection failed. Status returns the status of the connection to the backend server. ConnStatusType PgConnection::Status() Returns either CONNECTION_OK or CONNECTION_BAD depending on the state of the connection. PgDatabase makes a new connection to a backend database server. PgDatabase(const char *conninfo) After a PgDatabase has been created it should be checked to make sure the connection to the database succeeded before sending queries to the object. This can easily be done by retrieving the current status of the PgDatabase object with the Status or ConnectionBad methods. DBName Returns the name of the current database. const char *PgConnection::DBName() Notifies Returns the next notification from a list of unhandled notification messages received from the backend. PGnotify* PgConnection::Notifies() See PQnotifies for details. Exec Sends a query to the backend server. It's probably more desirable to use one of the next two functions. ExecStatusType PgConnection::Exec(const char* query) Returns the result of the query. The following status results can be expected: PGRES_EMPTY_QUERY PGRES_COMMAND_OK, if the query was a command PGRES_TUPLES_OK, if the query successfully returned tuples PGRES_COPY_OUT PGRES_COPY_IN PGRES_BAD_RESPONSE, if an unexpected response was received PGRES_NONFATAL_ERROR PGRES_FATAL_ERROR ExecCommandOk Sends a command query to the backend server. int PgConnection::ExecCommandOk(const char *query) Returns TRUE if the command query succeeds. ExecTuplesOk Sends a command query to the backend server. int PgConnection::ExecTuplesOk(const char *query) Returns TRUE if the command query succeeds. ErrorMessage Returns the last error message text. const char *PgConnection::ErrorMessage() Tuples Returns the number of tuples (rows) in the query result. int PgDatabase::Tuples() const Fields Returns the number of fields (attributes) in each tuple of the query result. int PgDatabase::Fields() FieldName Returns the field (attribute) name associated with the given field index. Field indices start at 0. const char *PgDatabase::FieldName(int field_num) const FieldNum PQfnumber Returns the field (attribute) index associated with the given field name. int PgDatabase::FieldNum(const char* field_name) const -1 is returned if the given name does not match any field. FieldType Returns the field type associated with the given field index. The integer returned is an internal coding of the type. Field indices start at 0. Oid PgDatabase::FieldType(int field_num) const FieldType Returns the field type associated with the given field name. The integer returned is an internal coding of the type. Field indices start at 0. Oid PgDatabase::FieldType(const char* field_name) const FieldSize Returns the size in bytes of the field associated with the given field index. Field indices start at 0. int PgDatabase::FieldSize(int field_num) const Returns the space allocated for this field in a database tuple given the field number. In other words the size of the server's binary representation of the data type. -1 is returned if the field is variable size. FieldSize Returns the size in bytes of the field associated with the given field index. Field indices start at 0. int PgDatabase::FieldSize(const char *field_name) const Returns the space allocated for this field in a database tuple given the field name. In other words the size of the server's binary representation of the data type. -1 is returned if the field is variable size. GetValue Returns a single field (attribute) value of one tuple of a PGresult. Tuple and field indices start at 0. const char *PgDatabase::GetValue(int tup_num, int field_num) const For most queries, the value returned by GetValue is a null-terminated string representation of the attribute value. But if BinaryTuples is TRUE, the value returned by GetValue is the binary representation of the type in the internal format of the backend server (but not including the size word, if the field is variable-length). It is then the programmer's responsibility to cast and convert the data to the correct C type. The pointer returned by GetValue points to storage that is part of the PGresult structure. One should not modify it, and one must explicitly copy the value into other storage if it is to be used past the lifetime of the PGresult structure itself. BinaryTuples is not yet implemented. GetValue Returns a single field (attribute) value of one tuple of a PGresult. Tuple and field indices start at 0. const char *PgDatabase::GetValue(int tup_num, const char *field_name) const For most queries, the value returned by GetValue is a null-terminated string representation of the attribute value. But if BinaryTuples is TRUE, the value returned by GetValue is the binary representation of the type in the internal format of the backend server (but not including the size word, if the field is variable-length). It is then the programmer's responsibility to cast and convert the data to the correct C type. The pointer returned by GetValue points to storage that is part of the PGresult structure. One should not modify it, and one must explicitly copy the value into other storage if it is to be used past the lifetime of the PGresult structure itself. BinaryTuples is not yet implemented. GetLength Returns the length of a field (attribute) in bytes. Tuple and field indices start at 0. int PgDatabase::GetLength(int tup_num, int field_num) const This is the actual data length for the particular data value, that is the size of the object pointed to by GetValue. Note that for ASCII-represented values, this size has little to do with the binary size reported by PQfsize. GetLength Returns the length of a field (attribute) in bytes. Tuple and field indices start at 0. int PgDatabase::GetLength(int tup_num, const char* field_name) const This is the actual data length for the particular data value, that is the size of the object pointed to by GetValue. Note that for ASCII-represented values, this size has little to do with the binary size reported by PQfsize. GetIsNull Returns whether a field has the null value. bool GetIsNull(int tup_num, int field_num) const Note that GetValue will return the empty string for null fields, not the NULL pointer. GetIsNull Returns whether a field has the null value. bool GetIsNull(int tup_num, const char *field_name) const Note that GetValue will return the empty string for null fields, not the NULL pointer. DisplayTuples OBSOLESCENT: Prints out all the tuples and, optionally, the attribute names to the specified output stream. void PgDatabase::DisplayTuples(FILE *out = 0, bool fillAlign = true, const char* fieldSep = "|",bool printHeader = true, bool quiet = false) const PrintTuples OBSOLESCENT: Prints out all the tuples and, optionally, the attribute names to the specified output stream. void PgDatabase::PrintTuples(FILE *out = 0, bool printAttName = true, bool terseOutput = false, bool fillAlign = false) const CmdTuples Returns the number of rows affected after an INSERT, UPDATE or DELETE. If the command was anything else, it returns -1. int PgDatabase::CmdTuples() const OidStatus const char *PgDatabase::OidStatus() const GetLine int PgDatabase::GetLine(char* string, int length) PutLine void PgDatabase::PutLine(const char* string) EndCopy int PgDatabase::EndCopy() PostgreSQL supports asynchronous notification via the LISTEN and NOTIFY commands. A backend registers its interest in a particular semaphore with the LISTEN command. All backends that are listening on a particular named semaphore will be notified asynchronously when a NOTIFY of that name is executed by another backend. No additional information is passed from the notifier to the listener. Thus, typically, any actual data that needs to be communicated is transferred through the relation. In the past, the documentation has associated the names used for asynchronous notification with relations or classes. However, there is in fact no direct linkage of the two concepts in the implementation, and the named semaphore in fact does not need to have a corresponding relation previously defined. libpq++ applications are notified whenever a connected backend has received an asynchronous notification. However, the communication from the backend to the frontend is not asynchronous. The libpq++ application must poll the backend to see if there is any pending notification information. After the execution of a query, a frontend may call PgDatabase::Notifies to see if any notification data is currently available from the backend. PgDatabase::Notifies returns the notification from a list of unhandled notifications from the backend. The function returns NULL if there are no pending notifications from the backend. PgDatabase::Notifies behaves like the popping of a stack. Once a notification is returned from PgDatabase::Notifies, it is considered handled and will be removed from the list of notifications. PgDatabase::Notifies retrieves pending notifications from the server. PGnotify* PgDatabase::Notifies() The second sample program gives an example of the use of asynchronous notification. The copy command in PostgreSQL has options to read from or write to the network connection used by libpq++. Therefore, functions are necessary to access this network connection directly so applications may take full advantage of this capability. PgDatabase::GetLine reads a newline-terminated line of characters (transmitted by the backend server) into a buffer string of size length. int PgDatabase::GetLine(char* string, int length) Like the Unix system routine fgets (3), this routine copies up to length-1 characters into string. It is like gets (3), however, in that it converts the terminating newline into a null character. PgDatabase::GetLine returns EOF at end of file, 0 if the entire line has been read, and 1 if the buffer is full but the terminating newline has not yet been read. Notice that the application must check to see if a new line consists of a single period ("."), which indicates that the backend server has finished sending the results of the copy. Therefore, if the application ever expects to receive lines that are more than length-1 characters long, the application must be sure to check the return value of PgDatabase::GetLine very carefully. PgDatabase::PutLine Sends a null-terminated string to the backend server. void PgDatabase::PutLine(char* string) The application must explicitly send a single period character (".") to indicate to the backend that it has finished sending its data. PgDatabase::EndCopy syncs with the backend. int PgDatabase::EndCopy() This function waits until the backend has finished processing the copy. It should either be issued when the last string has been sent to the backend using PgDatabase::PutLine or when the last string has been received from the backend using PgDatabase::GetLine. It must be issued or the backend may get out of sync with the frontend. Upon return from this function, the backend is ready to receive the next query. The return value is 0 on successful completion, nonzero otherwise. As an example: PgDatabase data; data.Exec("CREATE TABLE foo (a int4, b char(16), d double precision)"); data.Exec("COPY foo FROM STDIN"); data.PutLine("3\tHello World\t4.5\n"); data.PutLine("4\tGoodbye World\t7.11\n"); &... data.PutLine("\\.\n"); data.EndCopy();