32.1. 数据库连接控制函数

32.1. 数据库连接控制函数
上一页	上一级	Chapter 32. libpq：C 语言前端函数库	首页	下一页

32.1. 数据库连接控制函数 #

32.1.1. 连接字符串
32.1.2. 连接参数关键字

以下函数用于建立与 PostgreSQL 数据库服务端的物理连接。客户端应用程序可以同时维护多个活动的后台连接（例如用于同时并发访问多个数据库）。每个物理连接由一个 PGconn 结构体对象表示，可以通过函数 PQconnectdb、PQconnectdbParams 或 PQsetdbLogin 获取。请注意：这些函数总是返回一个非空的对象指针（除非系统内存极度匮乏连分配该对象的内存都不足）。在通过该连接发送查询前，应第一时间调用 PQstatus 函数检查返回状态以核验连接是否成功建立。

Warning

若不受信任的用户有权访问尚未采用安全模式使用规范的数据库，请在每次建立会话时首先从 search_path 中移除所有人均可写入的公开模式。可以在连接参数中将关键字 options 设置为 -csearch_path=。或者，可以在建立连接后第一时间执行 PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)")。该安全防范措施并非仅针对 libpq，而是普遍适用于任何执行任意 SQL 命令的客户端接口。

Warning

在 Unix 操作系统上，在已打开 libpq 数据库连接的情况下执行进程分叉（fork）可能引发不可预测的异常行为，因为父进程与子进程会共享相同的物理套接字描述符和底层操作系统资源。出于这个原因，强烈不建议此类用法；但在子进程中调用 exec 系列函数加载全新的可执行程序则是完全安全的。

PQconnectdbParams #

建立与数据库服务器的全新物理连接。

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

该函数使用从两个以 NULL 结尾的指针数组中提取的参数建立全新的数据库连接。第一个数组 keywords 是字符串数组，每个元素为一个配置关键字。第二个数组 values 给出了对应每个关键字的配置值。与下文的 PQsetdbLogin 不同，此接口无需修改函数签名即可任意扩展参数集合，因此在编写全新的应用程序时，强烈推荐使用此函数（或其对应的非阻塞异步版本 PQconnectStartParams 和 PQconnectPoll）。

当前所有被支持识别的参数关键字详见 Section 32.1.2。

传入的数组可以为空数组以使用所有内置默认参数，也可以包含一个或多个参数设置。两个数组在长度上必须严格匹配。参数解析会在遇到 keywords 数组中的首个 NULL 元素时停止。此外，如果与某个非 NULL 关键字对应的 values 元素为 NULL 或空字符串，该配置条目将被忽略并继续处理下一对数组项。

当 expand_dbname 为非零时，系统会检查第一个 dbname 关键字的取值是否为连接字符串（connection string）。如果是，它会被自动“展开”（expanded）为从该字符串中解析出的各个独立连接参数。如果该值包含等号（=）或以 URI 协议前缀开头，则被视为连接字符串而非单纯的数据库名称（连接字符串格式的更多细节见 Section 32.1.1）。只有首次出现的 dbname 会被这样处理；后续出现的任何 dbname 参数都将被视为普通数据库名。

通常，参数数组按照从头到尾的顺序依次处理。如果某个关键字重复出现，则采用最后遇到的有效非空值。特别是当连接字符串中解析出的关键字与 keywords 数组中的项发生冲突时，该规则同样适用。因此，开发者可以精细控制数组项是覆盖连接字符串中的值还是被其覆盖：出现在展开的 dbname 之前的数组项会被连接字符串中的对应字段覆盖，而连接字符串中的字段又会被出现在 dbname 之后的数组项所覆盖（前提是这些项提供了非空值）。

在处理完所有数组项和任何展开的连接字符串后，任何仍未显式指定的连接参数将以默认值填充。如果未设定参数对应的环境变量（参见 Section 32.15）已被设置，则采用环境变量的值；若环境变量同样未设置，则采用系统内置的默认值。

