본문으로 건너뛰기

7.3 전환 명령

leader를 옮기는 명령은 둘입니다. switchover는 leader가 살아 있는 정상 클러스터에서 계획적으로 실행하고, failover는 leader가 없는 비정상 상황에서 수동 복구용으로 실행합니다. Part VI가 Patroni가 스스로 수행하는 자동 failover를 다뤘다면, 이 장의 명령은 사람이 전환을 직접 트리거하는 수단입니다.

patronictl switchover​

기본은 대화형입니다. 옵션 없이 실행하면 현재 leader, 승격할 candidate, 실행 시각을 차례로 묻고 마지막에 확인을 받습니다. 스크립트에서는 옵션으로 전부 지정하고 --force로 확인 프롬프트를 생략합니다.

# 대화형
patronictl switchover batman

# 비대화형: leader와 candidate를 지정하고 즉시 실행
patronictl switchover batman --leader node1 --candidate node2 --scheduled now --force

# 새벽 2시로 예약
patronictl switchover batman --leader node1 --scheduled 2026-08-05T02:00+09:00 --force

# 예약 취소
patronictl flush batman switchover
  • --leader/--primary: 현재 leader 이름을 지정합니다
  • --candidate: 새 leader로 승격할 멤버를 지정합니다
  • --scheduled: 실행 시각을 지정합니다. now를 넣으면 즉시 실행입니다. 예약된 switchover는 patronictl flush CLUSTER switchover로 폐기합니다

REST API 동등 수단은 POST /switchover로, body의 leader가 필수이고 candidate와 scheduled_at은 선택입니다. 즉시 실행 성공은 200, 예약 성공은 202를 반환합니다.

patronictl failover​

patronictl failover batman --candidate node3 --force

--candidate가 필수입니다. leader를 잃은 클러스터에서 지정한 멤버를 승격합니다.

경고

failover의 --leader 옵션은 3.2.0에서 deprecated되었고 4.0.0에서 제거되었습니다. 구버전 기준으로 작성된 runbook이나 블로그의 patronictl failover --leader ... 예시는 4.x에서 동작하지 않습니다. leader가 살아 있는 정상 클러스터의 전환에는 switchover를 씁니다.

REST의 POST /failover는 body에 candidate가 필수이며, body에 leader를 넣으면 switchover로 처리됩니다. patronictl 쪽 명령 구분과 같은 논리입니다.

history: 전환 이력 확인​

자동이든 수동이든 전환이 일어날 때마다 PostgreSQL timeline이 갈라집니다. history는 이 timeline 분기 이력을 보여줍니다.

patronictl history batman
+----+----------+------------------------------+----------------------------------+------------+
| TL |      LSN | Reason                       | Timestamp                        | New Leader |
+----+----------+------------------------------+----------------------------------+------------+
|  1 | 25623960 | no recovery target specified | 2026-07-12T03:11:27.125527+00:00 | node1      |
|  2 | 25624344 | no recovery target specified | 2026-07-19T22:41:02.634912+00:00 | node3      |
+----+----------+------------------------------+----------------------------------+------------+

각 행은 timeline 번호, 분기가 일어난 LSN, 사유 문자열, timeline이 생성된 시각, 그리고 그때 새 leader가 된 멤버입니다. 형식은 PostgreSQL의 timeline history 파일과 같고 여기에 시각이 추가되어 있습니다. 새벽에 예상치 못한 failover가 있었는지, 언제 몇 번 전환이 일어났는지 사후 확인할 때 먼저 보는 명령입니다. REST로는 GET /history가 같은 이력을 JSON 배열로 반환합니다.

reinit: 탈락 노드 재구축​

전환 뒤 구 leader가 새 timeline을 따라가지 못하는 경우가 있습니다. pg_rewind를 쓰지 않거나 rewind가 실패한 상황이 대표적입니다. 이때 그 노드의 데이터 디렉토리를 지우고 처음부터 다시 만드는 명령이 reinit입니다.

patronictl reinit batman node1 --wait
patronictl reinit batman node1 --from-leader --force

데이터 디렉토리를 제거한 뒤 pg_basebackup 또는 설정된 replica 생성 방법으로 다시 받으며, replica 상태의 노드에서만 실행이 허용됩니다.

  • --wait: 재구축이 끝날 때까지 기다렸다가 반환합니다
  • --force: 확인 프롬프트를 생략합니다
  • --from-leader: basebackup을 leader에서 직접 받습니다
노트

reinit는 데이터를 처음부터 다시 받는 작업이라 DB 크기에 비례해 오래 걸립니다. 재구축 없이 timeline 분기를 따라잡는 pg_rewind 경로는 Part VI 참고.

정리​

  • leader가 정상이면 switchover, leader가 없으면 failover --candidate. 4.0부터 failover에 --leader 옵션은 없습니다.
  • 전환 이력은 history로 timeline 단위로 확인합니다.
  • 전환에서 탈락한 노드가 새 timeline에 합류하지 못하면 reinit으로 재구축합니다.