Connection Parameters

host

Name of the host to connect to. If the host name starts with a slash (/), Unix domain socket communications instead of TCP/IP communications are used. The value is the directory where the socket file is stored. If host is not specified, the default behavior is to connect to the Unix-domain socket in the /tmp directory (or the socket directory specified during GaussDB installation). On a machine without a Unix-domain socket, the default behavior is to connect to localhost.

You can specify multiple host names by using a character string separated by commas (,). Multiple host names can be specified.

hostaddr

IP address of the host to connect to. The value is in standard IPv4 address format, for example, 172.28.40.9. If a non-null character string is specified, TCP/IP communications are used.

You can specify multiple IP addresses by using a character string separated by commas (,). Multiple IP addresses can be specified.

Replacing host with hostaddr can prevent applications from querying host names, which may be important for applications with time constraints. However, a host name is required for GSSAPI or SSPI authentication methods. Therefore, the following rules are used:

1. If host is specified but hostaddr is not, a query for the host name will be executed.
2. If hostaddr is specified but host is not, the value of hostaddr is the server network address. If the host name is required for authentication, the connection attempt fails.
3. If both host and hostaddr are specified, the value of hostaddr is the server network address. The value of host is ignored unless it is required by authentication, in which case it is used as the host name.
   NOTICE:

   • If host is not the server name in the network address specified by hostaddr, the authentication may fail.
   • If neither host nor hostaddr is specified, libpq will use a local Unix domain socket for connection. If the machine does not have a Unix domain socket, it will attempt to connect to localhost.

port

Port number of the host server, or the socket file name extension for Unix-domain connections.

You can specify multiple port numbers by using a character string separated by commas (,). Multiple port numbers can be specified.

user

Name of the user to be connected. By default, the username is the same as the OS name of the user running the application.

dbname

Database name. The default value is the same as the username.

password

Password to be used if the server requires password authentication.

connect_timeout

Maximum timeout period of the connection, in seconds (written as a decimal integer string). The value 0 or null indicates infinity. You are advised not to set the connection timeout period to a value less than 2 seconds.

client_encoding

Client encoding for the connection. In addition to the values accepted by the corresponding server options, you can use auto to determine the correct encoding from the current environment in the client (the LC_CTYPE environment variable in the Unix system).

tty

This parameter can be ignored. (This parameter was used to specify the location to which the debugging output of the server was sent).

options

Adds command-line options to send to the server at runtime.

application_name

Specifies the current user identity for the application_name parameter.

fallback_application_name

Specifies a backup value for the application_name parameter. This value is used if no value is set for application_name through a connection parameter or the PGAPPNAME environment variable. In a common tool program, if you set a default name but do not want the default name to be overwritten by the user, you can specify a backup value.

keepalives

Specifies whether TCP keepalive is enabled on the client side. The default value is 1, indicating that the function is enabled. The value 0 indicates that the function is disabled. Ignore this parameter for Unix-domain connections.

keepalives_idle

The number of seconds of inactivity after which TCP should send a keepalive message to the server. The value 0 indicates that the default value is used. Ignore this parameter for Unix-domain connections or if keep-alive is disabled.

keepalives_interval

The number of seconds after which a TCP keepalive message that is not acknowledged by the server should be retransmitted. The value 0 indicates that the default value is used. Ignore this parameter for Unix-domain connections or if keep-alive is disabled.

keepalives_count

Controls the number of times that keepalive messages are sent through TCP. The value 0 indicates that the default value is used. Ignore this parameter for Unix-domain connections or if keep-alive is disabled.

tcp_user_timeout

Specifies the maximum duration for which transmitted data can remain unacknowledged before the TCP connection is forcibly closed on an OS that supports the TCP_USER_TIMEOUT socket option. The value 0 indicates that the default value is used. Ignore this parameter for Unix-domain connections.

rw_timeout

Sets the read and write timeout interval of the client connection.

sslmode

Specifies whether to enable SSL encryption.

• disable: SSL connection is disabled.
• allow: If the database server requires SSL connection, SSL connection can be enabled. However, authenticity of the database server will not be verified.
• prefer: If the database supports SSL connection, SSL connection is preferred. However, authenticity of the database server will not be verified.
• require: SSL connection is required and data is encrypted. However, authenticity of the database server will not be verified.
• verify-ca: SSL connection is required. Currently, Windows ODBC does not support certificate-based authentication.
• verify-full: SSL connection is required. Currently, Windows ODBC does not support certificate-based authentication.

sslcompression