PQconnectdb #

建立与数据库服务器的全新物理连接。

PGconn *PQconnectdb(const char *conninfo);

该函数使用从字符串 conninfo 中提取的连接参数建立全新的数据库连接。

传入的字符串可以为空以使用所有默认参数，也可以包含一个或多个由空白字符分隔的键值对参数设置，或者包含一个符合规范的连接 URI。详见 Section 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 的前身，接受固定数量的位置参数。其功能完全一致，未包含的高级参数始终自动采用默认值。对于任何希望使用默认值的固定参数，请传入 NULL 或空字符串。

如果 dbName 包含等号（=）或具有合法的连接 URI 前缀，它会被直接视作 conninfo 连接字符串，其余参数将按照针对 PQconnectdbParams 所述的规则叠加应用。

pgtty 现已彻底废弃，传入的任何参数值都会被系统直接忽略。

PQsetdb #

建立与数据库服务器的全新物理连接。

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

这是一个将 login 和 pwd 传递空指针并调用 PQsetdbLogin 的便捷宏定义，仅为兼容极古老的遗留程序而保留。

PQconnectStartParams PQconnectStart PQconnectPoll #

以非阻塞异步方式发起与数据库服务器的连接建立。

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 域名解析。详情请参阅 Section 32.1.2 中该参数的说明。
如果调用了 PQtrace，请确保跟踪输出的流对象不会引发 I/O 阻塞。
在调用 PQconnectPoll 之前，必须确保底层套接字处于恰当的读写就绪状态，如下文所述。

要发起非阻塞连接请求，请调用 PQconnectStart 或 PQconnectStartParams。若返回空指针，表示 libpq 内存不足以分配新的 PGconn 结构体。否则将返回有效的结构体指针（此时它尚不代表与数据库建立了可用物理连接）。接下来调用 PQstatus(conn)；若返回结果为 CONNECTION_BAD，则表明连接尝试已在初期失败（通常是由非法连接参数引起的）。

若初始化函数成功返回，接下来的阶段是轮询驱动 libpq 以推进连接握手序列。调用 PQsocket(conn) 获取底层物理套接字描述符（注意：切勿假定套接字在整个握手期间保持不变）。按如下循环轮询：若 PQconnectPoll(conn) 上次返回 PGRES_POLLING_READING，则等待套接字可读（通过 select()、poll() 或类似事件驱动机制）；随后再次调用 PQconnectPoll(conn)。反之若上次返回 PGRES_POLLING_WRITING，则等待套接字可写并再次调用轮询函数。在首轮迭代时（即尚未调用过该函数时），假定其返回状态为 PGRES_POLLING_WRITING。持续此循环，直到函数返回 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/TLS 传输加密握手协商。
CONNECTION_GSS_STARTUP #: 正在进行 GSSAPI 传输加密握手协商。
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 指针为空的条目结束。如果无法分配内存，则返回空指针。注意，当前的默认值（val 字段）将取决于环境变量和其他上下文。缺失或无效的服务文件会被静默忽略。调用者必须把连接选项数据视为只读。

在处理完选项数组之后，通过把它传递给 PQconninfoFree 来释放它。如果不这样做，每次调用 PQconndefaults 都会泄漏少量内存。

PQconninfo #

返回一条活动连接所使用的连接选项。

PQconninfoOption *PQconninfo(PGconn *conn);

返回一个连接选项数组。它可用于确定 PQconnectdb 的所有可能选项以及用于连接到服务器的值。返回值指向一个 PQconninfoOption 结构数组，该数组以一个 keyword 指针为空的条目结束。上文针对 PQconndefaults 的所有说明同样适用于 PQconninfo 的结果。

PQconninfoParse #

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

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

