PGconnobject, which is obtained from the function
PQsetdbLogin. Note that these functions will always return a non-null object pointer, unless perhaps there is too little memory even to allocate the
PQstatusfunction should be called to check the return value for a successful connection before queries are sent via the connection object.
search_path. One can set parameter key word
-csearch_path=. Alternately, one can issue
conn, "SELECT pg_catalog.set_config('search_path', '', false)") after connecting. This consideration is not specific to libpq; it applies to every interface for executing arbitrary SQL commands.
execfrom the child process to load a new executable is safe.
NULL-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. Unlike
PQsetdbLoginbelow, the parameter set can be extended without changing the function signature, so use of this function (or its nonblocking analogs
PQconnectPoll) is preferred for new application programming.
NULLentry in the
keywordsarray. Also, if the
valuesentry associated with a non-
NULLor an empty string, that entry is ignored and processing continues with the next pair of array entries.
expand_dbnameis non-zero, the value for the first
dbnamekey word is checked to see if it is a connection 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 in Section 33.1.1.) Only the first occurrence of
dbnameis treated in this way; any subsequent
dbnameparameter is processed as a plain database name.
NULLor empty) is used. This rule applies in particular when a key word found in a connection string conflicts with one appearing in the
keywordsarray. 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 expanded
dbnameentry can be overridden by fields of the connection string, and in turn those fields are overridden by array entries appearing after
dbname(but, again, only if those entries supply non-empty values).
PQconnectdbwith a fixed set of parameters. It has the same functionality except that the missing parameters will always take on default values. Write
NULLor an empty string for any one of the fixed parameters that is to be defaulted.
PQsetdbLoginwith null pointers for the
pwdparameters. It is provided for backward compatibility with very old programs.
PQconnectdb, and so the application can manage this operation in parallel with other activities.
PQconnectPoll, as described below.
PQconnectStartParams. If the result is null, then libpq has been unable to allocate a new
PGconnstructure. Otherwise, a valid
PGconnpointer is returned (though not yet representing a valid connection to the database). Next call
PQstatus(conn). If the result is
CONNECTION_BAD, the connection attempt has already failed, typically because of invalid connection parameters.
PQconnectStartParamssucceeds, 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. (Caution: do not assume that the socket remains the same across
PQconnectPollcalls.) Loop thus: If
PGRES_POLLING_READING, wait until the socket is ready to read (as indicated by
poll(), or similar system function). Then call
PQconnectPoll(conn)again. Conversely, if
PGRES_POLLING_WRITING, wait until the socket is ready to write, then call
PQconnectPoll(conn)again. On the first iteration, i.e., if you have yet to call
PQconnectPoll, behave as if it last returned
PGRES_POLLING_WRITING. Continue this loop until
PGRES_POLLING_FAILED, indicating the connection procedure has failed, or
PGRES_POLLING_OK, indicating the connection has been successfully made.
PQstatus. If this call returns
CONNECTION_BAD, then the connection procedure has failed; if the call returns
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:
connect_timeoutconnection parameter is ignored when using
PQconnectPoll; it is the application's responsibility to decide whether an excessive amount of time has elapsed. Otherwise,
PQconnectStartfollowed by a
PQconnectPollloop is equivalent to
PQconnectdboptions and their current default values. The return value points to an array of
PQconninfoOptionstructures, which ends with an entry having a null
keywordpointer. The null pointer is returned if memory could not be allocated. Note that the current default values (
valfields) 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.
PQconnectdboptions and the values that were used to connect to the server. The return value points to an array of
PQconninfoOptionstructures, which ends with an entry having a null
keywordpointer. All notes above for
PQconndefaultsalso apply to the result of
NULLif there is a problem with the connection string. This function can be used to extract the
PQconnectdboptions in the provided connection string. The return value points to an array of
PQconninfoOptionstructures, which ends with an entry having a null
PQconninfoOptionfor any option not present in the connection string will have
NULL; default values are not inserted.
*errmsgis set to
NULLon success, else to a
malloc'd error string explaining the problem. (It is also possible for
*errmsgto be set to
NULLand the function to return
NULL; this indicates an out-of-memory condition.)
PQreset(above) in that they act in a nonblocking manner. These functions suffer from the same restrictions as
PQresetStart. If it returns 0, the reset has failed. If it returns 1, poll the reset using
PQresetPollin exactly the same way as you would create the connection using
PQpingParamsreports the status of the server. It accepts connection parameters identical to those of
PQconnectdbParams, 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.
PQpingreports the status of the server. It accepts connection parameters identical to those of
PQconnectdb, 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.
PQdefaultSSLKeyPassHook_OpenSSLhandler. The callback should determine the password for the key and copy it to result-buffer
size. The string in
bufmust be null-terminated. The callback must return the length of the password stored in
bufexcluding the null terminator. On failure, the callback should set
buf = '\0'and return 0. See
PQdefaultSSLKeyPassHook_OpenSSLin libpq's source code for an example.
conn->sslkeywhen the callback is invoked. This will be empty if the default key path is being used. For keys that are engine specifiers, it is up to engine implementations whether they use the OpenSSL password callback or define their own handling.
PQdefaultSSLKeyPassHook_OpenSSL, or call it first and try something else if it returns 0, or completely override it.
longjmp(...), etc. It must return normally.
PQgetSSLKeyPassHook_OpenSSLreturns the current client certificate key password hook, or
NULLif none has been set.
value, with space(s) between settings. Spaces around a setting's equal sign are optional. To write an empty value, or a value containing spaces, surround it with single quotes, for example
keyword = 'a value'. Single quotes and backslashes within a value must be escaped with a backslash, i.e.,
postgres://. Each of the remaining URI parts is optional. The following examples illustrate valid URI syntax:
=) is replaced with
%3Dand the space character with
postgresql://host1:port1,host2:port2,host3:port3/is equivalent to a connection string of the form
host=host1,host2,host3 port=port1,port2,port3. As further described below, each host will be tried in turn until a connection is successfully established.
hostis not specified, or is empty, is to connect to a Unix-domain socket in
/tmp(or whatever socket directory was specified when PostgreSQL was built). On Windows and on machines without Unix-domain sockets, the default is to connect to
172.28.40.9. If your machine supports IPv6, you can also use those addresses. TCP/IP communication is always used when a nonempty string is specified for this parameter. If this parameter is not specified, the value of
hostwill be looked up to find the corresponding IP address — or, if
hostspecifies an IP address, that value will be used directly.
hostaddrallows the application to avoid a host name look-up, which might be important in applications with time constraints. However, a host name is required for GSSAPI or SSPI authentication methods, as well as for
verify-fullSSL certificate verification. The following rules are used:
hostis specified without
hostaddr, a host name lookup occurs. (When using
PQconnectPoll, the lookup occurs when
PQconnectPollfirst considers this host name, and it may cause
PQconnectPollto block for a significant amount of time.)
hostaddris specified without
host, the value for
hostaddrgives the server network address. The connection attempt will fail if the authentication method requires a host name.
hostaddrare specified, the value for
hostaddrgives the server network address. The value for
hostis ignored unless the authentication method requires it, in which case it will be used as the host name.
hostis not the name of the server at network address
hostaddr. Also, when both
hostis used to identify the connection in a password file (see Section 33.15).
hostaddrvalues is also accepted, in which case each host in the list is tried in order. An empty item in the list causes the corresponding host name to be used, or the default host name if that is empty as well. See Section 22.214.171.124 for details.
hostaddrparameters, this parameter may specify a comma-separated list of ports of the same length as the host list, or it may specify a single port number to be used for all hosts. An empty string, or an empty item in a comma-separated list, specifies the default port number established when PostgreSQL was built.
%APPDATA%\postgresql\pgpass.confon Microsoft Windows. (No error is reported if this file does not exist.)
requiremeans that the connection must employ channel binding,
prefermeans that the client will choose channel binding if available, and
disableprevents the use of channel binding. The default is
preferif PostgreSQL is compiled with SSL support; otherwise the default is
10). Zero, negative, or not specified means wait indefinitely. The minimum allowed timeout is 2 seconds, therefore a value of
1is interpreted as
2. This timeout applies separately to each host name or IP address. For example, if you specify two hosts and
connect_timeoutis 5, each host will time out if no connection is made within 5 seconds, so the total time spent waiting for a connection might be up to 10 seconds.
client_encodingconfiguration parameter for this connection. In addition to the values accepted by the corresponding server option, you can use
autoto determine the right encoding from the current locale in the client (
LC_CTYPEenvironment variable on Unix systems).
-c geqo=offsets the session's value of the
off. Spaces within this string are considered to separate command-line arguments, unless escaped with a backslash (
\\to represent a literal backslash. For a detailed discussion of the available options, consult Chapter 19.
application_namevia a connection parameter or the
PGAPPNAMEenvironment variable. Specifying a fallback name is useful in generic utility programs that wish to set a default application name but allow it to be overridden by the user.
TCP_KEEPIDLEor an equivalent socket option is available, and on Windows; on other systems, it has no effect.
TCP_KEEPINTVLor an equivalent socket option is available, and on Windows; on other systems, it has no effect.
TCP_KEEPCNTor an equivalent socket option is available; on other systems, it has no effect.
TCP_USER_TIMEOUTis available; on other systems, it has no effect.
gssencmodeis ignored for Unix domain socket communication. If PostgreSQL is compiled without GSSAPI support, using the
requireoption will cause an error, while
preferwill be accepted but libpq will not actually attempt a GSSAPI-encrypted connection.
sslmodeis ignored for Unix domain socket communication. If PostgreSQL is compiled without SSL support, using options
verify-fullwill cause an error, while options
preferwill be accepted but libpq will not actually attempt an SSL connection.
sslmode. To force use of SSL encryption in an environment that has working GSSAPI infrastructure (such as a Kerberos server), also set
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
prefer). This option is only available if PostgreSQL is compiled with SSL support.
~/.postgresql/postgresql.crt. This parameter is ignored if an SSL connection is not made.
~/.postgresql/postgresql.key, or it can specify a key obtained from an external “engine” (engines are OpenSSL loadable modules). An external engine specification should consist of a colon-separated engine name and an engine-specific key identifier. This parameter is ignored if an SSL connection is not made.
sslkey, allowing client certificate private keys to be stored in encrypted form on disk even when interactive passphrase input is not practical.
Enter PEM pass phrase:prompt that OpenSSL will emit by default when an encrypted client certificate key is provided to
.pgpass. It can be used in a service file connection definition. Users with more sophisticated uses should consider using openssl engines and tools like PKCS#11 or USB crypto offload devices.
requirepeer=postgres. When making a Unix-domain socket connection, if this parameter is set, the client checks at the beginning of the connection that the server process is running under the specified user name; if it is not, the connection is aborted with an error. This parameter can be used to provide server authentication similar to that available with SSL certificates on TCP/IP connections. (Note that if the Unix-domain socket is in
/tmpor another publicly writable location, any user could start a server listening there. Use this parameter to ensure that you are connected to a server run by a trusted user.) This option is only supported on platforms for which the
peerauthentication method is implemented; see Section 20.9.
TLSv1.3. The supported protocols depend on the version of OpenSSL used, older versions not supporting the most modern protocol versions. If not specified, the default is
TLSv1.2, which satisfies industry best practices as of this writing.
TLSv1.3. The supported protocols depend on the version of OpenSSL used, older versions not supporting the most modern protocol versions. If not set, this parameter is ignored and the connection will use the maximum bound defined by the backend, if set. Setting the maximum protocol version is mainly useful for testing or if some component has issues working with a newer protocol.
postgres, but that can be changed when building PostgreSQL via the
--with-krb-srvnamoption of configure. In most environments, this parameter never needs to be changed. Some Kerberos implementations might require a different service name, such as Microsoft Active Directory which requires the service name to be in upper case (
gssapito cause libpq to use the GSSAPI library for authentication instead of the default SSPI.
pg_service.confthat holds additional connection parameters. This allows applications to specify only a service name so connection parameters can be centrally maintained. See Section 33.16.
read-write, only a connection in which read-write transactions are accepted by default is considered acceptable. The query
SHOW transaction_read_onlywill be sent upon any successful connection; if it returns
on, the connection will be closed. If multiple hosts were specified in the connection string, any remaining servers will be tried just as if the connection attempt had failed. The default value of this parameter,
any, regards all connections as acceptable.