# 34.1.数据库连接控制功能

34.1.1. 连结字符串

34.1.2. 参数关键字

以下函数处理与PostgreSQL后端服务器的连接。一个应用程序可以同时打开多个后端连接。(这样做的一个原因是访问多个数据库。)每个连接都由一个PGconn对象,它是从函数中获取的PQconnectdb,PQconnectdbParamsPQsetdbLogin。请注意,这些函数将始终返回非空对象指针,除非内存太少,甚至无法分配PGconn对象这个PQ状态在通过连接对象发送查询之前,应该调用函数来检查成功连接的返回值。

# 警告

如果不受信任的用户可以访问未采用安全模式使用模式,通过从中删除可公开写入的架构开始每个会话搜索路径.可以设置参数关键字选项重视-csearch_path=.或者,你可以发布PQexec(*康涅狄格州*,“选择pg_目录。设置_配置('search_path','',false)”)连接后。这种考虑并不是libpq特有的;它适用于执行任意SQL命令的每个接口。

# 警告

在Unix上,用开放的libpq连接分叉进程可能会导致不可预测的结果,因为父进程和子进程共享相同的套接字和操作系统资源。因此,不建议使用这种用法,尽管执行官从子进程加载新的可执行文件是安全的。

PQconnectdbParams

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

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

此函数使用从两个数据库中获取的参数打开一个新的数据库连接无效的-端接阵列。第一个,关键词,定义为字符串数组,每个字符串都是一个关键字。第二个,价值观,给出每个关键字的值。不像PQsetdbLogin下面,参数集可以在不更改函数签名的情况下进行扩展,因此使用此函数(或其非阻塞类似物连接星图民意测验)是新应用程序编程的首选。

中列出了当前识别的参数关键字第34.1.2节.

传递的数组可以为空以使用所有默认参数,也可以包含一个或多个参数设置。它们的长度必须匹配。处理将首先停止无效的进入关键词大堆此外,如果价值观与非-无效的 关键词参赛作品是无效的或空字符串,则忽略该条目,并继续处理下一对数组条目。

什么时候展开_dbname为非零,第一个的值*库名检查关键字是否为连接字符串*。如果是,则将其“扩展”为从字符串中提取的各个连接参数。如果该值包含等号,则该值被视为连接字符串,而不仅仅是数据库名称(=)或者它以URI模式指示符开头。(有关连接字符串格式的更多详细信息,请参见第34.1.1节)只有第一次出现*库名被这样对待;任何后续的库名*参数作为普通数据库名称处理。

通常,参数数组从头到尾都会被处理。如果有任何关键字被重复,最后一个值(即无效的或空)使用。当在连接字符串中找到的关键字与在连接字符串中出现的关键字冲突时,此规则尤其适用关键词大堆因此,程序员可以确定数组项是否可以覆盖或被从连接字符串中获取的值覆盖。在展开的*库名条目可以被连接字符串的字段覆盖,而这些字段又被后面出现的数组条目覆盖库名*(但同样,仅当这些条目提供非空值时)。

在处理所有数组项和任何扩展的连接字符串后,任何未设置的连接参数都将用默认值填充。如果未设置参数对应的环境变量(请参见第34.15节)设置,则使用其值。如果环境变量也未设置,则使用参数的内置默认值。

PQconnectdb

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