解析一个连接字符串并把得到的选项作为一个数组返回；如果连接字符串有问题，则返回 NULL。这个函数可用于提取所提供连接字符串中的 PQconnectdb 选项。返回值指向一个 PQconninfoOption 结构数组，该数组以一个 keyword 指针为空的条目结束。

所有合法的选项都会出现在结果数组中，但任何未出现在连接字符串中的选项，其 PQconninfoOption 的 val 将被设置为 NULL；默认值不会被插入。

如果 errmsg 不是 NULL，那么成功时 *errmsg 会被设置为 NULL，否则会被设置为一个由 malloc 分配的、解释该问题的错误字符串。（*errmsg 也可能被设置为 NULL 且函数返回 NULL；这表示内存不足的情况。）

在处理完选项数组之后，通过把它传递给 PQconninfoFree 来释放它。如果不这样做，每次调用 PQconninfoParse 都会泄漏一些内存。反过来，如果发生了错误并且 errmsg 不是 NULL，请确保使用 PQfreemem 释放该错误字符串。

PQfinish #

关闭到服务器的连接。同时释放 PGconn 对象使用的内存。

void PQfinish(PGconn *conn);

注意，即使到服务器的连接尝试失败（如 PQstatus 所指示的那样），应用程序也应当调用 PQfinish 来释放 PGconn 对象使用的内存。在 PQfinish 被调用之后，不得再使用该 PGconn 指针。

PQreset #

重置并重新建立与服务端的网络通信通道。

void PQreset(PGconn *conn);

这个函数会关闭到服务器的连接，并尝试使用之前使用的所有相同参数建立一条新连接。如果一条可用的连接丢失了，这对错误恢复可能有用。

PQresetStart PQresetPoll #

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

int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);

这些函数会关闭到服务器的连接，并尝试使用之前使用的所有相同参数建立一条新连接。如果一条可用的连接丢失了，这对错误恢复可能有用。它们与 PQreset（上文）的区别在于它们以非阻塞的方式行动。这些函数受到与 PQconnectStartParams、 PQconnectStart 和 PQconnectPoll 相同的限制。

要发起一次连接重置，调用 PQresetStart。如果它返回 0，则重置失败。如果它返回 1，则以与使用 PQconnectPoll 创建连接完全相同的方式用 PQresetPoll 轮询重置。

PQpingParams #

PQpingParams 报告服务器的状态。它接受与 PQconnectdbParams 相同的连接参数（如上所述）。要获取服务器状态，不必提供正确的用户名、密码或数据库名；然而，如果提供了不正确的值，服务器将记录一次失败的连接尝试。

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

该函数返回以下值之一：

PQPING_OK #: 服务器正在运行，并且看起来正在接受连接。
PQPING_REJECT #: 服务器正在运行，但处于不允许连接的状态（启动、关闭或崩溃恢复）。
PQPING_NO_RESPONSE #: 无法联系到服务器。这可能表明服务器没有运行，或者给定的连接参数有问题（例如端口号错误），或者存在网络连接问题（例如防火墙阻塞了连接请求）。
PQPING_NO_ATTEMPT #: 由于所提供的参数明显不正确，或者存在某种客户端问题（例如内存不足），因而没有尝试联系服务器。

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 中的字符串必须以空字符结尾。回调必须返回存储在 buf 中的密码的长度（不包括空终止符）。失败时，回调应当设置 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);

32.1.1. 连接字符串 #

若干 libpq 函数会解析一个用户指定的字符串以获得连接参数。这些字符串有两种可接受的格式：纯键/值字符串和 URI。URI 通常遵循 RFC 3986，但允许多主机连接字符串，下文将进一步描述。

32.1.1.1. 键值对连接字符串 #

在键/值格式中，每个参数设置的形式为 keyword = value，各设置之间用空格分隔。设置的等号周围的空格是可选的。要写一个空值，或者一个包含空格的值，请用单引号把它括起来，例如 keyword = 'a value'。值中的单引号和反斜杠必须用反斜杠转义，即 \' 和 \\。

