文档首页/ 云数据库 GaussDB/ 开发指南（分布式_V2.0-10.x）/ 应用程序开发教程/ 基于ecpg开发/ 嵌入式SQL-C程序开发/ 嵌入式SQL语法参考/ CONNECT
更新时间：2026-07-28 GMT+08:00
查看PDF
分享

CONNECT

功能描述

在客户端和SQL服务器之间建立连接。

语法格式

CONNECT TO connection_target [ AS connection_name ] [ USER connection_user ]

参数说明

  • connection_target
    以下形式指定连接的目标服务器：
    • [ database_name ] [ @host ] [ :port ]：通过TCP/IP连接。
    • unix:gaussdb://host [ :port ] / [ database_name ] [ ?connection_option ]：通过Unix域套接字连接。
    • tcp:gaussdb://host [ :port ] / [ database_name ] [ ?connection_option ]：通过TCP/IP连接。
    • SQL string constant：包含上述三种形式之一的值。

    其他connection_target参数介绍请参见ecpg兼容。

  • connection_name

    用于该连接的一个可选标识符，可以在其他命令中引用它。可以是一个SQL标识符或者一个宿主变量。

  • connection_user

    用于数据库连接的用户名/密码。

    以下方式选择一种使用：

    1. user_name/password
    2. user_name SQLIDENTIFIED BY password
    3. user_name USING password

    此参数也能指定用户名和密码。

    用户名和密码可以是SQL标识符、字符串常量或者宿主变量。

上述参数中斜体部分为变量，请根据实际情况进行修改。

示例

指定连接参数变体的示例： 
EXEC SQL CONNECT TO "connectdb" AS main; 
EXEC SQL CONNECT TO "connectdb" AS second; 
EXEC SQL CONNECT TO 'connectdb' AS main; 
EXEC SQL CONNECT TO REGRESSDB1 as main; 
EXEC SQL CONNECT TO connectdb AS :id; 
EXEC SQL CONNECT TO connectdb AS main USER connectuser/connectdb; 
EXEC SQL CONNECT TO connectdb AS main USER connectuser USING "connectdb"; 
EXEC SQL CONNECT TO connectdb AS main; 
EXEC SQL CONNECT TO tcp:gaussdb://localhost/connectdb USER connectuser IDENTIFIED BY connectpw; 
EXEC SQL CONNECT TO tcp:gaussdb://localhost:$PORT/connectdb USER connectuser SQLIDENTIFIED BY connectpw; 
EXEC SQL CONNECT TO unix:gaussdb://localhost/connectdb USER connectuser SQLIDENTIFIED BY "connectpw"; 
EXEC SQL CONNECT TO unix:gaussdb://localhost/connectdb USER connectuser USING "connectpw";

连接语法使用示例：

#include <stdlib.h>
#include <string.h>
#include <stdio.h>

