PQconnectdb

PQconnectdb makes a new connection to the database server.

PGconn *PQconnectdb(const char *conninfo)

This routine opens a new database connection using the parameters taken from the string conninfo and blocks until the connection attempt operation has completed. This routine has non-blocking analogs, PQconnectStart and PQconnectPoll.

To make a connection, a PQconn object is obtained by calling PQconnectdb or PQsetdbLogin. The PQstatus function can then be called. The passed string can be empty to use all default parameters, or it can contain one or more parameter settings separated by whitespace.

Each parameter setting is in the form keyword = value. (To write a NULL value or a value containing spaces, surround it with single quotes, for example, keyword = 'a value'. Single quotes within the value must be written as \'. Spaces around the equal sign are optional.) The currently recognized parameter keywords are:

The return value is a pointer to an abstract struct that represents the connection to the backend.

PQsetdbLogin

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 of PQconnectdb; it has a fixed number of parameters but the same functionality. This function exists mainly to support legacy applications. New applications should use the PQconnectdb function.

PQsetdb

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 calls PQsetdbLogin with NULL pointers for the login and pwd parameters. It is provided primarily for backward compatibility with old programs; PQconnectdb is preferred for new development.

PQconnectStart, PQconnectPoll

PQconnectStart and PQconnectPoll make a connection to the database server in a non-blocking manner.

PGconn *PQconnectStart(const char *conninfo) PostgresPollingStatusType PQconnectPoll(PGconn *conn)

These two routines open a connection to a database server that prevents your application's thread of execution from being blocked on remote I/O.

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 as long as the following 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 the Section called Database Connection Functions 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.

1. To begin, 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).

2. 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 using PQconnectPoll(conn) so that it may proceed with the connection sequence. Loop in this way, considering the connection "inactive" by default.

PQconnectPoll Return Values

• If PQconnectPoll last returned PGRES_POLLING_ACTIVE, consider it "active" instead.

• If PQconnectPoll last returned PGRES_POLLING_READING, perform a select for reading on PQsocket(conn).

• If PQconnectPoll last returned PGRES_POLLING_WRITING, perform a select for writing on PQsocket(conn).

• If you have yet to call PQconnectPoll, for example, after the call to PQconnectStart, behave as if it last returned PGRES_POLLING_WRITING.

• If the Select() shows that the socket is ready, consider it "active".

• If it has been decided that this connection is "active", call PQconnectPoll(conn) again.

• If this call returns PGRES_POLLING_FAILED, the connection procedure has failed.

• If this call returns PGRES_POLLING_OK, the connection has been successfully made.

Note that the use of select() to ensure that the socket is ready is merely an example; if you have other facilities available, such as poll(), you can use those instead.

At any time during connection, you can check the status of the connection by calling PQstatus. This function returns a value of type ConnStatusType and may then be checked to determine status. If it returns CONNECTION_BAD, then the connection procedure has failed; if it returns CONNECTION_OK, then the connection is ready. Either of these states should be equally detectable from the return value of PQconnectPoll, as above. Other states may be shown during (and only during) an asynchronous connection procedure. These indicate the current stage of the connection procedure, and may be useful to provide feedback to the user. The status may include:

• CONNECTION_STARTED: Waiting for connection to be made.

• CONNECTION_MADE: Connection OK; waiting to send.

• CONNECTION_AWAITING_RESPONSE: Waiting for a response from the postmaster.

• CONNECTION_AUTH_OK: Received authentication; waiting for backend start-up.

• CONNECTION_SETENV: Negotiating environment.

    switch(PQstatus(conn))
    {
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
            feedback = "Connecting...";
    }

If PQconnectStart returns a non-NULL pointer, you must call PQfinish when you are finished with it to dispose of the structure and any associated memory blocks. You must do this even if a call to PQconnectStart or PQconnectPoll failed.

PQconnectPoll will currently block if libpq is compiled with USE_SSL defined. This restriction may be removed in the future.

PQconnectStart and PQconnectPoll leave the socket in a non-blocking state as if PQsetnonblocking had been called.