Example:

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

可识别的参数关键字列在 Section 32.1.2 中。

32.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:// 或 postgres://。其余的每个 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

所有命名参数都必须匹配 Section 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 的连接字符串。如下文进一步描述的，每个主机都会被依次尝试，直到成功建立一条连接。

32.1.1.3. 指定多主机连接 #

可以指定多个要连接的主机，这样它们就会按照给定的顺序被尝试。在键/值格式中，host、 hostaddr 和 port 选项接受以逗号分隔的值列表。每个被指定的选项中必须给出相同数量的元素，例如，第一个 hostaddr 对应第一个主机名，第二个 hostaddr 对应第二个主机名，依此类推。作为一个例外，如果只指定了一个 port，它将应用于所有主机。

在连接 URI 格式中，你可以在 URI 的 host 部分中列出多个以逗号分隔的 host:port 对。

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

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

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

32.1.2. 连接参数关键字 #

当前可识别的参数关键字有：

host #

要连接到的主机的名称。如果主机名看起来像一个绝对路径名，它指定 Unix 域通信而非 TCP/IP 通信；该值是存储套接字文件的目录的名字。（在 Unix 上，绝对路径名以斜杠开头。在 Windows 上，以盘符开头的路径也会被识别。）如果主机名以 @ 开头，它被视为抽象命名空间中的 Unix 域套接字（当前在 Linux 和 Windows 上受支持）。当 host 未被指定或为空时，默认行为是连接到 /tmp 中的 Unix 域套接字（或构建 PostgreSQL 时指定的任何套接字目录）。在 Windows 上，默认是连接到 localhost。

也接受以逗号分隔的主机名列表，在这种情况下，列表中的每个主机名都会被依次尝试；列表中的空项会选择上文解释的默认行为。详情请参见 Section 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 不是位于网络地址 hostaddr 处的服务器的名字，身份验证很可能会失败。此外，当同时指定了 host 和 hostaddr 时， host 会被用来在密码文件中标识这条连接（参见 Section 32.16）。

也接受以逗号分隔的 hostaddr 值列表，在这种情况下，列表中的每个主机都会被依次尝试。列表中的空项会导致使用对应的主机名，如果主机名也为空则使用默认主机名。详情请参见 Section 32.1.1.3。

在既没有主机名也没有主机地址的情况下， libpq 将使用本地 Unix 域套接字连接；或者在 Windows 上，它将尝试连接到 localhost。

port #

在服务器主机上要连接到的端口号，或者 Unix 域连接的套接字文件名扩展。如果在 host 或 hostaddr 参数中给出了多个主机，这个参数可以指定一个与主机列表长度相同的、以逗号分隔的端口列表，或者指定一个用于所有主机的单一端口号。空字符串，或以逗号分隔列表中的空项，指定构建 PostgreSQL 时确立的默认端口号。

dbname #

数据库名。默认与用户名相同。在某些上下文中，会检查该值是否为扩展格式；关于这些格式的更多细节请参见 Section 32.1.1。

user #

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

password #

当服务器要求密码身份验证时要使用的密码。

passfile #

指定用于存储密码的文件（参见 Section 32.16）。默认为 ~/.pgpass，在 Microsoft Windows 上为 %APPDATA%\postgresql\pgpass.conf。（如果这个文件不存在，不会报告错误。）

require_auth #

指定客户端要求服务器使用的身份验证方法。如果服务器没有使用所需的方法来验证客户端，或者服务器没有完全完成身份验证握手，连接将失败。也可以提供一个以逗号分隔的方法列表，服务器必须恰好使用其中一种，连接才能成功。默认情况下，任何身份验证方法都会被接受，并且服务器可以完全跳过身份验证。

