1.1 Patroni란 무엇인가

공식 문서는 Patroni를 “a template for high availability (HA) PostgreSQL solutions using Python"이라고 소개한다. 이 한 문장에서 눈여겨볼 단어는 template이다. Patroni는 설치만 하면 완성되는 HA 제품이 아니라, 합의 저장소(DCS)와 연결 라우팅, 백업 도구를 자기 환경에 맞게 골라 조합하는 것을 전제로 한 골격이다. 실제로 Patroni 본체가 맡는 일은 leader 선출과 failover 자동화이고, 클라이언트를 primary로 이어 주는 일은 HAProxy나 vip-manager 같은 도구가, 백업은 pgBackRest나 Barman 같은 도구가 맡는 조합 구성이 일반적이다.

어떤 문제를 푸는가

PostgreSQL은 streaming replication을 내장한다. replica는 primary가 보내는 WAL을 실시간으로 적용하고, pg_ctl promote 한 번이면 primary로 승격된다. 그런데 딱 여기까지다. primary 장애를 감지하는 것, 여러 replica 중 누구를 승격할지 고르는 것, 승격 뒤 나머지 노드가 새 primary를 따라가게 만드는 것은 전부 PostgreSQL 바깥의 일이다.

Patroni는 이 빈칸을 채운다. DCS(Distributed Configuration Store)를 통한 leader election으로 자동 failover를 처리하고, split brain을 피하는 장치를 제공한다. 이것이 왜 어려운 문제인지는 1.2에서 따로 다룬다.

bot 패턴

Patroni는 클러스터의 모든 노드에서 데몬으로 돈다. 각 데몬은 자기 노드의 PostgreSQL 프로세스를 직접 기동하고, 구성하고, 감시한다. systemd가 postgres를 띄우고 Patroni는 옆에서 지켜보기만 하는 구조가 아니다. 데몬 자신이 PostgreSQL을 띄우는 주체다. 이렇게 노드마다 붙은 agent들이 외부 저장소를 통해 협의하는 방식을 bot 패턴이라고 부른다.

    flowchart TD
  subgraph DCS["DCS (etcd 등)"]
    KEY["leader key (TTL)"]
  end
  subgraph N1["노드 1"]
    P1["Patroni"] -->|기동/관리| PG1["PostgreSQL<br/>primary"]
  end
  subgraph N2["노드 2"]
    P2["Patroni"] -->|기동/관리| PG2["PostgreSQL<br/>replica"]
  end
  subgraph N3["노드 3"]
    P3["Patroni"] -->|기동/관리| PG3["PostgreSQL<br/>replica"]
  end
  P1 -->|TTL 갱신| KEY
  P2 -->|감시| KEY
  P3 -->|감시| KEY
  

primary 노드의 Patroni는 DCS의 leader key를 TTL 주기로 갱신하고, replica 노드의 Patroni는 그 key가 살아 있는지 감시한다. key가 만료되면 replica들이 leader race를 벌여 새 primary를 정한다. 이 루프의 상세 동작은 Part II에서 다룬다.

기능 면에서는 leader 선출과 failover 외에도 REST API(상태 조회, health check, 구성 변경), patronictl CLI, synchronous와 quorum commit을 포함한 여러 replication 모드, Prometheus metrics, Citus 클러스터 지원을 제공한다.

지원 DCS

합의 저장소로 쓸 백엔드는 다음 중에서 고른다.

• etcd (v2/v3 프로토콜)
• ZooKeeper
• Exhibitor (ZooKeeper 관리 도구 경유)
• Consul
• Kubernetes API
• Raft (pysyncobj 기반 내장 구현, deprecated)

Raft 백엔드는 릴리스 노트가 “유지에 최선을 다하겠지만 발생 가능한 문제에 대한 보증도 책임도 지지 않는다"고 경고하는 deprecated 상태다. 신규 구성이라면 etcd 계열이나 Kubernetes API처럼 활발히 지원되는 백엔드를 고르는 편이 무난하다. 백엔드별 특성은 Part III에서 비교한다.

버전과 지원 범위

Patroni는 MIT 라이선스 오픈소스다. 이 노트의 기준 버전인 4.1.4는 2026년 7월 7일에 릴리스됐고, 같은 날 4.0.10과 3.3.11도 함께 나왔다. 즉 4.1.x 최신 라인과 별개로 4.0.x, 3.3.x 유지보수 브랜치가 병행 유지되는 중이다.

• 지원 PostgreSQL: 9.3에서 18까지
• 요구 Python: 3.6 이상 (4.1.1에서 Python 3.14 지원 추가)
• psycopg 요구: psycopg2>=2.5.4 또는 psycopg2-binary 또는 psycopg[binary]>=3.0.0

설치는 pip extras로 DCS 클라이언트를 함께 고르거나 배포판 패키지를 쓴다.

pip install patroni[psycopg3,etcd3]      # extras: etcd, etcd3, consul, zookeeper, kubernetes, raft 등
sudo apt install patroni                 # Debian/Ubuntu
sudo dnf install patroni patroni-etcd    # RHEL 9 이상

정리

• Patroni는 template이다. DCS, 연결 라우팅, 백업 도구를 조합해 HA 구성을 완성한다
• 각 노드에서 데몬(bot)으로 돌며 자기 노드의 PostgreSQL을 직접 관리하고, DCS의 leader key로 leader를 정한다
• DCS로 etcd, ZooKeeper, Consul, Kubernetes API 등을 지원한다. MIT 라이선스, 최신 4.1.4, PostgreSQL 9.3에서 18까지 지원한다