下列函数会建立到一个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
)对于新应用编程要更好。
当前能被识别的参数关键词被列举在第 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
的宏,其中为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
都不会阻塞:
hostaddr
和host
参数必须被合适地使用,以防止做DNS查询。详见第 34.1.2 节中这些参数的文档。
如果你调用PQtrace
,确保你追踪的该流对象不会阻塞。
如后文所述,你必须要确保在调用PQconnectPoll
之前,套接字处于合适的状态。
要开始无阻塞的连接请求,可调用PQconnectStart
或者PQconnectStartParams
。如果结果为空,则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
的返回值检测。在一个异步连接过程中(也只有在这个过程中)也可能出现其他状态。这些状态指示该连接过程的当前阶段,并且可能有助于为用户提供反馈。这些状态是:
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
。
注意当PQconnectStart
或PQconnectStartParams
返回一个非空的指针时,你必须在用完它之后调用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
指针的条目结束。
所有合法选项将出现在结果数组中,但是任何在连接字符串中没有出现的选项的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,用与使用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
令一个应用取代 libpq的 default 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);
几个libpq函数解析用户指定的字符串以获取连接参数。 这些字符串有两种被接受的格式:普通的关键字/值字符串和URI。URI通常遵循 RFC 3986,除了允许多主机连接字符串,如下面进一步描述的那样。
在关键词/值格式中,每一个参数设置的形式都是关键词
=
值
,在设置之间有空白。
设置的等号周围的空白是可选的。
要写一个空值或一个包含空白的值,将它用单引号包围,例如关键词 = 'a value'
。
值里面的单引号和反斜线必须用一个反斜线转义,即\'
和\\
。
例子:
host=localhost port=5432 dbname=mydb connect_timeout=10
能被识别的参数关键词在第 34.1.2 节中列出。
一个连接URI的一般形式是:
postgresql://[userspec
@][hostspec
][/dbname
][?paramspec
] whereuserspec
is:user
[:password
] andhostspec
is: [host
][:port
][,...] andparamspec
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需要使用百分号编码
对其进行编码,如果其中包含具有特殊含义的符号。这里是一个示例,其中等号(=
)被替换为
%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
或为空时,默认行为是连接到Unix域套接字在
/tmp
(或在构建PostgreSQL时指定的套接字目录)中。在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
而没有指定host
,
则hostaddr
的值给出服务器的网络地址。
如果身份验证方法需要主机名,则连接尝试将失败。
如果同时指定了host
和hostaddr
,
则hostaddr
的值给出服务器的网络地址。
除非身份验证方法需要,否则host
的值将被忽略,
在这种情况下,它将用作主机名。
请注意,如果host
不是网络地址hostaddr
上服务器的名称,
则身份验证可能会失败。
此外,当同时指定host
和hostaddr
时,
host
用于在密码文件中标识连接(请参阅第 34.16 节)。
也可以接受一个逗号分隔的hostaddr
值列表,此时将按顺序尝试列表中的每个主机。
列表中的空项会导致使用相应的主机名,如果主机名也为空,则使用默认主机名。详见
第 34.1.1.3 节。
没有主机名或主机地址,
libpq将使用本地的Unix域套接字进行连接;
或者在Windows和没有Unix域套接字的机器上,它将尝试连接到localhost
。
port
连接到服务器主机的端口号,或者Unix域连接的套接字文件名扩展。
如果在host
或hostaddr
参数中给出了多个主机,
则此参数可以指定与主机列表长度相同的逗号分隔的端口列表,或者可以指定用于所有主机的单个端口号。
空字符串,或逗号分隔列表中的空项,指定了在构建PostgreSQL时建立的默认端口号。
dbname
数据库名称。默认为与用户名相同。在某些情况下,该值会被检查是否为扩展格式; 有关更多详细信息,请参阅第 34.1.1 节。
user
PostgreSQL用户连接的用户名。 默认为运行应用程序的操作系统用户名相同。
password
如果服务器要求密码验证,则使用密码。
passfile
指定用于存储密码的文件名(参见第 34.16 节)。
默认为~/.pgpass
,或在Microsoft Windows上为%APPDATA%\postgresql\pgpass.conf
。
(如果此文件不存在,则不会报告错误。)
channel_binding
这个选项控制客户端对通道绑定的使用。设置为require
表示连接必须使用通道绑定,
prefer
表示客户端将在可用时选择通道绑定,
而disable
则阻止使用通道绑定。默认情况下,
如果PostgreSQL是使用SSL支持编译的,则默认为prefer
;
否则默认为disable
。
Channel binding是服务器向客户端进行身份验证的一种方法。它仅在使用PostgreSQL 11或更高版本服务器,并使用SCRAM
身份验证方法的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 keepalive数量。
值为零时使用系统默认值。对通过Unix域套接字建立的连接或禁用keepalives的连接,此参数将被忽略。
仅在支持TCP_KEEPCNT
或等效套接字选项的系统上受支持;
在其他系统上,此参数无效。
tcp_user_timeout
控制在连接在强制关闭之前,传输数据可以保持未被确认的毫秒数。
值为零时使用系统默认值。此参数对通过Unix域套接字进行的连接无效。
仅在支持TCP_USER_TIMEOUT
的系统上受支持;在其他系统上,它没有效果。
replication
这个选项确定连接是否应该使用复制协议而不是正常协议。这就是PostgreSQL复制连接以及诸如 pg_basebackup这样的工具在内部使用的方式,但也可以被第三方应用程序使用。 要了解复制协议的描述,请参考第 55.4 节。
支持以下值(不区分大小写):
true
, on
,
yes
, 1
连接进入物理复制模式。
database
连接进入逻辑复制模式,连接到dbname
参数中指定的数据库。
false
, off
,
no
, 0
连接是常规连接,这是默认行为。
在物理或逻辑复制模式下,只能使用简单查询协议。
gssencmode
这个选项确定是否以及如何优先与服务器协商安全的GSS TCP/IP连接。有三种模式:
disable
仅尝试非GSSAPI加密连接
prefer
(默认)如果存在GSSAPI凭据(即在凭据缓存中),首先尝试 GSSAPI加密连接;如果失败或没有凭据,则尝试 非GSSAPI加密连接。这是在编译PostgreSQL时使用GSSAPI支持时的默认设置。
require
仅尝试GSSAPI加密连接
gssencmode
在Unix域套接字通信中被忽略。如果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 节。
sslmode
被忽略用于Unix域套接字通信。
如果PostgreSQL没有SSL支持编译,
使用选项require
、verify-ca
或
verify-full
会导致错误,而选项allow
和prefer
将被接受,但libpq实际上不会尝试建立SSL
连接。
请注意,如果可能使用GSSAPI加密,
则优先使用该加密,而不考虑SSL的值。要在具有可用GSSAPI
基础设施(如Kerberos服务器)的环境中强制使用
SSL加密,还需将
gssencmode
设置为disable
。
requiressl
此选项已被sslmode
设置所取代。
如果设置为1,则需要与服务器建立SSL连接(这相当于sslmode
require
)。libpq将拒绝连接,如果服务器不接受
SSL连接。如果设置为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
中指定的密钥的密码,允许客户端证书私钥在磁盘上以加密形式存储,即使交互式密码输入不可行。
指定此参数为任何非空值将抑制输入PEM密码短语:
当提供加密的客户端证书密钥给libpq
时,
OpenSSL默认会发出的提示。
如果密钥未加密,则忽略此参数。该参数对由OpenSSL引擎指定的密钥没有影响,除非引擎使用OpenSSL密码回调机制进行提示。
没有与此选项等效的环境变量,也没有在.pgpass
中查找它的功能。它可以在服务文件连接定义中使用。
使用更复杂功能的用户应考虑使用OpenSSL引擎和类似PKCS#11或USB加密卸载设备的工具。
sslrootcert
这个参数指定一个包含SSL证书颁发机构(CA)证书的文件名。
如果文件存在,服务器的证书将被验证是否由这些机构之一签名。
默认值是~/.postgresql/root.crt
。
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
身份验证方法的平台上受支持;请参见第 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身份验证服务名称匹配,才能成功进行身份验证。
(另请参见第 21.6 节。)
默认值通常为postgres
,
但在构建PostgreSQL时可以通过
--with-krb-srvnam
选项进行更改
configure。
在大多数环境中,通常不需要更改此参数。
一些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
(默认)任何成功的连接都是可接受的
read-write
会话必须默认接受读写事务(即,服务器不能处于热备模式,
并且default_transaction_read_only
参数必须为off
)
read-only
会话默认不接受读写事务(相反)
primary
服务器不能处于热备模式
standby
服务器必须处于热备模式
prefer-standby
首先尝试找到一个热备服务器,但如果列出的主机中没有一个是热备服务器,
则再次尝试any
模式