pgbouncer

管理数据库连接池。

概要

pgbouncer [OPTION ...] config.ini
  OPTION
   [ -d | --daemon ]
   [ -R | --restart ]
   [ -q | --quiet ]
   [ -v | --verbose ]
   [ {-u | --user}=username ]
pgbouncer [ -V | --version ] | [ -h | --help ]

描述

PgBouncer是Greenplum和PostgreSQL数据库的轻量级连接池管理器。数据库可能位于不同的Greenplum数据库集群或PostgreSQL后端。PgBouncer为每个数据库用户和数据库组合创建一个池。池连接只能重用于同一用户和数据库的另一个连接请求。客户端应用程序连接到连接池的主机和端口，而不是Greenplum数据库Master主机和端口。PgBouncer或者为客户端创建一个新的数据库连接，或者重用一个现有的连接。当客户端断开连接时，连接被返回到池中以供重用。

PgBouncer支持PostgreSQL和Greenplum数据库共享的标准连接接口。请求数据库连接的客户端提供PgBouncer运行的主机名和端口，以及数据库名称、用户名和口令。PgBouncer在其配置文件中查找所请求的数据库（可能是实际数据库的别名），以查找数据库连接的主机名、端口和数据库名称。配置文件项还决定了如何对用户进行身份认证以及连接将使用哪个数据库角色 - “强制用户”可以覆盖随客户端连接请求提供的用户名。

PgBouncer需要一个认证文件，它是包含用户和口令列表的文本文件。口令可以是明文、MD5编码或LDAP/AD查找字符串。用户还可以设置PgBouncer来查询目标数据库中的pg_shadow表，以查找不在认证文件中的用户。

PgBouncer以三种池模式之一共享连接：

• 会话池 – 当客户端连接时，只要它保持连接状态，就会为其分配连接。当客户端断开时，连接被放回到池中。
• 事务池 – 在事务期间，连接被分配给客户端。当PgBouncer发现事务完成时，连接被放回池中。此模式只能用于不使用依赖会话功能的应用程序。
• 语句池 – 语句池就像事务池，但不允许多语句事务。这个模式是为了在客户端执行自动提交模式，并且是针对PostgreSQL上的PL/Proxy的。

可以为PgBouncer实例设置默认池模式，并且可以为单个数据库和用户覆盖该模式。

通过连接到虚拟的pgbouncer数据库，用户可以使用类似于SQL的命令来监视和管理PgBouncer。可以更改配置参数而无需重新启动PgBouncer，并且可以重新加载配置文件来获取更改。

PgBouncer还不支持SSL连接。如果要加密客户端和PgBouncer之间的流量，可以使用stunnel这个免费的软件工具，它使用OpenSSL加密库创建TLS加密的隧道。请参阅Greenplum数据库管理员指南中的“用stunnel保护PgBouncer连接”以获取指导。

额外的使用信息请参阅PgBouncer FAQ。

本参考话题包含以下额外的参考信息：

• PgBouncer的配置文件
• PgBouncer的认证文件格式
• PgBouncer管理控制台命令

选项

-d | —daemon

运行PgBouncer作为守护进程（后台进程）。默认是作为前台进程运行。

作为守护进程启动时，PgBouncer显示启动消息。要禁止显示消息，请添加-q选项。

要关闭PgBouncer守护程序，请登录管理控制台并发出SHUTDOWN命令。

注意： 此选项在Windows服务器上不起作用。

-R | —restart

使用指定的命令行参数重新启动PgBouncer。在重新启动期间，维护与数据库的非TLS连接，TLS连接被丢弃。

如果用户只指定-R选项，PgBouncer将在重新启动后在命令行上显示日志信息。要作为守护程序重新启动PgBouncer，请指定选项-Rd。

注意： 仅在操作系统支持Unix套接字且PgBouncer配置没有unix_socket_dir的情况下有效。此选项在Windows服务器上不起作用。

-q | —quiet

安静地运行，不在命令行（stdout）上显示消息。

