Pgbouncer 用户手册

From PgsqlWiki

Jump to: ,

 pgbouncer(1)

名称

pgbouncer - PostgreSQL 的轻量的连接池。

 摘要

  pgbouncer [-d][-R][-v] 
  pgbouncer -V|-h

 描述

pgbouncer 是一个 PostgreSQL 的连接池。任何目标应用都可以把 pgbouncer 当作一个 PostgreSQL 服务器来连接，然后 pgbouncer 会处理与服务器连接，或者是重用已存在的连接。

pgbouncer 的目标是降低因为新建到 PostgreSQL 的连接而导致的性能损失。

为了协调事务语意和连接池的关系，pgbouncer 支持几种不同粗暴程度的连接轮转方式：

Session pooling/会话连接池

最礼貌的方法。在客户端连接的时候，将会给他分配一个服务器连接，并且在客户端连接的全程都分配给它。在客户端中断连接的时候，这个服务器连接将会放回连接池。

Transaction pooling/事务连接池

服务器连接只是在一个事务的过程里赋予客户端的。在 PgBouncer 注意到事务结束后，服务器就会放回连接池。

Statement pooling/语句连接池

最激进的模式。在每个查询结束之后，服务器的连接都会立即放回连接池。在这种模式下将不允许多语句的事务，因为它们的事务语意会被破坏。

pgbouncer 的管理接口包含一些新的 SHOW 命令，在与特定的虚拟数据库 pgbouncer 连接的时候可以用于观察系统状态。

 快速入门

下面列出了基本的设置步骤。

1. 创建一个配置文件pgbouncer.ini。细节见。最简单的：

     [databases]
     template1 = host=127.0.0.1 port=5432 dbname=template1
     
     [pgbouncer]
     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

2. 创建 users.txt 文件：

     "someuser" "same_password_as_in_server"

3. 启动 pgbouncer：

     $ pgbouncer -d pgbouncer.ini

4. 让你的应用（或者 psql 客户端）连接到 pgbouncer，而不是直接连接到 PostgreSQL 服务器。

     $ psql -h 127.0.0.1 -p 6543 -U someuser template1

5. 通过连接到特殊的管理数据库 pgbouncer 并且发出 show help; 命令开始来管理 pgbouncer：

     $ psql -h 127.0.0.1 -p 6543 -U someuser pgbouncer
     pgbouncer=# show help;
     NOTICE:  Console usage
     DETAIL:
       SHOW [HELP|CONFIG|DATABASES|FDS|POOLS|CLIENTS|SERVERS|SOCKETS|LISTS|VERSION]
       SET key = arg
       RELOAD
       PAUSE
       SUSPEND
       RESUME
       SHUTDOWN

6. 如果你修改了一些配置文件中可配置的配置参数，那么可以用下面命令重新装载：

     pgbouncer=# RELOAD;

 命令行参数

-d

在后台运行。没有这个参数的话进程会在前台执行。

-R

做一个在线的重启。这个意思是连接到正在运行的进程上，从里面装载打开的 socket 并且使用这些 socket 继续运行。

-v

增加输出信息的冗长度。

-V

显示版本。

-h

显示简短的帮助。

 管理员终端

通过连接到标准的 listen_addr/listen_port 并且声明 pgbouncer 为连接数据库，那么可以使用管理控制台。

  $ psql -h 127.0.0.1 -p 6543 pgbouncer

只有在配置参数 admin_users 或者 stats_users 才允许连接到控制台。

另外，如果连接通过 UNIX socket，并且客户端和正在运行的进程有着一样的 UNIX 用户 uid 的话，允许通过 pgbouncer 用户无密码登录。

 SHOW 命令

SHOW 命令输出一些数据行，所包含的字段在下面描述。

SHOW STATS;

显示统计。

database

统计是根据每个数据库分比例的。

total_requests

pgbouncer 连接池处理的 SQL 请求的总数。

total_received

pgbouncer 接收到的网络流量的总字节数。

total_sent

pgbouncer 发出的网络流量的总字节数。

total_query_time

pgbouncer 活跃在与 PostgreSQL 上面的时间开销总数，单位是毫秒。

avg_req

在最后一次统计过程中的每秒平均请求数。

avg_recv

每秒（从客户端）接收到的平均数据量。

avg_sent

每秒发送（给客户端）的平均数据量。

avg_query

平均的查询时间，单位是毫秒。

SHOW SERVERS;

type

S, 表示服务器。

user

pgbouncer 用于连接服务器的用户名。

database

服务器端的数据库名。

state

pgbouncer 服务器连接的状态，active，used 或者 idle 之一。

addr

PostgreSQL 服务器的 IP 地址。

port

PostgreSQL 服务器的端口。

local_addr

本地机器上的发起连接地址。

local_port

本地机器上的发起连接端口。

connect_time

连接建立的时间。

request_time

请求发出的时间。

ptr

这个连接的内部对象地址。用做唯一 ID。

link

这个服务器对应的客户端地址。

SHOW CLIENTS;

type

C，表示客户端。

