9.3 9.4 9.5 9.6 10 11 12 13 14
阿里云PostgreSQL 问题报告 纠错本页面

34.1. 数据库连接控制函数

34.1.1. 连接字符串
34.1.2. 参数关键词

下列函数会建立到一个PostgreSQL后端服务器的连接。 一个应用程序可以在一个时刻打开多个后端连接(原因之一就是为了访问多个数据库)。 每个连接用一个PGconn对象表示,它从函数PQconnectdbPQconnectdbParams,或PQsetdbLogin得到。 注意这些函数将总是返回一个非空的对象指针,除非正好没有内存来分配PGconn对象。 在通过该连接对象发送查询之前,应该调用PQstatus函数来检查返回值以确定是否得到了一个成功的连接。

警告

如果不可信用户能够访问一个没有采用安全方案使用模式的数据库,开始每个会话时应该从search_path中移除公共可写的方案。我们可以把参数关键词options设置为-csearch_path=。也可以在连接后发出PQexec(conn, "SELECT pg_catalog.set_config('search_path', '', false)")。这种考虑并非专门针对libpq,它适用于每一种用来执行任意SQL命令的接口。

警告

在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可以预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec来载入新的可执行代码是安全的。

PQconnectdbParams

开启一个到数据库服务器的新连接。

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

这个函数使用从两个以NULL结尾的数组中取得的参数打开一个新的数据库连接。第一个数组keywords被定义为一个字符串数组,每一个元素是一个关键词。第二个数组values给出了每个关键词的值。和下面的PQsetdbLogin不同,可以在不改变函数签名的情况下扩展参数集合,因此使用这个函数(或者与之相似的非阻塞的PQconnectStartParamsPQconnectPoll)对于新应用编程要更好。

当前能被识别的参数关键词被列举在第 34.1.2 节中。

被传递的数组可以为空,这样就会使用所有默认参数。 也可以只包含一个或几个参数设置。他们在长度上必须匹配。 对于参数数组的处理将会停止于keywords数组中第一个NULL元素。 而且,如果与非-NULL keywords条目相关联的values条目为NULL或者空字符串,则忽略该项并继续处理下一对数组项。

expand_dbname为非零时,会检查第一个dbname关键词的值以查看它是否为一个connection string。 如果是,它被扩展到从字符串中提取的单独的连接参数。 该值被认为是一个连接字符串,而不仅是一个数据库名称,如果它包含一个等号(=)或者它以URI模式标志符开头, (有关连接字符串格式的更多详情可见第 34.1.1 节。) 只有dbname的第一次出现会按这种方式处理,任何后续dbname值会被当做一个普通数据库名处理。

通常,参数数组从开头到结尾进行处理。 当关键词有重复时,使用最后一个值(不是 NULL 或空)。 此规则特别适用于连接字符串中的关键字与一个出现在keywords数组中的关键字冲突的情况。 因此,程序员可以决定数组条目是否能被覆盖或用连接字符串获取的值覆盖。 出现在扩展的dbname条目之前的数组条目可以被连接字符串的字段所覆盖,反之,这些字段被dbname之后出现的数组条目所覆盖。(但是,再有,只有在那些条目支持非空值时。)

在处理完所有数组条目和任何扩展的连接字符串后,所有未设置的连接参数都将使用默认值填充。 如果一个未设置参数的相关环境变量(参见 第 34.15 节)被设置了,它的值会被使用。 如果环境变量未被设置,则使用参数的内置默认值。

PQconnectdb

开启一个到数据库服务器的新连接。

PGconn *PQconnectdb(const char *conninfo);

这个函数使用从字符串conninfo中得到的参数开启一个新的数据库连接。

被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见第 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的宏,其中为loginpwd参数使用空指针。提供它是为了向后兼容非常老的程序。

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 完成可能在应用的主循环中发生,而不是在PQconnectdbParamsPQconnectdb中,并且因此应用能够把这种操作和其他动作并行处理。

PQconnectStartParams中,数据库连接使用从keywordsvalues数组中取得的参数创建,并且被expand_dbname控制,这和之前描述的PQconnectdbParams相同。

PQconnectStart中,数据库连接使用从字符串conninfo中取得的参数创建,这和之前描述的PQconnectdb相同。

只要满足一些限制,PQconnectStartParamsPQconnectStartPQconnectPoll都不会阻塞:

  • hostaddrhost参数必须被合适地使用,以防止做DNS查询。详见第 34.1.2 节中这些参数的文档。

  • 如果你调用PQtrace,确保你追踪的该流对象不会阻塞。

  • 如后文所述,你必须要确保在调用PQconnectPoll之前,套接字处于合适的状态。