-v | —verbose

增加消息详细度。显示额外的消息。可以多次使用。

{-u | —user}=username

PgBouncer进程假定的username的身份。

-V | —version

显示版本并退出。

-h | —help

显示帮助信息并退出。

PgBouncer的配置文件

PgBouncer的配置文件（通常是pgbouncer.ini）是”ini”格式。小节名称封闭在方括号（[和 ]）中。以”;”或”#”开头的行被注释或者忽略。当该”;”和”#” 字符出现在行后面时候不被识别。

概要

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

描述

PgBouncer的配置文件最多有三个小节：

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

[databases]小节

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

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

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

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

PgBouncer配置文件可以包含%include指令，指定另一个文件来读取和处理。这允许将配置文件分成不同的部分。例如：

%include filename

位置参数

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

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中设置。

池配置

pool_size

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

connect_query

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

pool_mode

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

max_db_connections

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

额外参数

以下参数允许在服务器连接上设置默认参数值。

请注意，从版本1.1开始，PgBouncer会跟踪其值的客户端更改，因此它们在pgbouncer.ini中的使用已被废弃。

client_encoding

从服务器要求特定的client_encoding。

datestyle

从服务器要求特定的datestyle。

timezone

从服务器要求特定的timezone。

[pgbouncer]小节

logfile

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

默认：未设置。

注意： 在Windows机器上的时，该服务必须停止并启动。

.

pidfile

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

默认：未设置。

listen_addr

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

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

默认：未设置。

listen_port

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

默认：6432

unix_socket_dir

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

注意： Windows机器不支持。

默认值： /tmp

unix_socket_mode

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

默认为：0777

unix_socket_group

用于Unix套接字的组名。

默认：未设置。

user

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

默认：未设置。

auth_file

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

默认：未设置

auth_type

如何认证用户- 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

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。

注意： ulimit不适用于Windows环境。

默认：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

日志设置

syslog

切换syslog开启和关闭。在Windows上，使用eventlog代替。

默认值： 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_mode=any时候，忽略该列表。在这种情况下，任何用户名都被允许作为admin。

默认值：空

stats_users

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

默认值：空

连接健康检查、超时

server_reset_query

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

对Postgres 8.2及以下版本和Greenplum数据库的不错选择是：

server_reset_query = RESET ALL; SET SESSION AUTHORIZATION DEFAULT;

对于Postgres 8.3及以上版本，以下就足够了：

server_reset_query = DISCARD ALL;

使用事务池时，server_reset_query应为空，因为客户端不应使用任何会话功能。如果客户端使用会话功能，它们将被破坏，因为事务池不能保证下一个查询将在同一个连接上运行。

默认值： RESET ALL; SET SESSION AUTHORIZATION DEFAULT;

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配置）。

默认值：0.0（禁用）

危险超时

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

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包可能比这个大，所以没有必要把它设置的很大。

默认值：2048

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对的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 = 65432
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需要自己的用户数据库，是一个如下格式的文本文件：

"username1" "password" ...
"username2" "md5abcdef012342345" ...

每个用户有一行。每一行必须至少有两个字段。字段用双引号（”）括起来，第一个字段是用户名，第二个字段是纯文本或MD5编码的口令，行中其余部分被忽略。

此文件格式与Greenplum数据库用于认证信息的文本文件相似，PgBouncer可以直接用Greenplum数据库的认证文件工作。

为了避免使用纯文本口令，请使用MD5对用户口令进行编码。MD5编码口令的格式是：

"md5" + md5(password + username)

例如，以下命令为口令为1234的用户admin生成MD5字符串：

$ echo -n "1234admin" | md5sum
$ 45f2603610af569b6155c45067268c6b

MD5编码的口令是：

md545f2603610af569b6155c45067268c6b

PgBouncer管理控制台命令

通过连接到数据库pgbouncer可以访问PgBouncer管理控制台。

$ psql -p 6543 pgbouncer

