본문으로 건너뛰기
Docs
Part XVIII. 마이그레이션과 업그레이드
18.3 메이저 버전 업그레이드 (pg_upgrade)

18.3 메이저 버전 업그레이드 (pg_upgrade)

PostgreSQL은 메이저 버전을 매년 출시(1.1) — 14·15·16·17·18 등. 각 메이저는 binary 호환 안 됨 — 새 클러스터로 데이터 옮겨야. pg_upgrade가 빠른 in-place 업그레이드 표준입니다.

옵션 비교

방법다운타임메모
pg_dump + restore매우 큼모든 데이터 SQL로 export·import
pg_upgrade –copy중간 (~데이터 크기 비례)새 위치로 file 복사
pg_upgrade –link매우 짧음hard link — 디스크 두 배 안 씀
logical replication거의 0무중단 (18.4)

운영 권장:

  • 작은 DB (< 100GB) → pg_dump 도 OK
  • 100GB+ → pg_upgrade –link
  • 무중단 필수 → logical replication

pg_upgrade 동작 

    flowchart LR
  OLD["옛 17 cluster<br/>(PGDATA_17)"]
  NEW["새 18 cluster<br/>(빈 PGDATA_18)"]
  PG_UP["pg_upgrade"]

  OLD --> PG_UP
  PG_UP --> NEW

  classDef old fill:#fed7aa,stroke:#c2410c,color:#7c2d12
  classDef new fill:#d1fae5,stroke:#047857,color:#064e3b
  classDef tool fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
  class OLD old
  class NEW new
  class PG_UP tool
  1. 옛 클러스터의 스키마·시스템 카탈로그를 새 클러스터에 dump·load
  2. 옛 클러스터의 데이터 파일을 새로 복사 또는 link
  3. 새 클러스터를 옛 데이터로 부팅

--link 모드면 초 단위 완료(메타데이터만 처리).

사전 준비 

# 두 메이저 PostgreSQL 모두 설치
sudo dnf install -y postgresql17-server postgresql18-server

# 새 18 클러스터 initdb — 옛 클러스터와 같은 옵션
sudo -u postgres /usr/pgsql-18/bin/initdb \
  -D /var/lib/pgsql/18/data \
  --encoding=UTF8 --locale=C.UTF-8 --data-checksums

새 클러스터는 옵션이 옛과 일치해야 — --data-checksums, --locale, --encoding.

옛 클러스터 정지 + pg_upgrade 실행 

# 옛 클러스터 정지
sudo systemctl stop postgresql-17

# pg_upgrade 호출
sudo -u postgres /usr/pgsql-18/bin/pg_upgrade \
  --old-bindir=/usr/pgsql-17/bin \
  --new-bindir=/usr/pgsql-18/bin \
  --old-datadir=/var/lib/pgsql/17/data \
  --new-datadir=/var/lib/pgsql/18/data \
  --link

--link는 hard link — 데이터 크기와 무관하게 빠릅니다.

--check만 먼저 실행해 호환성·전제 검증:

sudo -u postgres /usr/pgsql-18/bin/pg_upgrade \
  --old-bindir=/usr/pgsql-17/bin --new-bindir=/usr/pgsql-18/bin \
  --old-datadir=/var/lib/pgsql/17/data --new-datadir=/var/lib/pgsql/18/data \
  --check

문제 없으면 실제 실행합니다.

pg_upgrade 출력 

Performing Consistency Checks
-----------------------------
Checking cluster versions                                   ok
Checking database user is the install user                  ok
...

Performing Upgrade
------------------
Analyzing all rows in the new cluster                       ok
Freezing all rows in the new cluster                        ok
Deleting files from new pg_xact                             ok
Copying old pg_xact to new server                           ok
...

Upgrade Complete
----------------
Optimizer statistics are not transferred by pg_upgrade so,
once you start the new server, consider running:
    /usr/pgsql-18/bin/vacuumdb --all --analyze-in-stages

ANALYZE 필수 — 통계가 안 옮겨와서.

새 클러스터 기동 

# 옛 서비스 정지·새 서비스 활성
sudo systemctl disable postgresql-17
sudo systemctl enable --now postgresql-18

# 통계 생성 (단계별)
sudo -u postgres /usr/pgsql-18/bin/vacuumdb --all --analyze-in-stages

--analyze-in-stages는 빠르게 일부 통계 → 점진적으로 정확합니다.

확장 호환성

확장이 새 메이저에 같은 버전 또는 호환이어야 합니다.

-- 새 클러스터에서
SELECT * FROM pg_available_extensions;
SELECT * FROM pg_extension;

종종 확장도 업그레이드 필요:

ALTER EXTENSION pgvector UPDATE;
ALTER EXTENSION pg_partman UPDATE;

운영 전 검증

  • 모든 application healthcheck
  • 핵심 쿼리 EXPLAIN 비교 (plan 변화)
  • pg_stat_statements reset 후 추세 추적

한계와 주의

항목메모
양쪽 메이저 OS 패키지 모두 설치돼 있어야디스크 여유
--link 후 옛 클러스터 재기동 안 됨hard link 변경됨 — 백업으로만 복구
extension의 메이저 호환사전 점검
logical replication slot옛 슬롯은 PG 17 이전 안 옮겨짐 — PG 17부터 일부 가능
timeline새 timeline 시작
매니지드 클라우드콘솔 in-place upgrade — 자체 관리

매니지드 클라우드의 메이저 업그레이드 

# AWS RDS
aws rds modify-db-instance \
  --db-instance-identifier mydb \
  --engine-version 18.0 \
  --allow-major-version-upgrade \
  --apply-immediately

콘솔의 Modify + Engine Version 변경. 수 분 다운타임.

Azure·Cloud SQL도 콘솔에서 in-place.

매니지드는 자체 pg_upgrade·logical replication 기반을 자동으로. 운영자는 결정·점검 시간 잡기만.

다운타임 어림 

pg_upgrade --link (1TB DB) — 1~5분
pg_upgrade --copy (1TB DB) — 1~3시간 (디스크 속도)
pg_dump + restore (1TB) — 수 시간~하루
logical replication 무중단 — 거의 0

롤백 계획

--link 후엔 옛 클러스터 못 씀. 롤백 = 백업으로 복원 = 시간 큽니다.

권장 절차:

  1. 업그레이드 전 백업·snapshot
  2. staging에서 동일 절차로 시뮬레이션
  3. 운영 점검 시간에 짧게
  4. 새 클러스터 검증 후 트래픽 전환
  5. 옛 클러스터·백업은 1~2주 유지

정리

  • pg_upgrade –link = 표준 빠른 in-place 업그레이드
  • 양쪽 메이저 PostgreSQL 모두 설치 + 빈 새 클러스터 initdb
  • --check로 사전 검증
  • 업그레이드 후 ANALYZE 필수
  • 확장 호환성·logical slot 한계 점검
  • 매니지드는 콘솔로 in-place
  • 무중단은 logical replication (다음 절)

다음 절(18.4)에서는 다운타임 거의 0의 — logical 복제 기반 무중단 업그레이드를 봅니다.

18.2 MySQL → PostgreSQL18.4 로지컬 복제 기반 무중단 업그레이드