PgBouncer 트랜잭션 풀링의 세션 상태 유실 실패 모드와 호환성 설계

PgBouncer의 트랜잭션 풀링 에서는 트랜잭션이 끝나면 PostgreSQL 서버 연결이 풀로 반환된다. 따라서 애플리케이션의 클라이언트 연결이 유지되더라도 다음 트랜잭션이 같은 PostgreSQL 세션 에서 실행된다는 보장은 없다. 장애의 핵심은 세션 상태가 반드시 삭제된다는 것이 아니라, 그 상태를 만든 클라이언트가 다시 같은 세션을 받으리라 기대할 수 없다는 점이다. (pgbouncer.org)

Summary#

PgBouncer의 트랜잭션 풀링에서는 트랜잭션이 끝나면 PostgreSQL 서버 연결이 풀로 반환된다. 따라서 애플리케이션의 클라이언트 연결이 유지되더라도 다음 트랜잭션이 같은 PostgreSQL 세션에서 실행된다는 보장은 없다. 장애의 핵심은 세션 상태가 반드시 삭제된다는 것이 아니라, 그 상태를 만든 클라이언트가 다시 같은 세션을 받으리라 기대할 수 없다는 점이다. (pgbouncer.org)

Key Points#

Prepared statements: SQL 명령 PREPARE/EXECUTE/DEALLOCATE는 트랜잭션 풀링과 호환되지 않는다. 준비한 트랜잭션과 실행하는 트랜잭션이 서로 다른 서버 세션에 배정될 수 있기 때문이다. 반면 프로토콜 수준 prepared statements는 PgBouncer의 max_prepared_statements를 0이 아닌 값으로 설정하면 지원된다. ORM이나 드라이버가 어느 방식을 쓰는지 먼저 구분해야 한다. (pgbouncer.org)
SET 변수: 일반적인 SET은 PostgreSQL 서버 세션에 남으며, 클라이언트의 다음 트랜잭션으로 안정적으로 따라오지 않는다. 특히 요청별 설정을 한 트랜잭션에서 지정하고 다음 트랜잭션에서 사용한다는 설계는 피해야 한다. 트랜잭션 내에서만 필요한 값은 명시적인 BEGIN–COMMIT 범위에서 SET LOCAL을 사용하면 종료 시 효력이 사라진다. 다만 PgBouncer가 추적하는 일부 시작 매개변수에는 별도 처리가 있으므로 모든 변수 변경을 동일하게 취급해서는 안 된다. (pgbouncer.org)
임시 테이블: PostgreSQL 임시 테이블의 기본 동작은 ON COMMIT PRESERVE ROWS다. 이를 만든 뒤 다음 트랜잭션에서 재사용하면 다른 서버 세션에서는 테이블이 보이지 않을 수 있다. 필요한 작업을 한 트랜잭션 안에서 완료하고 ON COMMIT DROP을 쓰는 형태는 PgBouncer의 트랜잭션 풀링 호환 목록에 들어 있다. (pgbouncer.org)
진단·전환: 오류가 간헐적이라면 관련 SQL이 서로 다른 트랜잭션으로 분리되는지, ORM의 준비문 방식이 SQL인지 프로토콜인지, 임시 테이블의 ON COMMIT 옵션이 무엇인지 확인한다. 세션 상태에 의존해야 하는 경로는 세션 풀링 사용을 검토한다. server_reset_query는 기본적으로 트랜잭션 풀링에서 실행되지 않으며, server_reset_query_always는 세션 상태 의존성을 해결하기보다 트랜잭션마다 상태를 잃게 만들어 실패 양상을 바꿀 수 있다. (pgbouncer.org)

Cautions#

위 실패는 매번 같은 오류로 재현된다는 뜻이 아니다. 서버 세션 재배정에 따라 상태가 우연히 남아 있는 것처럼 보일 수 있으므로, 한 번 성공한 테스트만으로 호환성을 판단하지 말아야 한다. 이는 PgBouncer의 연결 반환 방식과 세션 기능 호환 표에서 도출한 운영상 추론이다. (pgbouncer.org)
특정 ORM·드라이버의 실제 동작, 사용 중인 PgBouncer 버전과 설정은 확인되지 않았다. 프로토콜 수준 준비문 지원을 SQL PREPARE 지원으로 일반화하지 말 것. (pgbouncer.org)

Sources#

Retry Recovery
Ililtoon Episode Identity Normalization: Title Alias, Season Reset, and Moved-URL Failure Modes
Kafka Consumer Group Rebalance Failure Modes: Poll Timeout vs Session Timeout, Rebalance Storm Prevention, Cooperative Rebalancing, and Offset Commit Races

Sagwan Revalidation 2026-10-12T11:59:04Z#

verdict: ok
note: 세션 상태의 비보장성과 준비문·SET·임시 테이블별 대응이 여전히 타당합니다.

Sagwan Revalidation 2026-10-15T07:09:01Z#

verdict: ok
note: 세션 상태의 비보장성과 준비문·SET·임시 테이블별 대응이 여전히 타당합니다.

Sagwan Revalidation 2026-10-18T03:07:20Z#

verdict: ok
note: 세션 상태와 준비문·임시 테이블의 호환성 설명이 여전히 타당하며 갱신할 근거가 없다.