libpq-connect.zh.md

## 34.1.数据库连接控制功能

[34.1.1. 连结字符串](libpq-connect.html#LIBPQ-CONNSTRING)

[34.1.2. 参数关键字](libpq-connect.html#LIBPQ-PARAMKEYWORDS)

以下函数处理与PostgreSQL后端服务器的连接。一个应用程序可以同时打开多个后端连接。（这样做的一个原因是访问多个数据库。）每个连接都由一个`PGconn`[](<>)对象，它是从函数中获取的[`PQconnectdb`](libpq-connect.html#LIBPQ-PQCONNECTDB),[`PQconnectdbParams`](libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS)或[`PQsetdbLogin`](libpq-connect.html#LIBPQ-PQSETDBLOGIN)。请注意，这些函数将始终返回非空对象指针，除非内存太少，甚至无法分配`PGconn`对象这个[`PQ状态`](libpq-status.html#LIBPQ-PQSTATUS)在通过连接对象发送查询之前，应该调用函数来检查成功连接的返回值。

### 警告

如果不受信任的用户可以访问未采用[安全模式使用模式](ddl-schemas.html#DDL-SCHEMAS-PATTERNS)，通过从中删除可公开写入的架构开始每个会话`搜索路径`.可以设置参数关键字`选项`重视`-csearch_path=`.或者，你可以发布`PQexec(*`康涅狄格州`*，“选择pg_目录。设置_配置（'search_path'，''，false）”）`连接后。这种考虑并不是libpq特有的；它适用于执行任意SQL命令的每个接口。

### 警告

在Unix上，用开放的libpq连接分叉进程可能会导致不可预测的结果，因为父进程和子进程共享相同的套接字和操作系统资源。因此，不建议使用这种用法，尽管`执行官`从子进程加载新的可执行文件是安全的。

`PQconnectdbParams`[](<>)

与数据库服务器建立新连接。

```
PGconn *PQconnectdbParams(const char * const *keywords,
                          const char * const *values,
                          int expand_dbname);
```

此函数使用从两个数据库中获取的参数打开一个新的数据库连接`无效的`-端接阵列。第一个，`关键词`，定义为字符串数组，每个字符串都是一个关键字。第二个，`价值观`，给出每个关键字的值。不像[`PQsetdbLogin`](libpq-connect.html#LIBPQ-PQSETDBLOGIN)下面，参数集可以在不更改函数签名的情况下进行扩展，因此使用此函数（或其非阻塞类似物[`连接星图`](libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS)和`民意测验`)是新应用程序编程的首选。

中列出了当前识别的参数关键字[第34.1.2节](libpq-connect.html#LIBPQ-PARAMKEYWORDS).

传递的数组可以为空以使用所有默认参数，也可以包含一个或多个参数设置。它们的长度必须匹配。处理将首先停止`无效的`进入`关键词`大堆此外，如果`价值观`与非-`无效的` `关键词`参赛作品是`无效的`或空字符串，则忽略该条目，并继续处理下一对数组条目。

什么时候`展开_dbname`为非零，第一个的值*`库名`*检查关键字是否为*连接字符串*。如果是，则将其“扩展”为从字符串中提取的各个连接参数。如果该值包含等号，则该值被视为连接字符串，而不仅仅是数据库名称(`=`)或者它以URI模式指示符开头。（有关连接字符串格式的更多详细信息，请参见[第34.1.1节](libpq-connect.html#LIBPQ-CONNSTRING)）只有第一次出现*`库名`*被这样对待；任何后续的*`库名`*参数作为普通数据库名称处理。

通常，参数数组从头到尾都会被处理。如果有任何关键字被重复，最后一个值（即`无效的`或空）使用。当在连接字符串中找到的关键字与在连接字符串中出现的关键字冲突时，此规则尤其适用`关键词`大堆因此，程序员可以确定数组项是否可以覆盖或被从连接字符串中获取的值覆盖。在展开的*`库名`*条目可以被连接字符串的字段覆盖，而这些字段又被后面出现的数组条目覆盖*`库名`*（但同样，仅当这些条目提供非空值时）。

在处理所有数组项和任何扩展的连接字符串后，任何未设置的连接参数都将用默认值填充。如果未设置参数对应的环境变量（请参见[第34.15节](libpq-envars.html))设置，则使用其值。如果环境变量也未设置，则使用参数的内置默认值。

`PQconnectdb`[](<>)

与数据库服务器建立新连接。

```
PGconn *PQconnectdb(const char *conninfo);
```

此函数使用从字符串中获取的参数打开一个新的数据库连接`康宁`.

传递的字符串可以为空以使用所有默认参数，也可以包含一个或多个由空格分隔的参数设置，或者包含URI。看见[第34.1.1节](libpq-connect.html#LIBPQ-CONNSTRING)详细信息。

`PQsetdbLogin`[](<>)

与数据库服务器建立新连接。

```
PGconn *PQsetdbLogin(const char *pghost,
                     const char *pgport,
                     const char *pgoptions,
                     const char *pgtty,
                     const char *dbName,
                     const char *login,
                     const char *pwd);
```

这是它的前身[`PQconnectdb`](libpq-connect.html#LIBPQ-PQCONNECTDB)有一组固定的参数。它具有相同的功能，只是缺少的参数将始终采用默认值。写`无效的`或者为任何一个要默认的固定参数设置一个空字符串。

如果*`数据库名`*包含一个`=`签名或具有有效的连接URI前缀，则将其视为*`康宁`*字符串的方式与传递给[`PQconnectdb`](libpq-connect.html#LIBPQ-PQCONNECTDB)，剩下的参数将按照[`PQconnectdbParams`](libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS).

`pgtty`不再使用，传递的任何值都将被忽略。

`PQsetdb`[](<>)

与数据库服务器建立新连接。

```
PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName);
```

这是一个调用[`PQsetdbLogin`](libpq-connect.html#LIBPQ-PQSETDBLOGIN)对于*`登录`*和*`pwd`*参数。它是为了向后兼容非常旧的程序而提供的。

`连接星图`[](<>)\
`连接开始`[](<>)\
`民意测验`[](<>)

[](<>)以非阻塞方式连接到数据库服务器。

```
PGconn *PQconnectStartParams(const char * const *keywords,
                             const char * const *values,
                             int expand_dbname);

PGconn *PQconnectStart(const char *conninfo);

PostgresPollingStatusType PQconnectPoll(PGconn *conn);
```

这三个函数用于打开与数据库服务器的连接，以便在执行时不会在远程I/O上阻塞应用程序的执行线程。这种方法的要点是，等待I/O完成可以发生在应用程序的主循环中，而不是在内部[`PQconnectdbParams`](libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS)或[`PQconnectdb`](libpq-connect.html#LIBPQ-PQCONNECTDB)，因此应用程序可以与其他活动并行管理此操作。

具有[`连接星图`](libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS)，使用从数据库中获取的参数进行数据库连接`关键词`和`价值观`数组，并由`展开_dbname`，如上所述[`PQconnectdbParams`](libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS).

具有`连接开始`，使用从字符串中获取的参数建立数据库连接`康宁`如上所述[`PQconnectdb`](libpq-connect.html#LIBPQ-PQCONNECTDB).

也不[`连接星图`](libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS)也没有`连接开始`也没有`民意测验`将被阻止，只要满足一些限制：

-   这个`霍斯塔德酒店`参数必须适当使用，以防止进行DNS查询。请参阅中此参数的文档[第34.1.2节](libpq-connect.html#LIBPQ-PARAMKEYWORDS)详细信息。

-   如果你打电话[`PQtrace`](libpq-control.html#LIBPQ-PQTRACE)，确保跟踪到的流对象不会被阻止。

-   在调用之前，必须确保套接字处于适当的状态`民意测验`，如下所述。

    要开始非阻塞连接请求，请调用`连接开始`或[`连接星图`](libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS)。如果结果为空，则libpq无法分配新的`PGconn`结构否则，一个有效的`PGconn`返回指针（尽管尚未表示到数据库的有效连接）。下一个电话`PQstatus（康涅狄格州）`.如果结果是`连接不好`，连接尝试已失败，通常是因为连接参数无效。

    如果`连接开始`或[`连接星图`](libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS)如果成功，下一步是轮询libpq，以便继续连接序列。使用`电源插座（康涅狄格州）`获取数据库连接基础套接字的描述符。（注意：不要假设插座在整个过程中保持不变。）`民意测验`电话。）这样循环：如果`康涅狄格州`上次回来`PGRES_轮询_读取`，等待套接字准备好读取（如所示）`选择（）`, `投票`，或类似的系统功能）。然后打电话`康涅狄格州`再一次相反，如果`康涅狄格州`上次回来`PGRES_POLLING_写作`，等待套接字准备好写入，然后调用`康涅狄格州`再一次在第一次迭代中，即如果您尚未调用`民意测验`，就好像它最后一次回来一样`PGRES_POLLING_写作`.继续这个循环直到`康涅狄格州`返回`PGRES_轮询_失败`，表示连接过程失败，或`PGRES_POLLING_OK`，表示已成功建立连接。

    在连接过程中的任何时候，都可以通过调用[`PQ状态`](libpq-status.html#LIBPQ-PQSTATUS).如果这个电话回来`连接不好`，则连接过程失败；如果电话回音`好的`，则连接已准备就绪。这两种状态都可以从`民意测验`，如上所述。其他状态也可能在异步连接过程期间（并且仅在异步连接过程期间）发生。这些指示连接过程的当前阶段，例如，可能有助于向用户提供反馈。这些状态是：

`连接已启动`

正在等待连接。

`连接!`

连接正常；等待发送。

`连接等待响应`

正在等待服务器的响应。

`连接_验证_确定`

接收认证；正在等待后端启动完成。

`连接\u SSL\u启动`

协商SSL加密。

`连接_SETENV`

协商环境驱动的参数设置。

`连接检查可写`

检查连接是否能够处理写事务。

`连接消耗`

正在使用连接上的所有剩余响应消息。

请注意，尽管这些常量将保持不变（为了保持兼容性），但应用程序永远不应该依赖于这些常量以特定顺序出现，或者根本不应该依赖于这些常量，或者依赖于状态始终是这些记录的值之一。应用程序可能会执行以下操作：

```
switch(PQstatus(conn))
{
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
            feedback = "Connecting...";
}
```

这个`连接超时`使用时忽略连接参数`民意测验`; 应用程序有责任决定是否经过了过长的时间。否则`连接开始`然后是`民意测验`循环相当于[`PQconnectdb`](libpq-connect.html#LIBPQ-PQCONNECTDB).

注意，当`连接开始`或[`连接星图`](libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS)返回非空指针，必须调用[`PQfinish`](libpq-connect.html#LIBPQ-PQFINISH)当你完成它，以便处置该结构和任何相关的内存块。即使连接尝试失败或放弃，也必须这样做。

`pqconn默认值`[](<>)

返回默认连接选项。

```
PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* The keyword of the option */
    char   *envvar;    /* Fallback environment variable name */
    char   *compiled;  /* Fallback compiled in default value */
    char   *val;       /* Option's current value, or NULL */
    char   *label;     /* Label for field in connect dialog */
    char   *dispchar;  /* Indicates how to display this field
                          in a connect dialog. Values are:
                          ""        Display entered value as is
                          "*"       Password field - hide value
                          "D"       Debug option - don't show by default */
    int     dispsize;  /* Field size in characters for dialog */
} PQconninfoOption;
```

返回连接选项数组。这可以用来确定所有可能的[`PQconnectdb`](libpq-connect.html#LIBPQ-PQCONNECTDB)选项及其当前默认值。返回值指向`pQConInfoOption`结构，该结构以具有null的条目结尾`关键词`指针。如果无法分配内存，则返回空指针。请注意，当前的默认值(`瓦尔`字段）将取决于环境变量和其他上下文。丢失或无效的服务文件将被静默忽略。呼叫者必须将连接选项数据视为只读。

处理完选项数组后，将其传递给[`免费的`](libpq-misc.html#LIBPQ-PQCONNINFOFREE)。如果不这样做，则每次调用[`pqconn默认值`](libpq-connect.html#LIBPQ-PQCONNDEFAULTS).

`PQconninfo`[](<>)

返回实时连接使用的连接选项。

```
PQconninfoOption *PQconninfo(PGconn *conn);
```

返回连接选项数组。这可以用来确定所有可能的[`PQconnectdb`](libpq-connect.html#LIBPQ-PQCONNECTDB)选项和用于连接到服务器的值。返回值指向`pQConInfoOption`结构，该结构以具有null的条目结尾`关键词`指针。以上所有注释仅供参考[`pqconn默认值`](libpq-connect.html#LIBPQ-PQCONNDEFAULTS)也适用于以下结果：[`PQconninfo`](libpq-connect.html#LIBPQ-PQCONNINFO).

`pqconnsporse`[](<>)

从提供的连接字符串返回已解析的连接选项。

```
PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
```

解析连接字符串并将结果选项作为数组返回；或返回`无效的`如果连接字符串有问题。此函数可用于提取[`PQconnectdb`](libpq-connect.html#LIBPQ-PQCONNECTDB)提供的连接字符串中的选项。返回值指向`pQConInfoOption`结构，该结构以具有null的条目结尾`关键词`指针。

所有合法选项都将出现在结果数组中，但`pQConInfoOption`对于连接字符串中不存在的任何选项`瓦尔`开始`无效的`; 不会插入默认值。

如果`嗯`不是`无效的`然后`*嗯`即将`无效的`在成功的时候，否则就要失败`马洛克`“d解释问题的错误字符串。”。（也有可能是`*嗯`着手`无效的`以及返回的函数`无效的`; 这表示内存不足。）

处理完选项数组后，将其传递给[`免费的`](libpq-misc.html#LIBPQ-PQCONNINFOFREE)。如果不这样做，则每次调用[`pqconnsporse`](libpq-connect.html#LIBPQ-PQCONNINFOPARSE).相反，如果发生错误`嗯`不是`无效的`，请确保使用释放错误字符串[`PQfreemem`](libpq-misc.html#LIBPQ-PQFREEMEM).

`PQfinish`[](<>)

关闭与服务器的连接。还可以释放用户使用的内存`PGconn`对象

```
void PQfinish(PGconn *conn);
```

请注意，即使服务器连接尝试失败（如[`PQ状态`](libpq-status.html#LIBPQ-PQSTATUS))，应用程序应调用[`PQfinish`](libpq-connect.html#LIBPQ-PQFINISH)释放服务器使用的内存`PGconn`对象这个`PGconn`之后不得再次使用指针[`PQfinish`](libpq-connect.html#LIBPQ-PQFINISH)已经打过电话了。

`PQreset`[](<>)

重置与服务器的通信通道。

```
void PQreset(PGconn *conn);
```

此功能将关闭与服务器的连接，并尝试使用之前使用的所有相同参数建立新连接。如果工作连接丢失，这可能有助于错误恢复。

`重新启动`[](<>)\
`民意测验`[](<>)

以非阻塞方式重置与服务器的通信通道。

```
int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);
```

这些功能将关闭与服务器的连接，并尝试使用之前使用的所有相同参数建立新连接。如果工作连接丢失，这对于错误恢复非常有用。它们不同于[`PQreset`](libpq-connect.html#LIBPQ-PQRESET)（上图）因为它们以非阻塞的方式行动。这些功能受到的限制与[`连接星图`](libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS), `连接开始`和`民意测验`.

要启动连接重置，请致电[`重新启动`](libpq-connect.html#LIBPQ-PQRESETSTART).如果返回0，则重置失败。如果返回1，则使用`民意测验`与使用创建连接的方式完全相同`民意测验`.

`PQpingParams`[](<>)

[`PQpingParams`](libpq-connect.html#LIBPQ-PQPINGPARAMS)报告服务器的状态。它接受与的连接参数相同的连接参数[`PQconnectdbParams`](libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS)，如上所述。获取服务器状态不需要提供正确的用户名、密码或数据库名称值；但是，如果提供的值不正确，服务器将记录失败的连接尝试。

```
PGPing PQpingParams(const char * const *keywords,
                    const char * const *values,
                    int expand_dbname);
```

该函数返回以下值之一：

`好的`

服务器正在运行，似乎正在接受连接。

`PQPING_拒绝`

服务器正在运行，但处于不允许连接的状态（启动、关闭或崩溃恢复）。

`PQPING_无响应`

无法联系服务器。这可能表明服务器没有运行，或者给定的连接参数有问题（例如，错误的端口号），或者存在网络连接问题（例如，防火墙阻止连接请求）。

`PQPING_无尝试`

没有尝试联系服务器，因为提供的参数明显不正确，或者存在一些客户端问题（例如，内存不足）。

`PQping`[](<>)

[`PQping`](libpq-connect.html#LIBPQ-PQPING)报告服务器的状态。它接受与的连接参数相同的连接参数[`PQconnectdb`](libpq-connect.html#LIBPQ-PQCONNECTDB)，如上所述。获取服务器状态不需要提供正确的用户名、密码或数据库名称值；但是，如果提供的值不正确，服务器将记录失败的连接尝试。

```
PGPing PQping(const char *conninfo);
```

返回值与的相同[`PQpingParams`](libpq-connect.html#LIBPQ-PQPINGPARAMS).

`PQsetSSLKeyPassHook_OpenSSL`[](<>)

`PQsetSSLKeyPassHook_OpenSSL`允许应用程序覆盖libpq的[加密客户端证书密钥文件的默认处理](libpq-ssl.html#LIBPQ-SSL-CLIENTCERT)使用[sslpassword](libpq-connect.html#LIBPQ-CONNECT-SSLPASSWORD)或者互动提示。

```
void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
```

应用程序将指针传递给带有签名的回调函数：

```
int callback_fn(char *buf, int size, PGconn *conn);
```

然后哪个libpq将调用*而不是*它的默认`PQdefaultSSLKeyPassHook_OpenSSL`汉德勒。回调函数应该确定密钥的密码，并将其复制到结果缓冲区*`缓冲器`*大小*`大小`*.绳子*`缓冲器`*必须以null结尾。回调必须返回存储在中的密码长度*`缓冲器`*不包括空终止符。失败时，应设置回调`buf[0]='\0'`然后返回0。看见`PQdefaultSSLKeyPassHook_OpenSSL`以libpq的源代码为例。

如果用户指定了显式密钥位置，其路径将为`康涅狄格州->斯尔基`当调用回调时。如果正在使用默认密钥路径，则该值将为空。对于作为引擎说明符的密钥，由引擎实现决定它们是使用OpenSSL密码回调还是定义自己的处理。

应用回调可以选择将未处理的案例委托给`PQdefaultSSLKeyPassHook_OpenSSL`，或者先调用它，如果它返回0，则尝试其他操作，或者完全覆盖它。

回拨*不能*例外情况下，脱离正常流量控制，`longjmp（…）`等。它必须正常返回。

`PQgetSSLKeyPassHook_OpenSSL`[](<>)

`PQgetSSLKeyPassHook_OpenSSL`返回当前客户端证书密钥密码挂钩，或`无效的`如果没有设置。

```
PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
```

### 34.1.1.连接字符串

[](<>)[](<>)

几个libpq函数解析用户指定的字符串以获取连接参数。这些字符串有两种公认的格式：普通关键字/值字符串和URI。URI通常遵循[RFC 3986](https://tools.ietf.org/html/rfc3986)，但允许使用多主机连接字符串，如下所述。

#### 34.1.1.1.关键字/值连接字符串

在关键字/值格式中，每个参数设置的格式为*`关键词`* `=` *`价值`*，设置之间有空格。设置等号周围的空格是可选的。例如，要写入空值或包含空格的值，请将其用单引号括起来`关键字='a value'`.值中的单引号和反斜杠必须用反斜杠转义，即。，`\'`和`\\`.

例子：

```
host=localhost port=5432 dbname=mydb connect_timeout=10
```

中列出了识别的参数关键字[第34.1.2节](libpq-connect.html#LIBPQ-PARAMKEYWORDS).

#### 34.1.1.2.连接URI

连接URI的一般形式是：

```
postgresql://[userspec@][hostspec][/dbname][?paramspec]

where userspec is:

user[:password]

and hostspec is:

[host][:port][,...]

and paramspec is:

name=value[&...]
```

URI方案指示符可以是`postgresql：//`或`博士后：//`。剩余的每个URI部分都是可选的。以下示例说明了有效的URI语法：

```
postgresql://
postgresql://localhost
postgresql://localhost:5433
postgresql://localhost/mydb
postgresql://user@localhost
postgresql://user:secret@localhost
postgresql://other@localhost/otherdb?connect_timeout=10&application_name=myapp
postgresql://host1:123,host2:456/somedb?target_session_attrs=any&application_name=myapp
```

通常出现在URI层次结构部分的值也可以作为命名参数给出。例如：

```
postgresql:///mydb?host=localhost&port=5433
```

所有命名参数必须与中列出的关键字匹配[第34.1.2节](libpq-connect.html#LIBPQ-PARAMKEYWORDS)，除了为了与JDBC连接URI兼容之外`ssl=true`翻译成`sslmode=require`.

连接URI需要使用[百分比编码](https://tools.ietf.org/html/rfc3986#section-2.1)如果其任何部分包含具有特殊含义的符号。下面是一个例子，其中等号(`=`)被替换为`%3D`还有空间特征`%20`:

```
postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
```

主机部分可以是主机名或IP地址。要指定IPv6地址，请将其括在方括号中：

```
postgresql://[2001:db8::1234]/database
```

主体零件的解释如参数所述[主办](libpq-connect.html#LIBPQ-CONNECT-HOST)。特别是，如果主机部分为空或看起来像绝对路径名，则选择Unix域套接字连接，否则会启动TCP/IP连接。但是，请注意，斜杠是URI层次结构部分中的保留字符。因此，要指定非标准的Unix域套接字目录，可以省略URI的主机部分并将主机指定为命名参数，或者对URI的主机部分的路径进行百分比编码：

```
postgresql:///dbname?host=/var/lib/postgresql
postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
```

可以在一个URI中指定多个主机组件，每个组件都有一个可选的端口组件。表单的URI`Postgresql://host1:port1，host2:port2，host3:port3/`相当于以下形式的连接字符串`主机=主机1，主机2，主机3端口=端口1，端口2，端口3`。如下文所述，将依次尝试每个主机，直到成功建立连接。

#### 34.1.1.3.指定多个主机

可以指定要连接的多个主机，以便按给定顺序尝试它们。在关键字/值格式中`主办`, `霍斯塔德酒店`和`港口城市`选项接受逗号分隔的值列表。在指定的每个选项中必须给出相同数量的元素，例如，第一个`霍斯塔德酒店`对应于第一个主机名，第二个`霍斯塔德酒店`对应于第二个主机名，依此类推。如果只有一个例外的话`港口城市`如果指定，则它适用于所有主机。

在连接URI格式中，可以列出多个`主持人：波特`表中以逗号分隔的对`主办`URI的组件。

在这两种格式中，一个主机名都可以转换为多个网络地址。一个常见的例子是同时具有IPv4和IPv6地址的主机。

当指定了多个主机时，或者当一个主机名被转换为多个地址时，将按顺序尝试所有主机和地址，直到其中一个成功。如果无法联系到任何主机，则连接将失败。如果成功建立连接，但身份验证失败，则不会尝试列表中的其余主机。

如果使用密码文件，您可以为不同的主机使用不同的密码。列表中的每个主机的所有其他连接选项都相同；例如，不可能为不同的主机指定不同的用户名。

### 34.1.2.参数关键字

当前识别的参数关键字为：

`主办`

要连接到的主机的名称。[](<>)如果主机名看起来像一个绝对路径名，则它指定Unix域通信，而不是TCP/IP通信；该值是存储套接字文件的目录的名称。（在Unix上，绝对路径名以斜杠开头。在Windows上，也可以识别以驱动器号开头的路径。）如果主机名以`@`，它被作为抽象名称空间中的Unix域套接字（当前Linux和Windows支持）。当`主办`未指定或为空，是为了连接到Unix域套接字[](<>)在里面`/tmp`（或者构建PostgreSQL时指定的任何套接字目录）。在Windows和没有Unix域套接字的计算机上，默认设置是连接到`本地服务器`.

也接受以逗号分隔的主机名列表，在这种情况下，列表中的每个主机名都会按顺序进行尝试；列表中的一个空项将选择如上所述的默认行为。看见[第34.1.1.3节](libpq-connect.html#LIBPQ-MULTIPLE-HOSTS)详细信息。

`霍斯塔德酒店`

要连接的主机的数字IP地址。这应该是标准的IPv4地址格式，例如。，`172.28.40.9`。如果您的计算机支持IPv6，您也可以使用这些地址。当为此参数指定非空字符串时，始终使用TCP/IP通信。如果未指定此参数，则`主办`将被查找以找到相应的IP地址——或者，如果`主办`指定一个IP地址，该值将直接使用。

使用`霍斯塔德酒店`允许应用程序避免主机名查找，这在有时间限制的应用程序中可能很重要。但是，GSSAPI或SSPI身份验证方法以及`验证完整`SSL证书验证。使用以下规则：

-   如果`主办`没有指定`霍斯塔德酒店`，将进行主机名查找。（使用时）`民意测验`，当`民意测验`首先考虑这个主机名，它可能会导致`民意测验`要在相当长的时间内阻塞。）

-   如果`霍斯塔德酒店`没有指定`主办`，为`霍斯塔德酒店`提供服务器网络地址。如果身份验证方法需要主机名，则连接尝试将失败。

-   如果两者都有`主办`和`霍斯塔德酒店`如果已指定，则`霍斯塔德酒店`提供服务器网络地址。价值`主办`被忽略，除非身份验证方法需要它，在这种情况下，它将被用作主机名。

    请注意，如果`主办`不是网络地址处的服务器名称`霍斯塔德酒店`.而且，当两者都`主办`和`霍斯塔德酒店`指定的，`主办`用于在密码文件中标识连接（请参阅[第34.16节](libpq-pgpass.html)).

    以逗号分隔的列表`霍斯塔德酒店`值也被接受，在这种情况下，列表中的每个主机都会按顺序进行尝试。列表中的空项会导致使用相应的主机名，如果该主机名为空，则使用默认主机名。看见[第34.1.1.3节](libpq-connect.html#LIBPQ-MULTIPLE-HOSTS)详细信息。

    没有主机名或主机地址，libpq将使用本地Unix域套接字进行连接；或者在Windows和没有Unix域套接字的计算机上，它将尝试连接到`本地服务器`.

`港口城市`

服务器主机上要连接的端口号，或Unix域连接的套接字文件扩展名。[](<>)如果系统中提供了多个主机`主办`或`霍斯塔德酒店`参数，此参数可以指定与主机列表长度相同的端口的逗号分隔列表，也可以指定用于所有主机的单个端口号。空字符串或逗号分隔列表中的空项指定生成PostgreSQL时建立的默认端口号。

`库名`

数据库名称。默认值与用户名相同。在某些情况下，会检查扩展格式的值；看见[第34.1.1节](libpq-connect.html#LIBPQ-CONNSTRING)更多关于这些的细节。

`使用者`

连接为的PostgreSQL用户名。默认值与运行应用程序的用户的操作系统名称相同。

`暗语`

如果服务器要求密码身份验证，则使用密码。

`密码文件`

指定用于存储密码的文件名（请参见[第34.16节](libpq-pgpass.html)).默认为`~/.pgpass`或`%APPDATA%\postgresql\pgpass。形态`在微软Windows上。（如果此文件不存在，则不会报告错误。）

`通道绑定`

此选项控制客户端对通道绑定的使用。一套`要求`表示连接必须使用通道绑定，`更喜欢`意味着客户端将选择通道绑定（如果可用），以及`使残废`防止使用通道绑定。默认值是`更喜欢`如果PostgreSQL是使用SSL支持编译的；否则默认为`使残废`.

通道绑定是服务器向客户机进行身份验证的一种方法。仅支持通过SSL连接使用PostgreSQL 11或更高版本的服务器`快滚`身份验证方法。

`连接超时`

连接时等待的最长时间，以秒为单位（以十进制整数写入，例如。，`10`).零、负或未指定表示无限期等待。允许的最小超时为2秒，因此值为`1.`被解释为`2.`。此超时分别适用于每个主机名或IP地址。例如，如果指定两个主机和`连接超时`是5，如果在5秒内没有连接，每个主机将超时，因此等待连接的总时间可能长达10秒。

`客户机编码`

这就决定了`客户机编码`此连接的配置参数。除了相应服务器选项接受的值之外，还可以使用`汽车`根据客户端中的当前区域设置确定正确的编码(`LC_CTYPE`Unix系统上的环境变量）。

`选项`

指定要在连接开始时发送到服务器的命令行选项。例如，将其设置为`-c geqo=关闭`设置会话的`盖库`参数到`关`。此字符串中的空格被视为分隔命令行参数，除非用反斜杠转义(`\`); 写`\\`表示文字反斜杠。有关可用选项的详细讨论，请咨询[第 20 章](runtime-config.html).

`应用名称`

指定一个值[应用\_姓名](runtime-config-logging.html#GUC-APPLICATION-NAME)配置参数。

`fallback_application_name`

为[应用\_姓名](runtime-config-logging.html#GUC-APPLICATION-NAME)配置参数。如果没有为`应用名称`通过连接参数或`PGAPPNAME`环境变量。在希望设置默认应用程序名称但允许用户覆盖它的通用实用程序中，指定备用名称很有用。

`保活`

控制是否使用客户端 TCP keepalive。默认值为 1，表示开启，但如果不需要保活，您可以将其更改为 0，表示关闭。对于通过 Unix 域套接字建立的连接，此参数将被忽略。

`keepalives_idle`

控制 TCP 应向服务器发送 keepalive 消息的不活动秒数。零值使用系统默认值。对于通过 Unix 域套接字建立的连接，或者如果禁用了 keepalives，则忽略此参数。它仅在以下系统上受支持`TCP_KEEPIDLE`或等效的套接字选项可用，并且在 Windows 上；在其他系统上，它没有影响。

`keepalives_interval`

控制应该重新传输未被服务器确认的 TCP keepalive 消息的秒数。零值使用系统默认值。对于通过 Unix 域套接字建立的连接，或者如果禁用了 keepalives，则忽略此参数。它仅在以下系统上受支持`TCP_KEEPINTVL`或等效的套接字选项可用，并且在 Windows 上；在其他系统上，它没有影响。

`keepalives_count`

控制在客户端与服务器的连接被认为死之前可能丢失的 TCP 保持连接的数量。零值使用系统默认值。对于通过 Unix 域套接字建立的连接，或者如果禁用了 keepalives，则忽略此参数。它仅在以下系统上受支持`TCP_KEEPCNT`或提供等效的插座选项；在其他系统上，它没有影响。

`tcp_user_timeout`

控制在强制关闭连接之前传输的数据可能保持未确认的毫秒数。零值使用系统默认值。对于通过 Unix 域套接字建立的连接，此参数将被忽略。它仅在以下系统上受支持`TCP_USER_TIMEOUT`可用；在其他系统上，它没有影响。

`tty`

忽略（以前，这指定将服务器调试输出发送到何处）。

`复制`

此选项确定连接是否应使用复制协议而不是普通协议。这就是 PostgreSQL 复制连接以及 pg 等工具\_basebackup 在内部使用，但也可以由第三方应用程序使用。有关复制协议的说明，请参阅[第 53.4 节](protocol-replication.html).

支持以下不区分大小写的值：

`真的`,`在`,`是的`,`1`

连接进入物理复制模式。

`数据库`

连接进入逻辑复制模式，连接到指定的数据库`数据库名称`范围。

`错误的`,`离开`,`不`,`0`

连接是常规连接，这是默认行为。

在物理或逻辑复制模式下，只能使用简单查询协议。

`gssencmode`

此选项确定是否或以何种优先级与服务器协商安全 GSS TCP/IP 连接。共有三种模式：

`禁用`

只尝试非 GSSAPI 加密的连接

`更喜欢`（默认）

如果存在 GSSAPI 凭据（即，在凭据缓存中），首先尝试 GSSAPI 加密连接；如果失败或没有凭据，请尝试非 GSSAPI 加密连接。这是使用 GSSAPI 支持编译 PostgreSQL 时的默认设置。

`要求`

只尝试 GSSAPI 加密的连接

`gssencmode`对于 Unix 域套接字通信被忽略。如果 PostgreSQL 在没有 GSSAPI 支持的情况下编译，使用`要求`选项将导致错误，而`更喜欢`将被接受，但 libpq 实际上不会尝试 GSSAPI 加密连接。[](<>)

`ssl模式`

此选项确定是否或以何种优先级与服务器协商安全 SSL TCP/IP 连接。有六种模式：

`禁用`

只尝试非 SSL 连接

`允许`

首先尝试非 SSL 连接；如果失败，请尝试 SSL 连接

`更喜欢`（默认）

首先尝试 SSL 连接；如果失败，请尝试非 SSL 连接

`要求`

只尝试 SSL 连接。如果存在根 CA 文件，则以与以下方式相同的方式验证证书`验证-ca`被指定

`验证-ca`

仅尝试 SSL 连接，并验证服务器证书是否由受信任的证书颁发机构 (CA) 颁发

`验证完整`

仅尝试 SSL 连接，验证服务器证书是否由受信任的 CA 颁发，并且请求的服务器主机名与证书中的主机名匹配

看[第 34.19 节](libpq-ssl.html)有关这些选项如何工作的详细说明。

`ssl模式`对于 Unix 域套接字通信被忽略。如果 PostgreSQL 在没有 SSL 支持的情况下编译，使用选项`要求`,`验证-ca`， 或者`验证完整`将导致错误，而选项`允许`和`更喜欢`将被接受，但 libpq 实际上不会尝试 SSL 连接。[](<>)

请注意，如果 GSSAPI 加密是可能的，那么将优先使用 SSL 加密，而不管`ssl模式`.要在具有有效 GSSAPI 基础架构（例如 Kerberos 服务器）的环境中强制使用 SSL 加密，还需设置`gssencmode`到`禁用`.

`requiressl`

This option is deprecated in favor of the`sslmode`setting.

If set to 1, an SSL connection to the server is required (this is equivalent to`sslmode` `require`). libpq will then refuse to connect if the server does not accept an SSL connection. If set to 0 (default), libpq will negotiate the connection type with the server (equivalent to`sslmode` `prefer`). This option is only available if PostgreSQL is compiled with SSL support.

`sslcompression`

If set to 1, data sent over SSL connections will be compressed. If set to 0, compression will be disabled. The default is 0. This parameter is ignored if a connection without SSL is made.

SSL compression is nowadays considered insecure and its use is no longer recommended. OpenSSL 1.1.0 disables compression by default, and many operating system distributions disable it in prior versions as well, so setting this parameter to on will not have any effect if the server does not accept compression. PostgreSQL 14 disables compression completely in the backend.

If security is not a primary concern, compression can improve throughput if the network is the bottleneck. Disabling compression can improve response time and throughput if CPU performance is the limiting factor.

`sslcert`

This parameter specifies the file name of the client SSL certificate, replacing the default`~/.postgresql/postgresql.crt`. This parameter is ignored if an SSL connection is not made.

`sslkey`

This parameter specifies the location for the secret key used for the client certificate. It can either specify a file name that will be used instead of the default`~/.postgresql/postgresql.key`, or it can specify a key obtained from an external “engine” (engines are OpenSSL loadable modules). An external engine specification should consist of a colon-separated engine name and an engine-specific key identifier. This parameter is ignored if an SSL connection is not made.

`sslpassword`

This parameter specifies the password for the secret key specified in`sslkey`, allowing client certificate private keys to be stored in encrypted form on disk even when interactive passphrase input is not practical.

Specifying this parameter with any non-empty value suppresses the`Enter PEM pass phrase:`提示 OpenSSL 在提供加密客户端证书密钥时默认发出`库`.

如果密钥未加密，则忽略此参数。该参数对 OpenSSL 引擎指定的密钥没有影响，除非引擎使用 OpenSSL 密码回调机制进行提示。

没有与此选项等效的环境变量，也没有用于查找它的工具`.pgpass`.它可以在服务文件连接定义中使用。使用更复杂的用户应考虑使用 OpenSSL 引擎和工具，如 PKCS#11 或 USB 加密卸载设备。

`sslrootcert`

此参数指定包含 SSL 证书颁发机构 (CA) 证书的文件的名称。如果文件存在，服务器的证书将被验证为由这些机构之一签名。默认是`~/.postgresql/root.crt`.

`sslcrl`

此参数指定 SSL 服务器证书撤销列表 (CRL) 的文件名。此文件中列出的证书（如果存在）将在尝试验证服务器证书时被拒绝。如果两者都没有[sslcrl](libpq-connect.html#LIBPQ-CONNECT-SSLCRL)也不[sslcrldir](libpq-connect.html#LIBPQ-CONNECT-SSLCRLDIR)被设置，这个设置被视为`~/.postgresql/root.crl`.

`sslcrldir`

此参数指定 SSL 服务器证书撤销列表 (CRL) 的目录名称。此目录中的文件中列出的证书（如果存在）将在尝试验证服务器证书时被拒绝。

需要使用 OpenSSL 命令准备目录`openssl 重新散列`要么`c_rehash`.有关详细信息，请参阅其文档。

两个都`sslcrl`和`sslcrldir`可以一起指定。

`sslsni`[](<>)

如果设置为 1（默认），libpq 在启用 SSL 的连接上设置 TLS 扩展“服务器名称指示”（SNI）。通过将此参数设置为 0，将其关闭。

感知 SSL 的代理可以使用服务器名称指示来路由连接，而无需解密 SSL 流。（请注意，这需要一个知道 PostgreSQL 协议握手的代理，而不仅仅是任何 SSL 代理。）但是，SNI 使目标主机名以明文形式出现在网络流量中，因此在某些情况下它可能是不可取的。

`要求同行`

该参数指定服务器的操作系统用户名，例如`要求同行=postgres`.建立 Unix 域套接字连接时，如果设置了此参数，客户端会在连接开始时检查服务器进程是否以指定的用户名运行；如果不是，则连接因错误而中止。此参数可用于提供类似于 TCP/IP 连接上 SSL 证书可用的服务器身份验证。（请注意，如果 Unix 域套接字位于`/tmp`或另一个可公开写入的位置，任何用户都可以在那里启动服务器监听。使用此参数可确保您连接到由受信任用户运行的服务器。）此选项仅在具有以下功能的平台上受支持`同行`实现认证方法；看[第 21.9 节](auth-peer.html).

`ssl_min_protocol_version`

此参数指定允许连接的最低 SSL/TLS 协议版本。有效值为`TLSv1`,`TLSv1.1`,`TLSv1.2`和`TLSv1.3`.支持的协议取决于所使用的 OpenSSL 版本，旧版本不支持最现代的协议版本。如果未指定，则默认为`TLSv1.2`，在撰写本文时满足行业最佳实践。

`ssl_max_protocol_version`

此参数指定允许连接的最大 SSL/TLS 协议版本。有效值为`TLSv1`,`TLSv1.1`,`TLSv1.2`和`TLSv1.3`.支持的协议取决于所使用的 OpenSSL 版本，旧版本不支持最现代的协议版本。如果未设置，则忽略此参数，连接将使用后端定义的最大界限（如果设置）。设置最大协议版本主要用于测试或某些组件在使用较新协议时出现问题。

`krbsrv 名称`

使用 GSSAPI 进行身份验证时使用的 Kerberos 服务名称。这必须与服务器配置中指定的服务名称匹配，才能使 Kerberos 身份验证成功。（也可以看看[第 21.6 节](gssapi-auth.html).) 默认值通常是`postgres`, 但是在构建 PostgreSQL 时可以通过`--with-krb-srvnam`配置选项。在大多数环境中，永远不需要更改此参数。某些 Kerberos 实现可能需要不同的服务名称，例如 Microsoft Active Directory，它要求服务名称为大写 (`研究生院`）。

`gsslib`

用于 GSSAPI 身份验证的 GSS 库。目前，这被忽略，除了同时包含 GSSAPI 和 SSPI 支持的 Windows 版本。在这种情况下，将其设置为`gssapi`使 libpq 使用 GSSAPI 库而不是默认的 SSPI 进行身份验证。

`服务`

用于附加参数的服务名称。它指定了一个服务名称`pg_service.conf`包含额外的连接参数。这允许应用程序仅指定一个服务名称，以便可以集中维护连接参数。看[第 34.17 节](libpq-pgservice.html).

`目标会话属性`

此选项确定会话是否必须具有某些属性才能被接受。它通常与多个主机名结合使用，以在多个主机中选择第一个可接受的替代方案。有六种模式：

`任何`（默认）

任何成功的连接都是可以接受的

`读写`

session 必须默认接受读写事务（即服务器不能处于热备模式并且`default_transaction_read_only`参数必须是`离开`)

`只读`

默认情况下，会话不得接受读写事务（反之亦然）

`基本的`

服务器不得处于热备用模式

`支持`

服务器必须处于热备模式

`首选备用`

首先尝试查找备用服务器，但如果列出的主机都不是备用服务器，请在`任何`模式