Note: On Windows, there is a way to improve performance if a single database connection is repeatedly started and shutdown. Internally, libpq callsWSAStartup() andWSACleanup() for connection startup and shutdown, respectively.WSAStartup() increments an internal Windows library reference count which is decremented byWSACleanup(). When the reference count is just one, callingWSACleanup() frees all resources and all DLLs are unloaded. This is an expensive operation. To avoid this, an application can manually callWSAStartup() so resources will not be freed when the last database connection is closed.

PQconnectdbParams

Makes a new connection to the database server.

PGconn *PQconnectdbParams(const char * const *keywords,                          const char * const *values,                          int expand_dbname);

This function opens a new database connection using the parameters taken from twoNULL-terminated arrays. The first,keywords, is defined as an array of strings, each one being a key word. The second,values, gives the value for each key word. UnlikePQsetdbLogin below, the parameter set can be extended without changing the function signature, so use of this function (or its nonblocking analogsPQconnectStartParams andPQconnectPoll) is preferred for new application programming.

The currently recognized parameter key words are listed inSection 31.1.2.

Whenexpand_dbname is non-zero, thedbname key word value is allowed to be recognized as a connection string. Only the first occurrence ofdbname is expanded this way, any subsequentdbname value is processed as plain database name. More details on the possible connection string formats appear inSection 31.1.1.

The passed arrays can be empty to use all default parameters, or can contain one or more parameter settings. They should be matched in length. Processing will stop at the firstNULL element in thekeywords array.

If any parameter isNULL or an emptry string, the corresponding environment variable (seeSection 31.14) is checked. If the environment variable is not set either, then the indicated built-in defaults are used.

In general key words are processed from the beginning of these arrays in index order. The effect of this is that when key words are repeated, the last processed value is retained. Therefore, through careful placement of thedbname key word, it is possible to determine what may be overridden by aconninfo string, and what may not.

PQconnectdb

Makes a new connection to the database server.

PGconn *PQconnectdb(const char *conninfo);

This function opens a new database connection using the parameters taken from the stringconninfo.

The passed string can be empty to use all default parameters, or it can contain one or more parameter settings separated by whitespace, or it can contain aURI. SeeSection 31.1.1 for details.

PQsetdbLogin

Makes a new connection to the database server.

PGconn *PQsetdbLogin(const char *pghost,                     const char *pgport,                     const char *pgoptions,                     const char *pgtty,                     const char *dbName,                     const char *login,                     const char *pwd);

This is the predecessor ofPQconnectdb with a fixed set of parameters. It has the same functionality except that the missing parameters will always take on default values. WriteNULL or an empty string for any one of the fixed parameters that is to be defaulted.

If thedbName contains an= sign or has a valid connectionURI prefix, it is taken as aconninfo string in exactly the same way as if it had been passed toPQconnectdb, and the remaining parameters are then applied as specified forPQconnectdbParams.

PQsetdb

Makes a new connection to the database server.

PGconn *PQsetdb(char *pghost,                char *pgport,                char *pgoptions,                char *pgtty,                char *dbName);

This is a macro that callsPQsetdbLogin with null pointers for thelogin andpwd parameters. It is provided for backward compatibility with very old programs.

PQconnectStartParams
PQconnectStart
PQconnectPoll

Make a connection to the database server in a nonblocking manner.

PGconn *PQconnectStartParams(const char * const *keywords,                             const char * const *values,                             int expand_dbname);PGconn *PQconnectStart(const char *conninfo);PostgresPollingStatusType PQconnectPoll(PGconn *conn);

These three 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 insidePQconnectdbParams orPQconnectdb, and so the application can manage this operation in parallel with other activities.

WithPQconnectStartParams, the database connection is made using the parameters taken from thekeywords andvalues arrays, and controlled byexpand_dbname, as described above forPQconnectdbParams.

WithPQconnectStart, the database connection is made using the parameters taken from the stringconninfo as described above forPQconnectdb.

