10.1 rolling restart와 마이너 업그레이드

PostgreSQL 파라미터 중에는 reload만으로 적용되는 것과 재시작이 필요한 것이 있다. Patroni는 dynamic configuration 변경을 전 노드에 배포하지만, 재시작이 필요한 파라미터를 만나도 노드를 대신 재시작하지 않는다. 공식 FAQ는 이 설계를 다음과 같이 설명한다. “Patroni will mark the affected members with a flag of pending restart. It is up to you to determine when and how to restart the members.” 재시작 시점과 방법의 결정은 DBA의 몫이고, Patroni는 그 결정을 실행할 도구로 patronictl restart와 POST /restart를 제공한다.

pending restart 플래그의 생성과 해제

patronictl edit-config로 restart가 필요한 GUC를 바꾸면, 각 노드는 pg_settings의 context와 실제 적용 값을 비교해 자기 자신에게 pending restart 플래그를 붙인다. 이 플래그는 patronictl list 출력의 Pending restart 컬럼에 사유와 함께 표시되고(-e 또는 --extended 옵션으로 강제 표시), 해당 노드를 재시작하면 리셋된다.

    flowchart TD
  A["patronictl edit-config로<br/>파라미터 변경"] --> B["DCS의 config 키 갱신"]
  B --> C["각 노드 reload"]
  C --> D{"restart 필요<br/>파라미터인가"}
  D -->|아니오| E["즉시 적용"]
  D -->|예| F["pending restart 플래그"]
  F --> G["patronictl restart 실행"]
  G --> H["적용, 플래그 해제"]
  

플래그가 붙은 뒤 실제 재시작까지의 시간은 Patroni가 관여하지 않는다. 트래픽이 적은 시간대를 골라 재시작하든, 다음 정기 점검까지 미루든 클러스터는 그대로 동작한다.

patronictl restart의 선택 옵션

patronictl restart CLUSTER [MEMBER ...] [--pending] [--pg-version VER] \
    [--scheduled TIMESTAMP] [--any] [-r ROLE] [--timeout T] [--force]

• --pending: pending restart 플래그가 붙은 멤버만 선택한다.
• --pg-version: 관리 중인 PostgreSQL 버전이 지정 값보다 오래된 멤버만 선택한다. 마이너 업그레이드 후 구버전으로 남은 노드만 골라 재시작할 때 쓴다.
• --scheduled: 지정 시각에 재시작을 예약한다. now도 허용되며, 예약 취소는 patronictl flush CLUSTER restart로 한다.
• --any: 조건에 맞는 노드 중 랜덤으로 1대만 재시작한다.
• --timeout: 지정 시간을 넘기면 restart를 중단한다.

REST API로는 POST /restart에 restart_pending, role, postgres_version, timeout, schedule 필드를 담아 같은 동작을 요청한다.

# pending restart 플래그가 붙은 노드만 재시작
patronictl restart batman --pending

# 16.4보다 오래된 버전으로 실행 중인 노드만 재시작
patronictl restart batman --pg-version 16.4

# 새벽 3시(KST)로 예약
patronictl restart batman --scheduled 2026-08-01T03:00+09:00

shared memory 파라미터의 변경 순서

max_connections, max_prepared_transactions, max_locks_per_transaction, max_wal_senders, max_worker_processes는 shared memory 크기를 결정하는 파라미터로, standby의 값이 primary보다 작을 수 없다는 제약이 있다. 그래서 재시작 순서가 값의 증감 방향에 따라 달라진다.

• 값을 늘릴 때: standby를 먼저 재시작하고 primary를 마지막에 재시작한다.
• 값을 줄일 때: primary를 먼저 재시작하고 standby를 나중에 재시작한다.

값을 줄이면서 전 노드를 한 번에 재시작하면 Patroni가 standby에서 변경을 무시하고 원래 값으로 재시작한다. pg_controldata 기준으로 primary를 따라잡을 때까지 기다리는 동작으로, standby가 기동에 실패하며 FATAL crash loop에 빠지는 것을 막기 위한 보호다. 이 파라미터들이 DCS로만 변경되는 이유와 구성 3계층 구조는 Part IV. 설치와 구성에서 다룬다.

마이너 업그레이드

공식 문서에는 마이너 버전 업그레이드 전용 절차가 없다. FAQ에도 해당 항목이 없다. 마이너 업그레이드는 바이너리 교체와 재시작만으로 끝나는 작업이므로, rolling restart를 응용한 다음 절차가 통용된다. 공식 절차가 아니라 널리 쓰이는 관행이라는 전제로 읽어야 한다.

Zalando postgres-operator가 마이너 업그레이드를 “pod rolling update 후 switchover"로 자동화한 것도 같은 패턴이다. switchover 구간에서 클라이언트 재연결이 발생하므로, 애플리케이션의 재연결 동작을 함께 점검해 두는 편이 좋다.

정리

• restart가 필요한 파라미터 변경에서 Patroni가 하는 일은 pending restart 플래그까지다. 재시작 시점과 방법은 DBA가 결정한다.
• PostgreSQL 재시작은 patronictl restart로 실행한다. systemctl restart patroni는 failover를 유발할 위험이 있다.
• shared memory 파라미터는 늘릴 때 standby 먼저, 줄일 때 primary 먼저다. 마이너 업그레이드는 공식 절차가 없으며, replica부터 교체하고 switchover로 마무리하는 관행이 통용된다.