33.1. 数据库连接控制函数
下列函数会建立到一个PostgreSQL后端服务器的连接。一个应用程序可以在一个时刻打开多个后端连接(原因之一就是为了访问多个数据库)。每个连接用一个PGconn
对象表示,它从函数PQconnectdb
、PQconnectdbParams
或PQsetdbLogin
得到。注意这些函数将总是返回一个非空的对象指针,除非正好没有内存来分配PGconn
对象。在通过该连接对象发送查询之前,应该调用PQstatus
函数来检查返回值以确定是否得到了一个成功的连接。
警告
在 Unix 上,复制一个拥有打开 libpq 连接的进程可能导致不可以预料的结果,因为父进程和子进程会共享相同的套接字和操作系统资源。出于这个原因,我们不推荐这样的用法,尽管从子进程执行一个exec
来载入新的可执行代码是安全的。
注意
在 Windows 上,如果一个单一数据库连接被反复地开启并且关闭,这是一种提升性能的方式。在内部,libpq 为开启和关闭分别调用WSAStartup()
和WSACleanup()
。WSAStartup()
会增加一个内部 Windows 库引用计数而WSACleanup()
则会减少之。当引用计数正好为一时,调用WSACleanup()
会释放所有资源并且所有 DLL 会被卸载。这是一种昂贵的操作。为了避免它,一个应用可以手动调用WSAStartup()
,这样当最后的数据库连接被关闭时资源不会被释放。
PQconnectdbParams
-
开启一个到数据库服务器的新连接。
PGconn *PQconnectdbParams(const char * const *keywords, const char * const *values, int expand_dbname);
这个函数使用从两个以
NULL
结尾的数组中取得的参数打开一个新的数据库连接。第一个数组keywords
被定义为一个字符串数组,每一个元素是一个关键词。第二个数组values
给出了每个关键词的值。和下面的PQsetdbLogin
不同,可以在不改变函数签名的情况下扩展参数集合,因此使用这个函数(或者与之相似的非阻塞的PQconnectStartParams
和PQconnectPoll
)对于新应用编程要更好。当前能被识别的参数关键词被列举在第 33.1.2 节中。
其可能的格式详见第 33.1.1 节。 当
expand_dbname
为非零时,dbname
关键词的值被允许识别为一个连接字符串。只有dbname
的第一次出现会按这种方式扩展,任何后续dbname
值会被当 做一个普通数据库名处理。有关可能的连接字符串格式的详情可见 第 33.1.1 节。被传递的数组可以为空,这样就会使用所有默认参数。也可以只包含一个或几个参数设置。两个参数数组应该在长度上匹配。对于参数数组的处理将会停止于
keywords
数组中第一个非-NULL
元素。如果任何一个参数是
NULL
或者一个空字符串, 那么将会检查相应的环境变量(见第 33.14 节)。 如果该环境变量也没有被设置,那么将使用指示的内建默认值。通常,关键词的处理是从这些数组的头部开始并且以索引顺序进行。这样做的效果就是,当关键词有重复时,只会保留最后一个被处理的值。因此,通过小心地放置关键词
dbname
,可以决定什么会被一个conninfo
字符串所重载,以及什么不会被重载。 PQconnectdb
-
开启一个到数据库服务器的新连接。
PGconn *PQconnectdb(const char *conninfo);
这个函数使用从字符串
conninfo
中得到的参数开启一个新的数据库连接。被传递的字符串可以为空,这样将会使用所有的默认参数。也可以包含由空格分隔的一个或多个参数设置,还可以包含一个URI。详见第 33.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
。 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
参数被合适地使用,以确保不会做名字或逆向名字查询。详见第 33.1.2 节中这些参数的文档。 -
如果你调用
PQtrace
,确保你追踪的该流对象不会阻塞。 -
如后文所述,你要确保在调用
PQconnectPoll
之前,套接字处于合适的状态。
注意:
PQconnectStartParams
的使用和下文所示的PQconnectStart
类似。要开始一个非阻塞的连接请求,可调用
conn = PQconnectStart("
。如果connection_info_string
")conn
为空,那么libpq无法分配一个新的PGconn
结构。否则,一个合法的PGconn
指针将被返回(尽管并不表示代表一个到数据库的合法连接)。在从PQconnectStart
返回时,调用status = PQstatus(conn)
。如果status
等于CONNECTION_BAD
,就说明PQconnectStart
已经失败。如果
PQconnectStart
成功,下一个阶段是轮询libpq,这样它能够继续进行连接序列。使用PQsocket(conn)
来获得该数据库连接底层的套接字描述符。这样循环:如果PQconnectPoll(conn)
上一次返回PGRES_POLLING_READING
,等到该套接字准备好读取(按照select()
、poll()
或类似的系统函数所指示的)。则再次调用PQconnectPoll(conn)
。反之,如果PQconnectPoll(conn)
上一次返回PGRES_POLLING_WRITING
,等到该套接字准备好写入,则再次调用PQconnectPoll(conn)
。如果你还没有调用PQconnectPoll
,即刚好在对PQconnectStart
的调用之后,行为就像是它上次返回了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
返回一个非空的指针,你必须在用完它之后调用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
相同。
33.1.1. 连接字符串
几个libpq函数会解析一个用户指定的字符串来获得连接参数。这些字符串有两种被接受的格式:纯关键词 = 值
字符串以及URI。 URI通常遵循 RFC 3986,除了允许多主机连接字符串,如下面进一步的描述。
33.1.1.1. 关键词/值连接字符串
在第一种格式中,每一个参数设置的形式都是关键词 = 值
。等号周围的空白是可选的。要写一个空值或一个包含空白的值,将它用单引号包围,例如关键词 = 'a value'
。值里面的单引号和反斜线必须用一个反斜线转义,即\'
和\\
。
例子:
host=localhost port=5432 dbname=mydb connect_timeout=10
能被识别的参数关键词在第 33.1.2 节中列出。
33.1.1.2. 连接 URI
一个连接URI的一般形式是:
postgresql://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...]
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
在任意URI部分中可以使用百分号编码来包括有特殊含义的符号, 例如使用%3D
替换=
。 .
任何不对应第 33.1.2 节中列出的关键词的连接参数将被忽略并且关于它们的警告消息会被发送到stderr
。
为了提高和 JDBC 连接URI的兼容性,参数ssl=true
的实例会被翻译成sslmode=require
。
主机部分可能是主机名或一个 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
。 每个主机将依次尝试,直到连接成功建立。
33.1.1.3. 指定多个主机
可以指定多个要连接的主机,以便按给定顺序尝试它们。在关键字/值格式中, host
、hostaddr
和port
选项接受逗号分隔的值列表。 在每个选项中必须给出相同数量的元素,例如,第一个hostaddr
对应于第一个主机名称,第二个hostaddr
对应于第二个主机名称,等等。 作为例外,如果只指定了一个port
,它将应用于所有主机。
在连接URI格式中,您可以在URI的host
组件中列出多个由逗号分隔的 host:port
对。无论哪种格式,单个主机名也可以转换为多个网络地址。 这种情况的一个常见示例是同时拥有IPv4和IPv6地址的主机。
当指定多个主机时,或者将单个主机名转换为多个地址时, 将按顺序尝试所有主机和地址,直到成功为止。如果没有主机可以到达, 则连接失败。如果连接成功建立,但验证失败,则不尝试列表中剩余的主机。
如果使用密码文件,则可以为不同的主机设置不同的密码。 所有其他连接选项对于每个主机都是相同的, 因此不可能例如为不同的主机指定不同的用户名。
33.1.2. 参数关键词
当前被识别的参数关键词是:
host
-
要连接的主机名。如果主机名以一个斜线开始,则表示一个 Unix 域通信而不是 TCP/IP 通信,其值是存储套接字文件的目录名。 如果指定了多个主机名,则将以给出的顺序依次尝试每个主机名。 当
host
没有指定时的默认行为是连接到一个/tmp
(或者PostgreSQL编译时指定的任何套接字目录)中的 Unix 域套接字。在没有 Unix 域套接字的机器上,默认是连接到localhost
。还接受以逗号分隔的主机名列表,在这种情况下,列表中的每个主机名均按顺序尝试。 有关详细信息,请参见第 33.1.1.3 节 。
hostaddr
-
要连接的主机的数字 IP 地址。它应该是标准的 IPv4 地址格式,例如
172.28.40.9
。如果你的机器支持 IPv6,你也可以使用那些地址。当为这个参数指定一个非空字符串时,总是会使用 TCP/IP 通信。使用
hostaddr
代替host
允许应用能避免一次主机名查找,这对于具有时间约束的应用可能非常重要。不过,GSSAPI 或 SSPI 认证方法以及verify-full
SSL 证书验证还是要求一个主机名。使用的是下列规则:-
如果
host
被指定且没有hostaddr
,将发生一次主机名查找。 -
如果
hostaddr
被指定且没有host
,hostaddr
的值给出了服务器的网络地址。如果认证方法要求一个主机名则连接尝试将会失败。 -
如果
host
和hostaddr
都被指定,hostaddr
的值给出服务器的网络地址。host
的值将被忽略,除非认证方法要求它,在那种情况下它将被用作主机名。
注意如果
host
不是网络地址hostaddr
上的服务器名,认证很可能会失败。还有,注意host
而不是hostaddr
被用来标识口令文件中的连接(见第 33.15 节)。还接受以逗号分隔的
hostaddrs
列表,在这种情况下, 列表中的每个主机名均按顺序尝试。有关详细信息, 请参见第 33.1.1.3 节。如果没有一个主机名或主机地址,libpq将尝试使用一个本地 Unix 域套接字连接,或者在没有 Unix 域套接字的机器上尝试连接到
localhost
。 -
port
-
在服务器主机上要连接的端口号,或者用于 Unix 域连接的套接字文件名扩展。 如果在
host
或hostaddr
参数中给出了多个主机名, 那么这个参数可以指定等长的端口列表,或者它可以指定单个端口号用于所有主机。 dbname
-
数据库名。默认和用户名相同。在一般的环境下,会为扩展格式检查该值,详见第 33.1.1 节。
user
-
PostgreSQL 要作为哪个用户连接。默认与运行着该应用的用户的操作系统名相同。
password
-
服务器要求口令认证时要使用的口令。
passfile
-
声明要用于存储口令的文件的名称(参阅第 33.15 节)。 默认是
~/.pgpass
,或者微软Windows上是%APPDATA%\postgresql\pgpass.conf
。 (如果此文件不存在,则不报告错误。) connect_timeout
-
连接超时时间,以秒计(写成一个十进制整数字符串)。0 或未指定表示无限等待。 我们不推荐使用低于 2 秒的超时时间。 此超时单独适用于每个连接尝试。例如,如果指定了两台主机并且
connect_timeout
为5,如果没有主机在5秒内建立连接, 则每台主机都将超时,因此等待连接所花费的总时间可能高达10秒。 client_encoding
-
为连接设置
client_encoding
配置参数。除了被相应服务器选项所接受的值,你还能使用auto
从客户端的当前区域(Unix 系统上的LC_CTYPE
环境变量)决定正确的编码。 options
-
声明在连接开始时发送给服务器的命令行选项。例如,设置这个参数为
-c geqo=off
会把会话的geqo
参数值设置为off
。此字符串中的空格被视为分隔命令行参数, 除非使用反斜杠(\
)进行转义;写\\
来表示文字反斜杠。可用选项的详细讨论请参考 第 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
或等效的套接字选项可用的系统以及 Windows支持,在其他系统上,它没有效果。 tty
-
被忽略(之前,这指定向哪里发送服务器调试输出)。
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颁发并且请求的服务器主机名匹配证书中的主机名
这些选项如何工作的详细描述见第 33.18 节。
对于 Unix 域套接字通信,
sslmode
会被忽略。如果PostgreSQL被编译为不带 SSL 支持,使用选项require
、verify-ca
或verify-full
将导致错误,而选项allow
和prefer
将会被接受但是libpq将不会真正尝试SSL连接。 requiressl
-
为了支持
sslmode
模式,这个选项已被废弃。如果设置为 1,则要求一个到服务器的SSL连接(这等效于
sslmode
require
)。如果服务器不接受SSL连接,libpq则将拒绝连接。如果设置为 0(默认),libpq将与该服务器协商连接类型(等效于sslmode
prefer
)。只有PostgreSQL被编译为带有 SSL 支持,这个选项才可用。 sslcompression
-
如果设置为 1(默认),SSL 连接之上传送的数据将被压缩。如果设置为 0,压缩将被禁用(这要求OpenSSL 1.0.0 或更高)。如果建立的是一个没有 SSL 的连接,这个参数会被忽略。如果使用的OpenSSL版本不支持该参数,它也会被忽略。
压缩会占用 CUP 时间,但是当瓶颈为网络时可以提高吞吐量。如果 CPU 性能是限制因素,禁用压缩能够改进响应时间和吞吐量。
sslcert
-
这个参数指定客户端 SSL 证书的文件名,它替换默认的
~/.postgresql/postgresql.crt
。如果没有建立 SSL 连接,这个参数会被忽略。 sslkey
-
这个参数指定用于客户端证书的密钥位置。它能指定一个会被用来替代默认的
~/.postgresql/postgresql.key
的文件名,或者它能够指定一个从外部“引擎”(引擎是OpenSSL的可载入模块)得到的密钥。一个外部引擎说明应该由一个冒号分隔的引擎名称以及一个引擎相关的关键标识符组成。如果没有建立 SSL 连接,这个参数会被忽略。 sslrootcert
-
这个参数指定一个包含 SSL 证书机构(CA)证书的文件名称。如果该文件存在,服务器的证书将被验证是由这些机构之一签发。默认值是
~/.postgresql/root.crt
。 sslcrl
-
这个参数指定 SSL 证书撤销列表(CRL)的文件名。列在这个文件中的证书如果存在,在尝试认证该服务器证书时会被拒绝。默认值是
~/.postgresql/root.crl
。 requirepeer
-
这个参数指定服务器的操作系统用户,例如
requirepeer=postgres
。当建立一个 Unix 域套接字连接时,如果设置了这个参数,客户端在连接开始时检查服务器进程是否运行在指定的用户名之下。如果发现不是,该连接会被一个错误中断。这个参数能被用来提供与 TCP/IP 连接上 SSL 证书相似的服务器认证(注意,如果 Unix 域套接字在/tmp
或另一个公共可写的位置,任何用户能启动一个在那里监听的服务器。使用这个参数来保证你连接的是一个由可信用户运行的服务器)。这个选项只在实现了peer
认证方法的平台上受支持,见第 20.3.6 节。 krbsrvname
-
当用 GSSAPI 认证时,要使用的 Kerberos 服务名。为了让 Kerberos 认证成功,这必须匹配在服务器配置中指定的服务名(另见第 20.3.3 节)。
gsslib
-
用于 GSSAPI 认证的 GSS 库。只用在 Windows 上。设置为
gssapi
可强制 libpq 用 GSSAPI 库来代替默认的 SSPI 进行认证。 service
-
用于附加参数的服务名。它指定保持附加连接参数的
pg_service.conf
中的一个服务名。这允许应用只指定一个服务名,这样连接参数能被集中维护。见第 33.16 节。 target_session_attrs
-
如果这个参数设置为
read-write
, 则只有默认接受读写事务的连接才被认为是可接受的。查询SHOW transaction_read_only
将在任何成功连接上发送; 如果它返回on
,则将关闭连接。如果在连接字符串中指定了多个主机, 则将尝试任何剩余的服务器,就像连接尝试失败了一样。该参数的默认值any
, 将所有连接看做是可接受的。 -
本文转自PostgreSQL中文社区,原文链接:33.1. 数据库连接控制函数