PostgreSQL streaming replication (primary + standby)

설치된 primary에 pg_basebackup으로 하나 이상의 hot standby를 추가하고(복제 사용자, pg_hba, replication slot, 비동기 또는 동기 ANY/FIRST 모드, 지연 모니터링), Patroni 없는 이 클러스터의 운영 런북을 생성합니다: 계획된 switchover, 수동 failover(pg_promote), 이전 primary를 pg_rewind로 재합류, standby 재구축, cascading 및 지연 standby, slot 정리, 동기 설정 변경. Failover는 자동이 아니며 DBA가 수행합니다. 자동 failover는 pg-patroni를, 테이블 단위 또는 버전 간 데이터 흐름은 pg-logical-repl을 사용하십시오.

구성: primary 1대 + standby 1..N대

시나리오

• 설치: primary에 standby 추가 — 설치된 primary에 pg_basebackup으로 하나 이상의 hot standby를 추가합니다(slot, 동기/비동기, 모니터링). Primary는 계속 열려 있으며, 초기 복사는 primary에 디스크와 네트워크 부하를 줍니다.
• 계획된 switchover (역할 전환, 데이터 손실 없음) — 계획된 유지보수: primary를 정상 종료하고 첫 번째 standby를 promote하며, 이전 primary는 standby로 돌아옵니다. 데이터 손실은 없고 쓰기 중단은 보통 1분 미만입니다.
• 수동 failover (primary 장애, standby promote) — Primary가 다운되었거나 접근할 수 없음: 이전 primary를 격리(fencing)하고 가장 최신 standby를 수동으로 promote합니다. 비동기 모드에서는 마지막 트랜잭션이 유실될 수 있습니다.
• 이전 primary를 pg_rewind로 standby로 재합류 — Failover 후 이전 primary를 pg_rewind로 새 primary와 동기화하여 standby로 재합류시킵니다. 전체 복사보다 훨씬 빠릅니다.
• standby에서 WAL을 받는 새 standby 추가 (cascading) — 새 standby가 WAL을 primary 대신 첫 번째 standby에서 받습니다. 원격 데이터센터나 standby가 많은 구성에서 primary의 네트워크/WAL 전송 부하가 줄어듭니다. Primary에는 영향이 없습니다.
• 지연(delayed) standby 구성 — WAL을 몇 시간 늦게 적용하는 standby(recovery_min_apply_delay): 실수로 삭제된 데이터를 백업에서 복원하지 않고 복구하기 위한 용도입니다. Failover 후보가 아닙니다.
• standby를 처음부터 재구축 — Standby가 뒤처졌거나, 필요한 WAL이 삭제되었거나, 손상됨: 데이터 디렉터리를 옆으로 옮기고 primary에서 다시 복사합니다. Primary에는 영향이 없습니다.
• pg_wal 증가, 디스크 가득 참 (사용하지 않는 slot 정리) — WAL 누적 원인(비활성 slot, 아카이브 오류, wal_keep_size)을 찾고, 사용하지 않는 replication slot을 삭제하여 WAL 공간을 회수합니다. Primary는 계속 열려 있습니다.
• 동기 standby 추가 / 제거 (synchronous_standby_names) — 동기 목록을 폼의 모드(ANY/FIRST, k)에 따라 다시 쓰거나 비동기로 되돌립니다. reload로 적용되며 restart는 필요 없습니다. 잘못된 설정은 commit을 대기 상태로 만들 수 있으므로 먼저 점검합니다.

시작하기 전에

