본문으로 건너뛰기

pg_auto_failover

pg_auto_failover는 PostgreSQL에 자동 failover 기능을 더하는 도구입니다. etcd 같은 분산 합의 저장소를 사용하지 않습니다. 대신 monitor라는 PostgreSQL 인스턴스 하나가 witness와 orchestrator 역할을 함께 맡습니다. 각 노드의 keeper(pg_autoctl)는 monitor가 정한 목표 상태에 따라 로컬 PostgreSQL을 제어합니다. 이 노트는 v2.2(2025-04 릴리스) 공식 문서와 소스를 기준으로 구조를 설명합니다. Docker로 monitor와 노드 세 대를 실행해 장애를 직접 발생시켰습니다. 장애 처리에 걸린 시간과 로그도 기록했습니다.

이 노트가 답하려는 질문은 두 가지입니다. primary가 죽었을 때 pg_auto_failover는 왜 50초 가까이 기다리는지, 그리고 그 대기를 줄이면 무엇을 잃는지입니다. 처음 읽는다면 Part I → II → VII 순서를 권장합니다.

3분 요약​

  • 구성 요소는 monitor 하나와 각 데이터 노드에서 실행되는 keeper입니다. pgautofailover extension은 monitor의 PostgreSQL에만 설치합니다.
  • monitor는 노드마다 현재 상태와 목표 상태를 관리하는 상태 머신입니다. keeper는 1초마다 monitor의 node_active()를 호출해 목표 상태를 받습니다.
  • 기본 복제 방식은 synchronous replication입니다. number_sync_standbys가 0인 구성은 2노드의 기본값입니다. 이 구성에서 건강한 quorum standby가 하나도 없으면 monitor는 primary를 wait_primary로 바꿉니다. 이 상태에서는 동기 복제를 끄며 자동 failover도 수행하지 않습니다. number_sync_standbys가 1 이상이면 동기 복제를 끄지 않습니다. 따라서 quorum이 부족하면 쓰기가 멈춥니다.
  • 이 노트의 실습에서 primary를 kill한 뒤 새 primary에 다시 쓸 수 있기까지 2노드는 51초, 3노드는 54초가 걸렸습니다. 이 가운데 30초는 기존 primary가 스스로 멈출 시간을 확보하는 primary_demote_timeout입니다.
  • 대기 시간을 10초와 15초로 줄이자 쓰기 공백은 26초로 줄었습니다. 대신 비대칭 네트워크 분리 실험에서는 두 노드가 11초 동안 동시에 쓰기를 받았습니다.
  • monitor만 멈추고 데이터 노드끼리 복제를 유지하면 쓰기는 계속됩니다. failover, maintenance, 설정 변경은 멈춥니다. monitor와 standby의 연결을 함께 잃으면 primary keeper는 network_partition_timeout이 지난 뒤 PostgreSQL을 스스로 멈춥니다. monitor는 데이터 경로가 아니라 control plane의 단일 장애점입니다.
  • 2026-09 기준 최신 릴리스는 v2.2이고 지원 PostgreSQL은 13~17입니다. main 브랜치에는 2026-07 이후 PostgreSQL 18/19 지원과 split brain 관련 수정이 반영됐지만 아직 릴리스되지 않았습니다.

난이도별 학습 경로​

단계먼저 읽을 Part도달 목표
입문I → IImonitor와 keeper의 역할을 이해하고 로컬에서 2노드를 실행해 switchover를 해 본다
중급III → V → VI상태 머신 전이를 로그로 읽고 복제 설정과 운영 명령을 설계한다
운영VII → VIII → IX장애별 쓰기 공백과 데이터 보장을 설명하고 라우팅, 보안, 백업을 구성한다
정리X한계와 선택 기준을 정리하고 명령을 치트시트로 복습한다

전체 차례​

실습 프로젝트​

pg-auto-failover-lab은 공식 postgres:17 이미지에 PGDG 패키지를 설치한 Docker Compose 구성입니다. monitor 1대와 PostgreSQL 노드 2대, 측정용 클라이언트 1대를 실행합니다. 선택하면 PostgreSQL 노드를 3대로 구성할 수 있습니다.

cd pg-auto-failover-lab
docker compose build
docker compose up -d monitor app
docker compose up -d node1 node2
./scripts/wait-state.sh node2 secondary 300
./scripts/state.sh

기준과 범위​

  • pg_auto_failover: PGDG 패키지 pg-auto-failover-cli 2.2-4.pgdg13+1, monitor extension 2.2
  • PostgreSQL: 17.11 (Debian 13 기반 postgres:17 이미지)
  • 공식 문서: v2.2 태그의 docs/*.rst를 기준으로 삼았습니다. readthedocs의 main 문서는 2026-07 이후 크게 변경된 main 브랜치를 기준으로 합니다. 따라서 v2.2와 다른 부분이 있으며, 차이는 본문에 적었습니다.
  • 실측 환경: Apple Silicon macOS, Docker VM 2 vCPU 12 GB. 절대값보다 각 구간의 구성과 순서에 의미를 둡니다.
  • 범위 밖: Citus formation 운영, Azure 연동, 소스 빌드

표기 규약​

  • 본문 산문에는 PostgreSQL, pg_auto_failover라는 전체 이름을 씁니다. 명령은 pg_autoctl입니다.
  • failover, switchover, primary, standby, secondary, monitor, keeper, WAL, checkpoint, replication slot, quorum 같은 용어는 번역하지 않습니다.
  • 상태 이름(wait_primary, demote_timeout 등)은 소문자 코드 표기로 씁니다.
  • 모든 도식은 Mermaid입니다.

주요 공식 자료​

관련 영역​