方法可以通过添加 ! 前缀来取反，在这种情况下，服务器不得尝试所列的方法；任何其他方法都会被接受，并且服务器可以完全不验证客户端。如果提供了一个以逗号分隔的列表，服务器不得尝试所列取反方法中的 任何一种。取反与非取反的形式不能在同一个设置中组合。

作为最后一个特例， none 方法要求服务器不使用身份验证质询。（它也可以被取反，以要求某种形式的身份验证。）

可以指定以下方法：

password: 服务器必须请求明文密码身份验证。
md5: 服务器必须请求 MD5 哈希密码身份验证。
Warning
对 MD5 加密密码的支持已被弃用，并将在 PostgreSQL 未来的发行版中被移除。有关迁移到其他密码类型的细节，请参见 Section 20.3.2。
gss: 服务器必须通过 GSSAPI 请求一次 Kerberos 握手，或者建立一条 GSS 加密的通道（另请参见 gssencmode）。
sspi: 服务器必须请求 Windows SSPI 身份验证。
scram-sha-256: 服务器必须与客户端成功地完成一次 SCRAM-SHA-256 身份验证交换。
oauth: 服务器必须向客户端请求一个 OAuth bearer 令牌。
none: 服务器不得提示客户端进行身份验证交换。（这并不禁止通过 TLS 进行的客户端证书身份验证，也不禁止通过其加密传输进行的 GSS 身份验证。）

channel_binding #

这个选项控制客户端对通道绑定的使用。设置 require 表示连接必须采用通道绑定； prefer 表示如果可用客户端会选择通道绑定； disable 阻止通道绑定的使用。如果 PostgreSQL 编译时带有 SSL 支持，默认值为 prefer；否则默认值为 disable。

通道绑定是服务器向客户端验证自身的一种方法。它只在 SSL 连接上受支持，并且需要 PostgreSQL 11 或更高版本的服务器使用 SCRAM 身份验证方法。

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。这个字符串内的空格被视为分隔命令行参数，除非用反斜杠（\）转义；写 \\ 来表示一个字面上的反斜杠。有关可用选项的详细讨论，请参见 Chapter 19。

application_name #

为 application_name 配置参数指定一个值。

fallback_application_name #

为 application_name 配置参数指定一个后备值。如果没有通过连接参数或 PGAPPNAME 环境变量为 application_name 给出值，将使用这个值。对于希望设置一个默认应用程序名，但允许用户覆盖它的通用工具程序来说，指定一个后备名字很有用。

keepalives #

控制是否使用客户端侧的 TCP 保活。默认值为 1，表示开启；如果不想要保活，你可以把它改为 0，表示关闭。对于通过 Unix 域套接字建立的连接，这个参数会被忽略。

keepalives_idle #

控制多少秒的不活动之后 TCP 应当向服务器发送一条保活消息。值为零使用系统默认值。对于通过 Unix 域套接字建立的连接，或者在保活被禁用的情况下，这个参数会被忽略。它只在 TCP_KEEPIDLE 或等效套接字选项可用的系统上以及 Windows 上受支持；在其他系统上它没有效果。

keepalives_interval #

控制在一条未被服务器确认的 TCP 保活消息之后多少秒应当重传它。值为零使用系统默认值。对于通过 Unix 域套接字建立的连接，或者在保活被禁用的情况下，这个参数会被忽略。它只在 TCP_KEEPINTVL 或等效套接字选项可用的系统上以及 Windows 上受支持；在其他系统上它没有效果。

keepalives_count #

控制在客户端到服务器的连接被视为死亡之前，可以丢失多少个 TCP 保活。值为零使用系统默认值。对于通过 Unix 域套接字建立的连接，或者在保活被禁用的情况下，这个参数会被忽略。它只在 TCP_KEEPCNT 或等效套接字选项可用的系统上受支持；在其他系统上它没有效果。

tcp_user_timeout #