int main(void)
{
    /* 宿主变量定义，定义连接串所需的database、password等字段，实际值应从环境变量或配置文件读取，环境变量需用户自己按需配置；非环境变量情况下可直接赋值字符串。*/
    EXEC SQL BEGIN DECLARE SECTION;
    char* db = (char*)malloc((sizeof(char) * 200));
    char* pw = (char*)malloc((sizeof(char) * 200));
    EXEC SQL END DECLARE SECTION;
    char* db_env = getenv("EXAMPLE_DATABASENAME_ENV");
    char* pw_env =  getenv("EXAMPLE_PASSWD_ENV");
    strcpy(db, db_env);
    strcpy(pw, pw_env);

    /* 连接语句涉及数据库、用户、密码。需提前创建好并有相关操作权限。 */

    /* 连接方式：EXEC SQL CONNECT TO [ database_name ][ @host ][ :port ] [ USER connection_user ] */
    /* case1: 使用默认的本地连接方式，连接数据库为gaussdb库。 */
    EXEC SQL CONNECT TO gaussdb;

    /* case2：使用默认的本地连接方式，连接数据库为gaussdb库, 连接别名为conn1。 */
    EXEC SQL CONNECT TO gaussdb AS conn1;

    /* case3：使用ip+port方式（localhost数据库监听的本地地址，$PORT为数据库监听端口），连接数据库为connectdb库, 指定数据库别名，指定用户密码。$PORT换成真实的端口号 */
    EXEC SQL CONNECT TO connectdb@localhost:$PORT AS conn2 USER connectuser USING :pw;

    /* case4：使用ip+port方式（127.0.0.1数据库监听的本地地址，$PORT为数据库监听端口），连接数据库为connectdb库, 指定数据库别名，指定用户密码。 */
    EXEC SQL CONNECT TO connectdb@127.0.0.1:$PORT AS conn3 USER connectuser SQLIDENTIFIED BY :pw;

    /* case5： 关闭数据库连接 */
    EXEC SQL DISCONNECT gaussdb;
    EXEC SQL DISCONNECT conn1;
    EXEC SQL DISCONNECT conn2;
    EXEC SQL DISCONNECT conn3;

    /* 连接方式：EXEC SQL CONNECT TO <tcp|unix>:gaussdb://host [ :port ]/[ database_name ][ ?connection_option ] */
    /* case1: 通过宿主变量pw、db方式，替换url变量。 */
    strcpy(db, "tcp:gaussdb://localhost/connectdb");
    EXEC SQL CONNECT TO :db USER connectuser USING :pw;

    /* case2: 其中127.0.0.1为数据库侦听ip,connectdb为数据库database。 */
    EXEC SQL CONNECT TO tcp:gaussdb://127.0.0.1/connectdb AS conn4 USER connectuser USING :pw;

    /* case3:其中127.0.0.1为数据库侦听ip,connectdb为数据库database,connect_timeout=14为连接串配置参数。 */
    EXEC SQL CONNECT TO tcp:gaussdb://localhost/connectdb?connect_timeout=14 AS conn5 USER connectuser SQLIDENTIFIED BY :pw;

    /* case4: 关闭所有连接 */
    EXEC SQL CLOSE ALL;

    /* 连接数据库，并执行业务 */
    EXEC SQL CONNECT TO tcp:gaussdb://127.0.0.1/connectdb AS conn4 USER connectuser USING :pw;
    EXEC SQL SET AUTOCOMMIT = ON;
    EXEC SQL CREATE TABLE t1(a INT);
    EXEC SQL INSERT INTO t1 VALUES(1), (2);
    EXEC SQL SELECT a FROM t1 WHERE a > 1;
    EXEC SQL DROP TABLE t1;
    EXEC SQL DISCONNECT CURRENT;
    free(pw);
    free(db);

    return 0;
}
使用宿主变量指定连接参数的示例： 
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(void)
{
    EXEC SQL BEGIN DECLARE SECTION;
    /* 此处dbname、user、pwd应从环境变量或配置文件读取，环境变量需用户自己按需配置；非环境变量情况下可直接赋值字符串 */
    char *dbname     = getenv("EXAMPLE_DBNAME_ENV");    /* 数据库名 */
    char *user       = getenv("EXAMPLE_USERNAME_ENV");  /* 连接用户名 */
    char *pwd        = getenv("EXAMPLE_PASSWD_ENV");    /* 密码 */
    char *connection = "tcp:gaussdb://localhost:$PORT/testdb";  /* 连接字符串 $PORT换成真实的端口号 */
    char ver[256];                  /* 存储版本字符串的缓冲区 */
    EXEC SQL END DECLARE SECTION;

    /* 开启调试日志 */
    ECPGdebug(1, stderr);

    /* 连接到数据库 */
    EXEC SQL CONNECT TO :dbname;
    /* 设置搜索路径 */
    EXEC SQL SELECT pg_catalog.set_config('search_path', '', false);
    EXEC SQL COMMIT;
    /* 查询数据库版本 */
    EXEC SQL SELECT version() INTO :ver;
    /* 断开连接 */
    EXEC SQL DISCONNECT;

    /* 打印数据库版本 */
    printf("version: %s\n", ver);

    /* 使用连接字符串连接到数据库 */
    EXEC SQL CONNECT TO :connection USER :user USING :pwd;
    /* 设置搜索路径 */
    EXEC SQL SELECT pg_catalog.set_config('search_path', '', false);
    EXEC SQL COMMIT;
    /* 查询数据库版本 */
    EXEC SQL SELECT version() INTO :ver;
    /* 断开连接 */
    EXEC SQL DISCONNECT;

    /* 打印数据库版本 */
    printf("version: %s\n", ver);

    return 0;
}

运行结果如下（根据本地环境结果会不一致，此处运行结果仅供参考）：

version: gaussdb (GaussDB Kernel 506.0.0 build 7cc7ccbb) compiled at 2025-02-24 09:17:26 commit 10340 last mr 22441 debug
version: gaussdb (GaussDB Kernel 506.0.0 build 7cc7ccbb) compiled at 2025-02-24 09:17:26 commit 10340 last mr 22441 debug

相关链接

DISCONNECT，SET CONNECTION

相关文档