1``` c++
2PGconn *PQconnectdbParams(const char * const *keywords,
3                          const char * const *values,
4                          int expand_dbname);
5```
6
7这个函数使用从两个以`NULL`结尾的数组中取得的参数打开一个新的数据库连接。第一个数组`keywords`被定义为一个字符串数组，每一个元素是一个关键词。第二个数组`values`给出了每个关键词的值。和下面的`PQsetdbLogin`不同，可以在不改变函数签名的情况下扩展参数集合，因此使用这个函数（或者与之相似的非阻塞的`PQconnectStartParams`和`PQconnectPoll`）对于新应用编程要更好。
8
9当前能被识别的参数关键词被列举在参数关键词中。
10
11当`expand_dbname`为非零时，*`dbname`* 关键词的值被允许识别为一个连接字符串。只有 *`dbname`* 的第一次出现会按这种方式扩展，任何后续 *`dbname`* 值会被当做一个普通数据库名处理。有关可能的连接字符串格式的详情可见连接字符串。
12
13被传递的数组可以为空，这样就会使用所有默认参数。也可以只包含一个或几个参数设置。两个参数数组应该在长度上匹配。对于参数数组的处理将会停止于`keywords`数组中第一个非-`NULL`元素。
14
15如果任何一个参数是`NULL`或者一个空字符串，那么将会检查相应的环境变量（见环境变量）。如果该环境变量也没有被设置，那么将使用内建的默认值。
16
17通常，关键词的处理是从这些数组的头部开始并且以索引顺序进行。这样做的效果就是，当关键词有重复时，只会保留最后一个被处理的值。因此，通过小心地放置关键词*`dbname`*，可以决定什么会被一个*`conninfo`*字符串所重载，以及什么不会被重载。

1``` c++
2PGconn *PQconnectdb(const char *conninfo);
3```
4
5这个函数使用从字符串`conninfo`中得到的参数开启一个新的数据库连接。
6
7被传递的字符串可以为空，这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置，还可以包含一个URI。详见连接字符串。

1``` c++
2PGconn *PQsetdbLogin(const char *pghost,
3                     const char *pgport,
4                     const char *pgoptions,
5                     const char *pgtty,
6                     const char *dbName,
7                     const char *login,
8                     const char *pwd);
9```
10
11这是`PQconnectdb`的带有固定参数集合的前辈。它具有相同的功能，不过其中缺失的参数将总是采用默认值。对任意一个固定参数写`NULL`或一个空字符串将会使它采用默认值。
12
13如果*`dbName`*包含一个`=`符号或者具有一个合法的连接URI前缀，它会被当作一个*`conninfo`*字符串，就好像它已经被传递给了`PQconnectdb`，并且剩余的参数则被应用为指定给`PQconnectdbParams`。

1``` c++
2PGconn *PQsetdb(char *pghost,
3                char *pgport,
4                char *pgoptions,
5                char *pgtty,
6                char *dbName);
7```
8
9这是一个调用`PQsetdbLogin`的宏，其中为*`login`*和*`pwd`*参数使用空指针。提供它是为了向后兼容非常老的程序。