PGconn *PQconnectdb(const char *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有一组固定的参数。它具有相同的功能,只是缺少的参数将始终采用默认值。写无效的或者为任何一个要默认的固定参数设置一个空字符串。

如果*数据库名包含一个=签名或具有有效的连接URI前缀,则将其视为康宁*字符串的方式与传递给PQconnectdb,剩下的参数将按照PQconnectdbParams.

pgtty不再使用,传递的任何值都将被忽略。

PQsetdb

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

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

这是一个调用PQsetdbLogin对于*登录pwd*参数。它是为了向后兼容非常旧的程序而提供的。

连接星图
连接开始
民意测验

以非阻塞方式连接到数据库服务器。

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,因此应用程序可以与其他活动并行管理此操作。

具有连接星图,使用从数据库中获取的参数进行数据库连接关键词价值观数组,并由展开_dbname,如上所述PQconnectdbParams.

具有连接开始,使用从字符串中获取的参数建立数据库连接康宁如上所述PQconnectdb.

也不连接星图也没有连接开始也没有民意测验将被阻止,只要满足一些限制:

  • 这个霍斯塔德酒店参数必须适当使用,以防止进行DNS查询。请参阅中此参数的文档第34.1.2节详细信息。

  • 如果你打电话PQtrace,确保跟踪到的流对象不会被阻止。

  • 在调用之前,必须确保套接字处于适当的状态民意测验,如下所述。

    要开始非阻塞连接请求,请调用连接开始连接星图。如果结果为空,则libpq无法分配新的PGconn结构否则,一个有效的PGconn返回指针(尽管尚未表示到数据库的有效连接)。下一个电话PQstatus(康涅狄格州).如果结果是连接不好,连接尝试已失败,通常是因为连接参数无效。

    如果连接开始连接星图如果成功,下一步是轮询libpq,以便继续连接序列。使用电源插座(康涅狄格州)获取数据库连接基础套接字的描述符。(注意:不要假设插座在整个过程中保持不变。)民意测验电话。)这样循环:如果康涅狄格州上次回来PGRES_轮询_读取,等待套接字准备好读取(如所示)选择(), 投票,或类似的系统功能)。然后打电话康涅狄格州再一次相反,如果康涅狄格州上次回来PGRES_POLLING_写作,等待套接字准备好写入,然后调用康涅狄格州再一次在第一次迭代中,即如果您尚未调用民意测验,就好像它最后一次回来一样PGRES_POLLING_写作.继续这个循环直到康涅狄格州返回PGRES_轮询_失败,表示连接过程失败,或PGRES_POLLING_OK,表示已成功建立连接。

    在连接过程中的任何时候,都可以通过调用PQ状态.如果这个电话回来连接不好,则连接过程失败;如果电话回音好的,则连接已准备就绪。这两种状态都可以从民意测验,如上所述。其他状态也可能在异步连接过程期间(并且仅在异步连接过程期间)发生。这些指示连接过程的当前阶段,例如,可能有助于向用户提供反馈。这些状态是:

连接已启动

正在等待连接。

连接!

连接正常;等待发送。

连接等待响应

正在等待服务器的响应。

连接_验证_确定

接收认证;正在等待后端启动完成。

连接\u SSL\u启动

协商SSL加密。

连接_SETENV

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

连接检查可写

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

连接消耗

正在使用连接上的所有剩余响应消息。

请注意,尽管这些常量将保持不变(为了保持兼容性),但应用程序永远不应该依赖于这些常量以特定顺序出现,或者根本不应该依赖于这些常量,或者依赖于状态始终是这些记录的值之一。应用程序可能会执行以下操作:

switch(PQstatus(conn))
{
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
            feedback = "Connecting...";
}

这个连接超时使用时忽略连接参数民意测验; 应用程序有责任决定是否经过了过长的时间。否则连接开始然后是民意测验循环相当于PQconnectdb.

注意,当连接开始连接星图返回非空指针,必须调用PQfinish当你完成它,以便处置该结构和任何相关的内存块。即使连接尝试失败或放弃,也必须这样做。

pqconn默认值

返回默认连接选项。

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选项及其当前默认值。返回值指向pQConInfoOption结构,该结构以具有null的条目结尾关键词指针。如果无法分配内存,则返回空指针。请注意,当前的默认值(瓦尔字段)将取决于环境变量和其他上下文。丢失或无效的服务文件将被静默忽略。呼叫者必须将连接选项数据视为只读。

处理完选项数组后,将其传递给免费的。如果不这样做,则每次调用pqconn默认值.

PQconninfo

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

PQconninfoOption *PQconninfo(PGconn *conn);

返回连接选项数组。这可以用来确定所有可能的PQconnectdb选项和用于连接到服务器的值。返回值指向pQConInfoOption结构,该结构以具有null的条目结尾关键词指针。以上所有注释仅供参考pqconn默认值也适用于以下结果:PQconninfo.