NeitherPQconnectStartParams norPQconnectStart norPQconnectPoll will block, so long as a number of restrictions are met:

• Thehostaddr andhost parameters are used appropriately to ensure that name and reverse name queries are not made. See the documentation of these parameters inSection 31.1.2 for details.

• If you callPQtrace, ensure that the stream object into which you trace will not block.

• You ensure that the socket is in the appropriate state before callingPQconnectPoll, as described below.

Note: use ofPQconnectStartParams is analogous toPQconnectStart shown below.

To begin a nonblocking connection request, callconn = PQconnectStart("connection_info_string"). Ifconn is null, thenlibpq has been unable to allocate a newPGconn structure. Otherwise, a validPGconn pointer is returned (though not yet representing a valid connection to the database). On return fromPQconnectStart, callstatus = PQstatus(conn). Ifstatus equalsCONNECTION_BAD,PQconnectStart has failed.

IfPQconnectStart succeeds, the next stage is to polllibpq so that it can proceed with the connection sequence. UsePQsocket(conn) to obtain the descriptor of the socket underlying the database connection. Loop thus: IfPQconnectPoll(conn) last returnedPGRES_POLLING_READING, wait until the socket is ready to read (as indicated byselect(),poll(), or similar system function). Then callPQconnectPoll(conn) again. Conversely, ifPQconnectPoll(conn) last returnedPGRES_POLLING_WRITING, wait until the socket is ready to write, then callPQconnectPoll(conn) again. If you have yet to callPQconnectPoll, i.e., just after the call toPQconnectStart, behave as if it last returnedPGRES_POLLING_WRITING. Continue this loop untilPQconnectPoll(conn) returnsPGRES_POLLING_FAILED, indicating the connection procedure has failed, orPGRES_POLLING_OK, indicating the connection has been successfully made.

At any time during connection, the status of the connection can be checked by callingPQstatus. If this call returnsCONNECTION_BAD, then the connection procedure has failed; if the call returnsCONNECTION_OK, then the connection is ready. Both of these states are equally detectable from the return value ofPQconnectPoll, 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)){        case CONNECTION_STARTED:            feedback = "Connecting...";            break;        case CONNECTION_MADE:            feedback = "Connected to server...";            break;...        default:            feedback = "Connecting...";}

Theconnect_timeout connection parameter is ignored when usingPQconnectPoll; it is the application's responsibility to decide whether an excessive amount of time has elapsed. Otherwise,PQconnectStart followed by aPQconnectPoll loop is equivalent toPQconnectdb.

Note that ifPQconnectStart returns a non-null pointer, you must callPQfinish 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.

PQconndefaults

Returns the default connection options.

PQconninfoOption *PQconndefaults(void);typedef struct{    char   *keyword;   /* The keyword of the option */    char   *envvar;    /* Fallback environment variable name */    char   *compiled;  /* Fallback compiled in default value */    char   *val;       /* Option's current value, or NULL */    char   *label;     /* Label for field in connect dialog */    char   *dispchar;  /* Indicates how to display this field                          in a connect dialog. Values are:                          ""        Display entered value as is                          "*"       Password field - hide value                          "D"       Debug option - don't show by default */    int     dispsize;  /* Field size in characters for dialog */} PQconninfoOption;

Returns a connection options array. This can be used to determine all possiblePQconnectdb options and their current default values. The return value points to an array ofPQconninfoOption structures, which ends with an entry having a nullkeyword 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. A missing or invalid service file will be silently ignored. Callers must treat the connection options data as read-only.

After processing the options array, free it by passing it toPQconninfoFree. If this is not done, a small amount of memory is leaked for each call toPQconndefaults.

PQconninfo

Returns the connection options used by a live connection.

PQconninfoOption *PQconninfo(PGconn *conn);

Returns a connection options array. This can be used to determine all possiblePQconnectdb options and the values that were used to connect to the server. The return value points to an array ofPQconninfoOption structures, which ends with an entry having a nullkeyword pointer. All notes above forPQconndefaults also apply to the result ofPQconninfo.