1``` c++
2PGconn *PQconnectStartParams(const char * const *keywords,
3                             const char * const *values,
4                             int expand_dbname);
5
6PGconn *PQconnectStart(const char *conninfo);
7
8PalopgPollingStatusType PQconnectPoll(PGconn *conn);
9```
10
11这三个函数被用来开启一个到数据库服务的连接，这样你的应用的执行线程不会因为远程的I/O而被阻塞。这种方法的要点在于等待 I/O完成可能在应用的主循环中发生，而不是在`PQconnectdbParams`或`PQconnectdb`中，并且因此应用能够把这种操作和其他动作并行处理。
12
13在`PQconnectStartParams`中，数据库连接使用从`keywords`和`values`数组中取得的参数创建，并且被`expand_dbname`控制，这和之前描述的`PQconnectdbParams`相同。
14
15在`PQconnectStart`中，数据库连接使用从字符串`conninfo`中取得的参数创建，这和之前描述的`PQconnectdb`相同。
16
17只要满足一些限制，`PQconnectStartParams`或`PQconnectStart`或`PQconnectPoll`都不会阻塞：
18
19  * `hostaddr`和`host`参数必须被合适地使用，以防止做DNS查询。详见参数关键词中这些参数的文档。
20
21  * 如果你调用`PQtrace`，确保你追踪的该流对象不会阻塞。
22
23  * 如后文所述，你必须要确保在调用`PQconnectPoll`之前，套接字处于合适的状态。
24
25要开始无阻塞的连接请求，可调用`PQconnectStart`或者`PQconnectStartParams`。如果结果为空，则libpq无法分配一个新的`PGconn`结构。否则，一个有效的`PGconn`指针会被返回（不过还没有表示一个到数据库的有效连接）。接下来调用`PQstatus(conn)`。如果结果是`CONNECTION_BAD`，则连接尝试已经失败，通常是因为有无效的连接参数。
26
27如果`PQconnectStart`成功，下一个阶段是轮询libpq，这样它能够继续进行连接序列。使用`PQsocket(conn)`来获得该数据库连接底层的套接字描述符（警告：不要假定在`PQconnectPoll`调用之间套接字会保持相同）。这样循环：如果`PQconnectPoll(conn)`上一次返回`PGRES_POLLING_READING`，等到该套接字准备好读取（按照`select()`、`poll()`或类似的系统函数所指示的）。则再次调用`PQconnectPoll(conn)`。反之，如果`PQconnectPoll(conn)`上一次返回`PGRES_POLLING_WRITING`，等到该套接字准备好写入，则再次调用`PQconnectPoll(conn)`。在第一次迭代时，即如果你还没有调用`PQconnectPoll`，行为就像是它上次返回了`PGRES_POLLING_WRITING`。持续这个循环直到`PQconnectPoll(conn)`返回`PGRES_POLLING_FAILED`指示连接过程已经失败，或者返回`PGRES_POLLING_OK`指示连接已经被成功地建立。
28
29在连接期间的任意时刻，该连接的状态可以通过调用`PQstatus`来检查。如果这个调用返回`CONNECTION_BAD`，那么连接过程已经失败。如果该调用返回`CONNECTION_OK`，则该连接已经准备好。如前所述，这些状态同样都可以从`PQconnectPoll`的返回值检测。在一个异步连接过程中（也只有在这个过程中）也可能出现其他状态。这些状态指示该连接过程的当前阶段，并且可能有助于为用户提供反馈。这些状态是：
30
31`CONNECTION_STARTED`  
32:   等待连接被建立。
33
34`CONNECTION_MADE`  
35:   连接 OK，等待发送。
36
37`CONNECTION_AWAITING_RESPONSE`  
38:   等待来自服务的一个回应。
39
40`CONNECTION_AUTH_OK`  
41:   收到认证，等待后端启动结束。
42
43`CONNECTION_SSL_STARTUP`  
44:   协商 SSL 加密。
45
46`CONNECTION_SETENV`  
47:   协商环境驱动的参数设置。
48
49`CONNECTION_CHECK_WRITABLE`  
50:   检查连接是否能够处理写事务。
51
52`CONNECTION_CONSUME`  
53:   消费连接上的任何剩下的响应消息。
54
55注意，尽管这些常数将被保留（为了维护兼容性），一个应用永远不应该依赖这些状态按照特定顺序出现，或者根本就不依赖它们，或者不依赖状态总是这些文档中所说的值。一个应用可能做些这样的事情：
56
57``` c++
58switch(PQstatus(conn))
59{
60        case CONNECTION_STARTED:
61            feedback = "Connecting...";
62            break;
63
64        case CONNECTION_MADE:
65            feedback = "Connected to server...";
66            break;
67.
68.
69.
70        default:
71            feedback = "Connecting...";
72}
73```
74
75在使用`PQconnectPoll`时，连接参数`connect_timeout`会被忽略：判断是否超时是应用的责任。否则，`PQconnectStart`后面跟着后面跟着`PQconnectPoll`循环等效于`PQconnectdb`。
76
77注意当`PQconnectStart`或`PQconnectStart`返回一个非空的指针时，你必须在用完它之后调用`PQfinish`来处理那些结构和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。

