edoburu/pgbouncer

PgBouncer Docker镜像

概述

这是一个基于Alpine Linux的轻量级PgBouncer镜像，用于提供PostgreSQL连接池功能。PgBouncer作为应用与PostgreSQL数据库之间的中间层，可有效减少数据库连接的内存占用和启动成本，尤其适合需要优化数据库连接性能的Web应用场景。

核心功能与特性

• 超小体积：镜像大小小于10MB，拉取速度快
• 环境变量配置：支持通过环境变量轻松配置，无需手动修改配置文件
• 标准端口：使用PostgreSQL标准端口5432，对应用透明兼容
• 内置客户端工具：包含psql、pg_isready等PostgreSQL客户端工具
• 默认MD5认证：默认启用MD5认证，提升连接安全性
• 自动配置文件：若/etc/pgbouncer/pgbouncer.ini和/etc/pgbouncer/userlist.txt不存在，将自动创建

为什么使用PgBouncer

PostgreSQL连接会占用较多内存（约10MB/连接），且TLS连接建立存在显著的启动成本。Web应用通过使用持久连接可提升性能，但直接与数据库建立大量持久连接会消耗过多资源。

通过在Web应用与PostgreSQL数据库之间部署PgBouncer，可有效降低内存和启动成本：Web应用保持与PgBouncer的持久连接，而PgBouncer仅维持少量与实际PostgreSQL服务器的连接，并可复用这些连接供多个客户端使用。

可用标签

基础镜像标签：

• latest - 默认最新版本
• 1.X.Y-pZ - 特定分支版本

使用方法

基础运行命令

使用DATABASE_URL环境变量：

sh
docker run --rm \
    -e DATABASE_URL="postgres://user:pass@postgres-host/database" \
    -p 5432:5432 \
    edoburu/pgbouncer

或使用单独的环境变量：

sh
docker run --rm \
    -e DB_USER=user \
    -e DB_PASSWORD=pass \
    -e DB_HOST=postgres-host \
    -e DB_NAME=database \
    -p 5432:5432 \
    edoburu/pgbouncer

连接测试：

sh
psql 'postgresql://user:pass@localhost/dbname'

配置说明

几乎所有https://pgbouncer.github.io/config.html%E4%B8%AD%E7%9A%84%E8%AE%BE%E7%BD%AE%E9%83%BD%E5%8F%AF%E9%80%9A%E8%BF%87%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E5%AE%9A%E4%B9%89%EF%BC%88%E9%99%A4%E7%AB%AF%E5%8F%A3%E3%80%81syslog%E3%80%81pid%E7%AD%89Docker%E7%8E%AF%E5%A2%83%E4%B8%AD%E6%84%8F%E4%B9%89%E4%B8%8D%E5%A4%A7%E7%9A%84%E8%AE%BE%E7%BD%AE%EF%BC%89%E3%80%82%E8%AF%A6%E6%83%85%E8%A7%81https://github.com/edoburu/docker-pgbouncer/blob/master/entrypoint.sh%E3%80%82%E7%A4%BA%E4%BE%8B%EF%BC%9A

sh
docker run --rm \
    -e DATABASE_URL="postgres://user:pass@postgres-host/database" \
    -e POOL_MODE=session \
    -e SERVER_RESET_QUERY="DISCARD ALL" \
    -e MAX_CLIENT_CONN=100 \
    -p 5432:5432 \
    edoburu/pgbouncer

Docker Compose集成

示例配置见https://github.com/edoburu/docker-pgbouncer/tree/master/examples/docker-compose%E3%80%82

Kubernetes集成

示例配置见https://github.com/edoburu/docker-pgbouncer/tree/master/examples/kubernetes%E3%80%82

PostgreSQL配置

确保PostgreSQL接受来自PgBouncer所在机器的连接：

1. 更新postgresql.conf中的listen_addresses
2. 在pg_hba.conf中允许指定IP范围的连接（如10.0.0.0/8）：

conf
# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             10.0.0.0/8              md5

自定义配置

当默认pgbouncer.ini不满足需求，或需多用户通过单个PgBouncer实例连接时，可挂载自定义配置：

sh
docker run --rm \
    -e DB_USER=user \
    -e DB_PASSWORD=pass \
    -e DB_HOST=postgres-host \
    -e DB_NAME=database \
    -v pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini:ro \
    -p 5432:5432 \
    edoburu/pgbouncer

或扩展Dockerfile：

Dockerfile
FROM edoburu/pgbouncer:1.11.0
COPY pgbouncer.ini userlist.txt /etc/pgbouncer/

当pgbouncer.ini存在时，启动脚本不会覆盖它。若DATABASE_URL包含凭据或定义了DB_USER和DB_PASSWORD，会向userlist.txt添加额外条目。

userlist.txt格式：

txt
"username" "plaintext-password"

或

txt
"username" "md5<md5 of password + username>"

使用https://github.com/edoburu/docker-pgbouncer/blob/master/examples/generate-userlist%E7%94%9F%E6%88%90%E8%AF%A5%E6%96%87%E4%BB%B6%EF%BC%9A

sh
examples/generate-userlist >> userlist.txt

也可通过设置AUTH_USER，让单个用户连接PgBouncer并获取实际数据库密码，详见：<[***]>

连接管理控制台

当定义了管理员用户且userlist.txt中存在其密码时，可连接到特殊的pgbouncer数据库：

sh
psql postgres://postgres@容器主机名/pgbouncer  # 容器外
psql postgres://127.0.0.1/pgbouncer            # 容器内

支持执行多种https://pgbouncer.github.io/usage.html#admin-console%EF%BC%8C%E4%BE%8B%E5%A6%82%EF%BC%9A

sql
SHOW STATS;
SHOW SERVERS;
SHOW CLIENTS;
SHOW POOLS;

还可临时断开后端数据库（如重启时），同时保持Web应用与PgBouncer的连接：

sql
PAUSE;
RESUME;