Postgresql 中文操作指南

34.1. Database Connection Control Functions #

以下函数用于连接到 PostgreSQL 后端服务器。应用程序一次会打开多个后端连接。（这么做的原因之一是访问多个数据库。）每个连接都通过一个 PGconn 对象表示，该对象从函数 PQconnectdb 、 PQconnectdbParams 或 PQsetdbLogin 获取。请注意，除非甚至没有足够内存来分配 PGconn 对象，否则这些函数总是会返回一个非空对象指针。在通过连接对象发送查询之前，应该调用 PQstatus 函数来检查连接是否成功。

Warning

如果不受信任的用户有权访问未采用 secure schema usage pattern 的数据库，请通过从 search_path 中移除公共可写模式来开始每个会话。可以将参数关键字 options 设置为值 -csearch_path=。也可以在连接后发出 PQexec(_conn、"SELECT pg_catalog.set_config('search_path', '', false)")_。此考量不适用于 libpq，它适用于执行任意 SQL 命令的每个界面。

Warning

在 Unix 中，派生带有打开 libpq 连接的进程会带来不可预测的结果，因为父进程和子进程共享相同的套接字和操作系统资源。因此，不推荐这种用法，尽管从子进程执行`exec`来加载一个新的可执行文件是安全的。

  • PQconnectdbParams #

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

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

  • 此函数使用从两个以 NULL 终止的数组提取的参数打开一个新的数据库连接。第一个 keywords 被定义为一个字符串数组，每个字符串都是一个关键字。第二个 values 为每个关键字提供了值。不像下面的 PQsetdbLogin ，参数集在不更改函数签名的情况下可以进行扩展，因此对于新的应用程序编程，首选使用此函数（或其非阻塞模拟 PQconnectStartParams 和 PQconnectPoll ）。

  • 当前识别的参数关键字在 Section 34.1.2 中列出。

  • 传递的数组可以为空以使用所有默认参数，或者可以包含一个或多个参数设置。它们的长度必须匹配。处理将在`keywords`数组中的第一个`NULL`条目处停止。此外，如果与非`NULL` `keywords`条目关联的`values`条目是`NULL`或一个空字符串，该条目将被忽略，并且处理将使用下一对数组条目继续。

  • 当 expand_dbname 非零时，检查第一个 dbname 关键字的值，以查看它是否为 connection string。如果是，它将“扩展”为从字符串中提取的各个连接参数。如果值包含等号 (=) 或以 URI 架构指定符开头，那么该值被视为连接字符串，而不仅仅是数据库名称。（有关连接字符串格式的更多详细信息，请参阅 Section 34.1.1。）仅以这种方式处理 dbname 的第一次出现；将处理任何后续 dbname 参数作为普通数据库名称。

  • 一般情况下，参数数组是从头到尾进行处理的。如果任何关键字被重复，则使用最后一个值（不为`NULL`或空）。在连接字符串中找到的关键字与`keywords`数组中出现的关键字冲突时，此规则会特别适用。因此，程序员可以确定数组条目是否可以覆盖或被覆盖值从连接字符串。在扩展的`dbname`条目之前出现的数组条目可以被连接字符串的字段覆盖，进而这些字段会被`dbname`之后出现的数组条目覆盖（但再次强调，仅当那些条目提供非空值时）。

  • 在处理所有数组条目和任何展开的连接字符串后，所有保持未设置的连接参数都使用默认值填充。如果未设置的参数的对应环境变量（见 Section 34.15 ）已设置，则使用其值。如果环境变量也没有设置，则使用该参数的内置默认值。

    • PQconnectdb #

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