PQconndefaults

PQconndefaults returns the default connection options.

PQconninfoOption *PQconndefaults(void) struct PQconninfoOption { 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; /* Character to display for this field in a connect dialog. Values are: "" Display entered value as is "*" Password field - hide value "D" Debug option - do not show by default */ int dispsize; /* Field size in characters for dialog */ }

Returns a connection options array. You can use this to determine all possible PQconnectdb options and their current default values. The return value points to an array of PQconninfoOption structs, which ends with an entry having a NULL keyword pointer. Note that:

• The 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.

PQfinish

PQfinish closes the connection to the backend and frees memory used by the PGconn object.

void PQfinish(PGconn *conn)

Note that even if the backend connection attempt fails (as indicated by PQstatus), the application should call PQfinish to free the memory used by the PGconn object. Do not use the PGconn pointer after PQfinish has been called.

PQreset

PQreset resets the communication port with the backend.

void PQreset(PGconn *conn)

This function closes the connection to the backend and attempts to reestablish a new connection to the same postmaster, using the same parameters previously used. This may be useful for error recovery if a working connection is lost.

PQresetStart, PQresetPoll

PQresetStart and PQresetPoll reset the communication port with the backend in a non-blocking manner.

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

These functions close the connection to the backend and attempt to reestablish a new connection to the same postmaster, using all the same parameters previously used. This may be useful for error recovery if a working connection is lost. They differ from PQreset (above) in that they act in a non-blocking manner. These functions are subject to the same restrictions as PQconnectStart and PQconnectPoll.

If PQresetStart returns 0, the reset has failed. If it returns 1, poll the reset using PQresetPoll in exactly the same way as you would create the connection using PQconnectPoll.

PQdb

PQdb returns the database name of the connection.

char *PQdb(const PGconn *conn)

PQuser

PQuser returns the user name of the connection.

char *PQuser(const PGconn *conn)

PQpass

PQpass returns the password of the connection.

char *PQpass(const PGconn *conn)

PQhost

PQhost returns the server host name of the connection.

char *PQhost(const PGconn *conn)

PQport

PQport returns the port of the connection.

char *PQport(const PGconn *conn)

PQtty

PQtty returns the debug tty of the connection.

char *PQtty(const PGconn *conn)

PQoptions

PQoptions returns the backend options used in the connection.

char *PQoptions(const PGconn *conn)

PQstatus

PQstatus returns the status of the connection.

ConnStatusType PQstatus(const PGconn *conn)

The status can be one of a number of values. However, only two of these are seen outside of an asynchronous connection procedure - CONNECTION_OK or CONNECTION_BAD. A good connection to the database has the status CONNECTION_OK. A failed connection attempt is signaled by status CONNECTION_BAD. Ordinarily, an OK status will remain so until PQfinish, but a communications failure might result in the status changing to CONNECTION_BAD prematurely. In that case the application could try to recover by calling PQreset.

See PQconnectStart and PQconnectPoll for other status codes that might be seen.

PQerrorMessage

PQerrorMessage returns the error message most recently generated by an operation on the connection.

char *PQerrorMessage(const PGconn* conn);

Nearly all libpq functions will set PQerrorMessage if they fail. Note that, by libpq convention, a non-empty PQerrorMessage will include a trailing newline.

PQbackendPID

PQbackendPID returns the process ID of the backend server handling this connection.

int PQbackendPID(const PGconn *conn);

The backend PID is useful for debugging purposes and for comparison to NOTIFY messages (which include the PID of the notifying backend). Note that the PID belongs to a process executing on the database server host, not the local host.

PQgetssl

PQgetssl returns the SSL structure used in the connection, or NULL if SSL is not in use.

SSL *PQgetssl(const PGconn *conn);

You can use this structure to verify encryption levels, check the server certificate, and more. Refer to the OpenSSL documentation for information about this structure.

You must define USE_SSL in order to get the prototype for this function. Doing this will also automatically include ssl.h from OpenSSL.