6.3 Connecting with the Database

Point

It is recommended to use a connection service file to specify connection destinations. In the connection service file, a name (service name) is defined as a set, comprising information such as connection destination information and various types of tuning information set for connections. By using the service name defined in the connection service file when connecting to databases, it is no longer necessary to modify applications when the connection information changes.
Refer to "The Connection Service File" in "Client Interfaces" in the PostgreSQL Documentation for information.
If using a connection service file, perform either of the procedures below:
- Set the service name as a string literal or host variable, as follows:
  tcp:postgresql://?service=my_service
- Set the service name in the environment variable PGSERVICE, and use CONNECT TO DEFAULT

Use the CONNECT statement shown below to create a connection to the database server.

Format

EXEC SQL CONNECT TO target [AS connection-name] [USER user-name];

target

Write in one of the following formats:

dbname@host:port
tcp:postgresql://host:port/dbname[?options]
unix:postgresql://host[:port][/dbname][?options]
(Definition method when using the UNIX domain socket)
SQL string literal containing one of the above formats
Reference to a character variable containing one of the above formats
DEFAULT

user-name

Write in one of the following formats:

username
username/password
username IDENTIFIED BY password
username USING password

Description of the arguments

Argument	Description
dbname	Specify the database name.
host	Specify the host name for the connection destination.
port	Specify the port number for the database server. The default is "27500".
connection-name	Specify connection names to identify connections when multiple connections are to be processed within a single program.
username	Specify the user that will connect with the database. If this is omitted, the name used will be that of the user on the operating system that is executing the application.
password	Specify a password when authentication is required.
options	Specify the following parameter when specifying a time for timeout. Connect parameters with & when specifying more than one. The following shows the values specified for each parameter. connect_timeout Specify the timeout for connections. Specify a value between 0 and 2147483647 (in seconds). There is no limit set if you set 0 or an invalid value. If "1" is specified, the behavior will be the same as when "2" was specified. An error occurs when a connection cannot be established within the specified time. keepalives This enables keepalive. Keepalive is disabled if 0 is specified. Keepalive is enabling when any other value is specified. The default is keepalive enabled. Keepalive causes an error to occur when it is determined that the connection with the database is disabled. keepalives_idle Specify the time until the system starts sending keepalive messages when communication with the database is not being performed. Linux Specify a value between 1 and 32767 (in seconds). The default value of the system is used if this is not specified. Windows(R) Specify a value between 1 and 2147483647 (in seconds). 7200 will be set as default if a value outside this range is specified or if nothing is specified. keepalives_interval Specify the interval between resends when there is no response to keepalive messages. Linux Specify a value between 1 and 32767 (in seconds). The default value of the system is used if this is not specified. Windows(R) Specify a value between 1 and 2147483647 (in seconds). 1 will be set as default if a value outside this range is specified or if nothing is specified. keepalives_count Specify the number of resends for keepalive messages. Linux Specify a value between 1 and 127. The default value of the system is used if this is not specified. Windows(R) The system default value is used irrespective of what is specified for this parameter. tcp_user_timeout After establishing the connection, when sending from the client to the server, if the TCP resend process operates, specify the time until it is considered to be disconnected. Linux Specify a value between 0 and 2147483647 (in millseconds). The default value of the system is used if 0. 0 will be set as default if nothing is specified. Windows(R) Cannot be specified.

Note

If a value other than 0 is specified for the tcp_user_timeout parameter, the waiting time set by the tcp_keepalives_idle parameter and tcp_keepalives_interval parameter will be invalid and the waiting time specified by the tcp_user_timeout parameter will be used.

Code examples for applications

EXEC SQL CONNECT TO tcp:postgresql://sv1:27500/mydb?connect_timeout=20&keepalives_idle=20&keepalives_interval=5&keepalives_count=2&keepalives=1 USER myuser/myuser01;