只有在配置参数为admin_users或stats_users时，才能登陆到控制台。但是，当auth_mode=any时，任何用户都可以以stats_user身份登陆。

如果客户端与正在运行的进程具有相同的Unix用户UID，则用户名pgbouncer也可以通过Unix套接字登录而不需要口令。

管理控制台命令语法

pgbouncer=# show help;
NOTICE:  Console usage
DETAIL:
       SHOW HELP|CONFIG|DATABASES|POOLS|CLIENTS|SERVERS|VERSION
    SHOW STATS|FDS|SOCKETS|ACTIVE_SOCKETS|LISTS|MEM
    SHOW DNS_HOSTS|DNS_ZONES
    SET key = arg
    RELOAD
    PAUSE [<db>]
    RESUME [<db>]
    DISABLE <db>
    ENABLE <db>
    KILL <db>
    SUSPEND
    SHUTDOWN

管理命令

从PgBouncer管理员控制台，用户可以控制PgBouncer和Greenplum数据库之间的连接。用户也可以设置PgBouncer配置参数。

以下PgBouncer管理命令控制PgBouncer进程。

PAUSE [database]

如果没有指定数据库，PgBouncer将尝试从所有服务器断开连接，首先等待所有查询完成。 在所有查询完成之前，该命令不会返回。这个命令是用来准备重启数据库的。

如果指定了数据库名称，则只有该数据库被暂停。

如果运行一个PAUSE 数据库命令，然后运行PAUSE命令暂停所有数据库，则必须执行两个RESUME命令，一个用于所有数据库，一个用于指定的数据库。

SUSPEND

所有套接字缓冲区都被刷新，PgBouncer停止监听数据。在所有缓冲区为空之前，该命令不会返回。 在线重新启动PgBouncer时使用。

RESUME [ database ]

从之前的PAUSE或者SUSPEND命令恢复工作。

如果用PAUSE命令指定了数据库，则还必须使用RESUME命令指定数据库。

使用PAUSE命令暂停所有数据库之后，不支持使用RESUME database恢复单个数据库。

DISABLE database

拒绝数据库上的所有新客户端连接。

ENABLE database

在数据库上允许新的客户端连接。

KILL database

立即删除所有的客户端和服务器到指定数据库的连接。

SHUTDOWN

停止PgBouncer进程。从psql命令会话中退出，请输入\q。

RELOAD

PgBouncer进程重新加载当前的配置文件并更新可更改的设置。

SET key = value

覆盖指定的配置设置。请参见SHOW CONFIG;命令。

SHOW命令

SHOW category命令显示不同类型的PgBouncer信息。用户可以指定以下类别之一：

• ACTIVE_SOCKETS
• CLIENTS
• CONFIG
• DATABASES
• DNS_ZONES
• FDS
• POOLS
• SERVERS
• STATS
• LISTS
• MEM
• USERS
• VERSION

ACTIVE_SOCKETS

CLIENTS

CONFIG

当前PgBouncer参数设置的列表。

DATABASES

DNS_ZONES

FDS

SHOW FDS是用于联机重启的内部命令，例如升级到新的PgBouncer版本时。它显示正在使用的文件描述符列表以及附加其上的内部状态。这个命令阻塞内部事件循环，因此在PGBouncer被使用的时候不应该使用它。

当连接的用户拥有用户名“pgbouncer”，通过一个Unix套接字连接，并具有与正在运行的进程相同的UID时，实际的文件描述符将通过连接传递。 注意：这在Windows机器上不起作用。

LISTS

在两列中显示以下PgBouncer统计信息：项标签和值。

MEM

显示这些PgBouncer缓存的缓存内存信息：

• user_cache
• db_cache
• pool_cache
• server_cache
• client_cache
• iobuf_cache

POOLS

为每对（数据库，用户）创建一个新的池项。

setting is too small.

SERVERS

STATS

显示统计数据

USERS

VERSION

显示PgBouncer版本的信息

注意： 该参考文档基于PgBouncer 1.6.1文档。