以下函数处理与 PostgreSQL 后端服务器建立连接。应用程序可以同时打开多个后端连接。（这样做的一个原因是访问多个数据库。）每个连接由一个 PGconn 对象表示，该对象通过函数 PQconnectdb、PQconnectdbParams 或 PQsetdbLogin 获取。请注意，除非内存不足以分配 PGconn 对象，否则这些函数将始终返回非空指针。在通过连接对象发送查询之前，应调用 PQstatus 函数来检查返回值是否成功连接。
如果不受信任的用户可以访问未采用 安全模式使用模式 的数据库，请在每个会话开始时从 search_path 中删除可公开写入的模式。可以将参数关键字 options 设置为值 -csearch_path=。或者，可以在连接后发出 PQexec(。此注意事项并非 libpq 特有；它适用于执行任意 SQL 命令的每个接口。conn, "SELECT pg_catalog.set_config('search_path', '', false)")
在 Unix 系统上，具有开放 libpq 连接的进程会产生不可预测的结果，因为父进程和子进程共享相同的套接字和操作系统资源。因此，不推荐使用这种方式，尽管从子进程执行 exec 来加载新可执行文件是安全的。
PQconnectdbParams #与数据库服务器建立新连接。
PGconn *PQconnectdbParams(const char * const *keywords,
const char * const *values,
int expand_dbname);
此函数使用来自两个 NULL 终止数组的参数来打开新的数据库连接。第一个 keywords 定义为字符串数组，每个字符串都是一个关键字。第二个 values 为每个关键字提供值。与下面的 PQsetdbLogin 不同，参数集可以在不更改函数签名的情况下进行扩展，因此，新应用程序编程首选使用此函数（或其非阻塞类比 PQconnectStartParams 和 PQconnectPoll）。
当前识别的参数关键字列在 第 32.1.2 节 中。
传递的数组可以为空，以使用所有默认参数，或包含一个或多个参数设置。它们必须长度匹配。处理将在 keywords 数组的第一个 NULL 条目处停止。另外，如果与非 NULL keywords 条目关联的 values 条目是 NULL 或空字符串，则忽略该条目，并继续处理下一对数组条目。
当 expand_dbname 非零时，将检查第一个 dbname 关键字的值，以确定它是否为 连接字符串。如果是，它将被 “展开” 成从字符串中提取的各个连接参数。如果值包含等号（=）或以 URI 方案指示符开头，则该值被视为连接字符串，而不仅仅是数据库名称。（有关连接字符串格式的更多详细信息，请参阅 第 32.1.1 节。）只有 dbname 的第一次出现才这样处理；任何后续的 dbname 参数都将被处理为普通数据库名称。
通常，参数数组按从头到尾的顺序处理。如果任何关键字重复，则使用最后一个（非 NULL 或非空）值。此规则尤其适用于当连接字符串中找到的关键字与 keywords 数组中出现的关键字冲突时。因此，程序员可以确定数组条目是覆盖还是被连接字符串中的值覆盖。出现在展开的 dbname 条目之前的数组条目可以被连接字符串中的字段覆盖，而这些字段又被 dbname 之后的数组条目覆盖（但同样，仅当这些条目提供非空值时）。
在处理完所有数组条目和任何展开的连接字符串后，任何未设置的连接参数将用默认值填充。如果未设置参数的对应环境变量（请参阅 第 32.15 节）已设置，则使用其值。如果环境变量也未设置，则使用参数的内置默认值。
PQconnectdb #与数据库服务器建立新连接。
PGconn *PQconnectdb(const char *conninfo);
此函数使用 conninfo 字符串中的参数打开新的数据库连接。
传递的字符串可以为空，以使用所有默认参数，或者可以包含一个或多个由空格分隔的参数设置，或者可以包含一个URI。有关详细信息，请参阅 第 32.1.1 节。
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 的前身，具有固定的参数集。它具有与 PQconnectdb 相同的功能，只是缺少参数将始终采用默认值。对于要默认的固定参数中的任何一个，请写 NULL 或空字符串。
如果 dbName 包含 = 符号或具有有效的连接URI前缀，则它将被视为 conninfo 字符串，与传递给 PQconnectdb 的情况完全相同，然后剩余参数将按照 PQconnectdbParams 的说明进行应用。
pgtty 已不再使用，传递的任何值都将被忽略。
PQsetdb #与数据库服务器建立新连接。
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName);
这是一个宏，它使用 login 和 pwd 参数的空指针调用 PQsetdbLogin。它为了与非常旧的程序兼容而提供。
PQconnectStartParamsPQconnectStartPQconnectPoll #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 或 PQconnectdb 的内部发生，因此应用程序可以与其他活动并行管理此操作。
使用 PQconnectStartParams，数据库连接使用来自 keywords 和 values 数组的参数建立，并由 expand_dbname 控制，如上文对 PQconnectdbParams 的描述。
使用 PQconnectStart，数据库连接使用来自 conninfo 字符串的参数建立，如上文对 PQconnectdb 的描述。
只要满足一些限制条件，PQconnectStartParams、PQconnectStart 和 PQconnectPoll 都不会阻塞
必须正确使用 hostaddr 参数以防止 DNS 查询。有关此参数的详细信息，请参阅 第 32.1.2 节 的文档。
如果您调用 PQtrace，请确保跟踪到的流对象不会阻塞。
您必须确保在调用 PQconnectPoll 之前套接字处于适当状态，如下文所述。
要开始非阻塞连接请求，请调用 PQconnectStart 或 PQconnectStartParams。如果结果为 null，则 libpq 无法分配新的 PGconn 结构。否则，将返回一个有效的 PGconn 指针（尽管尚未表示与数据库的有效连接）。接下来调用 PQstatus(conn)。如果结果为 CONNECTION_BAD，则连接尝试已失败，通常是因为连接参数无效。
如果 PQconnectStart 或 PQconnectStartParams 成功，下一个阶段是轮询 libpq，以便它可以继续执行连接序列。使用 PQsocket(conn) 获取数据库连接底层套接字的描述符。（注意：不要假设套接字在 PQconnectPoll 调用之间保持不变。）按如下方式循环：如果 PQconnectPoll(conn) 上次返回 PGRES_POLLING_READING，请等到套接字准备好读取（由 select()、poll() 或类似的系统函数指示）。请注意，PQsocketPoll 可以通过抽象 select(2) 或 poll(2) 的设置来帮助减少样板代码（如果您的系统支持）。然后再次调用 PQconnectPoll(conn)。反之，如果 PQconnectPoll(conn) 上次返回 PGRES_POLLING_WRITING，请等到套接字准备好写入，然后再次调用 PQconnectPoll(conn)。在第一次迭代时，即如果您尚未调用 PQconnectPoll，则行为如同它上次返回 PGRES_POLLING_WRITING。继续此循环，直到 PQconnectPoll(conn) 返回 PGRES_POLLING_FAILED，表示连接过程失败，或 PGRES_POLLING_OK，表示连接已成功建立。
在连接的任何时候，都可以通过调用 PQstatus 来检查连接的状态。如果此调用返回 CONNECTION_BAD，则表示连接过程已失败；如果调用返回 CONNECTION_OK，则表示连接已就绪。这两种状态都可以通过 PQconnectPoll 的返回值（如上所述）来检测。在异步连接过程中（且仅在过程中），也可能出现其他状态。这些状态表示连接过程的当前阶段，可能有助于向用户提供反馈。这些状态是
CONNECTION_STARTED #等待连接建立。
CONNECTION_MADE #连接正常；等待发送。
CONNECTION_AWAITING_RESPONSE #等待服务器响应。
CONNECTION_AUTH_OK #已收到身份验证；等待后端启动完成。
CONNECTION_SSL_STARTUP #正在协商 SSL 加密。
CONNECTION_GSS_STARTUP #正在协商 GSS 加密。
CONNECTION_CHECK_WRITABLE #检查连接是否能够处理写事务。
CONNECTION_CHECK_STANDBY #检查连接是否是到处于待机模式的服务器。
CONNECTION_CONSUME #消耗连接上的任何剩余响应消息。
请注意，尽管这些常量会保留（以保持兼容性），但应用程序不应依赖于它们以特定顺序出现，或以任何顺序出现，或依赖于状态始终是这些文档化值之一。应用程序可以这样做：
switch(PQstatus(conn))
{
case CONNECTION_STARTED:
feedback = "Connecting...";
break;
case CONNECTION_MADE:
feedback = "Connected to server...";
break;
.
.
.
default:
feedback = "Connecting...";
}
使用 PQconnectPoll 时会忽略 connect_timeout 连接参数；应用程序负责决定是否经过了过多的时间。否则，PQconnectStart 加上 PQconnectPoll 循环等同于 PQconnectdb。
请注意，当 PQconnectStart 或 PQconnectStartParams 返回非空指针时，当您完成使用它后，必须调用 PQfinish 来释放结构和任何关联的内存块。即使连接尝试失败或被放弃，也必须这样做。
PQsocketPoll # 轮询通过 PQsocket 检索到的连接的底层套接字描述符。此函数的主要用途是遍历 PQconnectStartParams 文档中描述的连接序列。
typedef int64_t pg_usec_time_t;
int PQsocketPoll(int sock, int forRead, int forWrite,
pg_usec_time_t end_time);
此函数执行文件描述符的轮询，可选地带超时。如果 forRead 非零，函数将在套接字可读时终止。如果 forWrite 非零，函数将在套接字可写时终止。
超时由 end_time 指定，它表示停止等待的时间，以自 Unix 纪元（即 time_t 乘以一百万）以来的微秒数表示。如果 end_time 为 -1，则超时是无限的。如果 end_time 为 0（或实际上，在当前时间之前），则超时是即时的（无阻塞）。可以通过将所需的微秒数添加到 PQgetCurrentTimeUSec 的结果来方便地计算超时值。请注意，底层系统调用可能精度低于微秒，因此实际延迟可能不精确。
如果满足指定条件，函数返回大于 0 的值；如果发生超时，则返回 0；如果发生错误，则返回 -1。可以通过检查 errno(3) 值来检索错误。如果 forRead 和 forWrite 都为零，则函数立即返回超时指示。
PQsocketPoll 使用 poll(2) 或 select(2) 实现，具体取决于平台。有关更多信息，请参阅 poll(2) 中的 POLLIN 和 POLLOUT，或 select(2) 中的 readfds 和 writefds。
PQconndefaults #返回默认连接选项。
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 选项及其当前默认值。返回值指向 PQconninfoOption 结构的数组，该数组以 keyword 指针为 NULL 的条目结束。如果内存分配失败，则返回空指针。请注意，当前默认值（val 字段）将取决于环境变量和其他上下文。缺失或无效的服务文件将被静默忽略。调用者必须将连接选项数据视为只读。
处理完选项数组后，通过将其传递给 PQconninfoFree 来释放它。如果未执行此操作，每次调用 PQconndefaults 都会泄漏少量内存。
PQconninfo #返回活动连接使用的连接选项。
PQconninfoOption *PQconninfo(PGconn *conn);
返回连接选项数组。这可用于确定所有可能的 PQconnectdb 选项以及用于连接到服务器的值。返回值指向 PQconninfoOption 结构的数组，该数组以 keyword 指针为 NULL 的条目结束。上面关于 PQconndefaults 的所有注释也适用于 PQconninfo 的结果。
PQconninfoParse #从提供的连接字符串返回已解析的连接选项。
PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
解析连接字符串并返回结果选项作为数组；如果连接字符串有问题，则返回 NULL。此函数可用于提取提供的连接字符串中的 PQconnectdb 选项。返回值指向 PQconninfoOption 结构的数组，该数组以 keyword 指针为 NULL 的条目结束。
所有合法的选项都将存在于结果数组中，但对于连接字符串中不存在的任何选项，其 PQconninfoOption 的 val 将设置为 NULL；不插入默认值。
如果 errmsg 不为 NULL，则成功时 *errmsg 设置为 NULL，否则设置为解释问题的 malloc'd 错误字符串。（*errmsg 也可能被设置为 NULL 并且函数返回 NULL；这表示内存不足的情况。）
处理完选项数组后，通过将其传递给 PQconninfoFree 来释放它。如果未执行此操作，每次调用 PQconninfoParse 都会泄漏一些内存。反之，如果发生错误且 errmsg 不为 NULL，请务必使用 PQfreemem 释放错误字符串。
PQfinish #关闭与服务器的连接。还会释放 PGconn 对象使用的内存。
void PQfinish(PGconn *conn);
请注意，即使服务器连接尝试失败（如 PQstatus 所指示），应用程序也应调用 PQfinish 来释放 PGconn 对象使用的内存。PGconn 指针在调用 PQfinish 后不得再次使用。
PQreset #重置与服务器的通信通道。
void PQreset(PGconn *conn);
此函数将关闭与服务器的连接，并尝试建立新连接，使用所有先前使用的相同参数。如果工作连接丢失，这对于错误恢复可能很有用。
PQresetStartPQresetPoll #以非阻塞方式重置与服务器的通信通道。
int PQresetStart(PGconn *conn); PostgresPollingStatusType PQresetPoll(PGconn *conn);
这些函数将关闭与服务器的连接，并尝试建立新连接，使用所有先前使用的相同参数。如果工作连接丢失，这对于错误恢复可能很有用。它们与 PQreset（上面）的区别在于它们是非阻塞方式的。这些函数与 PQconnectStartParams、PQconnectStart 和 PQconnectPoll 存在相同的限制。
要发起连接重置，请调用 PQresetStart。如果它返回 0，则重置失败。如果它返回 1，则使用 PQresetPoll 以与使用 PQconnectPoll 创建连接完全相同的方式轮询重置。
PQpingParams #PQpingParams 报告服务器的状态。它接受与 PQconnectdbParams 相同的连接参数，如上所述。为了获取服务器状态，不必提供正确的用户名、密码或数据库名称值；但是，如果提供了不正确的值，服务器将记录一个失败的连接尝试。
PGPing PQpingParams(const char * const *keywords,
const char * const *values,
int expand_dbname);
该函数返回以下值之一
PQping #PQping 报告服务器的状态。它接受与 PQconnectdb 相同的连接参数，如上所述。为了获取服务器状态，不必提供正确的用户名、密码或数据库名称值；但是，如果提供了不正确的值，服务器将记录一个失败的连接尝试。
PGPing PQping(const char *conninfo);
返回值与 PQpingParams 相同。
PQsetSSLKeyPassHook_OpenSSL #PQsetSSLKeyPassHook_OpenSSL 允许应用程序使用 sslpassword 或交互式提示来覆盖 libpq 对 加密的客户端证书密钥文件的默认处理。
void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);
应用程序传递一个指向签名函数的回调函数的指针
int callback_fn(char *buf, int size, PGconn *conn);
然后，libpq 将调用该函数 而不是 其默认的 PQdefaultSSLKeyPassHook_OpenSSL 处理程序。回调函数应确定密钥的密码，并将其复制到大小为 size 的结果缓冲区 buf 中。buf 中的字符串必须以 null 结尾。回调函数必须返回存储在 buf 中（不包括 null 终止符）的密码的长度。失败时，回调函数应将 buf[0] = '\0' 设置为 0。有关示例，请参阅 libpq 源代码中的 PQdefaultSSLKeyPassHook_OpenSSL。
如果用户指定了显式密钥位置，当调用回调函数时，其路径将位于 conn->sslkey 中。如果使用默认密钥路径，则此值将为空。对于作为引擎指定符的密钥，引擎实现可以选择使用 OpenSSL 密码回调函数或定义自己的处理方式。
应用程序回调可以选择将未处理的情况委托给 PQdefaultSSLKeyPassHook_OpenSSL，或者首先调用它，如果它返回 0，则尝试其他方法，或者完全覆盖它。
回调函数不得通过异常、longjmp(...) 等方式逃离正常的流程控制。它必须正常返回。
PQgetSSLKeyPassHook_OpenSSL #PQgetSSLKeyPassHook_OpenSSL 返回当前客户端证书密钥密码钩子，如果未设置任何钩子，则返回 NULL。
PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);
几个 libpq 函数解析用户指定的字符串以获取连接参数。这些字符串有两种可接受的格式：纯关键字/值字符串和 URI。URI 通常遵循 RFC 3986，但允许使用多主机连接字符串，如下所述。
在关键字/值格式中，每个参数设置的形式为 keyword = value，设置之间用空格分隔。设置的等号周围的空格是可选的。要写入空值或包含空格的值，请将其用单引号括起来，例如 keyword = 'a value'。值中的单引号和反斜杠必须用反斜杠转义，即 \' 和 \\。
示例：
host=localhost port=5432 dbname=mydb connect_timeout=10
识别的参数关键字列在 第 32.1.2 节 中。
连接的一般形式URI是
postgresql://[userspec@][hostspec][/dbname][?paramspec] whereuserspecis:user[:password] andhostspecis: [host][:port][,...] andparamspecis:name=value[&...]
该URI方案标识符可以是 postgresql:// 或 postgres://。其余的每个URI部分是可选的。以下示例说明了有效的URI语法
postgresql:// postgresql:// postgresql://:5433 postgresql:///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
所有命名参数必须匹配 第 32.1.2 节 中列出的关键字，除了为了与 JDBC 连接兼容URI的情况下，ssl=true 的实例会被转换为 sslmode=require。
连接URI如果包含在任何部分具有特殊含义的符号，则需要使用 百分比编码进行编码。这里是一个例子，其中等号 (=) 被替换为 %3D，空格字符被替换为 %20
postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff
主机部分可以是主机名或 IP 地址。要指定 IPv6 地址，请将其括在方括号中
postgresql://[2001:db8::1234]/database
主机部分按照 host 参数的描述进行解释。特别是，如果主机部分为空或看起来像绝对路径名，则选择 Unix 域套接字连接，否则将建立 TCP/IP 连接。但是请注意，斜杠是 URI 分层部分的保留字符。因此，要指定非标准的 Unix 域套接字目录，请省略 URI 的主机部分并将主机指定为命名参数，或者对 URI 的主机部分中的路径进行百分比编码
postgresql:///dbname?host=/var/lib/postgresql postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
可以在单个 URI 中指定多个主机组件，每个组件可选地带有一个端口组件。形式为 postgresql://host1:port1,host2:port2,host3:port3/ 的 URI 等同于形式为 host=host1,host2,host3 port=port1,port2,port3 的连接字符串。如下文所述，将依次尝试每个主机，直到成功建立连接。
可以指定多个要连接的主机，以便按给定顺序尝试它们。在关键字/值格式中，host、hostaddr 和 port 选项接受逗号分隔的值列表。在指定的每个选项中必须给出相同数量的元素，例如，第一个 hostaddr 对应第一个主机名，第二个 hostaddr 对应第二个主机名，依此类推。作为例外，如果只指定了一个 port，则它适用于所有主机。
在连接 URI 格式中，可以在 URI 的 host 组件中列出多个以逗号分隔的 host:port 对。
在这两种格式中，单个主机名都可以转换为多个网络地址。一个常见的例子是同时具有 IPv4 和 IPv6 地址的主机。
当指定了多个主机，或者当单个主机名解析为多个地址时，将按顺序尝试所有主机和地址，直到其中一个成功为止。如果无法连接到任何主机，则连接失败。如果成功建立了连接但身份验证失败，则列表中的其余主机将不会被尝试。
如果使用密码文件，您可以为不同的主机设置不同的密码。列表中的每个主机都具有相同的其他连接选项；例如，不能为不同的主机指定不同的用户名。
当前识别的参数关键字是
host #要连接的主机名。 如果主机名看起来像绝对路径名，则它指定 Unix 域通信而不是 TCP/IP 通信；该值是存储套接字文件的目录的名称。（在 Unix 上，绝对路径名以斜杠开头。在 Windows 上，以驱动器字母开头的路径也被识别。）如果主机名以 @ 开头，则将其视为抽象命名空间中的 Unix 域套接字（目前在 Linux 和 Windows 上支持）。默认行为是当未指定 host 或 host 为空时，连接到 Unix 域套接字在 /tmp 中（或在编译 PostgreSQL 时指定的任何套接字目录）。在 Windows 上，默认是连接到 localhost。
也接受逗号分隔的主机名列表，在这种情况下，将按顺序尝试列表中的每个主机名；列表中的空项选择上述解释的默认行为。有关详细信息，请参阅 第 32.1.1.3 节。
hostaddr #要连接的主机的数字 IP 地址。这应该是标准的 IPv4 地址格式，例如 172.28.40.9。如果您的机器支持 IPv6，您也可以使用这些地址。当为此参数指定非空字符串时，始终使用 TCP/IP 通信。如果未指定此参数，则会查找 host 的值以查找相应的 IP 地址 — 或者，如果 host 指定了 IP 地址，则直接使用该值。
使用 hostaddr 可以让应用程序避免主机名查找，这在对时间有要求的应用程序中可能很重要。但是，GSSAPI 或 SSPI 身份验证方法以及 verify-full SSL 证书验证都需要主机名。使用以下规则
如果指定了 host 而未指定 hostaddr，则会发生主机名查找。（当使用 PQconnectPoll 时，查找会在 PQconnectPoll 首次考虑此主机名时发生，并且可能导致 PQconnectPoll 阻塞很长时间。）
如果指定了 hostaddr 而未指定 host，则 hostaddr 的值给出服务器网络地址。如果身份验证方法要求主机名，则连接尝试将失败。
如果同时指定了 host 和 hostaddr，则 hostaddr 的值给出服务器网络地址。除非身份验证方法需要 host，否则将忽略 host 的值，在这种情况下，它将被用作主机名。
请注意，如果 host 不是 hostaddr 网络地址处的服务器名称，身份验证很可能会失败。此外，当同时指定 host 和 hostaddr 时，host 用于在密码文件中标识连接（请参阅 第 32.16 节）。
也接受逗号分隔的 hostaddr 值列表，在这种情况下，将按顺序尝试列表中的每个主机。列表中的空项会导致使用相应的主机名，或者如果主机名也为空，则使用默认主机名。有关详细信息，请参阅 第 32.1.1.3 节。
如果没有主机名或主机地址，libpq 将使用本地 Unix 域套接字进行连接；或者在 Windows 上，它将尝试连接到 localhost。
port #连接到服务器主机上的端口号，或 Unix 域连接的套接字文件名扩展。 如果在 host 或 hostaddr 参数中给出了多个主机，则此参数可以指定一个与主机列表长度相同的逗号分隔的端口列表，或者可以指定一个适用于所有主机的单个端口号。空字符串或逗号分隔列表中的空项指定在编译 PostgreSQL 时建立的默认端口号。
dbname #数据库名称。默认与用户名相同。在某些上下文中，将检查值是否存在扩展格式；有关更多详细信息，请参阅 第 32.1.1 节。
user #要连接的 PostgreSQL 用户名。默认与运行应用程序的操作系统用户名相同。
password #如果服务器要求密码身份验证，则使用的密码。
passfile #指定用于存储密码的文件名（请参阅 第 32.16 节）。默认值为 ~/.pgpass，或 Microsoft Windows 上的 %APPDATA%\postgresql\pgpass.conf。（如果此文件不存在，则不报告错误。）
require_auth #指定客户端要求的服务器的身份验证方法。如果服务器不使用所需方法对客户端进行身份验证，或者身份验证握手未由服务器完全完成，则连接将失败。还可以提供方法组成的逗号分隔列表，服务器必须仅使用其中一种方法才能使连接成功。默认情况下，接受任何身份验证方法，并且服务器可以完全跳过身份验证。
方法可以通过添加 ! 前缀来否定，在这种情况下，服务器不得尝试列出的方法；接受任何其他方法，并且服务器可以完全不验证客户端。如果提供了逗号分隔的列表，则服务器不得尝试任何列出的否定方法。不能在同一设置中组合否定和非否定形式。
作为最后一个特殊情况，none 方法要求服务器不提示进行身份验证。（它也可以被否定，以要求某种形式的身份验证。）
以下方法可以指定
password服务器必须请求明文密码身份验证。
md5服务器必须请求 MD5 哈希密码身份验证。
MD5 加密密码的支持已弃用，将在 PostgreSQL 的未来版本中移除。有关迁移到其他密码类型的详细信息，请参阅第 20.5 节。
gss服务器必须通过以下方式请求 Kerberos 握手GSSAPI或建立一个GSS-加密通道（另请参阅 gssencmode）。
sspi服务器必须请求 WindowsSSPI身份验证。
scram-sha-256服务器必须成功地与客户端完成 SCRAM-SHA-256 身份验证交换。
oauth服务器必须从客户端请求 OAuth 承载令牌。
none服务器不得提示客户端进行身份验证交换。（这并不阻止通过 TLS 进行客户端证书身份验证，也不阻止通过其加密传输进行 GSS 身份验证。）
channel_binding #此选项控制客户端的通道绑定使用情况。设置为 require 表示连接必须使用通道绑定，prefer 表示客户端将在可用时选择通道绑定，而 disable 则阻止使用通道绑定。如果 PostgreSQL 是使用 SSL 支持编译的，则默认值为 prefer；否则默认值为 disable。
通道绑定是服务器向客户端进行身份验证的一种方法。它仅在与 PostgreSQL 11 或更高版本服务器使用 SCRAM 身份验证方法配合的 SSL 连接上受支持。
connect_timeout #连接时等待的最大时间（以秒为单位，写入为十进制整数，例如 10）。零、负数或未指定表示无限期等待。此超时分别适用于每个主机名或 IP 地址。例如，如果您指定了两个主机且 connect_timeout 为 5，则每个主机将在 5 秒内超时而未建立连接，因此等待连接的总时间可能长达 10 秒。
client_encoding #这会为当前连接设置 client_encoding 配置参数。除了服务器对应选项接受的值外，您还可以使用 auto 来确定来自客户端当前区域设置（Unix 系统上的 LC_CTYPE 环境变量）的正确编码。
options #指定要在连接开始时发送到服务器的命令行选项。例如，将其设置为 -c geqo=off 或 --geqo=off 会将会话的 geqo 参数值设置为 off。此字符串中的空格被视为分隔命令行参数，除非被反斜杠（\）转义；写入 \\ 以表示字面上的反斜杠。有关可用选项的详细讨论，请参阅 第 19 章。
application_name #为 application_name 配置参数指定值。
fallback_application_name #为 application_name 配置参数指定备用值。如果没有通过连接参数或 PGAPPNAME 环境变量给出 application_name 的值，则将使用此值。为通用实用程序指定备用名称很有用，这些实用程序希望设置默认应用程序名称但允许用户覆盖它。
keepalives #控制是否使用客户端 TCP keepalives。默认值为 1，表示开启，但如果不需要 keepalives，您可以将其更改为 0，表示关闭。对于通过 Unix 域套接字建立的连接，忽略此参数。
keepalives_idle #控制在 TCP 发送 keepalive 消息到服务器之前闲置的秒数。值为零表示使用系统默认值。对于通过 Unix 域套接字建立的连接，或者如果 keepalives 已禁用，则忽略此参数。仅在 TCP_KEEPIDLE 或等效套接字选项可用并且在 Windows 上可用时才支持此参数；在其他系统上，它没有影响。
keepalives_interval #控制未被服务器确认的 TCP keepalive 消息重传的秒数。值为零表示使用系统默认值。对于通过 Unix 域套接字建立的连接，或者如果 keepalives 已禁用，则忽略此参数。仅在 TCP_KEEPINTVL 或等效套接字选项可用并且在 Windows 上可用时才支持此参数；在其他系统上，它没有影响。
keepalives_count #控制在客户端与服务器的连接被视为死连接之前可以丢失的 TCP keepalives 数量。值为零表示使用系统默认值。对于通过 Unix 域套接字建立的连接，或者如果 keepalives 已禁用，则忽略此参数。仅在 TCP_KEEPCNT 或等效套接字选项可用时才支持此参数；在其他系统上，它没有影响。
tcp_user_timeout #控制已发送数据在连接被强制关闭之前可能保持未确认状态的毫秒数。值为零表示使用系统默认值。对于通过 Unix 域套接字建立的连接，则忽略此参数。仅在 TCP_USER_TIMEOUT 可用时才支持此参数；在其他系统上，它没有影响。
replication #此选项确定连接是否应使用复制协议而不是正常协议。这就是 PostgreSQL 复制连接以及 pg_basebackup 等工具内部使用的协议，但第三方应用程序也可以使用它。有关复制协议的描述，请参阅 第 54.4 节。
以下值（不区分大小写）受支持
true、on、yes、1连接进入物理复制模式。
database连接进入逻辑复制模式，连接到 dbname 参数中指定的数据库。
false、off、no、0连接是常规连接，这是默认行为。
在物理或逻辑复制模式下，只能使用简单查询协议。
gssencmode #此选项决定是否以及以何种优先级与服务器协商安全的GSSTCP/IP 连接。有三种模式
disable仅尝试非GSSAPI-加密连接
prefer (默认)如果存在GSSAPI凭据（即，在凭据缓存中），首先尝试GSSAPI-加密连接；如果失败或没有凭据，则尝试非GSSAPI-加密连接。这是 PostgreSQL 编译时GSSAPI支持的默认值。
require仅尝试GSSAPI-加密连接
-加密连接。如果 PostgreSQL 是使用 GSSAPI 支持编译的，使用 require 选项将导致错误，而 prefer 将被接受，但 libpq 实际上不会尝试GSSAPI-加密连接。
sslmode #此选项决定是否以及以何种优先级与服务器协商安全的SSL与服务器协商 TCP/IP 连接。有六种模式
disable仅尝试非SSLconnection
allow首先尝试非SSLconnection；如果失败，则尝试SSLconnection
prefer (默认)first try anSSLconnection; if that fails, try a non-SSLconnection
requireonly try anSSLconnection。如果存在根 CA 文件，则以与指定 verify-ca 相同的方式验证证书
verify-caonly try anSSLconnection，并验证服务器证书是由受信任的证书颁发机构（CA)
verify-fullonly try anSSLconnection，验证服务器证书是由受信任的CA颁发的，并且请求的服务器主机名与证书中的主机名匹配
有关这些选项如何工作的详细说明，请参阅 第 32.19 节。
对于 Unix 域套接字通信，sslmode 被忽略。如果 PostgreSQL 是在没有 SSL 支持的情况下编译的，使用 require、verify-ca 或 verify-full 选项将导致错误，而 allow 和 prefer 选项将被接受，但 libpq 实际上不会尝试SSL-encrypted connection.
请注意，如果GSSAPI加密是可能的，将优先使用它而不是SSL加密，无论 sslmode 的值如何。要在具有可用SSL基础结构（例如 Kerberos 服务器）的环境中强制使用GSSAPI加密，还将 gssencmode 设置为 disable。
requiressl #此选项已弃用，改用 sslmode 设置。
如果设置为 1，则需要与服务器建立SSL-encrypted connection（这等同于 sslmode require）。然后，如果服务器不接受SSL-encrypted connection，libpq 将拒绝连接。如果设置为 0（默认），libpq 将与服务器协商连接类型（等同于 sslmode prefer）。只有在 PostgreSQL 编译了 SSL 支持的情况下，此选项才可用。
sslnegotiation #此选项控制如何与服务器协商 SSL 加密（如果使用 SSL）。在默认的 postgres 模式下，客户端首先询问服务器是否支持 SSL。在 direct 模式下，客户端在建立 TCP/IP 连接后立即启动标准的 SSL 握手。传统的 PostgreSQL 协议协商对于不同的服务器配置最为灵活。如果已知服务器支持直接SSL连接，则后者需要少一次往返，从而减少连接延迟，并且还允许使用协议无关的 SSL 网络工具。直接 SSL 选项是在 PostgreSQL 版本 17 中引入的。
postgres执行 PostgreSQL 协议协商。如果未提供该选项，则这是默认设置。
direct在建立 TCP/IP 连接后立即启动 SSL 握手。这仅允许与 sslmode=require 或更高级别一起使用，因为较弱的设置可能导致在服务器不支持直接 SSL 握手时意外回退到明文身份验证。
sslcompression #如果设置为 1，则 SSL 连接上传输的数据将被压缩。如果设置为 0，则禁用压缩。默认值为 0。如果使用非 SSL 连接，则忽略此参数。
SSL 压缩现在被认为是不安全的，并且不再推荐使用。 OpenSSL 1.1.0 默认禁用了压缩，并且许多操作系统发行版在早期版本中也禁用了它，因此如果服务器不接受压缩，将此参数设置为 on 将不起任何作用。 PostgreSQL 14 在后端完全禁用了压缩。
如果安全性不是主要关注点，压缩可以提高吞吐量（如果网络是瓶颈）。如果 CPU 性能是限制因素，禁用压缩可以提高响应时间和吞吐量。
sslcert #此参数指定客户端 SSL 证书的文件名，替换默认的 ~/.postgresql/postgresql.crt。如果未建立 SSL 连接，则忽略此参数。
sslkey #此参数指定用于客户端证书的密钥的位置。它可以指定一个文件名，该文件名将替换默认的 ~/.postgresql/postgresql.key，或者它可以指定从外部“引擎”（引擎是 OpenSSL 可加载模块）获取的密钥。外部引擎规范应由一个冒号分隔的引擎名称和一个特定于引擎的密钥标识符组成。如果未建立 SSL 连接，则忽略此参数。
sslkeylogfile #此参数指定 libpq 在此 SSL 上下文中记录密钥的位置。这对于调试 PostgreSQL 协议交互或使用 Wireshark 等网络检查工具的客户端连接很有用。如果未建立 SSL 连接，或未使用 LibreSSL（LibreSSL 不支持密钥日志记录），则忽略此参数。密钥使用 NSS 格式记录。
密钥日志记录会在 keylog 文件中暴露潜在的敏感信息。密钥日志文件应与处理 sslkey 文件的同等谨慎度来处理。
sslpassword #此参数指定 sslkey 中密钥的密码，允许客户端证书私钥以加密形式存储在磁盘上，即使交互式输入密码不切实际。
使用此参数并提供任何非空值将抑制 OpenSSL 在向 libpq 提供加密的客户端证书密钥时默认发出的 Enter PEM pass phrase: 提示。
如果密钥未加密，则忽略此参数。该参数对 OpenSSL 引擎指定的密钥没有影响，除非引擎使用 OpenSSL 密码回调机制进行提示。
此选项没有环境变量等效项，也没有在 .pgpass 中查找的机制。它可以在服务文件连接定义中使用。有更复杂用途的用户应考虑使用 OpenSSL 引擎和 PKCS#11 或 USB 加密卸载设备等工具。
sslcertmode #此选项确定是否可以向服务器发送客户端证书，以及是否要求服务器请求客户端证书。有三种模式
disable客户端证书永远不会发送，即使存在（默认位置或通过 sslcert 提供）。
allow (默认)如果服务器请求证书并且客户端有可发送的证书，则可以发送证书。
require服务器必须请求证书。如果客户端不发送证书且服务器仍成功验证客户端，则连接将失败。
sslcertmode=require 不会增加任何额外的安全性，因为不能保证服务器正确验证证书；PostgreSQL 服务器通常会向客户端请求 TLS 证书，无论它们是否验证。此选项在排查更复杂的 TLS 设置时可能很有用。
sslrootcert #此参数指定包含 SSL 证书颁发机构 (CA) 证书的文件的名称。如果文件存在，服务器的证书将被验证为由其中一个颁发机构签名。默认值为 ~/.postgresql/root.crt。
可以指定特殊值 system，在这种情况下将加载 SSL 实现中受信任的 CA 根证书。这些根证书的确切位置因 SSL 实现和平台而异。特别是对于 OpenSSL，SSL_CERT_DIR 和 SSL_CERT_FILE 环境变量可能会进一步修改这些位置。
使用 sslrootcert=system 时，默认的 sslmode 会更改为 verify-full，任何更弱的设置都会导致错误。在大多数情况下，任何人都可以轻松获取受系统信任的、用于其控制的主机的证书，从而使 verify-ca 和所有更弱的模式变得无用。
魔术值 system 将优先于同名的本地证书文件。如果出于某种原因您发现自己处于这种情况，请改用替代路径，例如 sslrootcert=./system。
sslcrl #此参数指定 SSL 服务器证书吊销列表 (CRL) 的文件名。如果存在此文件，其中列出的证书将在尝试验证服务器证书时被拒绝。如果未设置 sslcrl 也未设置 sslcrldir，则此设置将按 ~/.postgresql/root.crl 处理。
sslcrldir #此参数指定 SSL 服务器证书吊销列表 (CRL) 的目录名。如果存在此目录，其中列出的证书将在尝试验证服务器证书时被拒绝。
目录需要使用 OpenSSL 命令 openssl rehash 或 c_rehash 进行准备。有关详细信息，请参阅其文档。
可以同时指定 sslcrl 和 sslcrldir。
sslsni #如果设置为 1 (默认)，libpq 会在启用 SSL 的连接上设置 TLS 扩展“服务器名称指示” (SNI)。将此参数设置为 0 可以禁用此功能。
SSL 感知的代理可以使用服务器名称指示来路由连接，而无需解密 SSL 流。(请注意，除非代理感知 PostgreSQL 协议握手，否则这需要将 sslnegotiation 设置为 direct。) 然而，SNI这会使目标主机名以明文形式出现在网络流量中，因此在某些情况下可能不希望这样做。
requirepeer #此参数指定服务器的操作系统用户名，例如 requirepeer=postgres。在建立 Unix 域套接字连接时，如果设置了此参数，客户端将在连接开始时检查服务器进程是否以指定的用户名运行；如果不是，连接将被中止并报错。此参数可用于提供类似于 TCP/IP 连接上 SSL 证书提供的服务器身份验证。 (请注意，如果 Unix 域套接字位于 /tmp 或其他可公开写入的位置，任何用户都可以启动一个监听在那里的服务器。使用此参数可确保您连接到的是由受信任用户运行的服务器。) 此选项仅在实现了 peer 身份验证方法的平台上受支持；请参阅 第 20.9 节。
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 版本，旧版本不支持最新的协议版本。如果未设置，则忽略此参数，并且连接将使用后端定义的最高边界（如果已设置）。设置最大协议版本主要用于测试或当某些组件在与较新协议配合使用时遇到问题时。
min_protocol_version #指定允许连接的最小协议版本。默认允许 libpq 支持的任何 PostgreSQL 协议版本，目前是 3.0。如果服务器不支持至少此协议版本，连接将被关闭。
当前支持的值包括 3.0、3.2 和 latest。latest 值等同于所使用的 libpq 版本支持的最新协议版本，目前是 3.2。
max_protocol_version #指定向服务器请求的协议版本。默认情况下，使用 PostgreSQL 协议的 3.0 版本，除非连接字符串指定了依赖于更高协议版本的功能，在这种情况下，将使用 libpq 支持的最新版本。如果服务器不支持客户端请求的协议版本，连接将自动降级到服务器支持的较低次要协议版本。连接尝试完成后，您可以使用 PQprotocolVersion 来了解确切协商的协议版本。
当前支持的值包括 3.0、3.2 和 latest。latest 值等同于所使用的 libpq 版本支持的最新协议版本，目前是 3.2。
krbsrvname #使用 GSSAPI 进行身份验证时要使用的 Kerberos 服务名。这必须与服务器配置中为 Kerberos 身份验证指定的#服务名匹配（另请参阅 第 20.6 节。）默认值通常是 postgres，但可以通过 configure 的 --with-krb-srvnam 选项在构建 PostgreSQL 时更改。在大多数环境中，此参数无需更改。某些 Kerberos 实现可能需要不同的服务名，例如 Microsoft Active Directory 需要服务名大写（POSTGRES）。
gsslib #用于 GSSAPI 身份验证的 GSS 库。目前，此参数除了 Windows 版本中包含 GSSAPI 和 SSPI 支持的情况外，其他情况均被忽略。在这种情况下，将其设置为 gssapi 将使 libpq 使用 GSSAPI 库进行身份验证，而不是默认的 SSPI。
gssdelegation #将 GSS 凭证转发（委派）给服务器。默认值为 0，表示凭证不会转发给服务器。将其设置为 1 以在可能时转发凭证。
scram_client_key #Base64 编码的 SCRAM 客户端密钥。这可以由外部数据包装器或类似中间件使用，以启用直通 SCRAM 身份验证。其中一种实现的示例请参见 第 F.38.1.10 节。它不应由用户或客户端应用程序直接指定。
scram_server_key #Base64 编码的 SCRAM 服务器密钥。这可以由外部数据包装器或类似中间件使用，以启用直通 SCRAM 身份验证。其中一种实现的示例请参见 第 F.38.1.10 节。它不应由用户或客户端应用程序直接指定。
service #用于附加参数的服务名。它指定 pg_service.conf 文件中的一个服务名，该服务名包含附加的连接参数。这允许应用程序仅指定一个服务名，以便可以集中维护连接参数。请参阅 第 32.17 节。
target_session_attrs #此选项决定会话是否必须具有某些属性才能被接受。它通常与多个主机名结合使用，以在多个主机中选择第一个可接受的备用主机。有六种模式：
any（默认）任何成功的连接都可接受
read-write会话默认必须接受读写事务（即，服务器不能处于热备用模式，并且 default_transaction_read_only 参数必须是 off）
read-only会话默认必须不接受读写事务（反之亦然）
primary服务器不能处于热备用模式
standby服务器必须处于热备用模式
prefer-standby首先尝试查找备用服务器，但如果列出的主机中没有备用服务器，则以 any 模式重试
load_balance_hosts #控制客户端尝试连接可用主机和地址的顺序。一旦连接尝试成功，将不再尝试其他主机和地址。此参数通常与多个主机名或返回多个 IP 的 DNS 记录结合使用。此参数可以与 target_session_attrs 结合使用，例如，仅在备用服务器之间进行负载均衡。成功连接后，返回连接上的后续查询都将发送到同一服务器。目前有两种模式：
disable（默认）不执行主机之间的负载均衡。主机按提供的顺序尝试，地址按从 DNS 或主机文件中接收的顺序尝试。
random主机和地址按随机顺序尝试。此值主要在同时打开多个连接时有用，可能来自不同的机器。这样，连接就可以在多个 PostgreSQL 服务器之间进行负载均衡。
随机负载均衡，由于其随机性，几乎不可能完全均匀分布，但在统计上非常接近。这里一个重要的方面是，该算法使用两个级别的随机选择：首先，主机将按随机顺序解析。然后，在解析下一个主机之前，当前主机的所有已解析地址将按随机顺序尝试。在某些情况下，此行为可能会大大偏离每个节点的连接数，例如当某些主机解析到比其他主机更多的地址时。但是，这种偏斜也可以被有意使用，例如，通过在主机字符串中多次提供较大服务器的主机名来增加其获得的连接数。
使用此值时，建议也为 connect_timeout 配置合理的值。因为那样，如果用于负载均衡的节点之一无响应，将尝试一个新节点。
oauth_issuer #当服务器请求连接的 OAuth 令牌时，要联系的可信发行者的 HTTPS URL。所有 OAuth 连接都需要此参数；它必须与 服务器的 HBA 配置中的 issuer 设置完全匹配。
作为标准身份验证握手的一部分，libpq 将向服务器请求一个“发现文档”：一个提供一组 OAuth 配置参数的 URL。服务器必须提供一个直接从 oauth_issuer 的组件构建的 URL，并且此值必须与发现文档本身中声明的发行者标识符完全匹配，否则连接将失败。这是为了防止一类针对 OAuth 客户端的“混合攻击”（mix-up attacks）。
您也可以显式地将 oauth_issuer 设置为用于 OAuth 发现的 /.well-known/ URI。在这种情况下，如果服务器请求不同的 URL，连接将失败，但自定义 OAuth 流程（custom OAuth flow）可能能够通过使用先前缓存的令牌来加快标准握手速度。（在这种情况下，建议同时设置 oauth_scope，因为客户端将没有机会向服务器请求正确的范围设置，并且令牌的默认范围可能不足以进行连接。） libpq 当前支持以下已知端点：
/.well-known/openid-configuration
/.well-known/oauth-authorization-server
发行者在 OAuth 连接握手中拥有高度特权。经验法则是，如果您不信任 URL 的操作员来处理对您服务器的访问，或者直接冒充您，那么该 URL 不应被信任为 oauth_issuer。
oauth_client_id #由授权服务器颁发的 OAuth 2.0 客户端标识符。如果 PostgreSQL 服务器 请求连接的 OAuth 令牌（并且没有安装自定义 OAuth 挂钩来提供一个），则必须设置此参数；否则，连接将失败。
oauth_client_secret #联系 OAuth 授权服务器时使用的客户端密码（如果有）。此参数是否必需由 OAuth 提供商决定；“公共”客户端通常不使用密码，而“机密”客户端通常使用。
oauth_scope #发送到授权服务器的访问请求的范围，指定为一个（可能为空的）空格分隔的 OAuth 范围标识符列表。此参数是可选的，用于高级用法。
通常，客户端将从 PostgreSQL 服务器获取适当的范围设置。如果使用此参数，则会忽略服务器请求的范围列表。这可以防止不太受信任的服务器向最终用户请求不当的访问范围。但是，如果客户端的范围设置不包含服务器所需的范围，服务器很可能会拒绝颁发的令牌，并且连接将失败。
空范围列表的含义取决于提供商。OAuth 授权服务器可以选择颁发带有“默认范围”（无论它是什么）的令牌，或者完全拒绝令牌请求。
如果您在文档中看到任何不正确、与您实际经验不符或需要进一步澄清的内容，请使用 此表格 报告文档问题。