pqconnsporse

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

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

解析连接字符串并将结果选项作为数组返回;或返回无效的如果连接字符串有问题。此函数可用于提取PQconnectdb提供的连接字符串中的选项。返回值指向pQConInfoOption结构,该结构以具有null的条目结尾关键词指针。

所有合法选项都将出现在结果数组中,但pQConInfoOption对于连接字符串中不存在的任何选项瓦尔开始无效的; 不会插入默认值。

如果不是无效的然后*嗯即将无效的在成功的时候,否则就要失败马洛克“d解释问题的错误字符串。”。(也有可能是*嗯着手无效的以及返回的函数无效的; 这表示内存不足。)

处理完选项数组后,将其传递给免费的。如果不这样做,则每次调用pqconnsporse.相反,如果发生错误不是无效的,请确保使用释放错误字符串PQfreemem.

PQfinish

关闭与服务器的连接。还可以释放用户使用的内存PGconn对象

void PQfinish(PGconn *conn);

请注意,即使服务器连接尝试失败(如PQ状态),应用程序应调用PQfinish释放服务器使用的内存PGconn对象这个PGconn之后不得再次使用指针PQfinish已经打过电话了。

PQreset

重置与服务器的通信通道。

void PQreset(PGconn *conn);

此功能将关闭与服务器的连接,并尝试使用之前使用的所有相同参数建立新连接。如果工作连接丢失,这可能有助于错误恢复。

重新启动
民意测验

以非阻塞方式重置与服务器的通信通道。

int PQresetStart(PGconn *conn);

PostgresPollingStatusType PQresetPoll(PGconn *conn);

这些功能将关闭与服务器的连接,并尝试使用之前使用的所有相同参数建立新连接。如果工作连接丢失,这对于错误恢复非常有用。它们不同于PQreset(上图)因为它们以非阻塞的方式行动。这些功能受到的限制与连接星图, 连接开始民意测验.

要启动连接重置,请致电重新启动.如果返回0,则重置失败。如果返回1,则使用民意测验与使用创建连接的方式完全相同民意测验.

PQpingParams

PQpingParams报告服务器的状态。它接受与的连接参数相同的连接参数PQconnectdbParams,如上所述。获取服务器状态不需要提供正确的用户名、密码或数据库名称值;但是,如果提供的值不正确,服务器将记录失败的连接尝试。

PGPing PQpingParams(const char * const *keywords,
                    const char * const *values,
                    int expand_dbname);

该函数返回以下值之一:

好的

服务器正在运行,似乎正在接受连接。

PQPING_拒绝

服务器正在运行,但处于不允许连接的状态(启动、关闭或崩溃恢复)。

PQPING_无响应

无法联系服务器。这可能表明服务器没有运行,或者给定的连接参数有问题(例如,错误的端口号),或者存在网络连接问题(例如,防火墙阻止连接请求)。

PQPING_无尝试

没有尝试联系服务器,因为提供的参数明显不正确,或者存在一些客户端问题(例如,内存不足)。

PQping

PQping报告服务器的状态。它接受与的连接参数相同的连接参数PQconnectdb,如上所述。获取服务器状态不需要提供正确的用户名、密码或数据库名称值;但是,如果提供的值不正确,服务器将记录失败的连接尝试。

PGPing PQping(const char *conninfo);

返回值与的相同PQpingParams.

PQsetSSLKeyPassHook_OpenSSL

PQsetSSLKeyPassHook_OpenSSL允许应用程序覆盖libpq的加密客户端证书密钥文件的默认处理使用sslpassword或者互动提示。

void PQsetSSLKeyPassHook_OpenSSL(PQsslKeyPassHook_OpenSSL_type hook);

应用程序将指针传递给带有签名的回调函数:

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

然后哪个libpq将调用而不是它的默认PQdefaultSSLKeyPassHook_OpenSSL汉德勒。回调函数应该确定密钥的密码,并将其复制到结果缓冲区*缓冲器大小大小.绳子缓冲器必须以null结尾。回调必须返回存储在中的密码长度缓冲器*不包括空终止符。失败时,应设置回调buf[0]='\0'然后返回0.看见PQdefaultSSLKeyPassHook_OpenSSL以libpq的源代码为例。

