+ sortas="libpq">with libpq
+
+
+
+
+
+ requiressl
+
+ This option is deprecated in favor of the sslmode
+ setting.
+
+
+ If set to 1, an
SSL connection to the server
+ is required (this is equivalent to sslmode
+
require). libpq will then refuse+ to connect if the server does not accept an
+
SSL connection. If set to 0 (default),
+
libpq will negotiate the connection type with+ the server (equivalent to sslmode
+ prefer). This option is only available if
+
PostgreSQL is compiled with SSL support.+
+
+
+
+
+ krbsrvname
+
+ Kerberos service name to use when authenticating with Kerberos 5
+ or GSSAPI.
+ This must match the service name specified in the server
+ configuration for Kerberos authentication to succeed. (See also
+ and .)
+
+
+
+
+
+ gsslib
+
+ GSS library to use for GSSAPI authentication. Only used on Windows.
+ Set to gssapi to force libpq to use the GSSAPI
+ library for authentication instead of the default SSPI.
+
+
+
+
+
+ service
+
+ Service name to use for additional parameters. It specifies a service
+ name in pg_service.conf that holds additional connection parameters.
+ This allows applications to specify only a service name so connection parameters
+ can be centrally maintained. See .
+
+
+
+
+
+ If any parameter is unspecified, then the corresponding
+ environment variable (see )
+ is checked. If the environment variable is not set either,
+ then the indicated built-in defaults are used.
PQconnectStartPQconnectStart
PQconnectPollPQconnectPoll
- Make a connection to the database server in a nonblocking manner.
-
-
- PGconn *PQconnectStart(const char *conninfo);
-
-
-
- PostgresPollingStatusType PQconnectPoll(PGconn *conn);
-
-
-
- These two functions are used to open a connection to a database server such
- that your application's thread of execution is not blocked on remote I/O
- whilst doing so.
- The point of this approach is that the waits for I/O to complete can occur
- in the application's main loop, rather than down inside
- PQconnectdb, and so the application can manage this
- operation in parallel with other activities.
-
-
- The database connection is made using the parameters taken from the string
- conninfo, passed to PQconnectStart. This string is in
- the same format as described above for PQconnectdb.
-
- Neither PQconnectStart nor PQconnectPoll will block, so long as a number of
- restrictions are met:
-
-
- The hostaddr and host parameters are used appropriately to ensure that
- name and reverse name queries are not made. See the documentation of
- these parameters under PQconnectdb above for details.
-
-
-
-
- If you call PQtrace, ensure that the stream object
- into which you trace will not block.
-
-
-
-
- You ensure that the socket is in the appropriate state
- before calling PQconnectPoll, as described below.
-
-
-
-
-
- To begin a nonblocking connection request, call conn = PQconnectStart("connection_info_string").
- If
conn is null, then
libpq has been unable to allocate a new PGconn- structure. Otherwise, a valid PGconn pointer is returned (though not yet
- representing a valid connection to the database). On return from
- PQconnectStart, call status = PQstatus(conn). If status equals
- CONNECTION_BAD, PQconnectStart has failed.
-
-
- If PQconnectStart succeeds, the next stage is to poll
-
libpq so that it can proceed with the connection sequence.- Use PQsocket(conn) to obtain the descriptor of the
- socket underlying the database connection.
- Loop thus: If PQconnectPoll(conn) last returned
- PGRES_POLLING_READING, wait until the socket is ready to
- read (as indicated by select(), poll(), or
- similar system function).
- Then call PQconnectPoll(conn) again.
- Conversely, if PQconnectPoll(conn) last returned
- PGRES_POLLING_WRITING, wait until the socket is ready
- to write, then call PQconnectPoll(conn) again.
- If you have yet to call
- PQconnectPoll, i.e., just after the call to
- PQconnectStart, behave as if it last returned
- PGRES_POLLING_WRITING. Continue this loop until
- PQconnectPoll(conn) returns
- PGRES_POLLING_FAILED, indicating the connection procedure
- has failed, or PGRES_POLLING_OK, indicating the connection
- has been successfully made.
-
-
- At any time during connection, the status of the connection can be
- checked by calling PQstatus. If this gives CONNECTION_BAD, then the
- connection procedure has failed; if it gives CONNECTION_OK, then the
- connection is ready. Both of these states are equally detectable
- from the return value of PQconnectPoll, described above. Other states might also occur
- during (and only during) an asynchronous connection procedure. These
- indicate the current stage of the connection procedure and might be useful
- to provide feedback to the user for example. These statuses are:
-
-
-
- CONNECTION_STARTED
-
- Waiting for connection to be made.
-
-
-
-
-
- CONNECTION_MADE
-
- Connection OK; waiting to send.
-
-
-
-
-
- CONNECTION_AWAITING_RESPONSE
-
- Waiting for a response from the server.
-
-
-
-
-
- CONNECTION_AUTH_OK
+ Make a connection to the database server in a nonblocking manner.
+
+
+ PGconn *PQconnectStart(const char *conninfo);
+
+
+
+ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
+
+
+
+ These two functions are used to open a connection to a database server such
+ that your application's thread of execution is not blocked on remote I/O
+ whilst doing so.
+ The point of this approach is that the waits for I/O to complete can occur
+ in the application's main loop, rather than down inside
+ PQconnectdb, and so the application can manage this
+ operation in parallel with other activities.
+
+
+ The database connection is made using the parameters taken from the string
+ conninfo, passed to PQconnectStart. This string is in
+ the same format as described above for PQconnectdb.
+
+ Neither PQconnectStart nor PQconnectPoll will block, so long as a number of
+ restrictions are met:
+
- Received authentication; waiting for backend start-up to finish.
+ The hostaddr and host parameters are used appropriately to ensure that
+ name and reverse name queries are not made. See the documentation of
+ these parameters under PQconnectdb above for details.
-
-
-
- CONNECTION_SSL_STARTUP
+
- Negotiating SSL encryption.
+ If you call PQtrace, ensure that the stream object
+ into which you trace will not block.
-
-
-
- CONNECTION_SETENV
+
- Negotiating environment-driven parameter settings.
+ You ensure that the socket is in the appropriate state
+ before calling PQconnectPoll, as described below.
-
-
-
- Note that, although these constants will remain (in order to maintain
- compatibility), an application should never rely upon these occurring in a
- particular order, or at all, or on the status always being one of these
- documented values. An application might do something like this:
+
+
+
+ To begin a nonblocking connection request, call conn = PQconnectStart("connection_info_string").
+ If
conn is null, then
libpq has been unable to allocate a new PGconn+ structure. Otherwise, a valid PGconn pointer is returned (though not yet
+ representing a valid connection to the database). On return from
+ PQconnectStart, call status = PQstatus(conn). If status equals
+ CONNECTION_BAD, PQconnectStart has failed.
+
+
+ If PQconnectStart succeeds, the next stage is to poll
+
libpq so that it can proceed with the connection sequence.+ Use PQsocket(conn) to obtain the descriptor of the
+ socket underlying the database connection.
+ Loop thus: If PQconnectPoll(conn) last returned
+ PGRES_POLLING_READING, wait until the socket is ready to
+ read (as indicated by select(), poll(), or
+ similar system function).
+ Then call PQconnectPoll(conn) again.
+ Conversely, if PQconnectPoll(conn) last returned
+ PGRES_POLLING_WRITING, wait until the socket is ready
+ to write, then call PQconnectPoll(conn) again.
+ If you have yet to call
+ PQconnectPoll, i.e., just after the call to
+ PQconnectStart, behave as if it last returned
+ PGRES_POLLING_WRITING. Continue this loop until
+ PQconnectPoll(conn) returns
+ PGRES_POLLING_FAILED, indicating the connection procedure
+ has failed, or PGRES_POLLING_OK, indicating the connection
+ has been successfully made.
+
+
+ At any time during connection, the status of the connection can be
+ checked by calling PQstatus. If this gives CONNECTION_BAD, then the
+ connection procedure has failed; if it gives CONNECTION_OK, then the
+ connection is ready. Both of these states are equally detectable
+ from the return value of PQconnectPoll, described above. Other states might also occur
+ during (and only during) an asynchronous connection procedure. These
+ indicate the current stage of the connection procedure and might be useful
+ to provide feedback to the user for example. These statuses are:
+
+
+
+ CONNECTION_STARTED
+
+ Waiting for connection to be made.
+
+
+
+
+
+ CONNECTION_MADE
+
+ Connection OK; waiting to send.
+
+
+
+
+
+ CONNECTION_AWAITING_RESPONSE
+
+ Waiting for a response from the server.
+
+
+
+
+
+ CONNECTION_AUTH_OK
+
+ Received authentication; waiting for backend start-up to finish.
+
+
+
+
+
+ CONNECTION_SSL_STARTUP
+
+ Negotiating SSL encryption.
+
+
+
+
+
+ CONNECTION_SETENV
+
+ Negotiating environment-driven parameter settings.
+
+
+
+
+
+ Note that, although these constants will remain (in order to maintain
+ compatibility), an application should never rely upon these occurring in a
+ particular order, or at all, or on the status always being one of these
+ documented values. An application might do something like this:
switch(PQstatus(conn))
{
feedback = "Connecting...";
}
-
-
- The connect_timeout connection parameter is ignored
- when using PQconnectPoll; it is the application's
- responsibility to decide whether an excessive amount of time has elapsed.
- Otherwise, PQconnectStart followed by a
- PQconnectPoll loop is equivalent to
- PQconnectdb.
-
-
- Note that if PQconnectStart returns a non-null pointer, you must call
- PQfinish when you are finished with it, in order to dispose of
- the structure and any associated memory blocks. This must be done even if
- the connection attempt fails or is abandoned.
-
-
-
-
-
-
PQconndefaultsPQconndefaults-
- Returns the default connection options.
+
+
+ The connect_timeout connection parameter is ignored
+ when using PQconnectPoll; it is the application's
+ responsibility to decide whether an excessive amount of time has elapsed.
+ Otherwise, PQconnectStart followed by a
+ PQconnectPoll loop is equivalent to
+ PQconnectdb.
+
+
+ Note that if PQconnectStart returns a non-null pointer, you must call
+ PQfinish when you are finished with it, in order to dispose of
+ the structure and any associated memory blocks. This must be done even if
+ the connection attempt fails or is abandoned.
+
+
+
+
+
+
PQconndefaultsPQconndefaults+
+ Returns the default connection options.
PQconninfoOption *PQconndefaults(void);
int dispsize; /* Field size in characters for dialog */
} PQconninfoOption;
-
-
- Returns a connection options array. This can be used to determine
- all possible PQconnectdb options and their
- current default values. The return value points to an array of
- PQconninfoOption structures, which ends
- with an entry having a null keyword pointer. The
- null pointer is returned if memory could not be allocated. Note that
- the current default values (val fields)
- will depend on environment variables and other context. Callers
- must treat the connection options data as read-only.
-
-
- After processing the options array, free it by passing it to
- PQconninfoFree. If this is not done, a small amount of memory
- is leaked for each call to PQconndefaults.
-
-
-
-
-
-
-
- Closes the connection to the server. Also frees
- memory used by the PGconn object.
-
- void PQfinish(PGconn *conn);
-
-
-
- Note that even if the server connection attempt fails (as
- indicated by PQstatus), the application should call PQfinish
- to free the memory used by the PGconn object.
- The PGconn pointer must not be used again after
- PQfinish has been called.
-
-
-
-
-
-
- Resets the communication channel to the server.
-
- void PQreset(PGconn *conn);
-
-
-
- This function will close the connection
- to the server and attempt to reestablish a new
- connection to the same server, using all the same
- parameters previously used. This might be useful for
- error recovery if a working connection is lost.
+
+
+ Returns a connection options array. This can be used to determine
+ all possible PQconnectdb options and their
+ current default values. The return value points to an array of
+ PQconninfoOption structures, which ends
+ with an entry having a null keyword pointer. The
+ null pointer is returned if memory could not be allocated. Note that
+ the current default values (val fields)
+ will depend on environment variables and other context. Callers
+ must treat the connection options data as read-only.
+
+
+ After processing the options array, free it by passing it to
+ PQconninfoFree. If this is not done, a small amount of memory
+ is leaked for each call to PQconndefaults.
+
+
+
+
+
+
+
+ Closes the connection to the server. Also frees
+ memory used by the PGconn object.
+
+ void PQfinish(PGconn *conn);
+
+
+
+ Note that even if the server connection attempt fails (as
+ indicated by PQstatus), the application should call PQfinish
+ to free the memory used by the PGconn object.
+ The PGconn pointer must not be used again after
+ PQfinish has been called.
+
+
+
+
+
+
+ Resets the communication channel to the server.
+
+ void PQreset(PGconn *conn);
+
+
+
+ This function will close the connection
+ to the server and attempt to reestablish a new
+ connection to the same server, using all the same
+ parameters previously used. This might be useful for
+ error recovery if a working connection is lost.
libpq application programmers should be careful to
maintain the PGconn abstraction. Use the accessor
functions described below to get at the contents of PGconn.
- Reference to internal PGconn fields using
+ Reference to internal PGconn fields using
libpq-int.h is not recommended because they are subject to change
in the future.
-
-
- The following functions return parameter values established at connection.
- These values are fixed for the life of the PGconn object.
+
-
-
-
- PQdb
-
-
-
+ The following functions return parameter values established at connection.
+ These values are fixed for the life of the PGconn object.
-
- Returns the database name of the connection.
-
- char *PQdb(const PGconn *conn);
-
-
-
-
+
+
+
+ PQdb
+
+
+
-
-
- PQuser
-
-
-
+
+ Returns the database name of the connection.
+
+ char *PQdb(const PGconn *conn);
+
+
+
+
-
- Returns the user name of the connection.
-
- char *PQuser(const PGconn *conn);
-
-
-
-
+
+
+ PQuser
+
+
+
-
-
- PQpass
-
-
-
+
+ Returns the user name of the connection.
+
+ char *PQuser(const PGconn *conn);
+
+
+
+
-
- Returns the password of the connection.
-
- char *PQpass(const PGconn *conn);
-
-
-
-
+
+
+ PQpass
+
+
+
-
-
- PQhost
-
-
-
+
+ Returns the password of the connection.
+
+ char *PQpass(const PGconn *conn);
+
+
+
+
-
- Returns the server host name of the connection.
-
- char *PQhost(const PGconn *conn);
-
-
-
-
+
+
+ PQhost
+
+
+
-
+
+ Returns the server host name of the connection.
+
+ char *PQhost(const PGconn *conn);
+
+
+
+
+
+
PQport
- Returns the status of the connection.
+ Returns the status of the connection.
ConnStatusType PQstatus(const PGconn *conn);
Returns the SSL structure used in the connection, or null
- if SSL is not in use.
+ if SSL is not in use.
SSL *PQgetssl(const PGconn *conn);
You must define USE_SSL in order to get the
- correct prototype for this function. Doing this will also
+ correct prototype for this function. Doing this will also
automatically include
ssl.h from
OpenSSL.
connections; it will fail when using protocol 2.0.
- The function creates a prepared statement named
-
stmtName from the query string, which- must contain a single SQL command.
stmtName can be- "" to create an unnamed statement, in which case any
- pre-existing unnamed statement is automatically replaced; otherwise
- it is an error if the statement name is already defined in the
- current session. If any parameters are used, they are referred
- to in the query as $1, $2, etc.
-
nParams is the number of parameters for which types- are pre-specified in the array
paramTypes[]. (The- array pointer can be NULL when
-
nParams is zero.) paramTypes[]- specifies, by OID, the data types to be assigned to the parameter
- symbols. If
paramTypes is NULL,- or any particular element in the array is zero, the server assigns
- a data type to the parameter symbol in the same way it would do
- for an untyped literal string. Also, the query can use parameter
- symbols with numbers higher than
nParams; data types- will be inferred for these symbols as well. (See
- PQdescribePrepared for a means to find out
- what data types were inferred.)
-
-
- As with PQexec, the result is normally a
- PGresult object whose contents indicate
- server-side success or failure. A null result indicates
- out-of-memory or inability to send the command at all. Use
- PQerrorMessage to get more information about
- such errors.
-
-
-
-
-
- Prepared statements for use with PQexecPrepared can also
- be created by executing SQL
- endterm="sql-prepare-title"> statements. (But PQprepare
- is more flexible since it does not require parameter types to be
- pre-specified.) Also, although there is no
libpq- function for deleting a prepared statement, the SQL
- linkend="sql-deallocate" endterm="sql-deallocate-title"> statement
- can be used for that purpose.
-
+ The function creates a prepared statement named
+
stmtName from the query string, which+ must contain a single SQL command.
stmtName can be+ "" to create an unnamed statement, in which case any
+ pre-existing unnamed statement is automatically replaced; otherwise
+ it is an error if the statement name is already defined in the
+ current session. If any parameters are used, they are referred
+ to in the query as $1, $2, etc.
+
nParams is the number of parameters for which types+ are pre-specified in the array
paramTypes[]. (The+ array pointer can be NULL when
+
nParams is zero.) paramTypes[]+ specifies, by OID, the data types to be assigned to the parameter
+ symbols. If
paramTypes is NULL,+ or any particular element in the array is zero, the server assigns
+ a data type to the parameter symbol in the same way it would do
+ for an untyped literal string. Also, the query can use parameter
+ symbols with numbers higher than
nParams; data types+ will be inferred for these symbols as well. (See
+ PQdescribePrepared for a means to find out
+ what data types were inferred.)
+
-
-
-
- PQexecPrepared
-
-
-
-
-
- Sends a request to execute a prepared statement with given
- parameters, and waits for the result.
+ As with PQexec, the result is normally a
+ PGresult object whose contents indicate
+ server-side success or failure. A null result indicates
+ out-of-memory or inability to send the command at all. Use
+ PQerrorMessage to get more information about
+ such errors.
+
+
+
+
+
+ Prepared statements for use with PQexecPrepared can also
+ be created by executing SQL
+ endterm="sql-prepare-title"> statements. (But PQprepare
+ is more flexible since it does not require parameter types to be
+ pre-specified.) Also, although there is no
libpq+ function for deleting a prepared statement, the SQL
+ linkend="sql-deallocate" endterm="sql-deallocate-title"> statement
+ can be used for that purpose.
+
+
+
+
+
+ PQexecPrepared
+
+
+
+
+
+ Sends a request to execute a prepared statement with given
+ parameters, and waits for the result.
PGresult *PQexecPrepared(PGconn *conn,
const char *stmtName,
const int *paramFormats,
int resultFormat);
-
-
- PQexecPrepared is like PQexecParams,
- but the command to be executed is specified by naming a
- previously-prepared statement, instead of giving a query string.
- This feature allows commands that will be used repeatedly to be
- parsed and planned just once, rather than each time they are
- executed. The statement must have been prepared previously in
- the current session. PQexecPrepared is supported
- only in protocol 3.0 and later connections; it will fail when
- using protocol 2.0.
-
-
- The parameters are identical to PQexecParams, except that the
- name of a prepared statement is given instead of a query string, and the
-
paramTypes[] parameter is not present (it is not needed since- the prepared statement's parameter types were determined when it was created).
-
-
-
-
-
-
- PQdescribePrepared
-
-
-
-
-
- Submits a request to obtain information about the specified
- prepared statement, and waits for completion.
+
+
+ PQexecPrepared is like PQexecParams,
+ but the command to be executed is specified by naming a
+ previously-prepared statement, instead of giving a query string.
+ This feature allows commands that will be used repeatedly to be
+ parsed and planned just once, rather than each time they are
+ executed. The statement must have been prepared previously in
+ the current session. PQexecPrepared is supported
+ only in protocol 3.0 and later connections; it will fail when
+ using protocol 2.0.
+
+
+ The parameters are identical to PQexecParams, except that the
+ name of a prepared statement is given instead of a query string, and the
+
paramTypes[] parameter is not present (it is not needed since+ the prepared statement's parameter types were determined when it was created).
+
+
+
+
+
+
+ PQdescribePrepared
+
+
+
+
+
+ Submits a request to obtain information about the specified
+ prepared statement, and waits for completion.
PGresult *PQdescribePrepared(PGconn *conn, const char *stmtName);
-
-
- PQdescribePrepared allows an application to obtain
- information about a previously prepared statement.
- PQdescribePrepared is supported only in protocol 3.0
- and later connections; it will fail when using protocol 2.0.
-
-
-
stmtName can be "" or NULL to reference- the unnamed statement, otherwise it must be the name of an existing
- prepared statement. On success, a PGresult with
- status PGRES_COMMAND_OK is returned. The
- functions PQnparams and
- PQparamtype can be applied to this
- PGresult to obtain information about the parameters
- of the prepared statement, and the functions
- PQnfields, PQfname,
- PQftype, etc provide information about the
- result columns (if any) of the statement.
-
-
-
-
-
-
- PQdescribePortal
-
-
-
-
-
- Submits a request to obtain information about the specified
- portal, and waits for completion.
+
+
+ PQdescribePrepared allows an application to obtain
+ information about a previously prepared statement.
+ PQdescribePrepared is supported only in protocol 3.0
+ and later connections; it will fail when using protocol 2.0.
+
+
+
stmtName can be "" or NULL to reference+ the unnamed statement, otherwise it must be the name of an existing
+ prepared statement. On success, a PGresult with
+ status PGRES_COMMAND_OK is returned. The
+ functions PQnparams and
+ PQparamtype can be applied to this
+ PGresult to obtain information about the parameters
+ of the prepared statement, and the functions
+ PQnfields, PQfname,
+ PQftype, etc provide information about the
+ result columns (if any) of the statement.
+
+
+
+
+
+
+ PQdescribePortal
+
+
+
+
+
+ Submits a request to obtain information about the specified
+ portal, and waits for completion.
PGresult *PQdescribePortal(PGconn *conn, const char *portalName);
-
-
- PQdescribePortal allows an application to obtain
- information about a previously created portal.
- (
libpq does not provide any direct access to- portals, but you can use this function to inspect the properties
- of a cursor created with a DECLARE CURSOR SQL command.)
- PQdescribePortal is supported only in protocol 3.0
- and later connections; it will fail when using protocol 2.0.
-
-
-
portalName can be "" or NULL to reference- the unnamed portal, otherwise it must be the name of an existing
- portal. On success, a PGresult with status
- PGRES_COMMAND_OK is returned. The functions
- PQnfields, PQfname,
- PQftype, etc can be applied to the
- PGresult to obtain information about the result
- columns (if any) of the portal.
-
-
-
-
-
+
- structure encapsulates the result returned by the server.
-
libpq application programmers should be
- careful to maintain the PGresult abstraction.
- Use the accessor functions below to get at the contents of
- PGresult. Avoid directly referencing the
- fields of the PGresult structure because they
- are subject to change in the future.
-
-
-
-
- PQresultStatus
-
-
-
-
-
- Returns the result status of the command.
-
- ExecStatusType PQresultStatus(const PGresult *res);
-
-
-
- PQresultStatus can return one of the following values:
-
-
-
- PGRES_EMPTY_QUERY
-
- The string sent to the server was empty.
-
-
-
-
-
- PGRES_COMMAND_OK
-
- Successful completion of a command returning no data.
-
-
-
-
-
- PGRES_TUPLES_OK
-
- Successful completion of a command returning data (such as
- a SELECT or SHOW).
-
-
-
-
-
- PGRES_COPY_OUT
-
- Copy Out (from server) data transfer started.
-
-
-
-
-
- PGRES_COPY_IN
-
- Copy In (to server) data transfer started.
-
-
-
-
-
- PGRES_BAD_RESPONSE
-
- The server's response was not understood.
-
-
-
-
-
- PGRES_NONFATAL_ERROR
-
- A nonfatal error (a notice or warning) occurred.
-
-
-
-
-
- PGRES_FATAL_ERROR
-
- A fatal error occurred.
-
-
-
-
-
- If the result status is PGRES_TUPLES_OK, then
- the functions described below can be used to retrieve the rows
- returned by the query. Note that a SELECT
- command that happens to retrieve zero rows still shows
- PGRES_TUPLES_OK.
- PGRES_COMMAND_OK is for commands that can never
- return rows (INSERT, UPDATE,
- etc.). A response of PGRES_EMPTY_QUERY might
- indicate a bug in the client software.
-
-
- A result of status PGRES_NONFATAL_ERROR will
- never be returned directly by PQexec or other
- query execution functions; results of this kind are instead passed
- to the notice processor (see
- linkend="libpq-notice-processing">).
-
-
-
-
-
-
- PQresStatus
-
-
-
-
-
- Converts the enumerated type returned by
- PQresultStatus into a string constant describing the
- status code. The caller should not free the result.
-
-
- char *PQresStatus(ExecStatusType status);
-
-
-
-
-
-
-
- PQresultErrorMessage
-
-
-
-
-
- Returns the error message associated with the command, or an empty string
- if there was no error.
-
- char *PQresultErrorMessage(const PGresult *res);
-
- If there was an error, the returned string will include a trailing
- newline. The caller should not free the result directly. It will
- be freed when the associated PGresult handle is
- passed to PQclear.
-
-
- Immediately following a PQexec or
- PQgetResult call,
- PQerrorMessage (on the connection) will return
- the same string as PQresultErrorMessage (on
- the result). However, a PGresult will
- retain its error message until destroyed, whereas the connection's
- error message will change when subsequent operations are done.
- Use PQresultErrorMessage when you want to
- know the status associated with a particular
- PGresult; use
- PQerrorMessage when you want to know the
- status from the latest operation on the connection.
-
-
-
-
-
-
PQresultErrorFieldPQresultErrorField-
- Returns an individual field of an error report.
-
- char *PQresultErrorField(const PGresult *res, int fieldcode);
-
-
fieldcode is an error field identifier; see the symbols- listed below. NULL is returned if the
- PGresult is not an error or warning result,
- or does not include the specified field. Field values will normally
- not include a trailing newline. The caller should not free the
- result directly. It will be freed when the
- associated PGresult handle is passed to
- PQclear.
-
-
- The following field codes are available:
-
-
- PG_DIAG_SEVERITY
-
- The severity; the field contents are ERROR,
- FATAL, or PANIC (in an error message),
- or WARNING, NOTICE, DEBUG,
- INFO, or LOG (in a notice message), or
- a localized translation of one of these. Always present.
-
-
-
-
-
-
- libpq
-
- PG_DIAG_SQLSTATE
-
- The SQLSTATE code for the error. The SQLSTATE code identifies
- the type of error that has occurred; it can be used by
- front-end applications to perform specific operations (such
- as error handling) in response to a particular database error.
- For a list of the possible SQLSTATE codes, see
- linkend="errcodes-appendix">. This field is not localizable,
- and is always present.
-
-
-
-
-
- PG_DIAG_MESSAGE_PRIMARY
-
- The primary human-readable error message (typically one line).
- Always present.
-
-
-
-
-
- PG_DIAG_MESSAGE_DETAIL
-
- Detail: an optional secondary error message carrying more
- detail about the problem. Might run to multiple lines.
-
-
-
-
-
- PG_DIAG_MESSAGE_HINT
-
- Hint: an optional suggestion what to do about the problem.
- This is intended to differ from detail in that it offers advice
- (potentially inappropriate) rather than hard facts. Might
- run to multiple lines.
-
-
-
-
-
- PG_DIAG_STATEMENT_POSITION
-
+ PQdescribePortal allows an application to obtain
+ information about a previously created portal.
+ (
libpq does not provide any direct access to+ portals, but you can use this function to inspect the properties
+ of a cursor created with a DECLARE CURSOR SQL command.)
+ PQdescribePortal is supported only in protocol 3.0
+ and later connections; it will fail when using protocol 2.0.
+
+
+
portalName can be "" or NULL to reference+ the unnamed portal, otherwise it must be the name of an existing
+ portal. On success, a PGresult with status
+ PGRES_COMMAND_OK is returned. The functions
+ PQnfields, PQfname,
+ PQftype, etc can be applied to the
+ PGresult to obtain information about the result
+ columns (if any) of the portal.
+
+
+
+
+
+
+ structure encapsulates the result returned by the server.
+
libpq application programmers should be
+ careful to maintain the PGresult abstraction.
+ Use the accessor functions below to get at the contents of
+ PGresult. Avoid directly referencing the
+ fields of the PGresult structure because they
+ are subject to change in the future.
+
+
+
+
+ PQresultStatus
+
+
+
+
+
+ Returns the result status of the command.
+
+ ExecStatusType PQresultStatus(const PGresult *res);
+
+
+
+ PQresultStatus can return one of the following values:
+
+
+
+ PGRES_EMPTY_QUERY
+
+ The string sent to the server was empty.
+
+
+
+
+
+ PGRES_COMMAND_OK
+
+ Successful completion of a command returning no data.
+
+
+
+
+
+ PGRES_TUPLES_OK
+
+ Successful completion of a command returning data (such as
+ a SELECT or SHOW).
+
+
+
+
+
+ PGRES_COPY_OUT
+
+ Copy Out (from server) data transfer started.
+
+
+
+
+
+ PGRES_COPY_IN
+
+ Copy In (to server) data transfer started.
+
+
+
+
+
+ PGRES_BAD_RESPONSE
+
+ The server's response was not understood.
+
+
+
+
+
+ PGRES_NONFATAL_ERROR
+
+ A nonfatal error (a notice or warning) occurred.
+
+
+
+
+
+ PGRES_FATAL_ERROR
+
+ A fatal error occurred.
+
+
+
+
+
+ If the result status is PGRES_TUPLES_OK, then
+ the functions described below can be used to retrieve the rows
+ returned by the query. Note that a SELECT
+ command that happens to retrieve zero rows still shows
+ PGRES_TUPLES_OK.
+ PGRES_COMMAND_OK is for commands that can never
+ return rows (INSERT, UPDATE,
+ etc.). A response of PGRES_EMPTY_QUERY might
+ indicate a bug in the client software.
+
+
+ A result of status PGRES_NONFATAL_ERROR will
+ never be returned directly by PQexec or other
+ query execution functions; results of this kind are instead passed
+ to the notice processor (see
+ linkend="libpq-notice-processing">).
+
+
+
+
+
+
+ PQresStatus
+
+
+
+
+
+ Converts the enumerated type returned by
+ PQresultStatus into a string constant describing the
+ status code. The caller should not free the result.
+
+
+ char *PQresStatus(ExecStatusType status);
+
+
+
+
+
+
+
+ PQresultErrorMessage
+
+
+
+
+
+ Returns the error message associated with the command, or an empty string
+ if there was no error.
+
+ char *PQresultErrorMessage(const PGresult *res);
+
+ If there was an error, the returned string will include a trailing
+ newline. The caller should not free the result directly. It will
+ be freed when the associated PGresult handle is
+ passed to PQclear.
+
+
+ Immediately following a PQexec or
+ PQgetResult call,
+ PQerrorMessage (on the connection) will return
+ the same string as PQresultErrorMessage (on
+ the result). However, a PGresult will
+ retain its error message until destroyed, whereas the connection's
+ error message will change when subsequent operations are done.
+ Use PQresultErrorMessage when you want to
+ know the status associated with a particular
+ PGresult; use
+ PQerrorMessage when you want to know the
+ status from the latest operation on the connection.
+
+
+
+
+
+
PQresultErrorFieldPQresultErrorField+
+ Returns an individual field of an error report.
+
+ char *PQresultErrorField(const PGresult *res, int fieldcode);
+
+
fieldcode is an error field identifier; see the symbols+ listed below. NULL is returned if the
+ PGresult is not an error or warning result,
+ or does not include the specified field. Field values will normally
+ not include a trailing newline. The caller should not free the
+ result directly. It will be freed when the
+ associated PGresult handle is passed to
+ PQclear.
+
+
+ The following field codes are available:
+
+
+ PG_DIAG_SEVERITY
+
+ The severity; the field contents are ERROR,
+ FATAL, or PANIC (in an error message),
+ or WARNING, NOTICE, DEBUG,
+ INFO, or LOG (in a notice message), or
+ a localized translation of one of these. Always present.
+
+
+
+
+
+
+ libpq
+
+ PG_DIAG_SQLSTATE
+
+ The SQLSTATE code for the error. The SQLSTATE code identifies
+ the type of error that has occurred; it can be used by
+ front-end applications to perform specific operations (such
+ as error handling) in response to a particular database error.
+ For a list of the possible SQLSTATE codes, see
+ linkend="errcodes-appendix">. This field is not localizable,
+ and is always present.
+
+
+
+
+
+ PG_DIAG_MESSAGE_PRIMARY
+
+ The primary human-readable error message (typically one line).
+ Always present.
+
+
+
+
+
+ PG_DIAG_MESSAGE_DETAIL
+
+ Detail: an optional secondary error message carrying more
+ detail about the problem. Might run to multiple lines.
+
+
+
+
+
+ PG_DIAG_MESSAGE_HINT
+
+ Hint: an optional suggestion what to do about the problem.
+ This is intended to differ from detail in that it offers advice
+ (potentially inappropriate) rather than hard facts. Might
+ run to multiple lines.
+
+
+
+
+
+ PG_DIAG_STATEMENT_POSITION
+
A string containing a decimal integer indicating an error cursor
position as an index into the original statement string. The
-
+
PG_DIAG_INTERNAL_POSITION
-
+
PG_DIAG_INTERNAL_QUERY
-
+
PG_DIAG_CONTEXT
-
+
PG_DIAG_SOURCE_FILE
-
+
PG_DIAG_SOURCE_LINE
-
+
PG_DIAG_SOURCE_FUNCTION
-
+
The client is responsible for formatting displayed information to meet
its needs; in particular it should break long lines as needed.
Newline characters appearing in the error message fields should be
treated as paragraph breaks, not line breaks.
-
+
Errors generated internally by
libpq will
have severity and primary message, but typically no other fields.
Errors returned by a pre-3.0-protocol server will include severity and
primary message, and sometimes a detail message, but no other fields.
-
+
Note that error fields are only available from
PGresult objects, not
-
+
void PQclear(PGresult *res);
-
+
You can keep a PGresult object around for
as long as you need it; it does not go away when you issue a new
-
+
PQmakeEmptyPGresult
PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
-
+
This is
libpq's internal function to allocate and initialize an empty PGresult object. This
-
+
Retrieving Query Result Information
-
+
These functions are used to extract information from a
PGresult object that represents a successful
would provide, but it has zero rows. For objects with other status values,
these functions will act as though the result has zero rows and zero columns.
-
+
-
+
PQnfields
-
+
PQfname
int column_number);
-
+
NULL is returned if the column number is out of range.
-
+
PQfnumber
const char *column_name);
-
+
-1 is returned if the given name does not match any column.
-
+
The given name is treated like an identifier in an SQL command,
that is, it is downcased unless double-quoted. For example, given
-
+
PQftable
int column_number);
-
+
InvalidOid is returned if the column number is out of range,
or if the specified column is not a simple reference to a table column,
-
+
PQftablecol
int column_number);
-
+
Zero is returned if the column number is out of range, or if the
specified column is not a simple reference to a table column, or
int column_number);
-
+
Format code zero indicates textual data representation, while format
code one indicates binary representation. (Other codes are reserved
-
+
PQftype
int column_number);
-
+
You can query the system table pg_type to
obtain the names and properties of the various data types. The
-
+
PQfmod
int column_number);
-
+
The interpretation of modifier values is type-specific; they
typically indicate precision or size limits. The value -1 is
-
+
PQfsize
int column_number);
-
+
PQfsize returns the space allocated for this column
in a database row, in other words the size of the server's
-
+
PQbinaryTuples
- Returns 1 if the PGresult contains binary data
- and 0 if it contains text data.
-
- int PQbinaryTuples(const PGresult *res);
-
-
-
- This function is deprecated (except for its use in connection with
- COPY), because it is possible for a single
- PGresult to contain text data in some columns and
- binary data in others. PQfformat is preferred.
- PQbinaryTuples returns 1 only if all columns of the
- result are binary (format 1).
-
-
-
-
-
-
- PQgetvalue
-
-
-
+ Returns 1 if the PGresult contains binary data
+ and 0 if it contains text data.
+
+ int PQbinaryTuples(const PGresult *res);
+
+
-
- Returns a single field value of one row of a
- PGresult. Row and column numbers start
- at 0. The caller should not free the result directly. It will
- be freed when the associated PGresult handle is
- passed to PQclear.
-
- char *PQgetvalue(const PGresult *res,
- int row_number,
- int column_number);
-
-
-
- For data in text format, the value returned by
- PQgetvalue is a null-terminated character
- string representation of the field value. For data in binary
- format, the value is in the binary representation determined by
- the data type's typsend and typreceive
- functions. (The value is actually followed by a zero byte in
- this case too, but that is not ordinarily useful, since the
- value is likely to contain embedded nulls.)
-
-
- An empty string is returned if the field value is null. See
- PQgetisnull to distinguish null values from
- empty-string values.
-
-
- The pointer returned by PQgetvalue points
- to storage that is part of the PGresult
- structure. One should not modify the data it points to, and one
- must explicitly copy the data into other storage if it is to be
- used past the lifetime of the PGresult
- structure itself.
-
-
-
-
-
-
- PQgetisnull
-
-
-
- in libpq
-
-
-
-
- Tests a field for a null value. Row and column numbers start
- at 0.
-
- int PQgetisnull(const PGresult *res,
- int row_number,
- int column_number);
-
-
-
- This function returns 1 if the field is null and 0 if it
- contains a non-null value. (Note that
- PQgetvalue will return an empty string,
- not a null pointer, for a null field.)
-
-
-
+ This function is deprecated (except for its use in connection with
+ COPY), because it is possible for a single
+ PGresult to contain text data in some columns and
+ binary data in others. PQfformat is preferred.
+ PQbinaryTuples returns 1 only if all columns of the
+ result are binary (format 1).
+
+
+
+
+
+
+ PQgetvalue
+
+
+
+
+
+ Returns a single field value of one row of a
+ PGresult. Row and column numbers start
+ at 0. The caller should not free the result directly. It will
+ be freed when the associated PGresult handle is
+ passed to PQclear.
+
+ char *PQgetvalue(const PGresult *res,
+ int row_number,
+ int column_number);
+
+
+
+ For data in text format, the value returned by
+ PQgetvalue is a null-terminated character
+ string representation of the field value. For data in binary
+ format, the value is in the binary representation determined by
+ the data type's typsend and typreceive
+ functions. (The value is actually followed by a zero byte in
+ this case too, but that is not ordinarily useful, since the
+ value is likely to contain embedded nulls.)
+
+
+ An empty string is returned if the field value is null. See
+ PQgetisnull to distinguish null values from
+ empty-string values.
+
+
+ The pointer returned by PQgetvalue points
+ to storage that is part of the PGresult
+ structure. One should not modify the data it points to, and one
+ must explicitly copy the data into other storage if it is to be
+ used past the lifetime of the PGresult
+ structure itself.
+
+
+
+
+
+
+ PQgetisnull
+
+
+
+ in libpq
+
+
+
+
+ Tests a field for a null value. Row and column numbers start
+ at 0.
+
+ int PQgetisnull(const PGresult *res,
+ int row_number,
+ int column_number);
+
+
+
+ This function returns 1 if the field is null and 0 if it
+ contains a non-null value. (Note that
+ PQgetvalue will return an empty string,
+ not a null pointer, for a null field.)
+
+
+
+
+
+
+ PQgetlength
+
+
+
+
+ Returns the actual length of a field value in bytes. Row and
+ column numbers start at 0.
+
+ int PQgetlength(const PGresult *res,
+ int row_number,
+ int column_number);
+
+
-
-
- PQgetlength
-
-
-
-
- Returns the actual length of a field value in bytes. Row and
- column numbers start at 0.
-
- int PQgetlength(const PGresult *res,
- int row_number,
- int column_number);
-
-
+ This is the actual data length for the particular data value,
+ that is, the size of the object pointed to by
+ PQgetvalue. For text data format this is
+ the same as strlen(). For binary format this is
+ essential information. Note that one should not
+ rely on PQfsize to obtain the actual data
+ length.
+
+
+
- This is the actual data length for the particular data value,
- that is, the size of the object pointed to by
- PQgetvalue. For text data format this is
- the same as strlen(). For binary format this is
- essential information. Note that one should not
- rely on PQfsize to obtain the actual data
- length.
-
-
-
+
+
+ PQnparams
+
+
+
-
-
- PQnparams
-
-
-
-
-
- Returns the number of parameters of a prepared statement.
-
- int PQnparams(const PGresult *res);
-
-
+
+ Returns the number of parameters of a prepared statement.
+
+ int PQnparams(const PGresult *res);
+
+
- This function is only useful when inspecting the result of
- PQdescribePrepared. For other types of queries it
- will return zero.
-
-
-
+ This function is only useful when inspecting the result of
+ PQdescribePrepared. For other types of queries it
+ will return zero.
+
+
+
-
-
- PQparamtype
-
-
-
-
- Returns the data type of the indicated statement parameter.
- Parameter numbers start at 0.
-
- Oid PQparamtype(const PGresult *res, int param_number);
-
-
-
- This function is only useful when inspecting the result of
- PQdescribePrepared. For other types of queries it
- will return zero.
-
-
-
-
-
-
- PQprint
-
-
-
-
-
- Prints out all the rows and, optionally, the column names to
- the specified output stream.
-
+
+
+ PQparamtype
+
+
+
+
+
+ Returns the data type of the indicated statement parameter.
+ Parameter numbers start at 0.
+
+ Oid PQparamtype(const PGresult *res, int param_number);
+
+
+
+ This function is only useful when inspecting the result of
+ PQdescribePrepared. For other types of queries it
+ will return zero.
+
+
+
+
+
+
+ PQprint
+
+
+
+
+
+ Prints out all the rows and, optionally, the column names to
+ the specified output stream.
+
void PQprint(FILE *fout, /* output stream */
const PGresult *res,
const PQprintOpt *po);
} PQprintOpt;
-
+
This function was formerly used by
psql to print query results, but this is no longer the case. Note
-
+
Retrieving Result Information for Other Commands
-
+
These functions are used to extract information from
PGresult objects that are not
SELECT results.
-
+
-
+
PQcmdTuples
char *PQcmdTuples(PGresult *res);
-
+
This function returns a string containing the number of rows
affected by the
SQL statement that generated the
-
+
PQoidValue
-
+
PQoidStatus
char *PQoidStatus(const PGresult *res);
-
+
This function is deprecated in favor of
PQoidValue. It is not thread-safe.
-
+
-
+
Escaping Strings for Inclusion in SQL Commands
-
+
in libpq
-
+
PQescapeStringConn escapes a string for use within an SQL
command. This is useful when inserting data values as literal constants
be escaped to prevent them from being interpreted specially by the SQL parser.
PQescapeStringConn performs this operation.
-
+
It is especially important to do proper escaping when handling strings that
SQL commands are fed to your database.
-
+
Note that it is not necessary nor correct to do escaping when a data
value is passed as a separate parameter in PQexecParams or
its sibling routines.
-
+
size_t PQescapeStringConn (PGconn *conn,
char *to, const char *from, size_t length,
int *error);
-
+
PQescapeStringConn writes an escaped version of the
from string to the to buffer, escaping
PQescapeStringConn returns the number of bytes written
to
to, not including the terminating zero byte.
-
+
size_t PQescapeString (char *to, const char *from, size_t length);
-
+
PQescapeString is an older, deprecated version of
PQescapeStringConn; the difference is that it does
PQescapeStringConn.
-
-
+
+
Escaping Binary Strings for Inclusion in SQL Commands
-
+
in libpq
-
+
size_t *to_length);
-
+
Certain byte values must be escaped (but all
byte values can be escaped) when used as part
information. PQescapeByteaConn performs this
operation, escaping only the minimally required bytes.
-
+
The
from parameter points to the first
byte of the string that is to be escaped, and the
escaped string length. This result string length includes the terminating
zero byte of the result.
-
+
PQescapeByteaConn returns an escaped version of the
from parameter binary string in memory
surround
PostgreSQL string literals are
not part of the result string.
-
+
On error, a NULL pointer is returned, and a suitable error message
is stored in the
conn object. Currently, the only
-
+
PQescapeBytea
size_t *to_length);
-
+
The only difference from PQescapeByteaConn is that
PQescapeBytea does not take a PGconn
it might give the wrong results. Also, it has no
way to return an error message on failure.
-
+
PQescapeBytea can be used safely in single-threaded
client programs that work with only one
PostgreSQL
-
+
PQunescapeBytea
— the reverse of PQescapeBytea. This
is needed when retrieving bytea data in text format,
but not when retrieving it in binary format.
-
+
unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
-
+
The
from parameter points to a string
such as might be returned by PQgetvalue when applied
the buffer in
to_length. The result must be
freed using PQfreemem when it is no longer needed.
-
+
This conversion is not exactly the inverse of
PQescapeBytea, because the string is not expected
-
+
PQfreemem
void PQfreemem(void *ptr);
-
+
Frees memory allocated by
libpq, particularly PQescapeByteaConn,
-
+
-
+
Asynchronous Command Processing
-
+
-
+
The PQexec function is adequate for submitting
commands in normal, synchronous applications. It has a couple of
deficiencies, however, that can be of importance to some users:
-
+
from a signal handler, but not otherwise.)
-
+
PQexec can return only one
-
+
Applications that do not like these limitations can instead use the
underlying functions that PQexec is built from:
PQdescribePrepared, and
PQdescribePortal
respectively.
-
+
int PQsendQuery(PGconn *conn, const char *command);
-
+
After successfully calling PQsendQuery, call
PQgetResult one or more times to obtain the
results. PQsendQuery cannot be called again
-
+
PQsendQueryParams
const int *paramFormats,
int resultFormat);
-
+
This is equivalent to PQsendQuery except that
query parameters can be specified separately from the query string.
The function's parameters are handled identically to
-
+
PQsendPrepare
int nParams,
const Oid *paramTypes);
-
+
This is an asynchronous version of PQprepare: it
returns 1 if it was able to dispatch the request, and 0 if not.
After a successful call, call PQgetResult to
-
+
PQsendQueryPrepared
const int *paramFormats,
int resultFormat);
-
+
This is similar to PQsendQueryParams, but
the command to be executed is specified by naming a
previously-prepared statement, instead of giving a query string.
-
+
PQsendDescribePrepared
int PQsendDescribePrepared(PGconn *conn, const char *stmtName);
-
+
This is an asynchronous version of PQdescribePrepared:
it returns 1 if it was able to dispatch the request, and 0 if not.
After a successful call, call PQgetResult to
-
+
PQsendDescribePortal
int PQsendDescribePortal(PGconn *conn, const char *portalName);
-
+
This is an asynchronous version of PQdescribePortal:
it returns 1 if it was able to dispatch the request, and 0 if not.
After a successful call, call PQgetResult to
-
+
PQgetResult
PGresult *PQgetResult(PGconn *conn);
-
+
PQgetResult must be called repeatedly until
it returns a null pointer, indicating that the command is done.
-
+
Using PQsendQuery and
PQgetResult solves one of
will still cause the client to block until the server completes the
next
SQL command. This can be avoided by proper
use of two more functions:
-
+
int PQconsumeInput(PGconn *conn);
-
+
PQconsumeInput normally returns 1 indicating
no error
, but returns 0 if there was some kind of
-
+
PQisBusy
int PQisBusy(PGconn *conn);
-
+
PQisBusy will not itself attempt to read data
from the server; therefore PQconsumeInput
-
+
A typical application using these functions will have a main loop that
uses select() or poll() to wait for
to detect
NOTIFY messages (see
linkend="libpq-notify">).
-
+
A client that uses
PQsendQuery/PQgetResult
simply cause the command to terminate sooner than it would have
otherwise.
-
+
By using the functions described above, it is possible to avoid
blocking while waiting for input from the database server. However,
however.) To prevent this possibility and achieve completely
nonblocking database operation, the following additional functions
can be used.
-
+
int PQsetnonblocking(PGconn *conn, int arg);
-
+
Sets the state of the connection to nonblocking if
-
+
PQisnonblocking
int PQisnonblocking(const PGconn *conn);
-
+
Returns 1 if the connection is set to nonblocking mode and 0 if
blocking.
-
+
PQflush
-
+
After sending any command or data on a nonblocking connection, call
PQflush. If it returns 1, wait for the socket
PQflush returns 0, wait for the socket to be
read-ready and then read the response as described above.
-
+
-
+
Cancelling Queries in Progress
-
+
SQL command
-
+
A client application can request cancellation of a command that is
still being processed by the server, using the functions described in
this section.
-
+
PGcancel *PQgetCancel(PGconn *conn);
-
+
PQgetCancel creates a
void PQfreeCancel(PGcancel *cancel);
-
+
PQfreeCancel frees a data object previously created
by PQgetCancel.
-
+
PQcancel
int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
-
+
The return value is 1 if the cancel request was successfully
dispatched and 0 if not. If not,
errbuf is filled must be a char array of size
errbufsize (the recommended size is 256 bytes).
-
+
Successful dispatch is no guarantee that the request will have
any effect, however. If the cancellation is effective, the current
processing the command), then there will be no visible result at
all.
-
+
PQcancel can safely be invoked from a signal
handler, if the
errbuf is a local variable in the
-
+
int PQrequestCancel(PGconn *conn);
-
+
PQrequestCancel is a deprecated variant of
PQcancel. It operates directly on the
-
+
-
+
The Fast-Path Interface
-
+
-
+
PostgreSQL provides a fast-path interface
to send simple function calls to the server.
-
+
This interface is somewhat obsolete, as one can achieve similar
fast-path function call.
-
+
requests execution of a server function via the fast-path interface:
int result_is_int,
const PQArgBlock *args,
int nargs);
-
+
typedef struct {
int len;
int isint;
} PQArgBlock;
-
+
The
fnid argument is the OID of the function to be executed.
args and nargs define the When
result_is_int is 0, the binary-format byte string sent by the server is returned unmodified.
-
+
PQfn always returns a valid
PGresult pointer. The result status should be
freeing the PGresult with
PQclear when it is no longer needed.
-
+
Note that it is not possible to handle null arguments, null results,
nor set-valued results when using this interface.
-
+
-
+
Asynchronous Notification
-
+
in libpq
-
+
PostgreSQL offers asynchronous notification
via the LISTEN and NOTIFY
associated table, but it is not necessary for there to be any associated
table.
-
+
libpq applications submit
LISTEN and UNLISTEN commands as
messages can subsequently be detected by calling
-
+
The function PQnotifies
returns the next notification from a list of unhandled
removed from the list of notifications.
PGnotify *PQnotifies(PGconn *conn);
-
+
typedef struct pgNotify {
char *relname; /* notification condition name */
int be_pid; /* process ID of notifying server process */
extra field is unused and will always point
to an empty string.)
-
+
gives a sample program that illustrates
the use of asynchronous notification.
-
+
PQnotifies does not actually read data from the
server; it just returns messages previously absorbed by another
PQexec. While this still works, it is deprecated
as a waste of processing power.
-
+
A better way to check for NOTIFY messages when you have no
useful commands to execute is to call
PQgetResult or PQexec, to
see if any notifications came in during the processing of the command.
-
+
-
+
Functions Associated with the <command>COPY</command> Command
-
+
with libpq
-
+
The COPY command in
PostgreSQL has options to read from or write
The functions described in this section allow applications to take
advantage of this capability by supplying or consuming copied data.
-
+
The overall process is that the application first issues the SQL
COPY command via PQexec or one
commands using the same connection while the COPY
operation is in progress.)
-
+
If a COPY command is issued via
PQexec in a string that could contain additional
NULL is it certain that the PQexec
command string is done and it is safe to issue more commands.
-
+
The functions of this section should be executed only after obtaining
a result status of PGRES_COPY_OUT or
PGRES_COPY_IN from PQexec or
PQgetResult.
-
+
A PGresult object bearing one of these status values
carries some additional data about the COPY operation
that is starting. This additional data is available using functions
that are also used in connection with query results:
-
+
-
+
PQbinaryTuples
-
+
PQfformat
-
+
These additional data values are only available when using protocol
3.0. When using protocol 2.0, all these functions will return 0.
-
+
Functions for Sending <command>COPY</command> Data
-
+
These functions are used to send data during COPY FROM
STDIN. They will fail if called when the connection is not in
COPY_IN state.
-
+
int nbytes);
-
+
Transmits the COPY data in the specified
buffer, of length nbytes, to the server.
the return value is -1. If the value is zero, wait for write-ready
and try again.)
-
+
The application can divide the COPY data stream
into buffer loads of any convenient size. Buffer-load boundaries
-
+
PQputCopyEnd
const char *errormsg);
-
+
Ends the COPY_IN operation successfully if
to force failure does not work when using pre-3.0-protocol
connections.)
-
+
The result is 1 if the termination data was sent, zero if it was
not sent because the attempt would block (this case is only possible
details if the return value is -1. If the value is zero, wait for
write-ready and try again.)
-
+
After successfully calling PQputCopyEnd, call
PQgetResult to obtain the final result status of the
-
+
-
+
Functions for Receiving <command>COPY</command> Data
-
+
These functions are used to receive data during COPY TO
STDOUT. They will fail if called when the connection is not in
COPY_OUT state.
-
+
int async);
-
+
Attempts to obtain another row of data from the server during a
COPY. Data is always returned one data row at
buffer must be freed using PQfreemem when no longer
needed.
-
+
When a row is successfully returned, the return value is the number
of data bytes in the row (this will always be greater than zero).
COPY is done. A result of -2 indicates that an
error occurred (consult PQerrorMessage for the reason).
-
+
When
async is true (not zero), PQgetCopyData will not block waiting for input; it
false (zero), PQgetCopyData will block until data is
available or the operation completes.
-
+
After PQgetCopyData returns -1, call
PQgetResult to obtain the final result status of the
-
+
-
+
Obsolete Functions for <command>COPY</command>
-
+
These functions represent older methods of handling COPY.
Although they still work, they are deprecated due to poor error handling,
inconvenient methods of detecting end-of-data, and lack of support for binary
or nonblocking transfers.
-
+
int length);
-
+
This function copies up to
length-1 characters into the buffer and converts the terminating newline into a zero byte.
-
+
PQgetlineAsync
int bufsize);
-
+
This function is similar to PQgetline, but it can be used
by applications
-
+
PQputline
const char *string);
-
+
The COPY data stream sent by a series of calls
to PQputline has the same format as that
PQputline call; it is okay to send a partial
line or multiple lines per call.
-
+
Before
PostgreSQL protocol 3.0, it was necessary
-
+
PQputnbytes
int nbytes);
-
+
This is exactly like PQputline, except that the data
buffer need not be null-terminated since the number of bytes to send is
-
+
PQendcopy
nonzero otherwise. (Use PQerrorMessage to
retrieve details if the return value is nonzero.)
-
+
When using PQgetResult, the application should
respond to a PGRES_COPY_OUT result by executing
ensure that a COPY command embedded in a series
of
SQL commands will be executed correctly.
-
+
Older applications are likely to submit a COPY
via PQexec and assume that the transaction
-
+
-
+
-
+
Control Functions
-
+
These functions control miscellaneous details of
libpq's behavior.
-
+
-
- Determines the verbosity of messages returned by
- PQerrorMessage and PQresultErrorMessage.
-
+
+ Determines the verbosity of messages returned by
+ PQerrorMessage and PQresultErrorMessage.
+
typedef enum {
PQERRORS_TERSE,
PQERRORS_DEFAULT,
PQERRORS_VERBOSE
} PGVerbosity;
-
+
PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
-
-
- PQsetErrorVerbosity sets the verbosity mode, returning
- the connection's previous setting. In TERSE mode,
- returned messages include severity, primary text, and position only;
- this will normally fit on a single line. The default mode produces
- messages that include the above plus any detail, hint, or context
- fields (these might span multiple lines). The VERBOSE
- mode includes all available fields. Changing the verbosity does not
- affect the messages available from already-existing
- PGresult objects, only subsequently-created ones.
-
-
-
-
-
-
- PQtrace
-
-
-
-
-
- Enables tracing of the client/server communication to a debugging file stream.
-
- void PQtrace(PGconn *conn, FILE *stream);
-
-
+
-
+ PQsetErrorVerbosity sets the verbosity mode, returning
+ the connection's previous setting. In TERSE mode,
+ returned messages include severity, primary text, and position only;
+ this will normally fit on a single line. The default mode produces
+ messages that include the above plus any detail, hint, or context
+ fields (these might span multiple lines). The VERBOSE
+ mode includes all available fields. Changing the verbosity does not
+ affect the messages available from already-existing
+ PGresult objects, only subsequently-created ones.
+
+
+
+
+
+
+ PQtrace
+
+
+
+
+
- On Windows, if the
libpq library and an application are- compiled with different flags, this function call will crash the
- application because the internal representation of the FILE
- pointers differ. Specifically, multithreaded/single-threaded,
- release/debug, and static/dynamic flags should be the same for the
- library and all applications using that library.
+ Enables tracing of the client/server communication to a debugging file stream.
+
+ void PQtrace(PGconn *conn, FILE *stream);
+
-
-
-
-
-
-
-
- PQuntrace
-
-
-
-
-
- Disables tracing started by PQtrace.
-
- void PQuntrace(PGconn *conn);
-
-
-
-
-
-
+
+
+ On Windows, if the
libpq library and an application are+ compiled with different flags, this function call will crash the
+ application because the internal representation of the FILE
+ pointers differ. Specifically, multithreaded/single-threaded,
+ release/debug, and static/dynamic flags should be the same for the
+ library and all applications using that library.
+
+
+
+
+
+
+
+
+ PQuntrace
+
+
+
+
+
+ Disables tracing started by PQtrace.
+
+ void PQuntrace(PGconn *conn);
+
+
+
+
+
+
-
+
Miscellaneous Functions
-
+
As always, there are some functions that just don't fit anywhere.
-
+
-
+
-
+
Notice Processing
-
+
in libpq
-
+
Notice and warning messages generated by the server are not returned
by the query execution functions, since they do not imply failure of
stderr, but the application can override this
behavior by supplying its own handling function.
-
+
For historical reasons, there are two levels of notice handling, called
the notice receiver and notice processor. The default behavior is for
its own notice receiver will typically ignore the notice processor
layer and just do all the work in the notice receiver.
-
+
The function PQsetNoticeReceiver
processor
PQsetNoticeProcessor sets or examines the current notice processor.
-
+
typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
-
+
PQnoticeReceiver
PQsetNoticeReceiver(PGconn *conn,
PQnoticeReceiver proc,
void *arg);
-
+
typedef void (*PQnoticeProcessor) (void *arg, const char *message);
-
+
PQnoticeProcessor
PQsetNoticeProcessor(PGconn *conn,
PQnoticeProcessor proc,
void *arg);
-
+
Each of these functions returns the previous notice receiver or
processor function pointer, and sets the new value. If you supply a
null function pointer, no action is taken, but the current pointer is
returned.
-
+
When a notice or warning message is received from the server, or
generated internally by
libpq, the notice
passed. (This pointer can be used to access application-specific state
if needed.)
-
+
The default notice receiver simply extracts the message (using
PQresultErrorMessage) and passes it to the notice
processor.
-
+
The notice processor is responsible for handling a notice or warning
message given in text form. It is passed the string text of the message
one passed to PQsetNoticeProcessor. (This pointer
can be used to access application-specific state if needed.)
-
+
The default notice processor is simply:
}
-
+
Once you have set a notice receiver or processor, you should expect
that that function could be called as long as either the
into the PGresult for possible use by functions like
PQgetvalue.
-
+
-
+
Environment Variables
-
+
-
+
The following environment variables can be used to select default
connection parameter values, which will be used by
PQsetdb if no value is directly specified by the calling
code. These are useful to avoid hard-coding database connection
information into simple client applications, for example.
-
+
-
+
PGDATABASE sets the
(see ).
-
+
of setting all the parameters.
-
+
selected by the server.
-
+
-
+
connection.
-
+
if
PostgreSQL is compiled with SSL support.
-
+
file.
-
+
when authenticating with Kerberos 5 or GSSAPI.
-
+
authentication.
-
+
-
+
The following environment variables can be used to specify default
behavior for each
PostgreSQL session. (See
and
commands for ways to set default behavior on a per-user or per-database
basis.)
-
+
....)
-
+
SET timezone TO ....)
-
+
....)
-
+
-
+
Refer to the
SQL command
endterm="sql-set-title"> for information on correct values for these
environment variables.
-
+
The following environment variables determine internal behavior of
libpq; they override compiled-in defaults.
-
+
pg_service.conf file.
-
+
-
+
-
-
+
+
The Password File
-
+
-
+
The file .pgpass in a user's home directory or the
file referenced by PGPASSFILE can contain passwords to
%APPDATA% refers to the Application Data subdirectory in
the user's profile).
-
+
This file should contain lines of the following format:
or the default socket directory) connections coming from the local
machine.
-
+
On Unix systems, the permissions on .pgpass must
disallow any access to world or group; achieve this by the command
no special permissions check is made.
-
-
+
+
The Connection Service File
-
+
-
+
The connection service file allows libpq connection parameters to be
associated with a single service name. That service name can then be
PGSYSCONFDIR environment variable.
-
-
+
+
LDAP Lookup of Connection Parameters
-
+
LDAP connection parameter lookup
-
+
If
libpq has been compiled with LDAP support (option
for configure)
The advantage is that if the connection parameters for a database change,
the connection information doesn't have to be updated on all client machines.
-
+
LDAP connection parameter lookup uses the connection service file
pg_service.conf (see
localhost and port
defaults to 389.
-
+
Processing of pg_service.conf is terminated after
a successful LDAP lookup, but is continued if the LDAP server cannot
rather get an error message in this case, add a syntactically incorrect
line after the LDAP URL.
-
+
A sample LDAP entry that has been created with the LDIF file
-
-
+
+
SSL Support
-
+
-
+
PostgreSQL has native support for using SSL
connections to encrypt client/server communications for increased
security. See for details about the server-side
-
+
libpq reads the system-wide
OpenSSL configuration file. By default, this
OPENSSL_CONF to the name of the desired configuration
file.
-
+
If the server demands a client certificate,
libpq will send the certificate stored in
-
-
+
+
Behavior in Threaded Programs
-
+
with libpq
-
+
libpq is reentrant and thread-safe if the
configure command-line option
addition, you might need to use additional compiler command-line
options when you compile your application code. Refer to your
system's documentation for information about how to build
- thread-enabled applications, or look in
+ thread-enabled applications, or look in
src/Makefile.global for PTHREAD_CFLAGS
and PTHREAD_LIBS. This function allows the querying of
libpq's thread-safe status:
-
+
int PQisthreadsafe();
-
+
Returns 1 if the
libpq is thread-safe
and 0 if it is not.
-
+
One thread restriction is that no two threads attempt to manipulate
the same PGconn object at the same time. In particular,
the same connection object. (If you need to run concurrent commands,
use multiple connections.)
-
+
PGresult objects are read-only after creation, and so
can be passed around freely between threads.
-
+
The deprecated functions PQrequestCancel and
PQoidStatus are not thread-safe and should not be
PQoidStatus can be replaced by
PQoidValue.
-
+
If you are using Kerberos inside your application (in addition to inside
libpq), you will need to do locking around
libpq source code for a way to do cooperative
locking between
libpq and your application.
-
+
If you experience problems with threaded applications, run the program
in src/tools/thread to see if your platform has
library might not match the library used to build the binaries.
-
-
+
+
Building <application>libpq</application> Programs
-
+
libpq applications
-
+
To build (i.e., compile and link) a program using
libpq you need to do all of the following
things:
-
+
-
+
Point your compiler to the directory where the
PostgreSQL header CPPFLAGS += -I/usr/local/pgsql/include
-
+
If there is any chance that your program might be compiled by
other users then you should not hardcode the directory location
/usr/local/include
-
+
Failure to specify the correct option to the compiler will
result in an error message such as
-
+
When linking the final program, specify the option
cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq
-
+
You can find out the library directory using
pg_config as well:
/usr/local/pgsql/lib
-
+
Error messages that point to problems in this area could look like
the following.
-
+
-
-
+
+
Example Programs
-
+
These examples and others can be found in the
directory src/test/examples in the source code
projects / postgresql.git / commitdiff