PostgreSQL major upgrade (pg_upgrade / logical replication)
PostgreSQL난이도: 고급소요 시간: 1–3시간 (+ 데이터 크기에 따라 추가)메이저 버전 업그레이드(예: 16 → 17): 방법 선택(pg_upgrade --link / --copy / --clone 또는 logical replication을 이용한 거의 무중단 이전), pg_upgrade --check, 확장 모듈 호환성, 구성 이전, 통계 재수집, rsync 또는 pg_basebackup을 이용한 standby 재구축, 이전 클러스터 삭제 및 롤백 runbook을 다룹니다. 단일 서버, streaming replication(primary + standby) 및 Patroni 클러스터(Patroni 공식 major upgrade 절차: Patroni 중지, leader에서 pg_upgrade, DCS 레코드 삭제, Patroni가 replica를 다시 복제)를 지원합니다. RHEL 계열과 Debian/Ubuntu(pg_upgradecluster 포함)가 대상입니다.
같은 메이저 버전 안의 업데이트(예: 17.4 → 17.6)에는 이 가이드 대신 pg-minor-update를 사용합니다. 테이블 단위의 지속적인 복제나 부분 이전에는 pg-logical-repl을, 작은 데이터베이스를 dump로 다른 서버에 옮길 때는 pg-dump-restore를 사용합니다.
구성: 같은 서버에서 in-place(pg_upgrade; 단일 서버, primary + standby 또는 Patroni 클러스터) 또는 새 서버로(logical)
시나리오
- Major upgrade — 메이저 버전 업그레이드(예: 16 → 17): 사전 점검, 백업, pg_upgrade 또는 logical replication, 검증 및 정리.
- 롤백 (업그레이드 실패 / 중단) — 업그레이드가 중간에 멈췄거나 새 버전에서 문제가 생겼을 때 이전 버전으로 되돌립니다. --link 방식에서 새 클러스터를 이미 시작했다면 백업으로만 되돌릴 수 있습니다.
시작하기 전에
- 소스 클러스터는 PostgreSQL …이며 PGDG 저장소에서 설치되어 있습니다(pg-install). 대상 버전 …은 소스보다 높습니다.
- 애플리케이션과 드라이버를 PostgreSQL …로 테스트했고, 같은 업그레이드를 테스트 환경에서 미리 리허설했습니다. …까지 각 메이저 버전 release notes의 "Migration to Version" 절(제거된 설정, 동작 변경)을 읽었습니다.
- 설치된 모든 확장 모듈(PostGIS, pg_repack, pgaudit, TimescaleDB…)에 …용 빌드가 있습니다. …용 확장 모듈이 없으면 업그레이드할 수 없습니다.
- …새 데이터 디렉터리용으로 현재 데이터 크기만큼 여유 공간이 있습니다.…이전 데이터 디렉터리와 새 데이터 디렉터리가 같은 파일 시스템에 있습니다(hard link 조건). WAL과 새 카탈로그용으로 몇 GB의 여유 공간이 있습니다.…파일 시스템이 reflink를 지원하며(XFS reflink=1 또는 Btrfs) 두 디렉터리가 같은 파일 시스템에 있습니다.…
- logical replication slot / subscription이 있으면 목록을 만들었습니다. …소스가 PostgreSQL 17 이상이면 pg_upgrade가 logical slot을 이전하지만 모든 변경 사항이 소비되어 있어야 합니다…소스가 PostgreSQL …이면 pg_upgrade가 logical slot을 이전하지 않으므로 업그레이드 후 다시 생성해야 합니다….
- primary에서 각 standby로 postgres 사용자의 비밀번호 없는 SSH가 가능하고 standby에 rsync가 설치되어 있습니다. 데이터 디렉터리 구조는 …/<version>/data 형식입니다(rsync는 공통 상위 디렉터리를 사용).
- Standby가 streaming 상태이고, primary의 pg_hba.conf가 복제 연결을 허용하며, … 비밀번호가 standby의 ~postgres/.pgpass에 있습니다.
- Patroni 클러스터가 정상입니다. …가 현재 leader이고, 모든 replica가 streaming 상태이며 지연이 없고 Pending restart도 없습니다. 클러스터 이름은 …, 구성은 …, REST API 비밀번호는 /etc/patroni/patroni.env에 있습니다(pg-patroni 구성). DCS(etcd)의 snapshot 백업을 받았습니다. 업그레이드 동안 클러스터는 완전히 중지되며 HAProxy/VIP를 통한 연결은 거부됩니다.
- Patroni 버전이 PostgreSQL …를 지원합니다(Patroni release notes의 새 메이저 버전 지원 항목). 오래된 Patroni는 새 버전의 파라미터와 컨트롤 파일을 인식하지 못할 수 있으므로 필요하면 먼저 Patroni를 rolling 방식으로 업데이트하십시오.
- 대상 서버에 pg-install로 PostgreSQL …를 설치했고, 비어 있으며 실행 중입니다. 소스에 있는 확장 모듈의 … 빌드가 설치되어 있습니다. 대상에서 소스의 … 포트에 접근할 수 있습니다.
- 이전할 테이블에 primary key 또는 replica identity가 있습니다(없으면 소스에서 UPDATE/DELETE가 오류를 냅니다). 표시된 테이블에 PK를 추가하거나 ALTER TABLE … REPLICA IDENTITY FULL을 적용하십시오.
- 복원을 시험해 본 최신 백업이 있습니다… (pgBackRest)…. 가능하면 서버/디스크 snapshot도 받습니다.… --link 방식에서는 새 클러스터를 시작한 뒤의 유일한 복귀 수단입니다.…
가이드 단계
- 사전 점검 — Patroni 클러스터 상태 확인 · 클러스터 속성 기록 · 확장 모듈 RPM/deb 목록 확인 · Prepared transaction 및 장시간 트랜잭션 확인
- 새 클러스터 준비 — 새 데이터 디렉터리 생성 · 같은 속성으로 새 클러스터 생성 (initdb) · 구성을 새 클러스터로 이전 · 새 버전에서 유효하지 않은 설정 확인 · 새 버전 기준으로 Patroni 파라미터 확인
- 백업 및 복귀 지점 — 백업 수행 (pgBackRest full) · 백업 수행 (pg_dumpall + snapshot)
- 호환성 점검 (pg_upgrade --check) — pg_upgrade --check
- 다운타임: 이전 클러스터 중지 — 애플리케이션 중지 · 다운타임 시작 시 마지막 백업 (pgBackRest incr) · 다운타임 시작 시 마지막 논리 백업 · 이전 primary 중지 · Replica에서 Patroni 중지 · Leader에서 Patroni 중지 …
- 업그레이드 — pg_upgrade 실행 · pg_upgradecluster로 업그레이드 · conf.d 파일을 새 클러스터로 이전 · pgBackRest 구성을 새 클러스터로 변경 · patroni.yml의 bin_dir와 data_dir를 새 버전으로 변경 · pgBackRest stanza를 새 버전으로 업그레이드 …
- 새 클러스터 시작 — 새 클러스터 시작 · Leader에서 Patroni 시작 · Standby 즉시 시작
- 업그레이드 후 작업 — 확장 모듈 업데이트 · 통계 수집 · pgBackRest 점검 및 새 full 백업
- 검증 — 버전, 설정, 데이터베이스 · Patroni 클러스터 검증 · 로그 확인 · 애플리케이션 테스트
- 이전 클러스터 제거 — 이전 데이터 디렉터리 삭제 · …Replica…Standby…의 이전 데이터 디렉터리 삭제 · 이전 버전 소프트웨어 제거
- 소스 서버 준비 — wal_level = logical · 소스 재시작 · 복제 사용자 생성 · pg_hba.conf에 대상 추가 · pg_hba reload · Publication 생성
- 대상의 스키마와 subscription — 소스 비밀번호를 .pgpass에 기록 · Role(globals) 복사 · 스키마 복사 · Subscription 생성 · 초기 복사 완료 대기 · 지연 확인
- 마지막 전환 (cutover) — 소스의 쓰기 중지 · 마지막 변경 사항 전송 확인 · Sequence 값 이전 · Subscription 삭제 · 통계 수집 · 애플리케이션을 대상으로 전환 …
- 롤백 — 새 클러스터 중지 · Replica에서 Patroni 중지 · Leader에서 Patroni 중지 · pg_control 복원 (--link, 새 클러스터 미시작) · …백업으로 롤백 (--link, 새 클러스터 시작됨)…논리 백업으로 롤백 (--link, 새 클러스터 시작됨)… · Patroni 없이 recovery 완료 …