PostgreSQL 연결 풀링: PgBouncer 설정과 튜닝

개요

PostgreSQL을 운영할 때 동시 연결이 늘어나면 성능 저하와 리소스 낭비가 발생한다. PgBouncer는 가볍고 효율적인 연결 풀러로, 클라이언트와 데이터베이스 사이에 연결을 재사용하여 오버헤드를 줄인다. 이 글에서는 postgres 연결 풀링 pgbouncer 개념, 기본 설정, pgbouncer 설정 예제와 pgbouncer 튜닝 가이드까지 실무 중심으로 설명한다.

PgBouncer 핵심 개념

풀링 모드

• session: 클라이언트 세션 전체를 하나의 서버 연결에 매핑. 가장 안전하지만 연결 수가 높아짐.
• transaction: 각 트랜잭션 단위로 서버 연결을 할당. 대부분의 웹서비스에 적합.
• statement: 개별 쿼리 단위로 연결을 사용. 제약이 많아 권장되지 않음.

주요 장점

• 빠른 연결 처리와 낮은 메모리 사용.
• 데이터베이스 서버의 연결 수 제한 회피.
• 간단한 설정으로 가용성 향상.

설치와 기본 설정

리눅스 배포판에서 패키지로 설치하거나 소스 컴파일로 설치할 수 있다. 설치 후 가장 중요한 파일은 pgbouncer.ini와 userlist.txt(또는 auth_query를 사용하는 경우 DB 인증 설정)이다.

기본 pgbouncer.ini 예제

[databases]
mydb = host=127.0.0.1 port=5432 dbname=mydb

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = md5
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 50
reserve_pool_size = 10
reserve_pool_timeout = 5
server_reset_query = DISCARD ALL
server_check_query = SELECT 1
logfile = /var/log/pgbouncer/pgbouncer.log
pidfile = /var/run/pgbouncer/pgbouncer.pid

위 예제에서 pool_mode는 서비스 특성에 맞게 선택한다. default_pool_size는 각 DB당 유지할 서버 연결 수를 의미한다.

userlist.txt 예제

"pguser" "md5c9d5e0a1e6f3f4b2a5d..."

성능 튜닝 포인트

성능 튜닝은 워크로드 특성과 인프라를 고려해야 한다. 다음 항목을 우선 점검한다.

1. max_client_conn

PgBouncer에 허용할 최대 클라이언트 수. 너무 낮으면 클라이언트가 대기하고, 너무 높으면 메모리 과다 사용으로 이어진다. 애플리케이션의 동시 연결 패턴을 측정해 적절히 설정한다.

2. default_pool_size 와 reserve_pool_size

default_pool_size는 각 데이터베이스와 사용자 조합당 기본 서버 연결 수다. OLTP 환경이면 비교적 작게 시작하고, 필요시 늘린다. burst를 흡수하기 위해 reserve_pool_size를 사용하면 짧은 피크를 견딜 수 있다.

3. server_lifetime, server_idle_timeout

• server_lifetime: 서버 연결을 재시작할 최대 시간. 장시간 재사용으로 인해 상태가 꼬일 수 있으므로 적절히 제한.
• server_idle_timeout: 유휴 서버 연결을 닫는 시간. 불필요한 커넥션을 줄이는 데 도움.

4. 서버 리소스 고려

PgBouncer는 가볍지만, 많은 수의 서버 연결을 유지하면 PostgreSQL 측 메모리와 프로세스 수가 증가한다. 서버 메트릭과 connection_limit를 같이 조정한다.

모니터링과 운영 체크리스트

• 로그 주기적 확인: 연결 거부, timeout, auth 오류 등을 확인.
• SHOW POOLS; SHOW CLIENTS; SHOW SERVERS; 명령으로 풀 상태 점검.
• Prometheus Exporter 연동으로 지표 수집 및 알람 설정.
• 버전 업그레이드 전 호환성 확인: pool_mode와 서버 쿼리 초기화 동작 차이.

문제 해결 사례

연결이 모자랄 때

에러 로그에 "no more connections" 메시지가 나오면 default_pool_size 또는 max_client_conn 증가를 검토한다. 그러나 무작정 늘리면 DB 서버가 부담을 겪으므로 단계적으로 조정한다.

트랜잭션 롱 러닝으로 인한 블로킹

transaction 모드에서 장시간 트랜잭션이 발생하면 풀을 고갈시킬 수 있다. 애플리케이션 쪽에서 트랜잭션 길이 단축이나 statement 모드 재검토가 필요하다.

운영 팁과 권장 설정 흐름

• 1) 트래픽 패턴을 측정해 초기값 설정(default_pool_size, max_client_conn).
• 2) transaction 모드로 시작해 문제 발생 시 session 모드 고려.
• 3) 모니터링 지표로 서버 연결과 큐 시간을 관찰하며 reserve_pool 조정.
• 4) 장애 시 로그와 SHOW 명령으로 원인 파악.

맺음말

PgBouncer는 postgres 연결 풀링 pgbouncer 적용 시 서버 자원 효율을 크게 개선한다. pgbouncer 설정 예제와 pgbouncer 튜닝 가이드를 통해 기본 구조를 이해하고, 실제 운영에서 모니터링을 바탕으로 점진적으로 조정하면 안정적인 성능 개선을 얻을 수 있다.