10.3 명령 치트시트

v2.2 기준 pg_autoctl 명령과 진단 SQL입니다. 괄호 안에는 이 노트의 실습에서 확인한 주의 사항을 적었습니다. 노드에서 명령을 실행하면 PGDATA 환경 변수 또는 --pgdata로 대상 노드를 찾습니다. 다른 곳에서 실행할 때는 --monitor URI를 지정합니다.

생성과 실행

# monitor
pg_autoctl create monitor --pgdata /var/lib/pgaf/monitor --pgport 5432 \
  --hostname monitor.example --auth scram-sha-256 --ssl-self-signed

# PostgreSQL 노드 (첫 노드는 single, 이후는 standby로 합류)
pg_autoctl create postgres --pgdata /var/lib/pgaf/data --pgport 5432 \
  --name node1 --hostname node1.example --dbname appdb \
  --monitor 'postgres://autoctl_node@monitor.example:5432/pg_auto_failover?sslmode=require' \
  --auth scram-sha-256 --ssl-self-signed

# 생성 직후 계속 실행하려면 --run, 서비스로 돌리려면 systemd unit 출력
pg_autoctl run
pg_autoctl show systemd | sudo tee /etc/systemd/system/pgautofailover.service
pg_autoctl stop
pg_autoctl reload
pg_autoctl status

(standby가 합류하기 전에 primary에서 CHECKPOINT를 실행하면 pg_basebackup의 checkpoint 대기 시간이 줄어듭니다. 실측 결과 97.8초에서 3.5초로 줄었습니다. 운영에서는 I/O 부하를 먼저 확인합니다)

조회

명령	내용
pg_autoctl show state [--json]	노드별 현재/목표 상태, LSN, 연결 상태
pg_autoctl show events [--count N]	monitor event 테이블
pg_autoctl show settings	number_sync_standbys, synchronous_standby_names, 노드별 priority와 quorum
pg_autoctl show standby-names	primary에 적용될 synchronous_standby_names
pg_autoctl show uri [--formation F]	monitor URI, 애플리케이션용 multi-host URI
pg_autoctl show file	설정, state, init, pid 파일 경로
pg_autoctl watch	상태 변화 대시보드
pg_autoctl config get [section.option]	keeper 설정 조회
pg_autoctl --version	버전과 호환 PostgreSQL

전환

pg_autoctl perform switchover [--formation default --group 0]
pg_autoctl perform failover                 # switchover와 같은 동작(v2.2 문서)
pg_autoctl perform promotion --name node3   # 지정 노드 승격

(2노드 switchover 실측 결과, 명령 반환에는 5.5초가 걸렸고 쓰기 공백은 1.35초였습니다. 알림 대기 중 발생한 get_nodes ERROR 로그는 무시해도 되었습니다)

maintenance

pg_autoctl enable maintenance                   # secondary에서
pg_autoctl enable maintenance --allow-failover  # primary에서 (failover 발생)
pg_autoctl disable maintenance

복제 설정

# 노드 속성: 노드에서 실행 (PG_AUTOCTL_MONITOR가 있으면 --name 필요)
pg_autoctl set node candidate-priority --name node3 0
pg_autoctl set node replication-quorum --name node3 false
pg_autoctl get node candidate-priority --name node3

# formation 속성: monitor 컨테이너에서는 --monitor URI 필요
pg_autoctl set formation number-sync-standbys \
  --monitor 'postgres://autoctl_node@localhost:5432/pg_auto_failover' 1
pg_autoctl get formation settings

(number-sync-standbys N은 quorum에 참여하는 standby가 N+1개 이상일 때만 허용됩니다. 실측 오류는 At least 3 standby nodes are required, and only 2 are currently participating in the replication quorum입니다)

노드 삭제

pg_autoctl drop node --destroy                          # 로컬 노드를 monitor에서 지우고 PGDATA 삭제
pg_autoctl drop node --formation default --name node3   # 원격에서 이름으로 삭제 (--monitor 필요)
pg_autoctl drop node --hostname node3 --pgport 5432 --force   # 응답 없는 노드 강제 제거

monitor 교체

# 1. 옛 monitor 차단(fencing)
# 2. 모든 노드에서, primary를 마지막으로
pg_autoctl disable monitor --force
# 3. 새 monitor 생성
pg_autoctl create monitor ...
# 4. primary 먼저, 그다음 standby
pg_autoctl enable monitor 'postgres://autoctl_node@new-monitor:5432/pg_auto_failover?sslmode=require'

(실측 결과, 150초 동안 쓰기 실패는 0건이었습니다. 복제 설정은 기본값으로 돌아갔습니다)

설정 파일

psql -d postgres -c "alter user pgautofailover_replicator password '...'"   # upstream 역할 비밀번호
pg_autoctl config set replication.password '...'   # keeper 쪽 값. 두 값을 함께 맞춤
pg_autoctl config set timeout.network_partition_timeout 20
pg_autoctl enable ssl --ssl-self-signed --ssl-mode require

monitor GUC (monitor의 PostgreSQL에서)

select name, setting, unit from pg_settings where name like 'pgautofailover.%' order by 1;
alter system set pgautofailover.primary_demote_timeout = '30s';
select pg_reload_conf();

진단 SQL (monitor의 pg_auto_failover DB)

-- 상태 한눈에
select nodeid, nodename, reportedstate, goalstate, health, reportedlsn, reportedtli,
       now() - reporttime as since_report
  from pgautofailover.node order by nodeid;

-- 최근 결정 이력
select to_char(eventtime, 'HH24:MI:SS.MS'), nodename, reportedstate, goalstate, description
  from pgautofailover.event
 where eventtime > now() - interval '10 minutes' order by eventid;

-- 전이가 멈춘 노드
select nodename, reportedstate, goalstate, now() - statechangetime
  from pgautofailover.node where reportedstate <> goalstate;

진단 SQL (데이터 노드)

select pg_is_in_recovery(), current_setting('transaction_read_only');
show synchronous_standby_names;
select application_name, state, sync_state from pg_stat_replication;
select slot_name, active, restart_lsn from pg_replication_slots;