• Primary …가 pg-install 가이드로 설치되어 실행 중입니다(PostgreSQL …, PGDATA …, 포트 …).
• Standby 서버에서는 pg-install 가이드의 운영체제 준비 단계(hostname, chrony, sysctl, THP)만 수행했습니다. 클러스터는 생성하지 않았으며, 소프트웨어는 이 가이드에서 설치합니다.
• 모든 서버가 같은 운영체제 계열, 같은 아키텍처(x86_64/aarch64), 같은 PostgreSQL 메이저 버전(…)입니다. Standby는 primary의 완전한 물리적 복사본입니다.
• Standby의 …에 primary 데이터 크기보다 최소 20% 이상 여유 공간이 있습니다.
• 서버끼리 포트 …로 접근할 수 있고, 호스트명이 해석되며, 시각이 NTP로 맞춰져 있습니다.
• 방화벽에서 서버 간 포트 …가 열려 있습니다(pg-install에서 애플리케이션 네트워크만 열었다면 복제 IP도 추가하십시오).
• Debian/Ubuntu에서는 설정 파일이 데이터 디렉터리 밖(/etc/postgresql)에 있어 pg_basebackup이 복사하지 않습니다. Standby에서 primary로 scp를 위한 root(또는 sudo 권한 사용자) 접근이 있거나, 파일을 수동으로 옮겨야 합니다.
• 이전 primary의 데이터 디렉터리가 온전하고 서버를 기동할 수 있습니다(디스크 장애 시에는 pg_rewind가 아니라 pg_basebackup으로 재구축해야 합니다).
• …Primary에 부하를 주는 초기 복사(pg_basebackup)에 적절한 시간을 정했습니다.…유지보수 시간이 시작되었고, 애플리케이션 팀이 짧은 쓰기 중단을 알고 있습니다.…Primary가 실제로 접근 불가함을 확인했고, 다시 살아나 두 번째 primary로 쓰기를 받지 않도록 보장했습니다(fencing).…새 primary가 정상이며 쓰기를 받고 있습니다.…새 서버(…)가 준비되었습니다: 운영체제 준비 완료, …가 비어 있고 공간이 충분하며, 초기 복사가 원본(…)에 부하를 줍니다.…… 재구축 중 읽기 부하를 다른 서버로 옮길 수 있으며, 복사는 primary에 부하를 줍니다.…디스크 사용량을 모니터링하고 있으며, slot 삭제 전에 해당 slot을 쓰는 standby 담당자와 협의했습니다.…동기 설정 변경은 유지보수 시간에 하며, commit 지연이 달라지므로 애플리케이션 팀이 알고 있습니다.…

가이드 단계

• 준비 (모든 서버) — 서버 이름을 /etc/hosts에 추가 · PGDG 저장소 추가 · PGDG 저장소 추가 · PostgreSQL 서버 소프트웨어 설치 · 데이터 디렉터리 준비 · 클러스터 설정 생성 및 데이터 디렉터리 비우기
• Primary 복제 준비 — pg_rewind 전제 조건 확인 · 복제 설정 파일 작성 · 설정 적용 · 복제 사용자 생성 · 복제 사용자 비밀번호 설정 · pg_hba.conf에 복제 규칙 추가 …
• Standby 구성 (pg_basebackup) — Primary로의 복제 연결 테스트 · Primary 복사본 생성: … · Primary에서 설정 파일 복사 · Standby 기동
• 검증 — Primary에서 복제 상태 확인 · Standby에서 WAL 수신자 확인 · Primary에 테스트 데이터 기록 · Standby에서 테스트 데이터 읽기 · 테스트 테이블 삭제
• 동기 복제 활성화 — 동기 설정 파일 작성 · 모든 서버에서 설정 적용 · 동기 상태 검증
• 모니터링 및 설치 후 작업 — 지연 모니터링 쿼리 (primary) · 지연 모니터링 쿼리 (standby) · Slot 사용량 모니터링 · 애플리케이션 연결 문자열 · Standby 기준으로 백업 설정
• Switchover 사전 점검 — Standby 상태 확인 · 새 primary 준비 상태 확인 · 이전 primary의 .pgpass와 pg_hba 확인
• Switchover — 이전 primary 정상 종료 · 새 primary의 마지막 WAL 수신 확인 · … 서버 promote · 새 primary에 slot 생성 · 이전 primary를 standby로 설정 · 이전 primary를 standby로 기동 …
• 수동 failover — 이전 primary 중지 및 비활성화 (fencing) · 가장 최신 standby 확인 · … 서버 promote · 동기 대기 임시 해제 · 새 primary에 slot 생성 · 나머지 standby를 새 primary로 전환: … …
• 이전 primary를 pg_rewind로 재합류 — 새 primary의 slot과 접속 규칙 확인 · 이전 primary 중지 상태 확인 · pg_rewind 시험 실행 · pg_rewind 실행 · Standby 설정 마무리 · 이전 primary를 standby로 기동 …
• pg_wal 비대화와 slot 정리 — pg_wal이 커지는 이유 · Slot 소유자 찾기 · 사용하지 않는 slot 삭제: … · Slot 삭제: 폼 입력 · WAL 공간 회수 확인 · 재발 방지: 상한과 모니터링
• 동기 standby 변경 — 현재 동기 상태 · 안전 점검: 충분한 standby가 연결되어 있는가? · 동기 설정 파일 작성 · 동기 설정 제거 (비동기로 전환) · 모든 서버에서 설정 적용 · 새 상태 검증