Movatterモバイル変換

33.1.1. Connection Strings

33.1.2. Parameter Key Words

Warning

If untrusted users have access to a database that has not adopted asecure schema usage pattern, begin each session by removing publicly-writable schemas fromsearch_path. One can set parameter key wordoptions to value-csearch_path=. Alternately, one can issuePQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)") after connecting. This consideration is not specific tolibpq; it applies to every interface for executing arbitrary SQL commands.

Warning

On Unix, forking a process with open libpq connections can lead to unpredictable results because the parent and child processes share the same sockets and operating system resources. For this reason, such usage is not recommended, though doing anexec from the child process to load a new executable is safe.

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 33.1.2.

The passed arrays can be empty to use all default parameters, or can contain one or more parameter settings. They must be matched in length. Processing will stop at the firstNULL entry in thekeywords array. Also, if thevalues entry associated with a non-NULLkeywords entry isNULL or an empty string, that entry is ignored and processing continues with the next pair of array entries.

Whenexpand_dbname is non-zero, the value for the firstdbname key word is checked to see if it is aconnection string. If so, it is“expanded” into the individual connection parameters extracted from the string. The value is considered to be a connection string, rather than just a database name, if it contains an equal sign (=) or it begins with a URI scheme designator. (More details on connection string formats appear inSection 33.1.1.) Only the first occurrence ofdbname is treated in this way; any subsequentdbname parameter is processed as a plain database name.

In general the parameter arrays are processed from start to end. If any key word is repeated, the last value (that is notNULL or empty) is used. This rule applies in particular when a key word found in a connection string conflicts with one appearing in thekeywords array. Thus, the programmer may determine whether array entries can override or be overridden by values taken from a connection string. Array entries appearing before an expandeddbname entry can be overridden by fields of the connection string, and in turn those fields are overridden by array entries appearing afterdbname (but, again, only if those entries supply non-empty values).

After processing all the array entries and any expanded connection string, any connection parameters that remain unset are filled with default values. If an unset parameter's corresponding environment variable (seeSection 33.14) is set, its value is used. If the environment variable is not set either, then the parameter's built-in default value is used.

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 33.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 parameter must be used appropriately to prevent DNS queries from being made. See the documentation of this parameter inSection 33.1.2 for details.

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

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

To begin a nonblocking connection request, callPQconnectStart orPQconnectStartParams. If the result 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). Next callPQstatus(conn). If the result isCONNECTION_BAD, the connection attempt has already failed, typically because of invalid connection parameters.

IfPQconnectStart orPQconnectStartParams 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. (Caution: do not assume that the socket remains the same acrossPQconnectPoll calls.) 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. On the first iteration, i.e., if you have yet to callPQconnectPoll, 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.

CONNECTION_CHECK_WRITABLE

Checking if connection is able to handle write transactions.

CONNECTION_CONSUME

Consuming any remaining response messages on connection.

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 whenPQconnectStart orPQconnectStartParams 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 establish a new connection, 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 establish a new connection, 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.

Severallibpq functions parse a user-specified string to obtain connection parameters. There are two accepted formats for these strings: plain keyword/value strings and URIs. URIs generally followRFC 3986, except that multi-host connection strings are allowed as further described below.

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

postgresql://[userspec@][hostspec][/dbname][?paramspec]whereuserspec is:user[:password]andhostspec is:[host][:port][,...]andparamspec is:name=value[&...]

postgresql://postgresql://localhostpostgresql://localhost:5433postgresql://localhost/mydbpostgresql://user@localhostpostgresql://user:secret@localhostpostgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapppostgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp

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

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

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

The currently recognized parameter key words are: