pgbouncer.ini

PgBouncer的配置文件。

概要

[databases]
db = ...
[pgbouncer]
...
[users]
...

描述

可以在配置文件pgbouncer.ini中指定PgBouncer配置参数并指定用户相关的配置参数。

PgBouncer的配置文件（通常是pgbouncer.ini）是.ini格式。 .ini格式的文件通常由小节、参数和参数值组成。小节名称封闭在方括号中， 例如，[section_name]。参数和值通常以 key\=value的方式展示。 以”;”或”#”开头的行被注释或者忽略。当该”;”和”#” 字符出现在行后面时候不被识别。

PgBouncer配置文件包含%include路由符，它指定了用来读取和处理的其他文件。 这让我们可以将配置文件拆分为多个部分。例如：

%include filename

如果提供的文件名不是绝对路径，当前操作系统工作路径被作为相对路径。

PgBouncer的配置文件包括以下小节，详细信息如下：

• [databases]小节
• [pgbouncer]小节
• [users]小节

[databases]小节

[databases]小节包含key\=value 键值对，其中键（key）是数据库名称，值（value） 是key\=value对的libpq连接字符串列表。

数据库名称可以包含不带引号的字符[0-9A-Za-z_.-]。包含其他字符的名称必须使用标准SQL标识符引用：

• 名字用双引号括起来（” “）。
• 用两个连续的双引号字符在一个标识符内表示一个双引号。

数据库名*是回退数据库。此键的值是所请求数据库的连接字符串。 如果自动创建的数据库项的空闲时间超过autodb_idle_timeout参数中指定的时间， 则会自动清理这些数据库项。

数据库连接参数

该值中可能包含以下参数以指定数据库的位置。

dbname

目标数据库名称。

默认值：与客户端数据库名称相同。

host

Greenplum的Master主机的名称或IP地址。主机名在连接时被解析。如果DNS返回多个结果， 则以循环方式使用它们。DNS结果会被缓存，并且dns_max_ttl参数确定 缓存项何时过期。

默认值：未设置，表示通过Unix套接字进行连接。

port

Greenplum数据库的Master端口。

默认：5432

user, password

如果设置了user=，则用指定的用户建立到目标数据库的所有连接。 这意味着数据库将只有一个池。

如果未设置user=参数，将尝试使用客户端传递的用户名登录到目标数据库。 这意味着每个连接到数据库的用户都会有一个池。

auth_user

如果设置了auth_user，任何未在auth_file文件中指定的用户， 通过以auth_user身份查询数据库中的pg_shadow表来认证。 auth_user的口令必须在auth_file中设置。

client_encoding

从服务器要求特定的client_encoding。

datestyle

从服务器要求特定的datestyle。

timezone

从服务器要求特定的timezone。

连接池配置

可以使用以下数据库连接池配置

pool_size

设置该数据库的最大池数。如果没有设置，则使用default_pool_size。

connect_query

在任何用户连接建立之后，允许执行查询。如果查询引发错误，则会被记录，否则将被忽略。

pool_mode

为此数据库设置池模式。如果未设置，则使用默认的pool_mode。

max_db_connections

为此数据库设置数据库范围内的最大连接数。此数据库的所有池连接总数不会超过此值。

[pgbouncer]小节

一般设置

logfile

指定日志文件的位置。日志文件保持打开状态。日志轮转后在PgBouncer管理控制台中执行 kill -HUP pgbouncer或运行RELOAD;命令。

默认：未设置。

pidfile

pid文件的名字。没有pid文件，PgBouncer不能作为后台进程（守护进程）运行。

默认：未设置。

listen_addr

PgBouncer侦听TCP连接的接口地址列表。用户也可以使用*， 表示在所有接口上进行监听。如果没有设置，则仅允许Unix套接字连接。

地址可以用数字（IPv4/IPv6）或名称来指定。

默认：未设置。

listen_port

要监听的端口。应用到TCP和UNIX套接字。

默认：6432

unix_socket_dir

指定Unix套接字的位置。适用于监听套接字和服务器连接。如果设置为空字符串， 则禁用Unix套接字。在线重新启动（-R选项）才能正常工作。

默认值：/tmp

unix_socket_mode

Unix套接字的文件系统模式。

默认为：0777

unix_socket_group

用于Unix套接字的组名。

默认：未设置。

user

如果设置，则指定启动后要更改的Unix用户。这只有在PgBouncer作为root启动或 user与当前用户相同时才有效。

默认：未设置。

auth_file

包含要加载的用户名和口令的文件的名称。文件格式与Greenplum数据库的 pg_auth文件相同，因此可以将此参数设置为其中一个后端文件。

默认：未设置

auth_hba_file

当auth_type为hba时使用的HBA配置文件。 HBA文件格式请参阅https://pgbouncer.github.io/config.html#hba-file-formatPgBouncer文档中PgBouncer支持的HBA授权文件格式的讨论部分。

默认：未设置

auth_type

如何认证用户- pam

使用PAM作为客户授权。auth\_file被忽略。 该方法与auth\_user选项一起使用。 报告给PAM的服务名为“pgbouncer”。PAM在HBA配置文件中不支持。
hba
实际授权类型从auth\_hba\_file文件中加载。 该设置允许不同的访问方法访问不同的路径。
cert
客户端必须使用有效的客户端证书连接到TLS。客户端的用户名取自证书中的CommonName字段。
md5
使用基于MD5的口令检查。auth\_file可能包含MD5加密或纯文本的口令。 这是默认的身份认证方法。
plain
通过网络发送明文口令。*已废弃*。
trust
不做认证。用户名仍然必须存在于auth\_file中。
any
像trust方法一样，但提供的用户名被忽略。要求将所有数据库配置为使 用特定用户登录。另外，控制台数据库允许任何用户以admin登录。

auth_query

从数据库加载用户口令的查询。如果用户不存在于auth_file中并且数据库项包含 auth_user，则该查询作为auth_user在数据库中运行以查找用户。

注意查询会在每个数据库中都执行，如果要运行函数，那么该函数需要在每个数据库中都安装。

默认值：SELECT usename, passwd FROM pg_shadow WHERE usename=$1

auth_user

如果设置了auth_user，任何未在auth_file文件中指定的用户， 通过以auth_user身份查询数据库中的pg_shadow表来认证。 auth_user的口令必须在auth_file中设置。

直接访问pg_shadow要求有Greenplum数据库的管理员权限。 推荐使用非管理员用户并调用函数来代替。

pool_mode

指定服务器连接何时可以被其他客户端重用。- session

当客户端断开连接时，连接返回到池。默认。
transaction
事务结束后，连接返回到池。
statement
当前查询完成后，连接返回到池。具有多个语句的长事务在此模式下被禁止。

max_client_conn

允许的最大客户端连接数。当增加时，文件描述符限制也应该增加。使用的文件描述符的实际数量大于 max_client_conn。当每个用户使用自己的用户名连接到服务器时， 使用的理论最大值是：

max_client_conn + (max_pool_size * total_databases * total_users)

如果在连接字符串中指定了数据库用户，则所有用户使用相同的用户名连接。那么理论上的最大连接是：

max_client_conn + (max_pool_size * total_databases)

（应该永远不要达到理论上的最大值，除非有人刻意为它加上负荷。但是，这意味着用户应该将文件 描述符的数量设置为一个安全的较高数字。在用户的操作系统文档中搜索ulimit。）

默认：100

default_pool_size

允许每个用户/数据库对的服务器连接数量。这可以在每个数据库配置中被覆盖。

默认：20

min_pool_size

当池中连接数低于这个数字时，将更多的服务器连接添加到池中。当平常的负载下降然后在一段时间 的不活跃期之后突然恢复到平常的负载时，这会改善行为。

默认值：0（禁用）

reserve_pool_size

对池允许的额外连接的数量。0 禁用。

默认： 0（禁用）

reserve_pool_timeout

如果客户端在这段时间内没有被服务，PgBouncer允许使用来自保留池的额外连接。0禁用。

默认值：5.0

max_db_connections

每个数据库的最大连接数。如果达到限制，关闭到池的客户端连接不会立即允许对另一个池建立服务器连接， 因为第一个池的服务器连接仍处于打开状态。一旦服务器连接关闭（由于空闲超时）， 将为等待池打开一个新的服务器连接。

默认：没限制

max_user_connections

每个用户的最大连接数。当用户达到限制时，关闭到池的客户端连接不会立即允许对另一个池建立服务器连接， 因为第一个池的服务器连接仍处于打开状态。一旦服务器连接关闭（由于空闲超时）， 将为等待池打开一个新的服务器连接。

server_round_robin

默认情况下，PgBouncer以LIFO（后进先出）顺序重用服务器连接，这样少数连接获得最大的负载。 这在单个服务器提供数据库时提供最佳性能。但是如果数据库IP后面有TCP循环，那么最好是PgBouncer 也以这种方式使用连接来实现均衡的负载。

默认值：0

ignore_startup_parameters

默认情况下，PgBouncer只允许它在启动包中可以跟踪的参数： client_encoding、datestyle、 timezone和 standard_conforming_strings。

所有其他参数都会产生错误。 要允许其他参数，在这里指定它们，这样PgBouncer可以忽略它们。

默认值：空

disable_pqexec

禁用简单查询协议（PQexec）。与扩展查询协议不同，简单查询协议允许在一个数据包中进行多个查询， 这允许某些种类的SQL注入攻击。禁用它可以提高安全性。这意味着只有专门使用扩展查询协议的客户端 才能工作。

默认值：0

application_name_add_host

将客户端主机地址和端口添加到连接启动时设置的应用程序名称设置。这有助于识别不良查询的来源。 如果应用程序在连接后执行了SET application_name，则设置将被覆盖而不被检测到。

默认值：1

conffile

显示当前配置文件位置。改变该参数会导致PgBouncer在下次RELOAD/SIGHUP后使用另外的配置文件。

默认值：文件来自命令行

service_name

仅在win32服务注册时使用。

默认值：pgbouncer

job_name

service_name的代称。

日志设置

syslog

切换syslog开启和关闭。

默认值：0

syslog_ident

以什么名字发送日志到syslog。

默认值： pgbouncer

syslog_facility

在什么设施下发送日志到系统日志。一些可能是： auth、authpriv、daemon、 user、local0-7

默认值： daemon

log_connections

记录成功的登陆。

默认值：1

log_disconnections

记录连接失败的原因。

默认值：1

log_pooler_errors

记录池中发送给客户端的错误消息。

默认值：1

stats_period

将汇总的统计信息写入日志的频率。

默认值：60

控制台访问控制

admin_users

允许连接并在控制台上运行所有命令的数据库用户列表，用逗号分隔。 当auth_type=any时候，忽略该列表。在这种情况下，任何用户名都被允许作为admin。

默认值：空

stats_users

逗号分隔的数据库用户列表，允许它们在控制台上连接并运行只读查询。这意味着除了SHOW FDS 之外的所有SHOW命令。

默认值：空

C连接健康检查、超时

server_reset_query

在连接释放时且没有对其他客户端可用之前，发送到服务器的查询。在那一刻没有事务正在进行， 所以它不应该包括ABORT或ROLLBACK。

该查询会清理任何改变模式为数据库会话，以保证下一个客户端连接获取更好的状态。默认为 DISCARD ALL

当使用事务池时，server_reset_query应该是空的， 因为客户端不能使用任何事务特性。如果客户端使用了事务特性，操作将会失败，因为事务池 不能保证下次运行相同的连接。

默认为： DISCARD ALL;

server_reset_query_always

server_reset_query是否应该在所有池模式下运行。如果此设置处于关闭状态 （默认），则server_reset_query将仅在处于会话池模式的池中运行。 事务池模式下的连接不应该有任何重置查询的需要。

默认值：0

server_check_delay

保持被释放连接可重用而不运行健康检查查询的时间。如果为0，则查询始终运行。

默认值：30.0

server_check_query

用来测试服务器连接的一个简单的无所作为的查询。

如果是一个空字符串，则禁用健康检查。

默认值：SELECT 1;

server_lifetime

池会尝试关闭连接时间超过这个秒数的服务器连接。将其设置为0意味着连接只能使用一次， 然后关闭。

默认值：3600.0

server_idle_timeout

如果服务器连接闲置超过这么多秒钟，它将被丢弃。如果此参数设置为0，则禁用超时。

默认值： 600.0

server_connect_timeout

如果在此秒数内连接和登录无法完成，则连接将被关闭。

默认值：15.0

server_login_retry

如果登陆由于connect()或认证失败而失败，则在重新尝试连接之前， 池会等待几秒钟。

默认值：15.0

client_login_timeout

如果客户端在此秒数内连接但无法登录，则会断开连接。需要这来避免死连接卡住 SUSPEND，从而导致在线重新启动。

默认值：60.0

autodb_idle_timeout

如果（通过*）自动创建的数据库池已经有这么多秒没有使用， 则它们将被释放。并且也放弃对它们的统计。

默认值： 3600.0

dns_max_ttl

缓存DNS查找结果多少秒。如果一个DNS查找返回几个答案，那么PgBouncer会在它们之间循环往复。实际的DNS TTL被忽略。

默认值：15.0

dns_nxdomain_ttl

可以缓存错误和NXDOMAIN DNS查找多长时间。以秒为单位。

默认值：15.0

dns_zone_check_period

检查区域序列号是否改变的周期。

PgBouncer可以从主机名（第一个点之后的所有内容）收集DNS区域，然后定期检查区域序列号是否更改。 如果检测到更改，则会再次查找该区域中的所有主机名。如果任何主机IP发生更改，则其连接将失效。

只适用于UDNS后端（用--with-udns或--with-cares配置）。

默认值：0.0（禁用）

TLS设置

client_tls_sslmode

TLS模式主要给客户端连接使用。TLS连接默认不启用。当启用时，必须同时配置 client_tls_key_file和client_tls_cert_file 参数，以使PgBouncer能够接受客户端连接。

• disable: plain TCP。如果客户端请求TLS。他会被忽略。默认配置。
• allow: 如果客户端请求TLS，他被使用。如果没请求，使用plain TCP。 如果客户端使用client-certificate，不会验证改值。
• prefer: 与allow相同
• require: 客户端必须使用TLS。如果不使用，客户端连接被拒绝。 如果客户端使用client-certificate，他不被验证。
• verify-ca: 客户端必须使用TLS并验证客户端授权。
• verify-full: 与verify-ca相同。

client_tls_key_file

PgBouncer使用私有密钥接受客户端连接

默认值：不设置。

client_tls_cert_file

根证书授权验证客户端授权。

默认值：未设置。

client_tls_ca_file

根证书授权验证客户端授权。

默认值：未设置。

client_tls_protocols

那种TLS协议被允许。

有效值为：tlsv1.0、tlsv1.1 、tlsv1.2。

快捷方式：all（tlsv1.0、tlsv1.1、tlsv1.2）、secure（tlsv1.2）、legacy（all）。

默认值：all

client_tls_ciphers

默认值：fast

client_tls_ecdhcurve

ECDH key交换使用的Elliptic Curve名称。

可用值：none（DH禁用）、auto（256-bit ECDH）、curve name。

默认值：auto

client_tls_dheparams

DHE key交换类型。

可用值：none（DH禁用）、auto（2048-bit ECDH）、 legacy（1024-bit ECDH）。

默认值：auto

server_tls_sslmode

连接到Greenplum数据库和PostgreSQL数据库的TLS模式。TLS连接默认被禁用。

• disable: plain TCP。如果客户端请求TLS。他会被忽略。默认配置。
• allow: 如果客户端请求TLS，他被使用。如果没请求，使用plain TCP。 如果客户端使用client-certificate，不会验证改值。
• prefer: 与allow相同
• require: 客户端必须使用TLS。如果不使用，客户端连接被拒绝。 如果客户端使用client-certificate，他不被验证。
• verify-ca: 客户端必须使用TLS并验证客户端授权。
• verify-full: 与verify-ca相同。

server_tls_ca_file

用于验证Greenplum和PostgreSQL数据库服务证书的证书验证文件。

默认值：不设置。

server_tls_key_file

依赖于Greenplum或PostgreSQL的PgBouncer私有密钥。

