Open Source
Patroni PostgreSQL HA
Patroni·etcd·PgBouncer·HAProxy 기반 PostgreSQL 고가용성(HA) 클러스터를 Ansible Playbook 실행 한 번으로 구축하는 오픈소스 프로젝트입니다.
Apache License 2.0 · 오픈소스GitHub 저장소
SQL 접속과 클러스터 제어
애플리케이션 연결은 VIP·HAProxy·PgBouncer를 거쳐 PostgreSQL에 도달하고, Patroni와 etcd는 별도의 경로에서 리더 상태를 조정합니다.
- 1.접속 포트 선택
- 같은 VIP의 5000 포트는 읽기·쓰기 연결을, 5001 포트는 리플리카 우선 연결을 받습니다. Keepalived가 HAProxy 호스트의 VIP를 관리합니다.
- 2.라우팅과 연결 풀링
- HAProxy는 Patroni REST API의 /primary·/replica 응답으로 대상을 선택하고, 해당 DB 호스트의 PgBouncer 6432 포트로 연결합니다.
- 3.저장과 복제
- PgBouncer는 같은 호스트의 PostgreSQL 5432 포트에 연결합니다. 리더의 WAL이 리플리카로 스트리밍되며 SQL 트래픽은 Patroni를 통과하지 않습니다.
- 4.리더 상태 조정
- 각 DB 호스트의 Patroni가 etcd의 리더 키를 관리하고 로컬 PostgreSQL의 승격·강등을 제어합니다. 상태 확인과 제어는 SQL 접속 경로와 분리됩니다.
기본 설정은 비동기 복제이며, 읽기 포트는 정상 리플리카가 없으면 리더로 연결됩니다. etcd 3노드의 정족수는 2입니다.
GitHub 문서·코드 확인리더 장애부터 재접속까지
리더 키 만료, 새 리더 선출, 상태 확인, 애플리케이션 재접속으로 이어지는 전환 과정을 단계별로 살펴봅니다.
- 1.리더 장애 감지
- 기존 리더가 etcd의 리더 키를 갱신하지 못하면 리스의 유효 기간이 만료됩니다. HAProxy도 상태 확인 실패를 통해 해당 연결 대상을 제외합니다.
- 2.리더 잠금 획득
- 승격 조건을 충족한 리플리카의 Patroni가 etcd 리더 키를 획득합니다. etcd 정족수와 복제 상태가 전환 결정에 관여합니다.
- 3.승격과 경로 변경
- 새 리더의 PostgreSQL이 승격되고 Patroni /primary가 200을 반환하면, HAProxy가 쓰기 연결을 새 리더의 PgBouncer로 전달합니다.
- 4.재접속과 상태 확인
- 애플리케이션이 같은 VIP:5000으로 새 연결을 맺습니다. patronictl과 실제 SQL로 역할·복제 상태를 확인하고, 기존 리더 재합류는 별도 복구 절차로 진행합니다.
기본 리더 키 TTL은 30초, Patroni 점검 주기는 10초입니다. 전환 시간은 상태와 설정에 따라 달라지며, DB 리더 변경이 반드시 VIP 이동을 뜻하지는 않습니다.
GitHub 문서·코드 확인배포 구성 선택과 설치 검증
etcd를 별도 배치하거나 3대 서버에 통합한 뒤 구성된 클러스터를 검증합니다.
- 1.분리형
- etcd 전용 호스트 3대와 DB 호스트 2대 이상을 사용합니다.
- 2.통합형
- 6개 구성요소를 3대 서버에 함께 배치합니다.
- 3.구성요소 역할
- SQL 연결 전달·연결 풀·저장·리더 조정을 구분합니다.
- 4.자동화
- 인벤토리를 설정하고 배포한 뒤 연결 경로와 복제를 검증합니다.
문서상 PostgreSQL 14–17, 기본값은 16입니다. 페일오버 중 연결이 끊길 수 있으며 동기 복제·pgBackRest는 선택 설정입니다.
GitHub 문서·코드 확인