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'

配置说明

几乎所有pgbouncer.ini中的设置都可通过环境变量定义（除端口、syslog、pid等Docker环境中意义不大的设置）。详情见入口脚本。示例：

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集成

示例配置见examples/docker-compose文件夹。

Kubernetes集成

示例配置见examples/kubernetes文件夹。

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>"

使用examples/generate-userlist生成该文件：

sh
examples/generate-userlist >> userlist.txt

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

连接管理控制台

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

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

支持执行多种管理控制台命令，例如：

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

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

sql
PAUSE;
RESUME;