如果用户指定了显式密钥位置,其路径将为康涅狄格州->斯尔基当调用回调时。如果正在使用默认密钥路径,则该值将为空。对于作为引擎说明符的密钥,由引擎实现决定它们是使用OpenSSL密码回调还是定义自己的处理。

应用回调可以选择将未处理的案例委托给PQdefaultSSLKeyPassHook_OpenSSL,或者先调用它,如果它返回0,则尝试其他操作,或者完全覆盖它。

回拨不能例外情况下,脱离正常流量控制,longjmp(…)等。它必须正常返回。

PQgetSSLKeyPassHook_OpenSSL

PQgetSSLKeyPassHook_OpenSSL返回当前客户端证书密钥密码挂钩,或无效的如果没有设置。

PQsslKeyPassHook_OpenSSL_type PQgetSSLKeyPassHook_OpenSSL(void);

# 34.1.1.连接字符串

几个libpq函数解析用户指定的字符串以获取连接参数。这些字符串有两种公认的格式:普通关键字/值字符串和URI。URI通常遵循RFC 3986 (opens new window),但允许使用多主机连接字符串,如下所述。

# 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://博士后://。剩余的每个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需要使用百分比编码 (opens new window)如果其任何部分包含具有特殊含义的符号。下面是一个例子,其中等号(=)被替换为%3D还有空间特征%20:

postgresql://user@localhost:5433/mydb?options=-c%20synchronous_commit%3Doff

主机部分可以是主机名或IP地址。要指定IPv6地址,请将其括在方括号中:

postgresql://[2001:db8::1234]/database

主体零件的解释如参数所述主办。特别是,如果主机部分为空或看起来像绝对路径名,则选择Unix域套接字连接,否则会启动TCP/IP连接。但是,请注意,斜杠是URI层次结构部分中的保留字符。因此,要指定非标准的Unix域套接字目录,可以省略URI的主机部分并将主机指定为命名参数,或者对URI的主机部分的路径进行百分比编码:

postgresql:///dbname?host=/var/lib/postgresql
postgresql://%2Fvar%2Flib%2Fpostgresql/dbname

可以在一个URI中指定多个主机组件,每个组件都有一个可选的端口组件。表单的URIPostgresql://host1:port1,host2:port2,host3:port3/相当于以下形式的连接字符串主机=主机1,主机2,主机3端口=端口1,端口2,端口3。如下文所述,将依次尝试每个主机,直到成功建立连接。

# 34.1.1.3.指定多个主机

可以指定要连接的多个主机,以便按给定顺序尝试它们。在关键字/值格式中主办, 霍斯塔德酒店港口城市选项接受逗号分隔的值列表。在指定的每个选项中必须给出相同数量的元素,例如,第一个霍斯塔德酒店对应于第一个主机名,第二个霍斯塔德酒店对应于第二个主机名,依此类推。如果只有一个例外的话港口城市如果指定,则它适用于所有主机。

在连接URI格式中,可以列出多个主持人:波特表中以逗号分隔的对主办URI的组件。

在这两种格式中,一个主机名都可以转换为多个网络地址。一个常见的例子是同时具有IPv4和IPv6地址的主机。

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

如果使用密码文件,您可以为不同的主机使用不同的密码。列表中的每个主机的所有其他连接选项都相同;例如,不可能为不同的主机指定不同的用户名。

# 34.1.2.参数关键字

当前识别的参数关键字为:

主办

要连接到的主机的名称。如果主机名看起来像一个绝对路径名,则它指定Unix域通信,而不是TCP/IP通信;该值是存储套接字文件的目录的名称。(在Unix上,绝对路径名以斜杠开头。在Windows上,也可以识别以驱动器号开头的路径。)如果主机名以@,它被作为抽象名称空间中的Unix域套接字(当前Linux和Windows支持)。当主办未指定或为空,是为了连接到Unix域套接字在里面/tmp(或者构建PostgreSQL时指定的任何套接字目录)。在Windows和没有Unix域套接字的计算机上,默认设置是连接到本地服务器.