控制在被发送的数据保持未被确认多少毫秒之后，连接将被强制关闭。值为零使用系统默认值。对于通过 Unix 域套接字建立的连接，这个参数会被忽略。它只在 TCP_USER_TIMEOUT 可用的系统上受支持；在其他系统上它没有效果。

replication #

这个选项决定连接是否应当使用复制协议来取代普通协议。这是 PostgreSQL 复制连接以及 pg_basebackup 之类的工具内部使用的协议，但第三方应用程序也可以使用它。有关复制协议的描述，请参见 Section 54.4。

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

true、on、 yes、1: 连接进入物理复制模式。
database: 连接进入逻辑复制模式，连接到 dbname 参数中指定的数据库。
false, off, no, 0: 这是一条普通连接，这是默认行为。

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

gssencmode #

这个选项决定是否与服务器协商一条安全的 GSS TCP/IP 连接，或以何种优先级协商。有三种模式：

disable: 只尝试非 GSSAPI 加密的连接
prefer (default): 如果存在 GSSAPI 凭据（即在凭据缓存中），首先尝试 GSSAPI 加密的连接；如果失败或没有凭据，则尝试非 GSSAPI 加密的连接。当 PostgreSQL 编译时带有 GSSAPI 支持时，这是默认值。
require: 只尝试 GSSAPI 加密的连接

对于 Unix 域套接字通信， gssencmode 会被忽略。如果 PostgreSQL 编译时没有 GSSAPI 支持，使用 require 选项会导致错误，而 prefer 会被接受，但 libpq 实际上不会尝试 GSSAPI 加密的连接。

sslmode #

这个选项决定是否与服务器协商一条安全的 SSL TCP/IP 连接，或以何种优先级协商。有六种模式：

disable: 只尝试非 SSL 连接
allow: 首先尝试非 SSL 连接；如果失败，则尝试一条 SSL 连接
prefer (default): 首先尝试 SSL 连接；如果失败，则尝试非 SSL 连接
require: 只尝试 SSL 连接。如果存在根 CA 文件，则按照指定了 verify-ca 时的相同方式验证证书
verify-ca: 只尝试 SSL 连接，并验证服务器证书是由一个受信任的证书颁发机构（CA）签发的
verify-full: 只尝试 SSL 连接，验证服务器证书是由一个受信任的 CA 签发的，并且所请求的服务器主机名与证书中的相匹配

See Section 32.19 for a detailed description of how these options work.

对于 Unix 域套接字通信， sslmode 会被忽略。如果 PostgreSQL 编译时没有 SSL 支持，使用选项 require、 verify-ca 或 verify-full 会导致错误，而选项 allow 和 prefer 会被接受，但 libpq 实际上不会尝试 SSL 连接。

注意，如果 GSSAPI 加密是可能的，那么无论 sslmode 的值如何，都会优先使用 GSSAPI 加密而非 SSL 加密。要在一个拥有可用的 GSSAPI 基础设施（例如 Kerberos 服务器）的环境中强制使用 SSL 加密，还要把 gssencmode 设置为 disable。

requiressl #

这个选项已被弃用，应改用 sslmode 设置。

如果设置为 1，则要求到服务器的 SSL 连接（这等同于 sslmode 的 require）。如果服务器不接受 SSL 连接， 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 上下文中使用的密钥的位置。这对于使用 Wireshark 之类的网络检查工具调试 PostgreSQL 协议交互或客户端连接很有用。如果没有建立 SSL 连接，或者使用了 LibreSSL （LibreSSL 不支持密钥记录），这个参数会被忽略。密钥以 NSS 格式记录。

Warning

密钥记录会把潜在的敏感信息暴露在密钥日志文件中。密钥日志文件应当与 sslkey 文件一样谨慎对待。

sslpassword #

这个参数指定 sslkey 中指定的私钥的密码，即使在交互式输入口令短语不可行的情况下，也允许客户端证书私钥以加密的形式存储在磁盘上。