默认值：不设置。

server_tls_cert_file

私有密钥证书。Greenplum或PostgreSQL数据库会验证它。

默认值：不设置。

server_tls_protocols

允许使用的TLS协议版本。

有效值为：tlsv1.0、tlsv1.1、 tlsv1.2。

快捷方式：all（tlsv1.0、tlsv1.1、tlsv1.2）、secure（tlsv1.2）、legacy（all）。

server_tls_ciphers

默认值：fast

危险超时

设置以下超时可能会导致意外的错误。

query_timeout

运行时间超过这个秒数的查询被取消。此参数只能与较小的服务器端 statement_timeout一起使用，以捕获出现网络问题的查询。

默认值：0.0（禁用）

query_wait_timeout

允许查询等待执行的最长时间（以秒为单位）。如果在此期间查询未分配连接， 则客户端将断开连接。 这用于防止无响应的服务器强占连接。

默认值：0.0（禁用）

client_idle_timeout

客户端连接空闲的时间超过了这么多秒钟就会被关闭。 这应该大于客户端连接的生命周期设置， 并且仅用于网络问题。

默认值：0.0（禁用）

idle_transaction_timeout

如果客户端处于“事务空闲”状态的时间超过这个秒数，则它被断开。

默认值：0.0（禁用）

低层网络设置

pkt_buf

包的内部缓冲区大小。影响发送的TCP包的尺寸和一般内存使用情况。 实际的libpq包可能比这个大，所以没有必要把它设置的很大。

默认值：4096

max_packet_size

PgBouncer接受的包的最大尺寸。包是一个查询或一个结果集行。完整的结果集可以更大。

默认值： 2147483647

listen_backlog

listen(2)系统调用的backlog参数。它表示有多少新的未答复的连接尝试被保留在队列中。 当队列已满时，进一步的新连接尝试被丢弃。

默认值：128

sbuf_loopcnt

在继续之前，在一个连接上处理数据多少次。没有这个限制，一个大的结果集的连接可能会使 PgBouncer停顿很长时间。一个循环处理一个pkt_buf数量的数据。0表示没有限制。

默认值：5

suspend_timeout

等待SUSPEND或reboot（-R）期间的缓冲区刷写多少秒钟。 如果刷写不成功，连接将被丢弃。

默认值：10

tcp_defer_accept

有关此选项和其他TCP选项的详细信息，请参阅tcp（7）手册页。

默认值：Linux上是45，其他为0

tcp_socket_buffer

默认值：不设置

tcp_keepalive

用OS默认值启用基本的keepalive。

Linux上，系统默认为 tcp_keepidle=7200、tcp_keepintvl=75、 tcp_keepcnt=9。

默认值：1

tcp_keepcnt

默认值：未设置

tcp_keepidle

默认值：未设置

tcp_keepintvl

默认值：未设置

[users]小节

这部分包含key\=value对， 其中key是用户名，value是 key\=value对的 libpq连接字符串列表。

池配置

pool_mode

设置池模式用于来自此用户的所有连接。如果未设置，则使用数据库或默认pool_mode。

示例配置文件

最小配置

[databases]
postgres = host=127.0.0.1 dbname=postgres auth_user=gpadmin
[pgbouncer]
pool_mode = session
listen_port = 6543
listen_addr = 127.0.0.1
auth_type = md5
auth_file = users.txt
logfile = pgbouncer.log
pidfile = pgbouncer.pid
admin_users = someuser
stats_users = stat_collector

使用客户端传递的连接参数：

[databases]
* =
[pgbouncer]
listen_port = 6543
listen_addr = 0.0.0.0
auth_type = trust
auth_file = bouncer/users.txt
logfile = pgbouncer.log
pidfile = pgbouncer.pid
ignore_startup_parameters=options

数据库默认

[databases]
; foodb over unix socket
foodb =
; redirect bardb to bazdb on localhost
bardb = host=127.0.0.1 dbname=bazdb
; access to destination database will go with single user
forcedb = host=127.0.0.1 port=300 user=baz password=foo client_encoding=UNICODE datestyle=ISO

另见

pgbouncer、 pgbouncer-admin、 PgBouncer配置页面