也接受以逗号分隔的主机名列表,在这种情况下,列表中的每个主机名都会按顺序进行尝试;列表中的一个空项将选择如上所述的默认行为。看见第34.1.1.3节详细信息。

霍斯塔德酒店

要连接的主机的数字IP地址。这应该是标准的IPv4地址格式,例如。,172.28.40.9。如果您的计算机支持IPv6,您也可以使用这些地址。当为此参数指定非空字符串时,始终使用TCP/IP通信。如果未指定此参数,则主办将被查找以找到相应的IP地址——或者,如果主办指定一个IP地址,该值将直接使用。

使用霍斯塔德酒店允许应用程序避免主机名查找,这在有时间限制的应用程序中可能很重要。但是,GSSAPI或SSPI身份验证方法以及验证完整SSL证书验证。使用以下规则:

  • 如果主办没有指定霍斯塔德酒店,将进行主机名查找。(使用时)民意测验,当民意测验首先考虑这个主机名,它可能会导致民意测验要在相当长的时间内阻塞。)

  • 如果霍斯塔德酒店没有指定主办,为霍斯塔德酒店提供服务器网络地址。如果身份验证方法需要主机名,则连接尝试将失败。

  • 如果两者都有主办霍斯塔德酒店如果已指定,则霍斯塔德酒店提供服务器网络地址。价值主办被忽略,除非身份验证方法需要它,在这种情况下,它将被用作主机名。

    请注意,如果主办不是网络地址处的服务器名称霍斯塔德酒店.而且,当两者都主办霍斯塔德酒店指定的,主办用于在密码文件中标识连接(请参阅第34.16节).

    以逗号分隔的列表霍斯塔德酒店值也被接受,在这种情况下,列表中的每个主机都会按顺序进行尝试。列表中的空项会导致使用相应的主机名,如果该主机名为空,则使用默认主机名。看见第34.1.1.3节详细信息。

    没有主机名或主机地址,libpq将使用本地Unix域套接字进行连接;或者在Windows和没有Unix域套接字的计算机上,它将尝试连接到本地服务器.

港口城市

服务器主机上要连接的端口号,或Unix域连接的套接字文件扩展名。如果系统中提供了多个主机主办霍斯塔德酒店参数,此参数可以指定与主机列表长度相同的端口的逗号分隔列表,也可以指定用于所有主机的单个端口号。空字符串或逗号分隔列表中的空项指定生成PostgreSQL时建立的默认端口号。

库名

数据库名称。默认值与用户名相同。在某些情况下,会检查扩展格式的值;看见第34.1.1节更多关于这些的细节。

使用者

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

暗语

如果服务器要求密码身份验证,则使用密码。

密码文件

指定用于存储密码的文件名(请参见第34.16节).默认为~/.pgpass%APPDATA%\postgresql\pgpass。形态在微软Windows上。(如果此文件不存在,则不会报告错误。)

通道绑定

此选项控制客户端对通道绑定的使用。一套要求表示连接必须使用通道绑定,更喜欢意味着客户端将选择通道绑定(如果可用),以及使残废防止使用通道绑定。默认值是更喜欢如果PostgreSQL是使用SSL支持编译的;否则默认为使残废.

通道绑定是服务器向客户机进行身份验证的一种方法。仅支持通过SSL连接使用PostgreSQL 11或更高版本的服务器快滚身份验证方法。

连接超时

连接时等待的最长时间,以秒为单位(以十进制整数写入,例如。,10).零、负或未指定表示无限期等待。允许的最小超时为2秒,因此值为1.被解释为2.。此超时分别适用于每个主机名或IP地址。例如,如果指定两个主机和连接超时是5,如果在5秒内没有连接,每个主机将超时,因此等待连接的总时间可能长达10秒。

客户机编码

这就决定了客户机编码此连接的配置参数。除了相应服务器选项接受的值之外,还可以使用汽车根据客户端中的当前区域设置确定正确的编码(LC_CTYPEUnix系统上的环境变量)。

选项

