PGBouncer介绍及使用方式

  1. 什么是pgbouncer
  PGBouncer是一个轻量级的针对PostgreSQL的数据库连接池工具，能够给客户端提供一个统一的链接视图。

  PgBouncer的作用
    a.PgBouncer可以在后端数据库和前端应用间建立连接的桥梁，由PgBouncer去处理和后端数据库的连接关系。
    b.对客户端连接进行限制，预防过多或者恶意的连接请求。

  PgBouncer的特点
    a.内存消耗低(默认为2k/连接)，因为Bouncer不需要每次都接受完整的数据包
    b.可以把不同的数据库连接到一个机器上，而对客户端保持透明
    c.支持在线的重新配置而无须重启
    d.仅支持V3协议，因此后端版本须>=7.4 (引自 pgsqldb中文站)

  2.如何安装
    我是在Ubuntu上安装的pgbouncer，很简单，通过apt-get install的方式就可以顺利的安装上了。安装完成后可以用dpkg -L "pgbouncer" 看到该pkg所包含的文件列表。

1. xuepeng @ first : ~ >
2. $ dpkg -L "pgbouncer"
3. /.
4. /usr
5. /usr/share
6. /usr/share/man
7. /usr/share/man/man1
8. /usr/share/man/man1/pgbouncer.1.gz
9. /usr/share/man/man5
10. /usr/share/man/man5/pgbouncer.5.gz
11. /usr/share/man/man8
12. /usr/share/man/man8/pgbouncer.8.gz
13. /usr/share/doc
14. /usr/share/doc/pgbouncer
15. /usr/share/doc/pgbouncer/README
16. /usr/share/doc/pgbouncer/AUTHORS
17. /usr/share/doc/pgbouncer/pgbouncer.ini.example.gz
18. /usr/share/doc/pgbouncer/README.Debian
19. /usr/share/doc/pgbouncer/copyright
20. /usr/share/doc/pgbouncer/NEWS.gz
21. /usr/share/doc/pgbouncer/changelog.Debian.gz
22. /usr/sbin
23. /usr/sbin/pgbouncer
24. /etc
25. /etc/default
26. /etc/default/pgbouncer
27. /etc/init.d
28. /etc/init.d/pgbouncer
29. /etc/pgbouncer.ini

    man和doc的路径我们就不关注了，是pgbouncer的帮助和说明文件，使用man就可以看到了。运行是用到的只是/usr/sbin/pgbouncer和/etc/pgbouncer.ini两个文件。/etc/init.d/pgbouncer是OS启动时用的，先不考虑了。

   3. 如何配置
    man 5 pgbouncer可以看到manaul中提供的一个最小配置的例子如下：

1.            [databases]
2.            pg_template1 = host=127.0.0.1 dbname=template1
4.            [pgbouncer]
5.            pool_mode = session
6.            listen_port = 6543
7.            listen_addr = 127.0.0.1
8.            auth_type = md5
9.            auth_file = users.txt
10.            logfile = pgbouncer.log
11.            pidfile = pgbouncer.pid
12.            admin_users = someuser
13.            stats_users = stat_collector

    上面的配置说明了该pgbouncer创建了针对127.0.0.1上的template1的一个连接池，该连接池对调用方的呈现的数据库名称是pg_template1,它映射到了template1上。所有访问pbbouncer上的pg_template1的请求都会转到template1上完成。

    pool_mode 指明了连接池的模型，pgbouncer目前支持三种连接池模型。分别是session, transaction和statment三个级别。
    a. session. 会话级链接。只有与当客户端的会话结束时，pgbouncer才会收回已分配的链接
    b. transaction 事务级连接。当事务完成后，pgbouncer会回收已分配的链接。也就是说客户端只是在事务中才能独占此链接，非事务的对数据库的请求是没有独享的链接的。
    c. statement 语句级链接。任何对数据库的请求完成后，pgbouncer都会回收链接。此种模式下，客户端不能使用事务，否则会造成数据的不一致。
    pgbouncer的默认设置是session链接。

    listen_port和listen_addr是pgbouncer监听的地址和端口号。

    auth_type和auth_file是bppgbouncer用以完成客户端身份认证。auth_file中保存用户名和密码，根据验证方式(auth_type)的不同，auth_file的内容也有不同。
    md5: 基于md5的密码验证，auth_file中需要有普通文本和md5值两种形式的密码；
    crypt: 基于crypt的密码验证(man 3 crypt), auth_file必须包含文本密码；
    plain: 明文验证方式；
    trust: 不进行验证，但auth_file依然需要保存用户名；
    any: 也不进行验证，而且auth_file中不需要保存用户名了。但此种方式需要在 pg_template1中明确说明用户名进行真实数据库的登录。如: pg_template1 = host=127.0.0.1 user=exampleuser dbname=template1.否则会报错的。

    需要说明的是： auth_file中的用户名、密码都必须使用双引号，否则还是报错。
   
    logfile和pidfile分别保存log文件和pid文件的路径。
   
    admin_users：列出哪些用户可以登录pgbouncer进行管理，以逗号进行分隔
    stats_users：列出哪些用户可以登录pgbouncer进行只读操作，如可以列出服务器状态，访问链接等，但是不能执行reload。

    4. 配置实例
      了解了上述几个关键的配置项后，我们进行一个简单的配置实例的练习。
      假想场景如下：我们有两个PostgreSQL的DB，名称分别为main和pgD1，上面各有一个名称为xuepeng的DB，现在需要通过pgbouncer把两个DB管理起来。使得客户端可以通过
         psql -h 127.0.0.1 -p 6000 -U xuepeng main_xuepeng
         psql -h 127.0.0.1 -p 6000 -U xuepeng pgD1_xuepeng
      访问不同的真实DB. (由于这些程序都是在一台机子上运行，因此ip都是127.0.0.1, 有关如何在一台机器上配置不同的PostgreSQL实例，请看 在一台机器上运行多个PostgreSQL实例)

      首先修改pgbouncer.ini中的[databases]块，增加下面两行内容：

