2nd/10_Wiki/Topics/Domain_Programming/Coding/DB_Connection_Pool.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
db-connection-pool	DB Connection Pool — 사이즈와 누수	Coding	draft	B	conceptual	2026-05-09	2026-05-09	database connection-pool postgres vibe-coding	language applicable_to Postgres / pgbouncer / Prisma Backend		pool size max_connections pgbouncer transaction mode

DB Connection Pool

"pool size = CPU 코어수 × 2" 가 좋은 출발점. 수백으로 키우면 DB 가 죽는다. 누수 패턴(connection 안 반환)이 throughput 폭발 원인의 90%.

📖 핵심 개념

• DB 한 connection = 메모리 ~10MB (Postgres) + 한 backend process. 수천이면 OOM.
• App pool 사이즈 vs DB max_connections 균형.
• 분산 환경: pgbouncer / RDS Proxy 로 multiplex.

💻 코드 패턴

node-postgres 기본

import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 20,                  // pool size
  idleTimeoutMillis: 30_000,// idle 30s 후 닫음
  connectionTimeoutMillis: 5_000, // pool 가득이면 5s 대기 후 throw
  statement_timeout: 30_000, // 쿼리 자체 30s
});

export async function withTx<T>(op: (c: Client) => Promise<T>): Promise<T> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    const r = await op(client);
    await client.query('COMMIT');
    return r;
  } catch (e) {
    await client.query('ROLLBACK');
    throw e;
  } finally {
    client.release(); // 누수 방지
  }
}

Pool size 계산

pool_size = ((core_count * 2) + effective_spindle_count)
// 8코어 SSD: 16~20

HikariCP / pg / mysql2 모두 비슷한 휴리스틱.

pgbouncer transaction mode

[databases]
mydb = host=postgres dbname=mydb pool_size=100

[pgbouncer]
pool_mode = transaction   # 트랜잭션 끝나면 즉시 반환
default_pool_size = 25    # backend 1개당 25 connection
max_client_conn = 1000    # 클라이언트 측 1000 가능

client 1000개 → backend 25개. 단 LISTEN/NOTIFY, prepared statement 일부 호환 X.

누수 감지

pool.on('connect', () => log.debug('connect'));
pool.on('remove', () => log.debug('remove'));

setInterval(() => {
  log.info('pool stats', { total: pool.totalCount, idle: pool.idleCount, waiting: pool.waitingCount });
}, 10_000);

waitingCount > 0 이 지속되면 pool 부족 또는 누수.

🤔 의사결정 기준

환경	설정
단일 인스턴스 + 가벼운 트래픽	max=20, no pgbouncer
다중 인스턴스 / 서버리스	pgbouncer transaction mode 또는 RDS Proxy
Lambda / Edge	RDS Proxy 또는 Hyperdrive — 매 cold start 새 connection 안 만들기
Long-running job	별도 pool / 별도 user (격리)
Read replica 사용	읽기/쓰기 분리 pool

❌ 안티패턴

• release() 누락: 매 요청 connection 누수 → 곧 모두 점유 → 새 요청 timeout. try/finally.
• 트랜잭션 안에서 외부 API 호출: connection 묶임. 외부 latency = pool 점유 시간. API 먼저, 그 후 트랜잭션.
• pool size 1000: DB 다운. 코어수 × 2~4 권장.
• prepared statement 캐시 + pgbouncer transaction mode: 다른 connection 으로 가서 statement 못 찾음. session mode 또는 disable cache.
• idleTimeout 너무 김: 사용 안 하는 connection 점유.
• statement_timeout 미설정: 한 슬로우 쿼리가 connection 영구 점유.
• connection 재시도 무한: DB 다운 시 폭주.

🤖 LLM 활용 힌트

• pool size = 코어수 × 2 출발.
• 트랜잭션은 withTx wrapper 패턴 + finally release.
• pgbouncer 면 prepared statement 정책 확인.

🔗 관련 문서

• DB_Migration_Safety
• DB_Transaction_Isolation