指定要在连接开始时发送到服务器的命令行选项。例如,将其设置为-c geqo=关闭设置会话的盖库参数到。此字符串中的空格被视为分隔命令行参数,除非用反斜杠转义(\); 写\\表示文字反斜杠。有关可用选项的详细讨论,请咨询第 20 章.

应用名称

指定一个值应用_姓名配置参数。

fallback_application_name

应用_姓名配置参数。如果没有为应用名称通过连接参数或PGAPPNAME环境变量。在希望设置默认应用程序名称但允许用户覆盖它的通用实用程序中,指定备用名称很有用。

保活

控制是否使用客户端 TCP keepalive。默认值为 1,表示开启,但如果不需要保活,您可以将其更改为 0,表示关闭。对于通过 Unix 域套接字建立的连接,此参数将被忽略。

keepalives_idle

控制 TCP 应向服务器发送 keepalive 消息的不活动秒数。零值使用系统默认值。对于通过 Unix 域套接字建立的连接,或者如果禁用了 keepalives,则忽略此参数。它仅在以下系统上受支持TCP_KEEPIDLE或等效的套接字选项可用,并且在 Windows 上;在其他系统上,它没有影响。

keepalives_interval

控制应该重新传输未被服务器确认的 TCP keepalive 消息的秒数。零值使用系统默认值。对于通过 Unix 域套接字建立的连接,或者如果禁用了 keepalives,则忽略此参数。它仅在以下系统上受支持TCP_KEEPINTVL或等效的套接字选项可用,并且在 Windows 上;在其他系统上,它没有影响。

keepalives_count

控制在客户端与服务器的连接被认为死之前可能丢失的 TCP 保持连接的数量。零值使用系统默认值。对于通过 Unix 域套接字建立的连接,或者如果禁用了 keepalives,则忽略此参数。它仅在以下系统上受支持TCP_KEEPCNT或提供等效的插座选项;在其他系统上,它没有影响。

tcp_user_timeout

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

tty

忽略(以前,这指定将服务器调试输出发送到何处)。

复制

此选项确定连接是否应使用复制协议而不是普通协议。这就是 PostgreSQL 复制连接以及 pg 等工具_basebackup 在内部使用,但也可以由第三方应用程序使用。有关复制协议的说明,请参阅第 53.4 节.

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

真的,,是的,1

连接进入物理复制模式。

数据库

连接进入逻辑复制模式,连接到指定的数据库数据库名称范围。

错误的,离开,,0

连接是常规连接,这是默认行为。

在物理或逻辑复制模式下,只能使用简单查询协议。

gssencmode

此选项确定是否或以何种优先级与服务器协商安全 GSS TCP/IP 连接。共有三种模式:

禁用

只尝试非 GSSAPI 加密的连接

更喜欢(默认)

如果存在 GSSAPI 凭据(即,在凭据缓存中),首先尝试 GSSAPI 加密连接;如果失败或没有凭据,请尝试非 GSSAPI 加密连接。这是使用 GSSAPI 支持编译 PostgreSQL 时的默认设置。

要求

只尝试 GSSAPI 加密的连接

gssencmode对于 Unix 域套接字通信被忽略。如果 PostgreSQL 在没有 GSSAPI 支持的情况下编译,使用要求选项将导致错误,而更喜欢将被接受,但 libpq 实际上不会尝试 GSSAPI 加密连接。

ssl模式

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

禁用

只尝试非 SSL 连接

允许

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

更喜欢(默认)

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

要求

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

验证-ca

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

验证完整

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

第 34.19 节有关这些选项如何工作的详细说明。

ssl模式对于 Unix 域套接字通信被忽略。如果 PostgreSQL 在没有 SSL 支持的情况下编译,使用选项要求,验证-ca, 或者验证完整将导致错误,而选项允许更喜欢将被接受,但 libpq 实际上不会尝试 SSL 连接。

请注意,如果 GSSAPI 加密是可能的,那么将优先使用 SSL 加密,而不管ssl模式.要在具有有效 GSSAPI 基础架构(例如 Kerberos 服务器)的环境中强制使用 SSL 加密,还需设置gssencmode禁用.

