6.3 switchover와 수동 failover

leader 교체를 사람이 개시하는 방법은 두 가지다. switchover는 클러스터가 healthy할 때, 즉 leader가 존재하는 상태에서 수행하는 계획된 교체다. 유지보수를 위한 노드 교체, 커널 패치 전 primary 이동 같은 작업이 여기에 해당한다. 수동 failover는 leader가 없어도 강제할 수 있는 비상 수단이다. 공식 문서는 failover에 대해 “Triggering a failover can cause data loss depending on how up-to-date the promoted replica is in comparison to the primary"라고 경고한다. 승격할 replica가 얼마나 최신이냐에 따라 데이터 손실이 생길 수 있다는 뜻이다.

두 연산의 요건 차이는 다음과 같다.

REST API로 실행하기

switchover는 POST /switchover로 요청한다. body에 leader는 필수이고 candidate와 scheduled_at(ISO 8601)은 선택이다.

# 즉시 switchover, 후임 지정
curl -s http://localhost:8008/switchover -XPOST \
  -d '{"leader":"postgresql1","candidate":"postgresql2"}'

# 예약 switchover
curl -s http://localhost:8008/switchover -XPOST \
  -d '{"leader":"postgresql0","scheduled_at":"2026-08-02T02:00+09:00"}'

# 예약 취소
curl -s http://localhost:8008/switchover -XDELETE

candidate를 지정하지 않으면 leader가 물러난 뒤 자격 있는 모든 노드가 leader race에 참여한다. 즉 후임 선정은 6.2 후보 선정과 같은 규칙을 따른다. 응답 코드는 즉시 실행 성공이 200, 예약 접수가 202이며 요청 오류나 실행 불가 상황에서는 400, 412, 503을 반환한다.

수동 failover는 POST /failover로 요청하며 candidate가 필수다.

curl -s http://localhost:8008/failover -XPOST \
  -d '{"candidate":"postgresql2"}'

leader 필드도 넣으면 Patroni는 그 요청을 switchover로 처리한다. failover에는 예약 기능이 없다. 문서 원문의 표현을 빌리면 “Be very careful when using this endpoint, as this can cause data loss in certain situations"이다.

patronictl로 실행하기

같은 연산을 patronictl 명령으로도 실행한다.

# 대화형 switchover (leader, candidate, 시각을 프롬프트로 확인)
patronictl switchover my-cluster

# 옵션 명시 + 확인 프롬프트 생략
patronictl switchover my-cluster \
  --primary postgresql1 --candidate postgresql2 --force

# 예약 switchover ("now" 리터럴도 허용)
patronictl switchover my-cluster --scheduled "2026-08-02T02:00+09:00"

# 수동 failover
patronictl failover my-cluster --candidate postgresql2 --force

--force는 확인 프롬프트를 생략하므로 자동화 스크립트에서 쓴다. --scheduled에는 timestamp 외에 리터럴 "now"도 허용된다.

synchronous mode가 켜진 클러스터에서 patronictl failover는 asynchronous 노드로의 강제 전환도 허용한다. sync replica가 모두 불능인 비상 상황을 위한 탈출구인데, 그 순간 synchronous replication이 주던 무손실 보장은 성립하지 않는다.

pause 중의 동작 차이

pause mode에서 Patroni는 자동 failover를 멈추지만 수동 개입까지 막지는 않는다. failover는 pause 중에도 동작한다. 반면 switchover는 candidate를 명시한 경우에만 동작한다. candidate 없이 leader만 내리면 후임 선정을 자동 leader race에 맡겨야 하는데, pause 중에는 그 race가 일어나지 않기 때문이다.

정리

• switchover는 leader 필수, 예약 지원, healthy 클러스터 전제다. failover는 candidate 필수, 예약 불가, leader가 없어도 강제된다.
• POST /failover에 leader까지 넣으면 switchover로 처리된다. 두 API의 경계는 결국 “현 leader가 정상적으로 물러나는 것을 전제하는가"이다.
• pause 중에는 failover만 온전히 동작하고, switchover는 candidate를 지정해야 한다.
• Patroni 4.0부터 role=master와 --master는 더 이상 받지 않는다.