7.3 전환 명령

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

    flowchart TD
  Q{"정상 leader가<br/>있는가"}
  Q -->|"있음"| SW["switchover"]
  Q -->|"없음"| FO["failover"]
  SW --> SW2["계획 전환<br/>예약 실행 지원"]
  FO --> FO2["수동 복구<br/>--candidate 필수"]
  

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를 잃은 클러스터에서 지정한 멤버를 승격한다.

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에서 직접 받는다

정리

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