1``` c++
2PQconninfoOption *PQconndefaults(void);
3
4typedef struct
5{
6    char   *keyword;   /* 该选项的关键词 */
7    char   *envvar;    /* 依赖的环境变量名 */
8    char   *compiled;  /* 依赖的内建默认值 */
9    char   *val;       /* 选项的当前值，或者 NULL */
10    char   *label;     /* 连接对话框中域的标签 */
11    char   *dispchar;  /* 指示如何在一个连接对话框中显示这个域。值是：
12                          ""        显示输入的值
13                          "*"       口令域 - 隐藏值
14                          "D"       调试选项 - 默认不显示 */
15    int     dispsize;  /* 用于对话框的以字符计的域尺寸 */
16} PQconninfoOption;
17```
18
19返回一个连接选项数组。这可以用来确定用于连接服务的所有可能的`PQconnectdb`选项和它们的当前缺省值。返回值指向一个`PQconninfoOption`结构的数组，该数组以一个包含空`keyword`指针的条目结束。如果无法分配内存，则返回该空指针。注意当前缺省值（`val`域）将依赖于环境变量和其他上下文。一个缺失或者无效的服务文件将会被无声地忽略掉。调用者必须把连接选项当作只读对待。
20
21在处理完选项数组后，把它交给`PQconninfoFree`释放。如果没有这么做，每次调用`PQconndefaults`都会导致一小部分内存泄漏。

1``` c++
2PQconninfoOption *PQconninfo(PGconn *conn);
3```
4
5返回一个连接选项数组。这可以用来确定用于连接服务的所有可能的`PQconnectdb`选项和它们的当前缺省值。返回值指向一个`PQconninfoOption`结构的数组，该数组以一个包含空`keyword`指针的条目结束。上述所有对于`PQconndefaults`的注解也适用于`PQconninfo`的结果。

1``` c++
2PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
3```
4
5解析一个连接字符串并且将结果选项作为一个数组返回，或者在连接字符串有问题时返回`NULL`。这个函数可以用来抽取所提供的连接字符串中的`PQconnectdb`选项。返回值指向一个`PQconninfoOption`结构的数组，该数组以一个包含空`keyword`指针的条目结束。
6
7所有合法选项将出现在结果数组中，但是任何在连接字符串中没有出现的选项的`PQconninfoOption`的`val`会被设置为`NULL`，默认值不会被插入。
8
9如果`errmsg`不是`NULL`，那么成功时`*errmsg`会被设置为`NULL`，否则设置为被`malloc`过的错误字符串以说明该问题（也可以将`*errmsg`设置为`NULL`并且函数返回`NULL`，这表示一种内存耗尽的情况）。
10
11在处理完选项数组后，把它交给`PQconninfoFree`释放。如果没有这么做，每次调用`PQconninfoParse`都会导致一小部分内存泄漏。反过来，如果发生一个错误并且`errmsg`不是`NULL`，确保使用`PQfreemem`释放错误字符串。

1``` c++
2void PQfinish(PGconn *conn);
3```
4
5注意，即使与服务的连接尝试失败（由`PQstatus`指示），应用也应当调用`PQfinish`来释放`PGconn`对象使用的内存。不能在调用`PQfinish`之后再使用`PGconn`指针。

1``` c++
2void PQreset(PGconn *conn);
3```
4
5此函数将关闭与服务的连接，并且使用所有之前使用过的参数尝试重新建立与同一个服务的连接。这可能有助于在工作连接丢失后的错误恢复。

1``` c++
2int PQresetStart(PGconn *conn);
3
4PalopgPollingStatusType PQresetPoll(PGconn *conn);
5```
6
7这些函数将关闭与服务的连接，并且使用所有之前使用过的参数尝试重新建立与同一个服务的连接。这可能有助于在工作连接丢失后的错误恢复。它们和上面的`PQreset`的不同在于它们工作在非阻塞方式。这些函数受到`PQconnectStartParams`、`PQconnectStart`和`PQconnectPoll`相同的限制。
8
9要发起一次连接重置，调用`PQresetStart`。如果它返回 0，那么重置失败。如果返回1，用与使用`PQresetPoll`建立连接的相同方法使用`PQconnectPoll`重置连接。

1``` c++
2PGPing PQpingParams(const char * const *keywords,
3                    const char * const *values,
4                    int expand_dbname);
5```
6
7该函数返回下列值之一：
8
9`PQPING_OK`  
10:   服务正在运行，并且看起来可以接受连接。
11
12`PQPING_REJECT`  
13:   服务正在运行，但是处于一种不允许连接的状态（启动、关闭或崩溃恢复）。
14
15`PQPING_NO_RESPONSE`  
16:   无法联系到服务。这可能表示服务没有运行，或者给定的连接参数中有些错误（例如，错误的端口号），或者有一个网络连接问题（例如，一个防火墙阻断了连接请求）。
17
18`PQPING_NO_ATTEMPT`  
19:   没有尝试联系服务，因为提供的参数显然不正确，或者有一些客户端问题（例如，内存用完）。

