Help Center/ GaussDB/ Developer Guide(Distributed_V2.0-8.x)/ Application Development Guide/ ECPG-based Development/ Managing Database Connections/ Connecting to a Database
Updated on 2025-08-19 GMT+08:00
View PDF

Connecting to a Database

You can run the following command to connect to the database:

EXEC SQL CONNECT TO target [AS connection-name] [USER user-name];
The target can be declared using the following methods. The italic part is a variable. Change it based on the actual situation.
  • dbname[@hostname][:port]
  • tcp:gaussdb://hostname[:port][/dbname][?options]
  • unix:gaussdb://hostname[:port][/dbname][?options]
  • An SQL string containing one of the above forms

ECPG supports IPv6 addresses. Enclose hostname with square brackets ([]). Examples of IPv6 format are as follows:

db1@[::1]
db1@[::1]:5432
tcp:gaussdb://[::1]/db1
tcp:gaussdb://[::1]:5432/db1
unix:gaussdb://[::1]/db1
unix:gaussdb://[::1]:5432/db1

Currently, ECPG supports the following IPv6 formats:

1. Uppercase abbreviated format

2. Lowercase abbreviated format

3. Uppercase full format

4. Lowercase full format

The IPv6 loopback address is ::1 or 0:0:0:0:0:0:0:1. Therefore, the Unix domain protocol supports only these two IPv6 formats.

There are also different ways to specify the username:
  • username/password
  • username SQLIDENTIFIED BY password
  • username USING password

As mentioned above, the username and password parameters can be an SQL identifier, an SQL string, or a reference to a character variable.

connection_name indicates the connection name. If a program uses only one connection, you can omit it. The most recently opened connection becomes the current connection.

An example is as follows: 
#include <stdlib.h>
EXEC SQL CONNECT TO mydb@sql.mydomain.com;  

EXEC SQL CONNECT TO unix:gaussdb://sql.mydomain.com/mydb AS myconnection USER username;  

EXEC SQL BEGIN DECLARE SECTION; 
/* The values of target, user, and passwd must be read from environment variables or configuration files. Environment variables need to be configured as required. If no environment variable is used, a character string can be directly assigned. */
const char *target = getenv("EXAMPLE_TARGET_ENV"); 
const char *user = getenv("EXAMPLE_USERNAME_ENV"); 
const char *passwd = getenv("EXAMPLE_PASSWD_ENV"); 
EXEC SQL END DECLARE SECTION;  
... 
EXEC SQL CONNECT TO :target USER :user USING :passwd; 
/* or EXEC SQL CONNECT TO :target USER :user/:passwd; */

For details about the complete usage example, see the example of using the connection syntax in CONNECT.

  • In the last form, character variables are referenced. For details about how to reference C variables in SQL statements, see Host Variables.
  • The format of the connection target is not described in the SQL standard. Therefore, to develop a portable application, you can use the method in the last example to encapsulate the connection target string into a variable.
  • For details about the ecpg compatibility, see ecpg Compatibility.
  • If ip-port is specified in the connection statement, username and password must be specified. This rule is determined by the GaussDB kernel communication authentication. If ip-port is not specified, the local $PGPORT (UDS) is used for communication.
  • If the SSL protocol is used for connection, run the tcp:gaussdb://hostname[:port][/dbname][?options] command and set sslmode to disable\require in options.