PGconn *PQconnectdb(const char *conninfo);

  • 此函数使用取自字符串`conninfo`的参数来打开一个新的数据库连接。

  • 已传递的字符串可以为空，以便使用所有默认参数；也可以包含一个或多个由空格分隔的参数设置；还可以包含一个 URI。有关详细信息，请参见 Section 34.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 字符串，其方式与将其传递给 PQconnectdb 时完全相同，然后按照 PQconnectdbParams 的规定应用剩余参数。

  • `pgtty`不再使用，并且将忽略任何传递的值。

    • PQsetdb #

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

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

  • 这是一个宏，它使用 PQsetdbLogin 调用 login 和 pwd 参数的空指针。它供向后兼容非常老的程序使用。

    • 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 将不会被阻塞：

  • 要开始非阻塞连接请求，请调用 PQconnectStart 或 PQconnectStartParams 。如果结果为 null，则 libpq 无法分配新的 PGconn 结构。否则，将返回一个有效的 PGconn 指针（尚未表示与数据库的有效连接）。然后调用 PQstatus(conn) 。如果结果为 CONNECTION_BAD ，则连接尝试已经失败，通常是由无效的连接参数造成的。

  • 如果 PQconnectStart 或 PQconnectStartParams 成功，则下一步是对 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 （表示连接成功建立）。

  • 在连接过程中，随时都可以通过调用 PQstatus 检查连接状态。如果此调用返回 CONNECTION_BAD ，则连接过程已失败；如果此调用返回 CONNECTION_OK ，则连接已准备好。在上面描述的 PQconnectPoll 的返回值中可同样检测到这两种状态。在（且仅在）异步连接过程中，还可能出现其他状态。这些指示连接过程的当前阶段，并且可能对例如为用户提供反馈有用。这些状态为：

  • 请注意，虽然这些常量将保持不变（为了保持兼容性），但应用程序永远不应依赖这些常量按特定顺序发生（或根本不发生），也不应依赖状态始终是这些文档值之一。应用程序可能会执行以下操作：

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 以丢弃结构以及任何关联的内存块。即使连接尝试失败或被放弃，也必须这样做。

    • 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 结构的数组，其以带有 null keyword 指针的项结束。如果无法分配内存，则返回 null 指针。注意，当前默认值（ val 字段）将取决于环境变量和其他上下文。将会忽略缺失或无效的服务文件。调用者必须将连接选项数据视为只读。

  • 处理选项数组后，通过将其传递给 PQconninfoFree 来释放它。如果未这样做，则每次调用 PQconndefaults 都会泄漏少许内存。

    • PQconninfo #

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

PQconninfoOption *PQconninfo(PGconn *conn);

  • 返回连接选项数组。这可用于确定所有可能的 PQconnectdb 选项以及用于连接到服务器的值。返回值指向 PQconninfoOption 结构的数组，其以带有 null keyword 指针的项结束。上面针对 PQconndefaults 的所有注释也适用于 PQconninfo 的结果。

    • PQconninfoParse #

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

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

  • 解析连接字符串并返回生成的选项作为数组；如果连接字符串出现问题，则返回 NULL 。此函数可用于在提供的连接字符串中提取 PQconnectdb 选项。返回值指向 PQconninfoOption 结构的数组，其以带有 null keyword 指针的项结束。

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

  • 如果 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，请使用 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);
void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);

  • 该应用程序传递具有以下签名的回调函数指针：

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

  • 然后，libpq 将调用 instead of 其默认 PQdefaultSSLKeyPassHook_OpenSSL 处理程序。回调应确定密钥的密码，并将它复制到大小为 size 的结果缓冲区 buf 。 buf 中的字符串必须以 null 结尾。返回所存储在 buf 中的密码长度，排除 null 结尾。如果失败，则回调应设置 buf[0] = '\0' 并返回 0。请参阅 libpq 源代码中的 PQdefaultSSLKeyPassHook_OpenSSL 来获取示例。

  • 如果用户指定了显式密钥位置，则在调用回调时，它的路径将在 conn→sslkey 中。如果使用的是默认密钥路径，则它将为空白。对于引擎说明符密钥，取决于引擎实现是使用 OpenSSL 密码回调还是定义它们自己的处理。

  • 应用程序回调可以选择将未处理的情况委托给 PQdefaultSSLKeyPassHook_OpenSSL，或者首先调用它，如果它返回 0，则尝试其他操作，或者完全重写它。

  • 回调 must not 使用异常、 longjmp(…​) 等控制正常的流控制。它必须正常返回。

    • PQgetSSLKeyPassHook_OpenSSL #

  • PQgetSSLKeyPassHook_OpenSSL 返回当前客户端证书密钥密码挂钩，如果尚未设置，则返回 NULL。

PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);

  • CONNECTION_STARTED #

    • 等待建立连接。

  • CONNECTION_MADE #

    • 连接正常；等待发送。

  • CONNECTION_AWAITING_RESPONSE #

    • 等待来自服务器的响应。

  • CONNECTION_AUTH_OK #

    • 收到身份验证；等待后端启动完成。

  • CONNECTION_SSL_STARTUP #

    • Negotiating SSL encryption.

  • CONNECTION_SETENV #

    • Negotiating environment-driven parameter settings.

  • CONNECTION_CHECK_WRITABLE #

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

  • CONNECTION_CONSUME #

    • 处理连接上所有剩余的响应消息。

  • PQPING_OK #

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

  • PQPING_REJECT #

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

  • PQPING_NO_RESPONSE #

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

  • PQPING_NO_ATTEMPT #

    • 因为给定参数明显错误或存在某些客户端问题（例如，内存不足），所以没有尝试联系服务器。

34.1.1. Connection Strings #

多项 libpq 函数解析用户指定字符串，以便获取连接参数。这些字符串有两种公认的格式：纯关键字/值字符串和 URI。URI 通常遵循 RFC 3986，但多主机连接字符串被允许，如下文进一步描述所示。

34.1.1.1. Keyword/Value Connection Strings #

在 keyword/value 格式中，每个参数设置都采用 keyword = value 这种形式，设置间有空格。设置等号周围的空格可选。要写入一个空值或一个包含空格的值，请用单引号括起来，例如 keyword = 'a value'。值中的单引号和反斜杠必须用反斜杠进行转义，即 \' 和 \\。

示例：

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

Section 34.1.2中列出了识别的参数关键字。

34.1.1.2. Connection URIs #

连接 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 34.1.2中列出的关键字匹配，但为了与 JDBC 连接 URI 兼容起见，ssl=true_的实例被转换为 _sslmode=require。

连接 URI 需要使用 percent-encoding进行编码，如果其中任何部分包含具有特殊含义的符号。以下是一个示例，其中等号 (=) 被替换为 %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 的连接字符串。如下所述，每个主机将按顺序尝试，直到成功建立连接。

34.1.1.3. Specifying Multiple Hosts #

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

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

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

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

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

