PgBouncer는 PostgreSQL을 위한 경량 커넥션 풀러다. 애플리케이션과 PostgreSQL 사이에 위치하여 데이터베이스 연결 수를 줄이고, 연결 오버헤드를 최소화한다.
커넥션 풀링 모드
| 모드 | 방식 | 트랜잭션 지원 | 적합 사례 |
|---|
| Session | 세션 동안 연결 유지 | 전체 지원 | 기본, LISTEN/NOTIFY 사용 시 |
| Transaction | 트랜잭션 동안만 연결 | 지원 | 대부분 웹 앱 (권장) |
| Statement | 문장 단위로 연결 반환 | 불가 | 단순 읽기 전용 |
설치 및 설정
ini
# /etc/pgbouncer/pgbouncer.ini
[databases]
# 데이터베이스 별칭 설정
blog = host=localhost port=5432 dbname=blog
blog_ro = host=replica-host port=5432 dbname=blog
[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = md5
auth_file = /etc/pgbouncer/userlist.txt
# 풀 모드 (권장: transaction)
pool_mode = transaction
# 연결 제한
max_client_conn = 1000 # 클라이언트 최대 연결
default_pool_size = 20 # DB당 실제 연결 수
min_pool_size = 5 # 최소 유지 연결
reserve_pool_size = 5 # 폭증 시 예비 연결
reserve_pool_timeout = 5 # 예비 연결 대기 시간(초)
# 연결 수명
max_db_connections = 50 # DB 최대 연결
server_idle_timeout = 600 # 유휴 연결 10분 후 해제
client_idle_timeout = 0 # 클라이언트 제한 없음
# 로그
log_connections = 0
log_disconnections = 0
log_pooler_errors = 1
# Admin 접속
admin_users = pgbouncer_admin
stats_users = pgbouncer_stats
# /etc/pgbouncer/userlist.txt
# "username" "md5hash_or_scram_password"
모니터링
sql
-- PgBouncer 관리 콘솔 접속
-- psql -p 6432 -U pgbouncer_admin pgbouncer
-- 풀 상태
SHOW POOLS;
-- database | user | cl_active | cl_waiting | sv_active | sv_idle | sv_used | maxwait
-- 클라이언트 연결
SHOW CLIENTS;
-- 서버 연결
SHOW SERVERS;
-- 통계
SHOW STATS;
-- total_query_count, total_query_time, avg_query_time ...
-- 연결 재설정 (설정 변경 후)
RELOAD;
-- 특정 DB 연결 일시 정지/재개
PAUSE blog;
RESUME blog;
관련 문서
