메이저 버전 업그레이드를 미루는 이유는 대개 하나다. 덤프 받고 복원하는 데 밤을 새워야 할 것 같아서다. 수백 GB짜리 DB를 pg_dumpall로 내렸다가 다시 올리면 테이블 크기에 따라 몇 시간이 날아간다. 그래서 17이 나온 지 한참인데도 운영 DB는 여전히 구버전에 머무는 경우를 자주 본다. pg_upgrade --link를 쓰면 데이터 파일을 복사하지 않고 하드링크만 다시 걸기 때문에 데이터 크기와 거의 무관하게 다운타임이 짧다.
결론부터 말하자면, 같은 파일시스템에 구/신 데이터 디렉터리를 두고 pg_upgrade --link를 돌리면 수백 GB 규모라도 실제 중단 시간을 몇 분 수준으로 끝낼 수 있다. 대신 새 클러스터를 한 번이라도 기동하면 구 클러스터로는 돌아갈 수 없다. 그래서 작업 전 백업과 --check 사전 점검이 전부라고 해도 과장이 아니다.
1. pg_upgrade와 --link 하드링크 모드
pg_upgrade는 구버전 데이터 디렉터리의 사용자 테이블 파일을 그대로 두고, 시스템 카탈로그만 새 버전 형식으로 옮겨 주는 도구다. 메이저 버전이 올라가도 테이블/인덱스의 디스크 저장 포맷은 바뀌지 않는 경우가 많아서 가능한 방식이다. 데이터 자체를 다시 쓰지 않으니 덤프/복원보다 훨씬 빠르다.
파일을 옮기는 방법은 여러 가지인데, 기본값은 --copy로 파일을 통째로 복사한다. --link는 복사 대신 하드링크를 만든다. 디스크에는 같은 블록을 가리키는 이름이 하나 더 생길 뿐이라 데이터 크기와 상관없이 순식간에 끝나고 추가 디스크도 거의 쓰지 않는다. 단 하드링크는 같은 파일시스템 안에서만 걸리므로, 구 데이터 디렉터리와 신 데이터 디렉터리가 동일한 파일시스템(마운트)에 있어야 한다. 별도 볼륨에 신규 클러스터를 만들면 --link는 실패한다.
PostgreSQL 18에는 --swap, --clone, --copy-file-range 같은 모드도 있다. --clone은 CoW(copy-on-write) 복제라 구 클러스터를 보존하면서도 빠르지만 Btrfs, XFS, APFS 같은 특정 파일시스템에서만 동작한다. 범용성과 속도를 같이 챙기려면 여전히 --link가 현실적인 선택이다.
2. 새 바이너리 설치와 신규 클러스터 초기화
17과 18 바이너리가 한 서버에 함께 있어야 한다. 배포판 패키지는 버전별로 경로가 갈린다. RHEL 계열 PGDG 저장소 기준으로 18을 추가 설치하면 대략 다음과 같다.
$ sudo dnf install -y postgresql18-server postgresql18-contrib $ /usr/pgsql-18/bin/postgres --version postgres (PostgreSQL) 18.1
신규 18 클러스터를 비어 있는 상태로 초기화한다. 여기서 한 번 걸린다. PostgreSQL 18부터 initdb가 데이터 체크섬을 기본으로 켠다. 반면 17 이전은 체크섬이 기본 꺼짐이었다. pg_upgrade는 구/신 클러스터의 체크섬 설정이 일치해야 하므로, 체크섬 없이 만든 17을 그대로 올리려면 새 클러스터도 체크섬을 꺼서 맞춰야 한다.
# 구 클러스터 체크섬 상태 확인
$ /usr/pgsql-17/bin/pg_controldata -D /var/lib/pgsql/17/data | grep -i checksum
Data page checksum version: 0
# 0이면 체크섬 꺼짐 -> 새 클러스터도 꺼서 초기화
$ sudo -u postgres /usr/pgsql-18/bin/initdb \
-D /var/lib/pgsql/18/data --no-data-checksums
구 클러스터가 체크섬을 쓰고 있었다면(값이 1) --no-data-checksums를 빼고 기본값으로 초기화하면 된다. 이 설정이 어긋나면 --check 단계에서 바로 걸러진다.
확장 모듈을 쓴다면 같은 이름의 .so 파일이 18 쪽 lib 디렉터리에도 있어야 한다. postgresql18-contrib처럼 패키지로 설치하면 자동으로 들어오지만, 직접 빌드한 확장은 새 버전에 맞춰 다시 빌드해 넣어야 한다. 이 단계에서 CREATE EXTENSION을 미리 실행하지는 않는다. 스키마 정의는 구 클러스터에서 그대로 복제된다.
3. --check로 먼저 걸러내기
실제 업그레이드 전에 --check를 돌린다. 이 옵션은 데이터를 건드리지 않고 호환성만 본다. 구 서버가 떠 있는 상태에서도 돌릴 수 있어서, 작업 창을 잡기 며칠 전에 미리 돌려 두면 좋다. 환경 변수로 경로를 넘기면 명령이 짧아진다.
$ export PGBINOLD=/usr/pgsql-17/bin $ export PGBINNEW=/usr/pgsql-18/bin $ export PGDATAOLD=/var/lib/pgsql/17/data $ export PGDATANEW=/var/lib/pgsql/18/data $ sudo -u postgres /usr/pgsql-18/bin/pg_upgrade --check Performing Consistency Checks ----------------------------- Checking cluster versions ok Checking database user is the install user ok Checking for prepared transactions ok Checking data type usage ok Checking for presence of required libraries ok Checking database connection settings ok *Clusters are compatible*
여기서 자주 막히는 지점이 있다. reg* 계열 데이터 타입이다. regclass, regrole, regtype은 넘어가지만 regproc, regconfig, regoper 같은 타입이 테이블 컬럼에 쓰이면 업그레이드가 막힌다. OID를 직접 참조하는 타입이라 버전이 바뀌면 의미가 깨지기 때문이다. --check가 해당 컬럼 목록을 파일로 떨궈 주니, 그걸 보고 타입을 바꾸거나 컬럼을 정리한 뒤 다시 돌린다.
확장 라이브러리가 새 클러스터에 없으면 "could not load library" 메시지가 나온다. 2단계에서 빠뜨린 .so가 있다는 뜻이라 그 확장을 18 쪽에 설치하면 해결된다.
4. 양쪽을 멈추고 업그레이드 실행
본 작업이 시작되는 지점부터가 다운타임이다. 애플리케이션 연결을 끊고 구 클러스터를 정상 종료한다. pg_upgrade는 구 클러스터가 비정상 종료된 상태를 거부하므로 fast 모드로 깔끔하게 내린다.
$ sudo systemctl stop postgresql-17 # 또는 $ sudo -u postgres /usr/pgsql-17/bin/pg_ctl -D /var/lib/pgsql/17/data -m fast stop
이제 --link로 실제 업그레이드를 돌린다. --jobs는 병렬 처리 수인데, PostgreSQL 18부터는 데이터베이스 단위 점검도 병렬로 돌아서 DB가 여러 개일 때 체감이 크다. CPU 코어 수 근처 값을 준다.
$ sudo -u postgres /usr/pgsql-18/bin/pg_upgrade --link --jobs 4 ... Adding ".old" suffix to old global/pg_control ok If you want to start the old cluster, you will need to remove the ".old" suffix from /var/lib/pgsql/17/data/global/pg_control.old. Because "link" mode was used, the old cluster cannot be safely started once the new cluster has been started. Upgrade Complete ----------------
출력에서 눈여겨볼 대목이 구 클러스터의 global/pg_control에 .old가 붙었다는 줄이다. pg_upgrade는 이 파일 이름을 일부러 바꿔서 구 클러스터가 실수로 기동되는 것을 막는다. 아직 새 클러스터를 띄우지 않았다면, 이 .old를 떼는 것만으로 17로 되돌릴 수 있다. 이 시점이 사실상 마지막 롤백 지점이다.
데이터 크기와 무관하게 이 단계 자체는 하드링크만 다시 거는 작업이라 짧게 끝난다. 실제 소요는 테이블/인덱스 개수(카탈로그 항목 수)에 더 좌우되며, 환경에 따라 다르지만 수만 개 객체 수준이면 대략 분 단위다.
5. 돌아갈 수 없는 선, 새 클러스터 기동
새 18 클러스터를 기동하는 순간 선을 넘는다. --link는 사용자 테이블 파일을 구/신이 공유하고 있고, 18이 뜨면서 그 파일들을 새 버전 형식으로 쓰기 시작한다. 이 뒤로는 구 17 클러스터를 안전하게 띄울 수 없다. 공유 파일이 이미 변형됐기 때문이다. 복구하려면 업그레이드 전에 받아 둔 백업으로 되돌리는 수밖에 없다.
$ sudo systemctl start postgresql-18
$ sudo -u postgres /usr/pgsql-18/bin/psql -c "SELECT version();"
version
-------------------------------------------------------------------------
PostgreSQL 18.1 on x86_64-pc-linux-gnu, compiled by gcc ...
그래서 --link 작업의 안전장치는 사실상 두 가지다. 하나는 작업 직전 받아 둔 물리 백업 또는 스냅샷이고, 다른 하나는 앞서 통과시킨 --check다. 되돌릴 수 없는 작업일수록 앞에서 거를 수 있는 건 다 걸러 두는 편이 맞다. 운영 환경이라면 작업 전 스토리지 스냅샷을 한 장 떠 두고 시작하길 권한다.
6. 통계 보존과 마무리 작업
예전에는 업그레이드 직후 플래너 통계가 비어 있어서 ANALYZE가 끝날 때까지 실행계획이 엉망이었다. 큰 DB에서는 이 재분석이 또 하나의 긴 다운타임이었다. PostgreSQL 18부터 pg_upgrade가 대부분의 옵티마이저 통계를 새 클러스터로 그대로 옮긴다. 기동 직후부터 쓸 만한 통계로 시작한다는 뜻이라, 체감 다운타임이 한 번 더 줄었다.
다만 확장 통계(extended statistics)는 넘어오지 않고, 일부 통계는 비어 있을 수 있다. 공식 안내대로 비어 있는 통계만 채우는 명령을 돌려 마무리한다.
$ sudo -u postgres /usr/pgsql-18/bin/vacuumdb --all \
--analyze-in-stages --missing-stats-only
$ sudo -u postgres /usr/pgsql-18/bin/vacuumdb --all --analyze-only
구 클러스터 삭제는 서두르지 않는다. 새 클러스터로 애플리케이션을 붙여 쿼리가 정상인지 확인한 다음에 지운다. pg_upgrade가 작업 디렉터리에 delete_old_cluster.sh를 만들어 두는데, 안을 열어 경로를 확인하고 실행하면 구 데이터 디렉터리가 지워진다. 서비스가 안정적으로 도는 걸 하루이틀 지켜본 뒤 돌려도 늦지 않다.
남은 확인거리라면 postgresql.conf와 pg_hba.conf다. pg_upgrade는 이 설정 파일을 자동으로 옮겨 주지 않으므로, 구 클러스터에서 손봤던 shared_buffers, work_mem, 접속 규칙 등을 새 클러스터 쪽에 다시 반영했는지 확인하고 재시작한다.