要开始无阻塞的连接请求,可调用PQconnectStart或者PQconnectStartParams。如果结果为空,则libpq无法分配一个新的PGconn结构。否则,一个有效的PGconn指针会被返回(不过还没有表示一个到数据库的有效连接)。接下来调用PQstatus(conn)。如果结果是CONNECTION_BAD,则连接尝试已经失败,通常是因为有无效的连接参数。

如果PQconnectStartPQconnectStartParams成功,下一个阶段是轮询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的返回值检测。在一个异步连接过程中(也只有在这个过程中)也可能出现其他状态。这些状态指示该连接过程的当前阶段,并且可能有助于为用户提供反馈。这些状态是:

CONNECTION_STARTED

等待连接被建立。

CONNECTION_MADE

连接 OK,等待发送。

CONNECTION_AWAITING_RESPONSE

等待来自服务器的一个回应。

CONNECTION_AUTH_OK

收到认证,等待后端启动结束。

CONNECTION_SSL_STARTUP

协商 SSL 加密。

CONNECTION_SETENV

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

CONNECTION_CHECK_WRITABLE

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

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

注意当PQconnectStartPQconnectStartParams返回一个非空的指针时,你必须在用完它之后调用PQfinish来处理那些结构和任何相关的内存块。即使连接尝试失败或被放弃时也必须完成这些工作。

PQconndefaults

返回默认连接选项。

PQconninfoOption *PQconndefaults(void);

typedef struct
{
    char   *keyword;   /* 该选项的关键词 */
    char   *envvar;    /* 依赖的环境变量名 */
    char   *compiled;  /* 依赖的内建默认值 */
    char   *val;       /* 选项的当前值,或者 NULL */
    char   *label;     /* 连接对话框中域的标签 */
    char   *dispchar;  /* 指示如何在一个连接对话框中显示这个域。值是:
                          ""        显示输入的值
                          "*"       口令域 - 隐藏值
                          "D"       调试选项 - 默认不显示 */
    int     dispsize;  /* 用于对话框的以字符计的域尺寸 */
} 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指针的条目结束。

所有合法选项将出现在结果数组中,但是任何在连接字符串中没有出现的选项的PQconninfoOptionval会被设置为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的不同在于它们工作在非阻塞方式。 这些函数受到PQconnectStartParamsPQconnectStartPQconnectPoll相同的限制。

要发起一次连接重置,调用PQresetStart。如果它返回 0,那么重置失败。如果返回 1,用与使用PQresetPoll建立连接的相同方法使用PQconnectPoll重置连接。

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 令一个应用取代 libpqdefault handling of encrypted client certificate key files , 使用sslpassword 或交互提示方式。

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-terminated)。 回调函数必须返回存储在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);

34.1.1. 连接字符串

几个libpq函数会解析一个用户指定的字符串来获得连接参数。 这些字符串有两种被接受的格式:纯的关键词/值字符串以及URI。 URI通常遵循RFC 3986,除非像下文进一步描述的那样允许多主机连接字符串。

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

在关键词/值格式中,每一个参数设置的形式都是关键词 = ,在设置之间有空白。 设置的等号周围的空白是可选的。 要写一个空值或一个包含空白的值,将它用单引号包围,例如关键词 = 'a value'。 值里面的单引号和反斜线必须用一个反斜线转义,即\'\\

例子:

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

能被识别的参数关键词在第 34.1.2 节中列出。

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://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

全部的命名参数必须匹配第 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. 指定多个主机

可以指定多个要连接的主机,这样它们会按给定的顺序被尝试。 在键/值格式中,hosthostaddrport选项都接受逗号分隔的值列表。 在指定的每一个选项中都必须给出相同数量的元素,这样第一个hostaddr对应于第一个主机名,第二个hostaddr对应于第二个主机名,以此类推。 不过,如果仅指定一个port,它将被应用于所有的主机。

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

不管是哪一种格式,单一的主机名可以被翻译成多个网络地址。常见的例子是一个主机同时具有IPv4和IPv6地址。

当多个主机被指定时或者单个主机名被翻译成多个地址时,所有的主机和地址都将按照顺序被尝试,直至遇到一个成功的。如果没有主机可以到达,则连接失败。如果成功地建立一个连接但是认证失败,也不会尝试列表中剩下的主机。

如果使用了口令文件,可以为不同的主机使用不同的口令。所有其他连接选项对列表中的每一台主机都是相同的,例如不能为不同的主机指定不同的用户名。

34.1.2. 参数关键词

当前被识别的参数关键词是:

host

要连接的主机名。如果一个主机名看起来像一个绝对路径名称,则表示一个 Unix 域通信而不是 TCP/IP 通信,其值是存储套接字文件的目录名。 (在Unix上, 绝对路径名称以斜杠开始。在Windows上,以驱动器符号开始的路径名称也可以被识别。) 如果主机名以@开头,它被作为抽象命名空间中的Unix-域套接字(当前在Linux和Windows上支持) 当host没有指定或者为空时的默认行为是连接到一个/tmp(或者PostgreSQL编译时指定的任何套接字目录)中的 Unix 域套接字。 在Windows和没有 Unix 域套接字的机器上,默认是连接到localhost

也接受由逗号分隔的主机名列表,这种情况下将依次尝试列表中的主机名,列表中的空项会选择上述的默认行为。详情请参考第 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,则会发生主机名查找(在使用PQconnectPoll时,PQconnectPoll第一次考虑这个主机名时会发生查找,可能会导致PQconnectPoll阻塞可观的时间)。

  • 如果hostaddr被指定且没有hosthostaddr的值给出了服务器的网络地址。如果认证方法要求一个主机名则连接尝试将会失败。

  • 如果hosthostaddr都被指定,hostaddr的值给出服务器的网络地址。host的值将被忽略,除非认证方法要求它,在那种情况下它将被用作主机名。

注意如果host不是网络地址hostaddr上的服务器名,认证很可能会失败。此外,当hosthostaddr都被指定时,host被用来在口令文件中标识该连接(见第 34.16 节)。

逗号分隔的hostaddr值列表也被接受,这种情况下将依次尝试列表中的主机。列表中的空项会导致对应的主机名被使用,或者如果对应的主机名也为空时使用默认主机名。详情请参考第 34.1.1.3 节

如果没有一个主机名或主机地址,libpq将尝试使用一个本地 Unix 域套接字连接,或者在Windows和没有 Unix 域套接字的机器上尝试连接到localhost

port

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

dbname

数据库名。默认和用户名相同。在一般的环境下,会为扩展格式检查该值,详见第 34.1.1 节

user

PostgreSQL 要作为哪个用户连接。默认与运行着该应用的用户的操作系统名相同。

password

服务器要求口令认证时要使用的口令。

passfile

指定用于存放口令的文件名(见第 34.16 节)。默认是~/.pgpass,或者是Microsoft Windows上的%APPDATA%\postgresql\pgpass.conf(如果该文件不存在也不会报错)。

channel_binding

这个选项控制客户端对通道绑定的使用。设置require意味着连接必须使用通道绑定,prefer意味着客户端将在可用时选择通道绑定,而disable阻止使用通道绑定。 默认值为prefer,如果PostgreSQL编译时带有支持SSL;否则默认为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。这个字符串中的空格被认为是命令行参数的分隔符,除非用一个反斜线(\)对它转义,用\\可以表示一个字面意义上的反斜线。可用选项的详细讨论请参考第 20 章

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或等效的套接字选项可用的系统以及 Windows支持,在其他系统上,它没有效果。

tcp_user_timeout

在强制关闭连接之前,控制传输数据的毫秒数可能保持未确认。 值为零使用系统默认值。对于通过 Unix 域套接字进行的连接,将忽略此参数。 它仅在TCP_USER_TIMEOUT可用的系统上支持;对其他系统,它没有任何影响。

tty

被忽略(之前,这指定向哪里发送服务器调试输出)。

replication

这个选项决定是否该连接应该使用复制协议而不是普通协议。这是PostgreSQL的复制连接以及pg_basebackup之类的工具在内部使用的协议,但也可以被第三方应用使用。关于复制协议的介绍可以参考第 53.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(默认)

首先尝试SSL连接,如果失败再尝试非SSL连接

require

只尝试SSL连接。如果存在一个根 CA 文件,以verify-ca被指定的相同方式验证该证书

verify-ca