1``` c++
2PGPing PQping(const char *conninfo);
3```
4
5返回值和`PQpingParams`相同。

1也接受由逗号分隔的主机名列表，这种情况下将依次尝试列表中的主机名，列表中的空项会选择上述的默认行为。详情请参考指定多个主机。

1使用`hostaddr`代替`host`允许应用能避免一次主机名查找，这对于具有时间约束的应用可能非常重要。不过，GSSAPI 或SSPI 认证方法以及`verify-full` SSL 证书验证还是要求一个主机名。使用的是下列规则：
2
3  * 如果指定了`host`但没有`hostaddr`，则会发生主机名查找（在使用`PQconnectPoll`时，`PQconnectPoll`第一次考虑这个主机名时会发生查找，可能会导致`PQconnectPoll`阻塞可观的时间）。
4
5  * 如果`hostaddr`被指定且没有`host`，`hostaddr`的值给出了服务的网络地址。如果认证方法要求一个主机名则连接尝试将会失败。
6
7  * 如果`host`和`hostaddr`都被指定，`hostaddr`的值给出服务的网络地址。`host`的值将被忽略，除非认证方法要求它，在那种情况下它将被用作主机名。
8
9注意如果`host`不是网络地址`hostaddr`上的服务名，认证很可能会失败。此外，当`host`和`hostaddr`都被指定时，`host`被用来在口令文件中标识该连接（见口令文件）。
10
11逗号分隔的`hostaddr`值列表也被接受，这种情况下将依次尝试列表中的主机。列表中的空项会导致对应的主机名被使用，或者如果对应的主机名也为空时使用默认主机名。详情请参考指定多个主机。
12
13如果没有一个主机名或主机地址，libpq将尝试使用一个本地 Unix域套接字连接，或者在没有 Unix 域套接字的机器上尝试连接到`localhost`。

1支持下列值，大小写无关：
2
3`true`、`on`、`yes`、`1`   
4:   连接进入到物理复制模式。
5
6`database`  
7:   连接进入到逻辑复制模式，连接到`dbname`参数中指定的数据库。
8
9`false`、`off`、`no`、`0`   
10:   该连接是一个常规连接，这是默认行为。
11
12在物理或者逻辑复制模式中，仅能使用简单查询协议。

1`disable`  
2:   只尝试非SSL连接
3
4`allow`  
5:   首先尝试非SSL连接，如果失败再尝试SSL连接
6
7`prefer`（默认）  
8:   首先尝试SSL连接，如果失败再尝试非SSL连接
9
10`require`  
11:   只尝试SSL连接。如果存在一个根 CA 文件，以`verify-ca`被指定的相同方式验证该证书
12
13`verify-ca`  
14:   只尝试SSL连接，并且验证服务证书是由一个可信的证书机构颁发的（`CA`）
15
16`verify-full`  
17:   只尝试SSL连接，验证服务证书是由一个可信的`CA`颁发并且请求的服务主机名匹配证书中的主机名
18
19这些选项如何工作的详细描述见SSL 支持。
20
21对于 Unix域套接字通信，`sslmode`会被忽略。如果PalopgSQL被编译为不带SSL支持，使用选项`require`、`verify-ca`或`verify-full`将导致错误，而选项`allow`和`prefer`将会被接受但是libpq将不会真正尝试SSL连接。

1如果设置为 1，则要求一个到服务的SSL连接（这等效于`sslmode` `require`）。如果服务不接受SSL连接，libpq则将拒绝连接。如果设置为0（默认），libpq将与该服务协商连接类型（等效于`sslmode` `prefer`）。只有PalopgSQL被编译为带有 SSL支持，这个选项才可用。

1现如今SSL压缩被认为是不安全的，因此已经不再推荐使用。OpenSSL1.1.0默认禁用压缩，并且很多操作系统发行版在前面的版本中也将其禁用，因此如果服务不接受压缩，将这个参数设置为on不会有任何效果。另一方面，1.0.0之前的OpenSSL不支持禁用压缩，因此对那些版本来说会忽略这个参数，而是否使用压缩取决于服务。
2
3如果安全性不是主要考虑的问题，在网络是瓶颈的情况下，压缩能够改进吞吐量。如果CPU性能是受限的因素，禁用压缩能提高响应时间和吞吐量。