Wiki / Connection Parameters
Connection Parameters
Compare versionslibpq connection keywords, environment mappings, defaults and precedence by client version.
Reading PostgreSQL 18.6.
55 entries; 51 recorded in PostgreSQL 18.6.
-
channel_binding Authentication
This option controls the client's use of channel binding. A setting of require means that the connection must employ channel binding, prefer means that the client will choose channel binding if available, and disable prevents the use of channel bind…
-
Not recorded in the selected version.
-
oauth_client_id Authentication
An OAuth 2.0 client identifier, as issued by the authorization server. If the PostgreSQL server requests an OAuth token for the connection (and if no custom OAuth hook is installed to provide one), then this parameter must be set; otherwise, the con…
-
oauth_client_secret Authentication
The client password, if any, to use when contacting the OAuth authorization server. Whether this parameter is required or not is determined by the OAuth provider; "public" clients generally do not use a secret, whereas "confidential" clients general…
-
oauth_issuer Authentication
The HTTPS URL of a trusted issuer to contact if the server requests an OAuth token for the connection. This parameter is required for all OAuth connections; it should exactly match the issuer setting in the server's HBA configuration .
-
oauth_scope Authentication
The scope of the access request sent to the authorization server, specified as a (possibly empty) space-separated list of OAuth scope identifiers. This parameter is optional and intended for advanced usage.
-
passfile Authentication
Specifies the name of the file used to store passwords (see Section 32.16 ). Defaults to ~/.pgpass , or %APPDATA%\postgresql\pgpass.conf on Microsoft Windows. (No error is reported if this file does not exist.)
-
password Authentication
Password to be used if the server demands password authentication.
-
require_auth Authentication
Specifies the authentication method that the client requires from the server. If the server does not use the required method to authenticate the client, or if the authentication handshake is not fully completed by the server, the connection will fai…
-
requirepeer Authentication
This parameter specifies the operating-system user name of the server, for example 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 pro…
-
scram_client_key Authentication
The base64-encoded SCRAM client key. This can be used by foreign-data wrappers or similar middleware to enable pass-through SCRAM authentication. See Section F.38.1.10 for one such implementation. It is not meant to be specified directly by users or…
-
scram_server_key Authentication
The base64-encoded SCRAM server key. This can be used by foreign-data wrappers or similar middleware to enable pass-through SCRAM authentication. See Section F.38.1.10 for one such implementation. It is not meant to be specified directly by users or…
-
user Authentication
PostgreSQL user name to connect as. Defaults to be the same as the operating system name of the user running the application.
-
dbname Connection destination
The database name. Defaults to be the same as the user name. In certain contexts, the value is checked for extended formats; see Section 32.1.1 for more details on those.
-
host Connection destination
Name of host to connect to. If a host name looks like an absolute path name, it specifies Unix-domain communication rather than TCP/IP communication; the value is the name of the directory in which the socket file is stored. (On Unix, an absolute pa…
-
hostaddr Connection destination
Numeric IP address of host to connect to. This should be in the standard IPv4 address format, e.g., 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 specifie…
-
load_balance_hosts Connection destination
Controls the order in which the client tries to connect to the available hosts and addresses. Once a connection attempt is successful no other hosts and addresses will be tried. This parameter is typically used in combination with multiple host name…
-
port Connection destination
Port number to connect to at the server host, or socket file name extension for Unix-domain connections. If multiple hosts were given in the host or hostaddr parameters, this parameter may specify a comma-separated list of ports of the same length a…
-
service Connection destination
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. …
-
target_session_attrs Connection destination
This option determines whether the session must have certain properties to be acceptable. It's typically used in combination with multiple host names to select the first acceptable alternative among several hosts. There are six modes:
-
gssdelegation GSSAPI and Kerberos
Forward (delegate) GSS credentials to the server. The default is 0 which means credentials will not be forwarded to the server. Set this to 1 to have credentials forwarded when possible.
-
gssencmode GSSAPI and Kerberos
This option determines whether or with what priority a secure GSS TCP/IP connection will be negotiated with the server. There are three modes:
-
gsslib GSSAPI and Kerberos
GSS library to use for GSSAPI authentication. Currently this is disregarded except on Windows builds that include both GSSAPI and SSPI support. In that case, set this to gssapi to cause libpq to use the GSSAPI library for authentication instead of t…
-
krbsrvname GSSAPI and Kerberos
Kerberos service name to use when authenticating with GSSAPI. This must match the service name specified in the server configuration for Kerberos authentication to succeed. (See also Section 20.6 .) The default value is normally postgres , but that …
-
application_name Session and protocol
Specifies a value for the application_name configuration parameter.
-
client_encoding Session and protocol
This sets the client_encoding configuration parameter for this connection. In addition to the values accepted by the corresponding server option, you can use auto to determine the right encoding from the current locale in the client ( LC_CTYPE envir…
-
fallback_application_name Session and protocol
Specifies a fallback value for the application_name configuration parameter. This value will be used if no value has been given for application_name via a connection parameter or the PGAPPNAME environment variable. Specifying a fallback name is usef…
-
max_protocol_version Session and protocol
Specifies the protocol version to request from the server. The default is to use version 3.0 of the PostgreSQL protocol, unless the connection string specifies a feature that relies on a higher protocol version, in which case the latest version supp…
-
min_protocol_version Session and protocol
Specifies the minimum protocol version to allow for the connection. The default is to allow any version of the PostgreSQL protocol supported by libpq, which currently means 3.0 . If the server does not support at least this protocol version the conn…
-
options Session and protocol
Specifies command-line options to send to the server at connection start. For example, setting this to -c geqo=off or --geqo=off sets the session's value of the geqo parameter to off . Spaces within this string are considered to separate command-lin…
-
replication Session and protocol
This option determines whether the connection should use the replication protocol instead of the normal protocol. This is what PostgreSQL replication connections as well as tools such as pg_basebackup use internally, but it can also be used by third…
-
Not recorded in the selected version.
-
Not recorded in the selected version.
-
Not recorded in the selected version.
-
requiressl TLS
This option is deprecated in favor of the sslmode setting.
-
This parameter specifies the maximum SSL/TLS protocol version to allow for the connection. Valid values are TLSv1 , TLSv1.1 , TLSv1.2 and TLSv1.3 . The supported protocols depend on the version of OpenSSL used, older versions not supporting the most…
-
This parameter specifies the minimum SSL/TLS protocol version to allow for the connection. Valid values are TLSv1 , TLSv1.1 , TLSv1.2 and TLSv1.3 . The supported protocols depend on the version of OpenSSL used, older versions not supporting the most…
-
sslcert TLS
This parameter specifies the file name of the client SSL certificate, replacing the default ~/.postgresql/postgresql.crt . This parameter is ignored if an SSL connection is not made.
-
sslcertmode TLS
This option determines whether a client certificate may be sent to the server, and whether the server is required to request one. There are three modes:
-
sslcompression TLS
If set to 1, data sent over SSL connections will be compressed. If set to 0, compression will be disabled. The default is 0. This parameter is ignored if a connection without SSL is made.
-
sslcrl TLS
This parameter specifies the file name of the SSL server certificate revocation list (CRL). Certificates listed in this file, if it exists, will be rejected while attempting to authenticate the server's certificate. If neither sslcrl nor sslcrldir i…
-
sslcrldir TLS
This parameter specifies the directory name of the SSL server certificate revocation list (CRL). Certificates listed in the files in this directory, if it exists, will be rejected while attempting to authenticate the server's certificate.
-
sslkey TLS
This parameter specifies the location for the secret key used for the client certificate. It can either specify a file name that will be used instead of the default ~/.postgresql/postgresql.key , or it can specify a key obtained from an external “ e…
-
sslkeylogfile TLS
This parameter specifies the location where libpq will log keys used in this SSL context. This is useful for debugging PostgreSQL protocol interactions or client connections using network inspection tools like Wireshark . This parameter is ignored i…
-
sslmode TLS
This option determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server. There are six modes:
-
sslnegotiation TLS
This option controls how SSL encryption is negotiated with the server, if SSL is used. In the default postgres mode, the client first asks the server if SSL is supported. In direct mode, the client starts the standard SSL handshake directly after es…
-
sslpassword TLS
This parameter specifies the password for the secret key specified in sslkey , allowing client certificate private keys to be stored in encrypted form on disk even when interactive passphrase input is not practical.
-
sslrootcert TLS
This parameter specifies the name of a file containing SSL certificate authority ( CA ) certificate(s). If the file exists, the server's certificate will be verified to be signed by one of these authorities. The default is ~/.postgresql/root.crt .
-
sslsni TLS
If set to 1 (default), libpq sets the TLS extension “ Server Name Indication ” ( SNI ) on SSL-enabled connections. By setting this parameter to 0, this is turned off.
-
connect_timeout Timeouts and keepalives
Maximum time to wait while connecting, in seconds (write as a decimal integer, e.g., 10 ). Zero, negative, or not specified means wait indefinitely. This timeout applies separately to each host name or IP address. For example, if you specify two hos…
-
keepalives Timeouts and keepalives
Controls whether client-side TCP keepalives are used. The default value is 1, meaning on, but you can change this to 0, meaning off, if keepalives are not wanted. This parameter is ignored for connections made via a Unix-domain socket.
-
keepalives_count Timeouts and keepalives
Controls the number of TCP keepalives that can be lost before the client's connection to the server is considered dead. A value of zero uses the system default. This parameter is ignored for connections made via a Unix-domain socket, or if keepalive…
-
keepalives_idle Timeouts and keepalives
Controls the number of seconds of inactivity after which TCP should send a keepalive message to the server. A value of zero uses the system default. This parameter is ignored for connections made via a Unix-domain socket, or if keepalives are disabl…
-
keepalives_interval Timeouts and keepalives
Controls the number of seconds after which a TCP keepalive message that is not acknowledged by the server should be retransmitted. A value of zero uses the system default. This parameter is ignored for connections made via a Unix-domain socket, or i…
-
tcp_user_timeout Timeouts and keepalives
Controls the number of milliseconds that transmitted data may remain unacknowledged before a connection is forcibly closed. A value of zero uses the system default. This parameter is ignored for connections made via a Unix-domain socket. It is only …
RecordedFirst recordedInterface or attribute changeNo longer recorded
Squares indicate presence in sampled builds, not first introduction. Select a square for the same-version definition and sources.
Changes in PostgreSQL 18.6 · Export JSON
Reading this collection
These are libpq client connection keywords, separate from server GUCs. Source-only keywords and symbolic compiled defaults are marked; an expression in source is not a measured effective default.