PQconninfoParse

Returns parsed connection options from the provided connection string.

PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);

Parses a connection string and returns the resulting options as an array; or returnsNULL if there is a problem with the connection string. This function can be used to extract thePQconnectdb options in the provided connection string. The return value points to an array ofPQconninfoOption structures, which ends with an entry having a nullkeyword pointer.

All legal options will be present in the result array, but thePQconninfoOption for any option not present in the connection string will haveval set toNULL; default values are not inserted.

Iferrmsg is notNULL, then*errmsg is set toNULL on success, else to amalloc'd error string explaining the problem. (It is also possible for*errmsg to be set toNULL and the function to returnNULL; this indicates an out-of-memory condition.)

After processing the options array, free it by passing it toPQconninfoFree. If this is not done, some memory is leaked for each call toPQconninfoParse. Conversely, if an error occurs anderrmsg is notNULL, be sure to free the error string usingPQfreemem.

PQfinish

Closes the connection to the server. Also frees memory used by thePGconn object.

void PQfinish(PGconn *conn);

Note that even if the server connection attempt fails (as indicated byPQstatus), the application should callPQfinish to free the memory used by thePGconn object. ThePGconn pointer must not be used again afterPQfinish has been called.

PQreset

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.

PQresetStart
PQresetPoll

Reset the communication channel to the server, in a nonblocking manner.

int PQresetStart(PGconn *conn);PostgresPollingStatusType PQresetPoll(PGconn *conn);

These functions 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 can be useful for error recovery if a working connection is lost. They differ fromPQreset (above) in that they act in a nonblocking manner. These functions suffer from the same restrictions asPQconnectStartParams,PQconnectStart andPQconnectPoll.

To initiate a connection reset, callPQresetStart. If it returns 0, the reset has failed. If it returns 1, poll the reset usingPQresetPoll in exactly the same way as you would create the connection usingPQconnectPoll.

PQpingParams

PQpingParams reports the status of the server. It accepts connection parameters identical to those ofPQconnectdbParams, described above. It is not necessary to supply correct user name, password, or database name values to obtain the server status; however, if incorrect values are provided, the server will log a failed connection attempt.

PGPing PQpingParams(const char * const *keywords,                    const char * const *values,                    int expand_dbname);

The function returns one of the following values:

PQPING_OK

The server is running and appears to be accepting connections.

PQPING_REJECT

The server is running but is in a state that disallows connections (startup, shutdown, or crash recovery).

PQPING_NO_RESPONSE

The server could not be contacted. This might indicate that the server is not running, or that there is something wrong with the given connection parameters (for example, wrong port number), or that there is a network connectivity problem (for example, a firewall blocking the connection request).

PQPING_NO_ATTEMPT

No attempt was made to contact the server, because the supplied parameters were obviously incorrect or there was some client-side problem (for example, out of memory).

PQping

PQping reports the status of the server. It accepts connection parameters identical to those ofPQconnectdb, described above. It is not necessary to supply correct user name, password, or database name values to obtain the server status; however, if incorrect values are provided, the server will log a failed connection attempt.

PGPing PQping(const char *conninfo);

The return values are the same as forPQpingParams.

31.1.1. Connection Strings

Severallibpq functions parse a user-specified string to obtain connection parameters. There are two accepted formats for these strings: plainkeyword = value strings andRFC 3986 URIs.

host=localhost port=5432 dbname=mydb connect_timeout=10

postgresql://[user[:password]@][netloc][:port][/dbname][?param1=value1&...]

postgresql://postgresql://localhostpostgresql://localhost:5433postgresql://localhost/mydbpostgresql://user@localhostpostgresql://user:secret@localhostpostgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp

postgresql:///mydb?host=localhost&port=5433

postgresql://[2001:db8::1234]/database

postgresql:///dbname?host=/var/lib/postgresqlpostgresql://%2Fvar%2Flib%2Fpostgresql/dbname

31.1.2. Parameter Key Words

The currently recognized parameter key words are: