PostgreSQL数据库网络层——libpq连接字符串和参数KV

Connection Strings

几个 libpq 函数解析用户指定的字符串以获取连接参数。 这些字符串有两种可接受的格式&＃xff1a;普通关键字/值字符串和 URI。 URI 通常遵循 RFC 3986&＃xff0c;但允许多主机连接字符串&＃xff0c;如下所述。
Several libpq functions parse a user-specified string to obtain connection parameters. There are two accepted formats for these strings: plain keyword/value strings and URIs. URIs generally follow RFC 3986, except that multi-host connection strings are allowed as further described below.

Keyword/Value Connection Strings
在关键字/值格式中&＃xff0c;每个参数设置的形式为关键字 &＃61; 值&＃xff0c;设置之间有空格。 设置等号周围的空格是可选的。 要写入空值或包含空格的值&＃xff0c;请用单引号将其括起来&＃xff0c;例如关键字 &＃61; ‘a value’。 值中的单引号和反斜杠必须用反斜杠转义&＃xff0c;即 ’ 和 \。比如host&＃61;localhost port&＃61;5432 dbname&＃61;mydb connect_timeout&＃61;10。
In the keyword/value format, each parameter setting is in the form keyword &＃61; value, with space(s) between settings. Spaces around a setting’s equal sign are optional. To write an empty value, or a value containing spaces, surround it with single quotes, for example keyword &＃61; ‘a value’. Single quotes and backslashes within a value must be escaped with a backslash, i.e., \&＃39; and \\.

Connection URIs
连接 URI 的一般形式是&＃xff1a;

URI 方案指示符可以是 postgresql:// 或 postgres://。 其余的每个 URI 部分都是可选的。 以下示例说明了有效的 URI 语法&＃xff1a;
The URI scheme designator can be either postgresql:// or postgres://. Each of the remaining URI parts is optional. The following examples illustrate valid URI syntax:

通常出现在 URI 的分层部分中的值也可以作为命名参数给出。 例如&＃xff1a;postgresql:///mydb?host&＃61;localhost&port&＃61;5433

所有命名参数必须与第 34.1.2 节中列出的关键字匹配&＃xff0c;除了为了与 JDBC 连接 URI 兼容&＃xff0c;ssl&＃61;true 的实例被转换为 sslmode&＃61;require。
如果连接 URI 的任何部分包含具有特殊含义的符号&＃xff0c;则需要使用百分比编码对其进行编码。 下面是一个示例&＃xff0c;其中等号 (&＃61;) 替换为 %3D&＃xff0c;空格字符替换为 %20&＃xff1a;postgresql://user&＃64;localhost:5433/mydb?options&＃61;-c%20synchronous_commit%3Doff
All named parameters must match key words listed in Section 34.1.2, except that for compatibility with JDBC connection URIs, instances of ssl&＃61;true are translated into sslmode&＃61;require. The connection URI needs to be encoded with percent-encoding if it includes symbols with special meaning in any of its parts. Here is an example where the equal sign (&＃61;) is replaced with %3D and the space character with %20:postgresql://user&＃64;localhost:5433/mydb?options&＃61;-c%20synchronous_commit%3Doff
主机部分可以是主机名或 IP 地址。 要指定 IPv6 地址&＃xff0c;请将其括在方括号中&＃xff1a;postgresql://[2001:db8::1234]/database

主机部分被解释为参数主机的描述。 特别是&＃xff0c;如果主机部分为空或看起来像绝对路径名&＃xff0c;则选择 Unix 域套接字连接&＃xff0c;否则将启动 TCP/IP 连接。 但是请注意&＃xff0c;斜杠是 URI 分层部分中的保留字符。 因此&＃xff0c;要指定一个非标准的 Unix 域套接字目录&＃xff0c;要么省略 URI 的主机部分并将主机指定为命名参数&＃xff0c;要么对 URI 的主机部分中的路径进行百分比编码&＃xff1a;
The host part is interpreted as described for the parameter host. In particular, a Unix-domain socket connection is chosen if the host part is either empty or looks like an absolute path name, otherwise a TCP/IP connection is initiated. Note, however, that the slash is a reserved character in the hierarchical part of the URI. So, to specify a non-standard Unix-domain socket directory, either omit the host part of the URI and specify the host as a named parameter, or percent-encode the path in the host part of the URI:

postgresql:///dbname?host&＃61;/var/lib/postgresql
postgresql://%2Fvar%2Flib%2Fpostgresql/dbname


可以在单个 URI 中指定多个主机组件&＃xff0c;每个组件都有一个可选的端口组件。 postgresql://host1:port1,host2:port2,host3:port3/ 形式的 URI 等效于 host&＃61;host1,host2,host3 port&＃61;port1,port2,port3 形式的连接字符串。 如下所述&＃xff0c;将依次尝试每个主机&＃xff0c;直到成功建立连接。It is possible to specify multiple host components, each with an optional port component, in a single URI. A URI of the form postgresql://host1:port1,host2:port2,host3:port3/ is equivalent to a connection string of the form host&＃61;host1,host2,host3 port&＃61;port1,port2,port3. As further described below, each host will be tried in turn until a connection is successfully established.

可以指定要连接的多个主机&＃xff0c;以便按给定顺序尝试它们。在关键字/值格式中&＃xff0c;host、hostaddr 和 port 选项接受逗号分隔的值列表。在指定的每个选项中必须给出相同数量的元素&＃xff0c;例如&＃xff0c;第一个 hostaddr 对应于第一个主机名&＃xff0c;第二个 hostaddr 对应于第二个主机名&＃xff0c;等等。作为一个例外&＃xff0c;如果只指定一个端口&＃xff0c;它适用于所有主机。It is possible to specify multiple hosts to connect to, so that they are tried in the given order. In the Keyword/Value format, the host, hostaddr, and port options accept comma-separated lists of values. The same number of elements must be given in each option that is specified, such that e.g., the first hostaddr corresponds to the first host name, the second hostaddr corresponds to the second host name, and so forth. As an exception, if only one port is specified, it applies to all the hosts.

在连接 URI 格式中&＃xff0c;您可以在 URI 的主机组件中列出多个以逗号分隔的主机&＃xff1a;端口对。In the connection URI format, you can list multiple host:port pairs separated by commas in the host component of the URI.

无论采用哪种格式&＃xff0c;单个主机名都可以转换为多个网络地址。这方面的一个常见示例是同时具有 IPv4 和 IPv6 地址的主机。In either format, a single host name can translate to multiple network addresses. A common example of this is a host that has both an IPv4 and an IPv6 address.

当指定多个主机时&＃xff0c;或者当一个主机名被翻译成多个地址时&＃xff0c;所有的主机和地址都会依次尝试&＃xff0c;直到一个成功。如果无法访问任何主机&＃xff0c;则连接失败。如果成功建立连接&＃xff0c;但身份验证失败&＃xff0c;则不会尝试列表中的其余主机。When multiple hosts are specified, or when a single host name is translated to multiple addresses, all the hosts and addresses will be tried in order, until one succeeds. If none of the hosts can be reached, the connection fails. If a connection is established successfully, but authentication fails, the remaining hosts in the list are not tried.

如果使用密码文件&＃xff0c;您可以为不同的主机设置不同的密码。对于列表中的每个主机&＃xff0c;所有其他连接选项都是相同的&＃xff1b;例如&＃xff0c;不可能为不同的主机指定不同的用户名。If a password file is used, you can have different passwords for different hosts. All the other connection options are the same for every host in the list; it is not possible to e.g., specify different usernames for different hosts.