본문으로 건너뛰기
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 안 됨
12.6 repmgr12.8 페일오버·스위치오버 시나리오