为这个参数指定任何非空值，都会抑制 OpenSSL 在向 libpq 提供加密的客户端证书密钥时默认发出的 Enter PEM pass phrase: 提示。

如果密钥没有加密，这个参数会被忽略。对于由 OpenSSL 引擎指定的密钥，除非引擎使用 OpenSSL 的密码回调机制进行提示，这个参数没有效果。

这个选项没有等效的环境变量，也没有在 .pgpass 中查找它的机制。它可以在服务文件连接定义中使用。有更复杂用途的用户应当考虑使用 OpenSSL 引擎以及 PKCS#11 或 USB 加密卸载设备之类的工具。

sslcertmode #

这个选项决定是否可以把客户端证书发送给服务器，以及是否要求服务器请求一张证书。有三种模式：

disable: 永远不发送客户端证书，即使有一张可用（位于默认位置或通过 sslcert 提供）。
allow (default): 如果服务器请求一张证书并且客户端有一张可发送的，则可以发送证书。
require: 服务器必须请求一张证书。如果客户端没有发送证书，而服务器仍然成功验证了客户端，连接将失败。

Note

sslcertmode=require 不会增加任何额外的安全性，因为无法保证服务器正确地验证证书； PostgreSQL 服务器通常会向客户端请求 TLS 证书，无论它们是否验证这些证书。在排查更复杂的 TLS 设置时，这个选项可能有用。

sslrootcert #

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

也可以指定特殊值 system，在这种情况下，将加载来自 SSL 实现的受信任 CA 根证书。这些根证书的确切位置因 SSL 实现和平台而异。特别是对于 OpenSSL，这些位置还可能被 SSL_CERT_DIR 和 SSL_CERT_FILE 环境变量进一步修改。

Note

当使用 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 身份验证方法的平台上受支持；参见 Section 20.3.6。

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 支持的最新版本。如果服务器不支持客户端请求的协议版本，连接将自动降级到服务器支持的较低次要协议版本。在连接尝试完成之后，你可以使用 PQfullProtocolVersion 来查明协商出的确切协议版本。

当前受支持的值是 3.0、3.2 和 latest。值 latest 等同于所使用的 libpq 版本支持的最新协议版本，当前是 3.2。

krbsrvname #

用 GSSAPI 进行身份验证时要使用的 Kerberos 服务名。它必须与服务器配置中为 Kerberos 身份验证指定的服务名相匹配，身份验证才能成功。（另请参见 Section 20.3.3。）默认值通常为 postgres，但在构建 PostgreSQL 时可以通过 configure 的 --with-krb-srvnam 选项更改它。在大多数环境中，这个参数从不需要更改。某些 Kerberos 实现可能要求一个不同的服务名，例如 Microsoft Active Directory 要求服务名采用大写形式（POSTGRES）。

gsslib #

用于 GSSAPI 身份验证的 GSS 库。目前除了同时包含 GSSAPI 和 SSPI 支持的 Windows 构建之外，它都会被忽略。在那种情况下，把它设置为 gssapi 会让 libpq 使用 GSSAPI 库进行身份验证，而不是默认的 SSPI。

gssdelegation #

向服务器转发（委托）GSS 凭据。默认值为 0，表示凭据不会被转发给服务器。把它设置为 1 以在可能的情况下转发凭据。

scram_client_key #

以 base64 编码的 SCRAM 客户端密钥。外部数据封装器或类似的中间件可以使用它来启用直通 SCRAM 身份验证。有关这样一种实现，请参见 Section F.38.1.10。它并不预期由用户或客户端应用程序直接指定。

scram_server_key #

以 base64 编码的 SCRAM 服务器密钥。外部数据封装器或类似的中间件可以使用它来启用直通 SCRAM 身份验证。有关这样一种实现，请参见 Section F.38.1.10。它并不预期由用户或客户端应用程序直接指定。

service #

