# 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：包含上述形式之一的值。
  
  
  ![](https://support.huaweicloud.com/distributed-devg-v8-gaussdb/public_sys-resources/caution_3.0-zh-cn.png)
  其他**connection_target** 参数介绍请参见[ecpg兼容](https://support.huaweicloud.com/distributed-devg-v8-gaussdb/gaussdb-12-0245.html#ZH-CN_TOPIC_0000002559105595__zh-cn_topic_0000002558216285_section8505927171)。
  
- **connection_name**
  用于该连接的一个可选标识符，可以在其他命令中引用它。可以是一个SQL标识符或者一个宿主变量。
  
- **connection_user**
  用于数据库连接的用户名。
  使用*user_name* /*password* 、*user_name* SQLIDENTIFIED BY *password* 或者*user_name* USING *password*之一，这个参数也能指定用户名和密码。
  用户名和密码可以是SQL标识符、字符串常量或者宿主变量。
  
![](https://support.huaweicloud.com/distributed-devg-v8-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
上述参数中斜体部分为变量，请根据实际情况进行修改。
#### 示例
指定连接参数变体的示例：
```
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 <stdlib.h>
#include <stdio.h>
int main(void)
{
// 宿主变量定义,定义连接串所需的database、password等字段，实际值应从环境变量或配置文件读取，环境变量需用户自己按需配置；非环境变量情况下可直接赋值字符串。
exec sql begin declare section;
    const int max_str_len = 200;
    char db[max_str_len] = getenv("EXAMPLE_DATABASENAME_ENV");
    char pw[max_str_len] = getenv("EXAMPLE_PASSWD_ENV");
    char new_pw[max_str_len] = getenv("EXAMPLE_NEW_PASSWD_ENV");
exec sql end declare section;
    // 打印调试日志
    ECPGdebug(1, stderr);
    // 连接语句涉及数据库、用户、密码。需提前创建好并有相关操作权限。
    // 连接方式：EXEC SQL CONNECT TO [ database_name ][ @host ][ :port ] [ USER connection_user ]
    // case1: 使用默认的本地连接方式，连接数据库为postgres库。
    exec sql connect to postgres;
    // case2：使用默认的本地连接方式，连接数据库为postgres库, 连接别名为conn1。
    exec sql connect to postgres as conn1;
    // case3：使用ip+port方式(localhost数据库监听的本地地址，$PORT为数据库监听端口)，连接数据库为connectdb库, 指定数据库别名，指定用户密码。
    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 postgres;
    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(pw, new_pw);
    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;
    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";  /* 连接字符串 */ 
    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; 
}
```
#### 相关链接
[DISCONNECT](https://support.huaweicloud.com/distributed-devg-v8-gaussdb/gaussdb-12-0186.html#ZH-CN_TOPIC_0000002527825858)，[SET CONNECTION](https://support.huaweicloud.com/distributed-devg-v8-gaussdb/gaussdb-12-0192.html#ZH-CN_TOPIC_0000002558945673)