user

客户端连接的用户。

database

数据库名。

state

客户端连接的状态，active，used，waiting或者idle之一。

addr

客户端的 IP 地址。

port

客户端连接去的端口。

local_addr

本地机器上连接到的对端地址。

local_port

本地机器上的连接到的对端端口。

connect_time

最后的客户端连接的时间戳。

request_time

最后的客户端请求的时间戳。

ptr

这个连接的内部对象的地址。用做唯一 ID。

link

这个客户端连接对应的服务器的地址。

 SHOW POOLS;

为每一对（数据库,用户）都会保留一条新的连接池记录。

database

数据库名。

user

用户名。

cl_active

当前 active (活跃)的客户端连接的个数。

cl_waiting

当前 waiting (等待)的客户端连接个数。

sv_active

当前 active (活跃)的服务器连接个数。

sv_idle

当前 idle (空闲) 的服务器连接个数。

sv_used

当前 used (在使用)的服务器连接个数。

sv_tested

当前 tested (测试过)的服务器连接个数。

sv_login

当前 login (登录)到 PostgreSQL 服务器的个数。

maxwait

队列中第一个（最老的那个）客户端等待的时间长度，单位是秒。如果这个数值开始上升，那么就意味着当前的连接池中的服务器处理请求的速度不够快。原因可能是服务器过载，也可能只是 pool_size 太小。

SHOW LISTS;

显示下列内部信息，分字段显示（不是按行显示）：

databases

数据库的个数。

users

用户的个数。

pools

连接池的个数。

free_clients

空闲客户端的个数。

used_clients

已用的客户端的个数。

login_clients

处于已登录状态的客户端个数。

free_servers

空闲服务器个数。

used_servers

已用服务器个数。

 SHOW USERS;

每行显示一个用户，字段明是 name。

 SHOW DATABASES;

name

已配置的数据库名字记录。

host

pgbouncer 连接到的主机名。

port

pgbouncer 连接到的端口号。

database

pgbouncer 实际连接的数据库名。

force_user

当用户是连接字串的一部分的时候，在 pgbouncer 和 PostgreSQL 之间的连接会强制成给出的用户，不管 client user 是什么。

pool_size

最大的服务器端连接数目。

 SHOW FDS;

显示正在使用的 fd 列表。如果连接的用户的用户名是 "pgbouncer"，那么通过 unix socket 连接，并且和运行的进程有同样的 UID，实际的 fd 列表是通过这个连接传递的。这个机制用于做在线重启。

fd

文件描述符的数字值。

task

pooler，client 或 server 之一。

user

使用该 FD 的连接用户。

database

使用该 FD 的连接的数据库。

addr

使用该 FD 的连接的 IP 地址，如果使用的是 unix socket，就是 unix。

port

使用该 FD 的连接的端口号。

cancel

这个连接的取消键字。

link

对应的服务器/客户端的 fd。如果为 idle （空闲）则为 NULL。

SHOW CONFIG;

显示当前配置设置，一个配置一行，字段如下：

key

配置变量名称

value

配置值

changeable

yes 或 no，显示这个变量是否可以在运行时修改。如果为 no，那么这个变量只能在启动的时候修改。

进程控制命令

PAUSE;

PgBouncer 尝试从所有服务器断开，首先会等待所有查询结束。这个命令在所有查询完成之前不会返回。

 SUSPEND;

所有 socket 的缓冲区都冲刷出去，然后 PgBouncer 停止在上面的监听。这条命令在所有 socket 冲刷完毕之前不会返回。

 RESUME;

从前面的 PAUSE 或者 SUSPEND 命令上头重新开始工作。

 SHUTDOWN;

PgBouncer 进程将会退出。

RELOAD;

PgBouncer 进程将会重载它的配置文件然后更新可修改的设置。

SIGNALS

SIGHUP

重载 config。和在控制台上发出 RELOAD 命令一样。

SIGINT

安全关闭。和在控制台上发出 PAUSE; 然后 SHUTDOWN; 一样。

SIGTERM

立即关闭。和在控制台上发出 SHUTDOWN; 是一样的。

LIBEVENT 设置

来自 libevent 文档：

我们可以关闭 epoll，kqueue，devpoll，poll 或者 select 的支持，方法是设置分别环境变量 EVENT_NOEPOLL，EVENT_NOKQUEUE，EVENT_NODEVPOLL，EVENT_NOPOLL 或者 EVENT_NOSELECT。

通过设置环境变量 EVENT_SHOW_METHOD，libevent 显示它使用的内核通知方法。

 认证文件格式

PgBouncer 需要它自己的用户数据库。用户从文本文件中装载，格式应该和 PostgreSQL 的 pg_auth/pg_pwd 文件一样。

"username1" "password" ... "username2" "md12342345234" ...

至少需要有两个字段，用双引号包围。首先是用户名，第二个是明文或者是 md5 散列后的口令。PgBouncer 忽略改行剩余的部分。

这样的文件格式允许指引 PgBouncer 直接到 PostgreSQL 数据目录的用户文件。