34.1.2. Parameter Key Words #

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

  • host #

    • 要连接到的主机的名称。如果主机名看起来像绝对路径名，则指定 Unix 域通信而不是 TCP/IP 通信；值是存储套接字文件的目录的名称。（在 Unix 上，绝对路径名以斜线开头。在 Windows 上，以驱动器字母开头的路径也将被识别。）如果主机名以 @ 开头，则它被视为抽象命名空间中的 Unix 域套接字（目前在 Linux 和 Windows 上受支持）。没有指定 host 或为空时的默认行为是连接到 /tmp 中的 Unix 域套接字（或 PostgreSQL 编译时指定的任何套接字目录）。在 Windows 上，默认是连接到 localhost。

    • 还接受以逗号分隔的主机名列表，在这种情况下，将按列表中的顺序尝试每个主机名；列表中的空项将选择如上所述的默认行为。有关详细信息，请参见 Section 34.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_上的服务器的名称，则身份验证可能会失败。此外，当同时指定 _host_和 _hostaddr_时，_host_用于在密码文件中识别连接（请参见 Section 34.16）。

    • 还接受以逗号分隔的 _hostaddr_值的列表，在这种情况下，将按列表中的顺序尝试每个主机。列表中的空项将导致使用相应的主机名，或者如果该主机名也为空，则使用默认主机名。有关详细信息，请参见 Section 34.1.1.3。

    • 如果没有主机名或主机地址，libpq 将使用本地 Unix 域套接字连接；或者在 Windows 中，它将尝试连接到 localhost。

  • port #

    • 连接到服务器主机的端口号或 Unix 域连接的套接字文件名扩展。如果在 host 或 hostaddr 参数中给出了多个主机，此参数可以指定与主机列表等长的端口分隔列表，或者它可以指定一个用于所有主机的端口号。空字符串或分隔列表中的空项指定 PostgreSQL 编译时建立的默认端口号。

  • dbname #

    • 数据库名称。默认为与用户名相同。在某些上下文中，将检查值的扩展格式；有关这些格式的更多详细信息，请参见 Section 34.1.1。

  • user #

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

  • password #

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

  • passfile #

    • 指定用于存储密码的文件的名称（请参见 Section 34.16）。默认为 ~/.pgpass，或在 Microsoft Windows 上为 %APPDATA%\postgresql\pgpass.conf。（如果此文件不存在，则不会报告错误。）

  • require_auth #

    • 指定客户端要求服务器采用的身份验证方法。如果服务器未采用所需的方法对客户端进行身份验证，或者服务器未完全完成身份验证握手，连接会失败。也可提供一个由逗号分隔的方法列表，服务器必须在其中准确使用一个方法，才能让连接成功。默认情况下，接受所有身份验证方法，服务器完全可以跳过身份验证。

    • 可以通过添加 ! 前缀来否定方法，在这种情况下，服务器必须 not 尝试列出的方法；接受任何其他方法，服务器完全可以不验证客户端。如果提供了由逗号分隔的方法列表，服务器将不能 any 尝试列出的否定方法。否定形式和非否定形式不能在同一设置中结合。

    • 最后一种特殊情况，none 方法要求服务器不使用身份验证质询。（也可以否定它，以要求某种形式的身份验证。）

    • 可以指定以下方法：

  • channel_binding #

    • 该选项控制客户端使用通道绑定的方式。 require 的设置表示连接必须采用通道绑定， prefer 表示如果可用，客户端将选择通道绑定，而 disable 禁止使用通道绑定。如果 PostgreSQL 编译好 SSL 支持，则默认为 prefer ；否则，默认为 disable 。

    • 通道绑定是服务器对客户端进行身份验证的一种方法。它仅在使用 SCRAM 身份验证方法且使用 PostgreSQL 11 或更高版本服务器的 SSL 连接上受支持。

  • connect_timeout #

    • 连接时要等待的最长时间（秒），以十进制整数书写，例如 10。零、负值或未指定表示无限期等待。允许的最小超时时间为 2 秒，因此，1 的值将解释为 2。此超时适用于各个主机名或 IP 地址。例如，如果指定两个主机和 connect_timeout 为 5，则在 5 秒内未建立连接，每个主机都会超时，因此，等待连接花费的总时间可能长达 10 秒。

  • client_encoding #

    • 这会为此连接设置 client_encoding 配置参数。除了相应的服务器选项所接受的值之外，您还可以使用 auto 以确定客户端当前区域设置中的正确编码（Unix 系统中的 LC_CTYPE 环境变量）。

  • options #

    • 指定在连接开始时发送给服务器的命令行选项。例如，将其设置为 -c geqo=off 会将 geqo 参数的会话值设置为 off 。如果使用反斜杠（ \ ）转义，则此字符串内的空格将被视为分隔命令行参数；请写入 \\ 来表示一个文字反斜杠。有关可用选项的详细讨论，请参阅 Chapter 20 。

  • 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 保活的数量。将 0 设置为使用系统默认值。此参数对于通过 Unix 域套接字进行的连接或者如果禁用了保活，将被忽略。它仅在存在 TCP_KEEPCNT 或等效套接字选项的系统中受支持；在其他系统中，它没有任何效果。

  • tcp_user_timeout #

    • 控制在强制关闭连接之前，已传输的数据保持未确认状态的时间（以毫秒为单位）。值为零时使用系统默认值。对于通过 Unix 域套接字建立的连接，此参数将被忽略。仅在可以选择 TCP_USER_TIMEOUT 的系统上受支持；在其他系统上，它无效。

  • replication #

    • 此选项用于确定连接是否应使用复制协议，而不是正常协议。这是 PostgreSQL 复制连接以及诸如 pg_basebackup 之类的工具在内部使用的方法，但第三方应用程序也可以使用此协议。有关复制协议的说明，请参阅 Section 55.4。

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

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

  • gssencmode #

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

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

  • sslmode #

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

    • 有关这些选项的工作方式的详细说明，请参见 Section 34.19。

    • 对于 Unix 域套接字通信，会忽略 sslmode。如果未启用 SSL 支持便编译 PostgreSQL，则使用选项 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）。仅当启用了 SSL 支持时才提供此选项。

  • sslcompression #

    • 如果设置为 1，则通过 SSL 连接发送的数据将被压缩。如果设置为 0，则会禁用压缩。默认值为 0。如果没有 SSL 连接，则会忽略此参数。

    • 如今 SSL 压缩被视为不安全，不再建议使用。OpenSSL 1.1.0 默认禁用压缩，而且许多操作系统发行版在较早的版本中也禁用了它，因此如果服务器不接受压缩，即使将此参数设置为开启也无效。PostgreSQL 14 完全禁用了后端的压缩。

    • 如果安全性不是主要问题，并且网络是瓶颈，则压缩可以提高吞吐量。如果 CPU 性能是限制因素，则禁用压缩可以提高响应时间和吞吐量。

  • sslcert #

    • 此参数指定客户端 SSL 证书的文件名，以替代默认值 ~/.postgresql/postgresql.crt。如果没有创建 SSL 连接，则会忽略此参数。

  • sslkey #

    • 此参数指定用于客户端证书的密钥的位置。它可以指定一个将代替默认值 ~/.postgresql/postgresql.key 使用的文件名，也可以指定从外部“引擎”获取的密钥（引擎是可加载的 OpenSSL 模块）。外部引擎规范应由用冒号分隔的引擎名称和引擎特定的密钥标识符组成。如果没有创建 SSL 连接，则会忽略此参数。

  • sslpassword #

    • 此参数指定 sslkey 中指定的密钥的密码，允许在交互式密码输入不切实际的情况下以加密形式将客户端证书私钥存储在磁盘上。

    • 使用任何非空值指定此参数会禁止在向 libpq 提供加密的客户端证书密钥时，OpenSSL 默认发出的 Enter PEM pass phrase: 提示。

    • 如果未加密此密钥，则会忽略此参数。此参数对由 OpenSSL 引擎指定的密钥无效，除非引擎针对提示使用 OpenSSL 密码回调机制。

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

  • sslcertmode #

    • 此选项决定客户端证书是否可以发送到服务器，以及服务器是否要求提供此证书。有三种模式：

  • sslrootcert #

    • 该参数指定包含 SSL 证书颁发机构 (CA) 证书的文件的名称。如果文件存在，则服务器的证书将被验证为由其中一个颁发机构签署的证书。默认为 ~/.postgresql/root.crt 。

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

  • 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 协议握手有感知能力的代理，而不仅仅是任何 SSL 代理。）但是，SNI 使目标主机名以明文显示在网络流量中，因此在某些情况下可能不希望使用。

  • requirepeer #

    • 此参数指定服务器的操作系统用户名，例如_requirepeer=postgres_。在建立 Unix 域套接字连接时，如果设置了此参数，则客户端将在连接开始时检查服务器进程是否在指定的用户名前运行；如果没有，则连接将终止并返回错误。此参数可用于提供与 TCP/IP 连接上的 SSL 证书类似的服务器验证。（注意，如果 Unix 域套接字在 _/tmp_或其他可公开写入的位置，则任何用户均可启动在此处侦听的服务器。使用此参数可确保连接到受信任用户运行的服务器。）此选项仅在实现了 _peer_验证方法的平台上受支持；请参见 Section 21.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 版本，旧版本不支持最现代的协议版本。如果未设置，则此参数将被忽略，并且该连接将使用后端定义的最大范围（如果已设置）。主要适用于测试或某些组件在使用较新的协议时出现问题的情况中设置最大协议版本。

  • krbsrvname #

    • 使用 GSSAPI 时使用的 Kerberos 服务名称。这必须与服务器配置中为 Kerberos 身份验证指定的名称相匹配，以成功进行身份验证。（参见 Section 21.6 。）默认值通常为 postgres ，但是当通过配置的 —​with-krb-srvnam 选项构建 PostgreSQL 时，可以更改该值。在大多数环境中，此参数永远不需要更改。一些 Kerberos 的实现可能需要不同的服务名称，例如 Microsoft Active Directory，它要求服务名称为大写（ POSTGRES ）。

  • gsslib #

    • 用于 GSSAPI 认证的 GSS 库。当前除了同时包含 GSSAPI 和 SSPI 支持的 Windows 构建之外，此项设置均被忽略。在这种情况下，将其设置为 gssapi 使得 libpq 使用 GSSAPI 库而非默认的 SSPI 进行认证。

  • gssdelegation #

    • 将 (委托) GSS 凭证转发到服务器。默认值为 0，这意味着不会将凭证转发到服务器。将其设置为 1 以便在可能的情况下转发凭证。

  • service #

    • 用于附加参数的服务名。它指定包含附加连接参数的 _pg_service.conf_中的服务名。这允许应用程序仅指定服务名，以便可以集中维护连接参数。参见 Section 34.17。

  • target_session_attrs #

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

  • load_balance_hosts #

    • 控制客户端尝试连接到可用主机和地址的顺序。一旦连接尝试成功，将不会再尝试其他主机和地址。此参数通常与多个主机名或返回多个 IP 的 DNS 记录结合使用。此参数可以与 target_session_attrs结合使用，例如，仅对备用服务器执行负载均衡。一旦成功连接，对返回连接的所有后续查询都将发送到同一个服务器。目前有两种模式：

  • password

    • 服务器必须请求纯文本密码身份验证。

  • md5

    • 服务器必须请求 MD5 哈希密码身份验证。

  • gss

    • 服务器必须通过 GSSAPI 请求 Kerberos 握手，或建立 GSS 加密的通道（另请参见 gssencmode）。

  • sspi

    • 服务器必须请求 Windows SSPI 身份验证。

  • scram-sha-256

    • 服务器必须与客户端成功完成 SCRAM-SHA-256 身份验证交换。

  • none

    • 服务器不得提示客户端进行身份验证交换。（这不禁止通过 TLS 进行客户端证书身份验证，也不禁止通过加密传输进行 GSS 身份验证。）

  • true, on, yes, 1

    • 连接进入物理复制模式。

  • database

    • 连接进入逻辑复制模式，连接到 dbname 参数中指定的数据库。

  • false, off, no, 0

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

  • disable

    • 仅尝试非 GSSAPI 加密连接

  • prefer (default)

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

  • require

    • 仅尝试 GSSAPI 加密连接

  • disable

    • 仅尝试非 SSL 连接

  • allow

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

  • prefer (default)

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

  • require

    • 仅尝试 SSL 连接。如果存在根 CA 文件，则以与指定 verify-ca 类似的方式验证证书

  • verify-ca

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

  • verify-full

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

  • disable

    • 即使可以（默认位置或通过 sslcert提供），也不会发送客户端证书。

  • allow (default)

    • 如果服务器请求客户端提供的证书，并且客户端有可供发送的证书，则可以发送证书。

  • require

    • 服务器 must 请求证书。如果客户端不发送证书而服务器成功对客户端进行认证，那么连接将失败。