requiressl

This option is deprecated in favor of thesslmodesetting.

If set to 1, an SSL connection to the server is required (this is equivalent tosslmode require). libpq will then refuse to connect if the server does not accept an SSL connection. If set to 0 (default), libpq will negotiate the connection type with the server (equivalent tosslmode prefer). This option is only available if PostgreSQL is compiled with SSL support.

sslcompression

If set to 1, data sent over SSL connections will be compressed. If set to 0, compression will be disabled. The default is 0. This parameter is ignored if a connection without SSL is made.

SSL compression is nowadays considered insecure and its use is no longer recommended. OpenSSL 1.1.0 disables compression by default, and many operating system distributions disable it in prior versions as well, so setting this parameter to on will not have any effect if the server does not accept compression. PostgreSQL 14 disables compression completely in the backend.

If security is not a primary concern, compression can improve throughput if the network is the bottleneck. Disabling compression can improve response time and throughput if CPU performance is the limiting factor.

sslcert

This parameter specifies the file name of the client SSL certificate, replacing the default~/.postgresql/postgresql.crt. This parameter is ignored if an SSL connection is not made.

sslkey

This parameter specifies the location for the secret key used for the client certificate. It can either specify a file name that will be used instead of the default~/.postgresql/postgresql.key, or it can specify a key obtained from an external “engine” (engines are OpenSSL loadable modules). An external engine specification should consist of a colon-separated engine name and an engine-specific key identifier. This parameter is ignored if an SSL connection is not made.

sslpassword

This parameter specifies the password for the secret key specified insslkey, allowing client certificate private keys to be stored in encrypted form on disk even when interactive passphrase input is not practical.

Specifying this parameter with any non-empty value suppresses theEnter PEM pass phrase:提示 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 重新散列要么c_rehash.有关详细信息,请参阅其文档。

两个都sslcrlsslcrldir可以一起指定。

sslsni

如果设置为 1(默认),libpq 在启用 SSL 的连接上设置 TLS 扩展“服务器名称指示”(SNI)。通过将此参数设置为 0,将其关闭。

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

要求同行

该参数指定服务器的操作系统用户名,例如要求同行=postgres.建立 Unix 域套接字连接时,如果设置了此参数,客户端会在连接开始时检查服务器进程是否以指定的用户名运行;如果不是,则连接因错误而中止。此参数可用于提供类似于 TCP/IP 连接上 SSL 证书可用的服务器身份验证。(请注意,如果 Unix 域套接字位于/tmp或另一个可公开写入的位置,任何用户都可以在那里启动服务器监听。使用此参数可确保您连接到由受信任用户运行的服务器。)此选项仅在具有以下功能的平台上受支持同行实现认证方法;看第 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 版本,旧版本不支持最现代的协议版本。如果未设置,则忽略此参数,连接将使用后端定义的最大界限(如果设置)。设置最大协议版本主要用于测试或某些组件在使用较新协议时出现问题。

krbsrv 名称

使用 GSSAPI 进行身份验证时使用的 Kerberos 服务名称。这必须与服务器配置中指定的服务名称匹配,才能使 Kerberos 身份验证成功。(也可以看看第 21.6 节.) 默认值通常是postgres, 但是在构建 PostgreSQL 时可以通过--with-krb-srvnam配置选项。在大多数环境中,永远不需要更改此参数。某些 Kerberos 实现可能需要不同的服务名称,例如 Microsoft Active Directory,它要求服务名称为大写 (研究生院)。

gsslib

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

服务

用于附加参数的服务名称。它指定了一个服务名称pg_service.conf包含额外的连接参数。这允许应用程序仅指定一个服务名称,以便可以集中维护连接参数。看第 34.17 节.

目标会话属性

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

任何(默认)

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

读写

session 必须默认接受读写事务(即服务器不能处于热备模式并且default_transaction_read_only参数必须是离开)

只读

默认情况下,会话不得接受读写事务(反之亦然)

基本的

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

支持

服务器必须处于热备模式

首选备用

首先尝试查找备用服务器,但如果列出的主机都不是备用服务器,请在任何模式