If this parameter is set to 1 (default value), the data transmitted over the SSL connection is compressed (this requires that the OpenSSL version be 0.9.8 or later). If it is set to 0, compression will be disabled (this requires OpenSSL 1.0.0 or later). If a connection without SSL is established, this parameter is ignored. If the OpenSSL version in use does not support this parameter, it will also be ignored. Compression takes up CPU time, but it increases throughput when the bottleneck is the network. If CPU performance is a limiting factor, disabling compression can improve response time and throughput.

sslcert

This parameter specifies the file name of the client SSL certificate. If no SSL connection is established, this parameter is ignored.

sslkey

This parameter specifies the location of the key used for the client certificate. It can specify a key obtained from an external "engine" (the engine is a loadable module of OpenSSL). The description of an external engine should consist of a colon-separated engine name and an engine-related key identifier. If no SSL connection is established, this parameter is ignored.

sslrootcert

This parameter specifies the name of a file that contains the SSL Certificate Authority (CA) certificate. If the file exists, the system authenticates the server certificate issued by one of these authorities.

sslcrl

This parameter specifies the file name of the SSL Certificate Revocation List (CRL). If a certificate listed in this file exists, the server certificate authentication will be rejected.

requirepeer

This parameter specifies the OS user of the server, for example, requirepeer=postgres. When a Unix domain socket connection is established, if this parameter is set, the client checks whether the server process is running under the specified username at the beginning of the connection. If not, the connection will be interrupted by an error. This parameter can be used to provide server authentication similar to that of the SSL certificate on TCP/IP connections. (Note that if the Unix domain socket is in /tmp or another public writable location, any user can start a server for listening to the location. Use this parameter to ensure that you are connected to a server that is run by a trusted user.) This option is supported only on platforms that implement the peer authentication method.

krbsrvname

This parameter specifies the Kerberos service name used for GSSAPI authentication. For successful Kerberos authentication, this value must match the service name specified in the server configuration.

gsslib

This parameter specifies the GSS library used for GSSAPI authentication. It is used only in the Windows OS. If this parameter is set to gssapi, the libpq is forced to use the GSSAPI library to replace the default SSPI for authentication.

service

This parameter specifies the name of the service for which the additional parameter is used. It specifies a service name in pg_service.conf that holds the additional connection parameters. This allows the application to specify only one service name so that the connection parameters can be centrally maintained.

authtype

authtype is no longer used, so it is marked as a parameter not to be displayed. It is retained in an array so as not to reject the conninfo string from old applications that might still try to set it.

remote_nodename

Specifies the name of the remote node connected to the local node.

localhost

Specifies the local host in a connection channel.

localport

Specifies the local port in a connection channel.

fencedUdfRPCMode

Specifies whether the fenced UDF RPC protocol uses Unix domain sockets or special socket file names. The default value is 0, indicating that the Unix domain socket mode is used and the file type is .s.PGSQL.%d. To use the fenced UDF mode, set this parameter to 1. In this case, the file type is .s.fencedMaster_unixdomain.

replication

Specifies whether the connection should use replication protocols instead of common protocols. Protocols with this parameter configured are internal protocols used for PostgreSQL replication connections and tools such as pg_basebackup, while they can also be used by third-party applications. The following values, which are case-insensitive, are supported:

• true, on, yes, and 1

Specify whether the physical replication mode is connected.

• database

Specifies that the logical replication mode and the database specified by dbname are connected.

• false, off, no, and 0

  Specify that the connection is a regular connection, which is the default behavior.

In physical or logical replication mode, only simple query protocols can be used.

backend_version

Specifies the backend version to be passed to the remote end.

prototype

Sets the current protocol level. The default value is PROTO_TCP.

enable_ce

Specifies whether a client is allowed to connect to a fully-encrypted database. The default value is 0 (disabled). To enable the encrypted equality query, set this parameter to 1.

connection_info

The value of connection_info is a JSON character string consisting of driver_name, driver_version, driver_path, and os_user.

If the value is not null, use connection_info and ignore connectionExtraInf.

If the value is null, a connection information string related to libpq is generated. When connectionExtraInf is set to false, the value of connection_info consists of only driver_name and driver_version.

connectionExtraInf

Specifies whether the value of connection_info contains extension information. The default value is 0. If the value contains other information, set this parameter to 1.

target_session_attrs

Specifies the type of the host to be connected. The connection is successful only when the host type is the same as the configured value. This parameter is verified only when multiple IP addresses are specified. The rules for setting target_session_attrs are as follows:

• any: All types of hosts can be connected.
• read-write: The connection is set up only when the connected host is readable and writable.
• read-only: Only readable hosts can be connected.
• primary (default value): Only the primary node in the primary/standby systems can be connected.
• standby: Only the standby node in the primary/standby systems can be connected.
• prefer-standby: The system first attempts to find a standby node for connection. If all hosts in the hosts list fail to be connected, try the any mode.