1. main_xuepeng = host=127.0.0.1 port=5432 dbname=xuepeng
2. pgD1_xuepeng = host=127.0.0.1 port=5433 dbname=xuepeng

      这样就表明main_xuepeng 是端口为5432的映射，pgD1_xuepeng是端口为5433的映射。

      然后修改auth_type的值为trust.(因为是本机测试用，就不使用验证了，生产环境不建议这么做。)
      接着创建/tmp/users.txt文件，并写入以下内容：

1. "admin" "password"
2. "readonly" "password"
3. "xuepeng" "password"

      修改auth_file的值为/tmp/users.txt, admin_users的值为admin, stats_users的值为readonly.
      这样我们就完成了最简单版的配置，其它的参数暂不做调整。

    5. 启动运行
      启动pgbouncer: pgbouncer -v /etc/pgbouncer.ini
      初次使用以及检查问题时建议使用-v参数，该参数能使pgbouncer打出较详细的log，便于定位问题。实际使用时用-d参数，表明以后台程序的方式运行。
     连接main_xuepeng: psql -h 127.0.0.1 -p 6000 -U xuepeng main_xuepeng
     这时候就可以进入端口号为5432的PostgreSQL的db了。同样，使用 psql -h 127.0.0.1 -p 6000 -U xuepeng pdD1_xuepeng可以进入端口号为5433的PostgreSQL的DB实例。

   6. 如何管理pgbouncer
      pgbouncer其实有一个虚拟的db存在，名称就是“pgbouncer”，如果我们执行
      pgsql -h 127.0.0.1 -p 6000 -U admin pgbouncer
      就会进入到管理的终端。-U后面是用户名， “pgbouncer” 就是登录的db名称，当发现是这个名称时，pgbouncer认为用户是要对pgbouncer本身进行管理，就不会把去请求真实的DB了。

      通过admin登录后，show help就能看到能够进行的操作，如下：

1. pgbouncer=# show help;
2. NOTICE:  Console usage
3. DETAIL:
4.         SHOW [HELP|CONFIG|DATABASES|FDS|POOLS|CLIENTS|SERVERS|SOCKETS|LISTS|VERSION]
5.         SET key = arg
6.         RELOAD
7.         PAUSE
8.         SUSPEND
9.         RESUME
10.         SHUTDOWN
11. SHOW
12. pgbouncer=#

      能够用show命名列出当前的各种状态信息，也能够执行reload，重新读取配置文件的内容(该命令能够在配置文件改动后，不需要重启程序就能使配置项生效).

     如果是通过 pgsql -h 127.0.0.1 -p 6000 -U readonly pgbouncer 方式登录，在执行reload时就会提示“ERROR:  admin access needed”的错误信息了。

   7. 如何停止
     以admin登录pgbouncer, 执行shutdown即可。

    初次使用时，建议使用-v参数，并关注pgbouncer的log输入，能发现不少有意思的东西 :)


   8. 参考
     http://pgbouncer.projects.postgresql.org/doc/config.html
     https://developer.skype.com/SkypeGarage/DbProjects/PgBouncer