只尝试SSL连接,并且验证服务器证书是由一个可信的证书机构颁发的(CA

verify-full

只尝试SSL连接,验证服务器证书是由一个可信的CA颁发并且请求的服务器主机名匹配证书中的主机名

这些选项如何工作的详细描述见第 34.19 节

对于 Unix 域套接字通信,sslmode会被忽略。如果PostgreSQL被编译为不带 SSL 支持,使用选项requireverify-caverify-full将导致错误,而选项allowprefer将会被接受但是libpq将不会真正尝试SSL连接。

注意如果GSSAPI加密是可能的,那么将优先使用SSL加密,而不考虑sslmode的值。 强制使用SSL加密,在具有工作的GSSAPI基础架构的环境中(例如Kerberos服务器),还将gssencmode设置为disable

requiressl

为了支持sslmode模式,这个选项已被废弃。

如果设置为 1,则要求一个到服务器的SSL连接(这等效于sslmode require)。如果服务器不接受SSL连接,libpq则将拒绝连接。如果设置为 0(默认),libpq将与该服务器协商连接类型(等效于sslmode prefer)。只有PostgreSQL被编译为带有 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 连接,这个参数会被忽略。

sslpassword

此参数指定在sslkey中指定的密钥的密码,在交互式密码短语输入不实用时,允许客户端证书私钥以加密形式存储在磁盘上。

指定该参数为任何非空值,阻止Enter PEM pass phrase: 提示OpenSSL将默认发出,在向libpq提供加密的客户端证书密钥时。

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

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

sslrootcert

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

sslcrl

这个参数指定 SSL 证书撤销列表(CRL)的文件名。 列在这个文件中的证书如果存在,在尝试认证该服务器证书时会被拒绝。 如果没有设置sslcrlsslcrldir ,这个设置是~/.postgresql/root.crl

sslcrldir

这个参数指定SSL证书废除列表(CRL)的目录名。 该目录中的文件中列出的证书,如果它存在,在尝试验证服务器的证书时将被拒绝。

该目录需要OpenSSL命令openssl rehashc_rehash来准备。 详细信息请参阅其文档。

sslcrlsslcrldir可以被一起指定。

sslsni

如果设置为1(默认值),libpq 在SSL-enabled连接上设置 TLS 扩展Server Name Indication(SNI) 。 通过设置这个参数为0,该项将被关闭。

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

requirepeer

这个参数指定服务器的操作系统用户,例如requirepeer=postgres。当建立一个 Unix 域套接字连接时,如果设置了这个参数,客户端在连接开始时检查服务器进程是运行在指定的用户名之下。如果发现不是,该连接会被一个错误中断。这个参数能被用来提供与 TCP/IP 连接上 SSL 证书相似的服务器认证(注意,如果 Unix 域套接字在/tmp或另一个公共可写的位置,任何用户能开始一个在那里监听的服务器。使用这个参数来保证你连接的是一个由可信用户运行的服务器)。这个选项只在实现了peer认证方法的平台上受支持,见第 21.9 节

ssl_min_protocol_version

此参数规定了允许连接的最小SSL/TLS协议版本。有效值为TLSv1,TLSv1.1, TLSv1.2TLSv1.3。 所支持的协议取决于所使用的OpenSSL版本,旧版本不支持最新的协议版本。如果没有指定,则默认为TLSv1.2,在撰写本文时的行业最佳实践。

ssl_max_protocol_version

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

krbsrvname

当用 GSSAPI 认证时,要使用的 Kerberos 服务名。为了让 Kerberos 认证成功,这必须匹配在服务器配置中指定的服务名(另见第 21.6 节)。 默认值通常是postgres,但可以通过configure--with-krb-srvnam选项在构建PostgreSQL时更改。 在大多数环境中,这个参数不需要更改。 某些Kerberos实现可能需要不同的服务名称,例如Microsoft Active Directory需要服务名称使用大写(POSTGRES)。

gsslib

用于GSSAPI身份验证的GSS库。目前,除了在包含GSSAPI和SSPI支持的Windows构建中,这一点被忽略了。 在这种情况下,将此设置为gssapi使 libpq 使用 GSSAPI 库进行身份验证,而不是默认 SSPI。

service

用于附加参数的服务名。它指定保持附加连接参数的pg_service.conf中的一个服务名。这允许应用只指定一个服务名,这样连接参数能被集中维护。见第 34.17 节

target_session_attrs

这个选项决定会话是否必须具有某些属性才能被接受。 它通常与多个主机名结合使用,以在多个主机中选择第一个可接受的选择项。 有六种模式:

any (default)

任何成功的连接是可接受的。

read-write

会话必须默认接受读-写事务(这是指,服务器必须不是热备模式,并且default_transaction_read_only参数必须是off

read-only

会话必须默认不接受读-写事务 (相反的)

primary

服务器必须不是热备模式

standby

服务器必须是热备模式

prefer-standby

先尝试查找备用服务器,但是如果列出的服务器中没有备用服务器,再尝试以any模式。