Note

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

Note

使用 sslrootcert=system 时，默认 sslmode 会更改为 verify-full，任何较弱的设置都会导致错误。在大多数情况下，任何人都很容易为他们控制的主机名获得系统信任的证书，从而使 verify-ca 和所有较弱的模式变得无用。

system 魔术值将优先于具有相同名称的本地证书文件。如果由于某种原因遇到此情况，请使用 sslrootcert=./system 等其他路径。

  • any (default)

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

  • read-write

    • 会话必须默认接受读写事务（即，服务器不得处于热备用模式，且 default_transaction_read_only 参数必须为 off）

  • read-only

    • 会话必须默认不接受读写事务（相反）

  • primary

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

  • standby

    • 服务器必须处于热备用模式

  • prefer-standby

    • 首先尝试查找备用服务器，但如果列出的主机都不是备用服务器，则在 any 模式中再试一次

  • disable (default)

    • 不执行跨主机的负载平衡。按提供顺序尝试主机，并按从 DNS 或 hosts 文件接收到的顺序尝试地址。

  • random

    • 随机尝试主机和地址。该值在同时打开多个连接时（可能来自不同的计算机）很有用。通过此方式，可以在多个 PostgreSQL 服务器之间进行负载平衡。

    • 虽然随机负载平衡由于其随机性几乎不会产生完全均匀的分布，但在统计上却非常接近。此处的一个重要方面是，该算法使用两级随机选择：首先，将按随机顺序解析主机。然后，其次，在解析下一个主机之前，将按随机顺序尝试当前主机的所有已解析地址。此行为可能会导致在某些情况下每个节点获得的连接数量大幅增加，例如当某些主机解析为比其他主机更多地址时。但是，这种倾斜也可以有目的地使用，例如，通过在主机字符串中多次提供其主机名来增加大型服务器获得的连接数。

    • 使用此值时，建议还为 connect_timeout 配置一个合理的值。因为在这之后，如果用于负载均衡的某个节点没有响应，则将尝试一个新节点。