본문으로 건너뛰기
Docs
Part XII. 복제와 고가용성
12.7 pg_auto_failover

12.7 pg_auto_failover

pg_auto_failover는 Microsoft Citus 팀이 만든 PostgreSQL HA 도구입니다. 별도 모니터 노드가 leader election과 상태 머신을 관장 — DCS 대신 PostgreSQL 인스턴스 자체를 monitor로 씁니다. Patroni·repmgr 대비 가장 단순한 설정이 강점.

구조 

    flowchart LR
  subgraph M["monitor"]
    MON["pg_auto_failover<br/>state machine"]
  end
  subgraph N1["node 1 (primary)"]
    K1["pg_autoctl"]
    PG1["PostgreSQL"]
  end
  subgraph N2["node 2 (standby)"]
    K2["pg_autoctl"]
    PG2["PostgreSQL"]
  end

  PG1 -- "streaming" --> PG2
  K1 -- "report state" --> MON
  K2 -- "report state" --> MON
  MON -- "promote 명령" --> K1
  MON -- "promote 명령" --> K2

  classDef mon fill:#fed7aa,stroke:#c2410c,color:#7c2d12
  classDef pg fill:#ede9fe,stroke:#6d28d9,color:#3b0764
  classDef ctl fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
  class MON mon
  class PG1,PG2 pg
  class K1,K2 ctl
  • monitor = 별도 PostgreSQL 인스턴스, 클러스터 상태 머신 보관
  • pg_autoctl = 각 데이터 노드의 데몬, monitor와 통신

설치 

sudo dnf install -y pg_auto_failover_17

모니터 구성 

# monitor 노드에서
sudo -u postgres pg_autoctl create monitor \
  --hostname monitor.example.com \
  --pgdata /var/lib/pgsql/17/monitor

sudo systemctl enable --now pgautofailover@monitor

데이터 노드 구성 

# primary
sudo -u postgres pg_autoctl create postgres \
  --monitor 'postgres://autoctl_node@monitor.example.com/pg_auto_failover' \
  --hostname node1.example.com \
  --pgdata /var/lib/pgsql/17/data \
  --name node1 \
  --auth scram-sha-256

# standby (다른 노드에서)
sudo -u postgres pg_autoctl create postgres \
  --monitor 'postgres://...' \
  --hostname node2.example.com \
  --pgdata /var/lib/pgsql/17/data \
  --name node2 \
  --auth scram-sha-256

각 노드에서:

sudo systemctl enable --now pgautofailover

상태 머신

pg_auto_failover의 강점 — 명시적 상태 머신으로 모든 전이를 추적합니다.

single → wait_primary → primary
         secondary → catchingup → primary (failover)
         demoted → catchingup → secondary

각 노드는 자기 상태를 monitor에 보고. monitor가 목표 상태를 지시. 운영자가 어느 단계에서 멈췄는지 즉시 파악합니다.

sudo -u postgres pg_autoctl show state
 Name |   Node |             Host:Port |       LSN | Reachable |    Current State |    Assigned State
------+--------+-----------------------+-----------+-----------+------------------+------------------
node1 |      1 |       node1.example:5432 | 0/3A1F8E0 |       yes |          primary |          primary
node2 |      2 |       node2.example:5432 | 0/3A1F8E0 |       yes |        secondary |        secondary

자동 failover

monitor가 primary 응답 없음 + 일정 시간 → secondary를 promote.

# 명시적 failover
sudo -u postgres pg_autoctl perform failover --formation default

# 명시적 switchover
sudo -u postgres pg_autoctl perform switchover --formation default

동기 vs 비동기

기본은 2-node에서 sync 안 됨 (single secondary는 quorum 불가). PG 14+의 pg_auto_failover 1.6+에서 3-node 동기 quorum 지원합니다.

pg_autoctl create postgres --replication-quorum

quorum 안 되면 fallback 동작은 secondary 우선 — 손실 가능 트레이드오프.

Patroni·repmgr와의 비교

측면Patronirepmgrpg_auto_failover
외부 의존DCS (etcd 등)없음monitor PostgreSQL
설치 복잡도중간중간낮음
상태 가시화DCS 조회repmgr cluster show명시적 상태 머신
멀티 노드 cascading가능가능단순
동기 quorum강력가능1.6+
운영 인기매우 높음안정 운영작지만 증가
k8s 친화매우 좋음약함보통

선택 기준:

  • 새 단순 운영, 학습 시간 줄이기 → pg_auto_failover
  • 큰 운영, 동기 quorum + k8s → Patroni
  • 옛 운영 유지 → repmgr

connection string failover

pg_auto_failover는 클라이언트가 multi-host conninfo를 쓰면 자동 failover 인식합니다.

postgres://app@node1.example.com:5432,node2.example.com:5432/app_main?target_session_attrs=read-write

target_session_attrs=read-write는 읽기·쓰기 가능한 노드만 선택. PG 12+ libpq 기능. HAProxy 없이도 동작합니다.

운영 명령 

# 노드 상태
pg_autoctl show state

# 노드 정보
pg_autoctl show settings

# 모니터로부터 명령 받지 않게 일시 정지
pg_autoctl enable maintenance

# 정상 모드 복귀
pg_autoctl disable maintenance

# 모니터에서 노드 drop
pg_autoctl drop node --name node3

한계

한계메모
monitor가 SPOFmonitor 자체도 HA 필요 (monitor의 stream 백업)
동기 multi-node 약간 약함Patroni가 더 유연
운영 도구 생태계 작음Patroni·repmgr에 비해 자료 적음
k8s 통합 약함Patroni가 표준

운영 안티패턴

안티패턴위험
monitor를 운영 데이터와 같은 호스트호스트 사고 시 monitor·data 둘 다
2-node + 동기 모드secondary 죽으면 primary 멈춤
pg_autoctl이 system service 등록 안 됨노드 재부팅 후 합류 실패
명시적 maintenance 안 풀음자동 failover 안 됨

정리

  • pg_auto_failover = Citus 팀의 단순한 HA. monitor PostgreSQL 인스턴스가 상태 머신 관리
  • 설치·운영이 가장 단순. 명시적 상태 머신이 진단 친화
  • 1.6+에서 3-node 동기 quorum 가능
  • libpq의 multi-host conninfo로 클라이언트 failover
  • monitor 자체 HA는 별도 고려
  • 신규 도입의 빠른 대안. 대규모는 여전히 Patroni 우세

다음 절(12.8)에서는 실전 — failover·switchover 시나리오와 테스트를 봅니다.

12.6 repmgr12.8 페일오버·스위치오버 시나리오