用于附加参数的服务名。它指定 pg_service.conf 中一个保存附加连接参数的服务名。这允许应用程序只指定一个服务名，从而让连接参数可以被集中维护。参见 Section 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 或 hosts 文件中接收到的顺序尝试。

random

主机和地址以随机顺序尝试。这个值主要在同时打开多条连接时有用，这些连接可能来自不同的机器。这样连接就可以在多个 PostgreSQL 服务器之间进行负载均衡。

虽然随机负载均衡由于其随机性几乎永远不会导致完全均匀的分布，但它在统计上相当接近。这里的一个重要方面是，这个算法使用两级随机选择：首先，主机将以随机顺序被解析。然后，在解析下一台主机之前，当前主机所有已解析的地址都会以随机顺序被尝试。在某些情况下，这种行为可能极大地歪曲每个节点获得的连接数量，例如当某些主机解析出的地址比其他主机多时。但这样的倾斜也可以被有意利用，例如通过在主机字符串中多次提供某台较大服务器的主机名，来增加它获得的连接数量。

在使用这个值时，建议同时为 connect_timeout 配置一个合理的值。这样，如果用于负载均衡的某个节点没有响应，就会尝试一个新的节点。

oauth_issuer #

如果服务器为连接请求一个 OAuth 令牌，要联系的受信任颁发者的 HTTPS URL。所有 OAuth 连接都需要这个参数；它应当与服务器的 HBA 配置中的 issuer 设置完全匹配。

作为标准身份验证握手的一部分， libpq 将向服务器请求一份 发现文档： 即一个提供一组 OAuth 配置参数的 URL。服务器必须提供一个直接由 oauth_issuer 的各部分构造而成的 URL，并且这个值必须与发现文档自身中声明的颁发者标识符完全匹配，否则连接将失败。这样做是为了防止针对 OAuth 客户端的一类 "混合攻击"。

你也可以把 oauth_issuer 显式设置为用于 OAuth 发现的 /.well-known/ URI。在这种情况下，如果服务器要求一个不同的 URL，连接将失败，但一个自定义 OAuth 流程可以通过使用先前缓存的令牌来加速标准握手。（在这种情况下，建议同时设置 oauth_scope，因为客户端将没有机会向服务器询问正确的作用域设置，而令牌的默认作用域可能不足以连接。） libpq 当前支持以下知名端点：

/.well-known/openid-configuration
/.well-known/oauth-authorization-server

Warning

在 OAuth 连接握手期间，颁发者拥有很高的特权。根据经验，如果你不信任某个 URL 的运营者来处理对你服务器的访问，或者不信任它直接冒充你，那么该 URL 就不应当被信任为 oauth_issuer。

oauth_client_id #

由授权服务器颁发的 OAuth 2.0 客户端标识符。如果 PostgreSQL 服务器为连接请求一个 OAuth 令牌（并且没有安装提供令牌的自定义 OAuth 钩子），那么必须设置这个参数；否则，连接将失败。

oauth_client_secret #

联系 OAuth 授权服务器时要使用的客户端密码（如果有）。这个参数是否必需由 OAuth 提供方决定； "公共"客户端通常不使用密码，而"机密"客户端通常使用。

oauth_scope #

发送给授权服务器的访问请求的作用域，表示为一个（可能为空的）以空格分隔的 OAuth 作用域标识符列表。这个参数是可选的，预期用于高级用法。

通常客户端会从 PostgreSQL 服务器获得适当的作用域设置。如果使用了这个参数，服务器请求的作用域列表将被忽略。这可以防止一个不太受信任的服务器向最终用户请求不适当的访问作用域。然而，如果客户端的作用域设置不包含服务器所需的作用域，服务器很可能会拒绝所颁发的令牌，连接将失败。

空作用域列表的含义取决于提供方。 OAuth 授权服务器可能选择颁发一个具有"默认作用域"的令牌（无论它碰巧是什么），也可能完全拒绝令牌请求。