pg_upgrade 란?

PostgreSQL v8.4.X 이상에서 PostgreSQL 의 Major 릴리스로의 업그레이드를 지원합니다.
pg_upgrade (과거에는 pg_migrator 라고 함)를 사용하면 PostgreSQL 데이터 파일에 저장된 데이터 를 Major version Upgrade에 필요한 데이터들을 Dump / Reload 없이 업그레이드할 수 있습니다.

Minor version Upgrade 에는 필요하지 않습니다.
PostgreSQL 릴리즈는 시스템 테이블의 레이아웃을 자주 변경하는 새로운 기능을 정기적으로 추가하지만 내부 데이터 저장 형식은 거의 변경되지 않습니다.

따라서 pg_upgrade 는 새 시스템 테이블을 생성하고 단순히 이전 사용자 데이터 파일을 재사용함으로써 신속한 업그레이드를 수행합니다.
향후 릴리스에서 이전 데이터 형식을 읽을 수 없도록 데이터 저장 형식을 변경하는 경우 pg_upgrade 를 해당 업그레이드에 사용할 수 없습니다. (커뮤니티는 이러한 상황을 피하기 위해 노력할 것입니다.)
pg_upgrade 는 32/64비트 바이너리를 포함하여 호환 가능한 컴파일 시간 설정을 확인하여 이전 클러스터와 새 클러스터가 바이너리 호환되는지 확인 합니다.

pg_upgrade 로 확인할 수는 없지만 모든 외부 모듈도 바이너리와 호환되는 것도 중요합니다 .
pg_upgrade 는 스냅샷 및 베타 릴리스를 포함하여 8.4.X 이상에서 PostgreSQL 의 현재 주요 릴리스로의 업그레이드를 지원합니다.

Synopsis

pg_upgrade -b old_binary_dir [-B new_binary_dir] -d old_config_dir -D new_config_dir [option]…

Option

• -b bindir or –old-bindir = bindir
  이전 PostgreSQL 바이너리 디렉토리 (environment variable PGBINOLD)

• -B bindir or –new-bindir = bindir
  새로운 PostgreSQL 바이너리 디렉토리 (environment variable PGBINNEW)

• -c or –check
  데이터 변경 없이 양쪽 클러스터 체크

• -d configdir or --old-datadir = configdir
  이전 데이터베이스 클러스터 환경 디렉토리 (environment variable PGDATAOLD)

• -D configdir or –new-datadir = configdir
  새로운 데이터베이스 클러스터 환경 디렉토리 (environment variable PGDATANEW)

• -j njobs or –jobs = njobs
  수행 시 사용할 프로세스나 스레드 수

• -kor –link
  새로운 클러스터에 파일을 복사하는 것 대신 하드 링크를 사용합니다.

• -N or –no-sync
  기본적으로, pg_upgrade 는 업그레이드된 클러스터의 모든 파일이 디스크에 안전하게 기록될 때 까지 대기합니다. 해당 옵션을 사용하면 pg_upgrade 는 대기하지 않고 반환되어 더 빠르지만 후속 운영 체제 충돌로 인해 데이터 디렉토리가 손상될 수 있습니다. 일반적으로 해당 옵션은 테스트에 유용하지만 제품 설치시에는 사용해선 안됩니다.

• -o options or –old-options options
  이전 postgres 명령에 직접 전달되는 옵션; 여러 옵션 호출이 추가됩니다.

• -O options or –new-options options
  새로운 postgres 명령에 직접 전달되는 옵션; 여러 옵션 호출이 추가됩니다.

• -p port or –old-port = port
  이전 클러스터 포트 (environment variable PGPORTOLD)

• -P port or --new-port = port
  새로운 클러스터 포트 (environment variable PGPORTNEW)

• -r or –retain
  새로운 클러스터 포트

• -s dir or –socketdir = dir
  새로운 클러스터 포트 (environment variable PGSOCKETDIR)

• -v or –verbose
  상세 로깅 활성화

• -V or –version
  버전 정보 표시 후 종료

• –clone
  파일을 새 클러스터에 복사하는 대신 효율적인 파일 복제(일부 시스템에서는 ” reflinks ” 라고도 함 )를 사용합니다. 이로 인해 데이터 파일이 거의 즉각적으로 복사 되어 이전 클러스터를 그대로 유지하면서 -k/ --link 의 속도 이점을 얻을 수 있습니다.파일 복제는 일부 운영 체제 및 파일 시스템에서만 지원됩니다. 옵션을 사용했는데 지원되지 않으면 pg_upgrade 실행에 오류가 발생합니다. 현재 Btrfs 및 XFS(reflink 지원으로 생성된 파일 시스템)가 있는 Linux(커널 4.5 이상)와 APFS가 있는 macOS에서 지원됩니다.

• -? or –help
  도움말을 표시한 후 종료

Usage

다음은 pg_upgrade 로 업그레이드를 수행하는 단계입니다.

Single 서버를 업그레이드 하는 방법과 Replication 서버를 업그레이드 하는 과정이 모두 담겨 있어 천천히 읽어 보시면 좋습니다.

1. 선택적으로 이전 클러스터 백업

새로운 클러스터 설치시 이전 클러스터의 경로와 중복 되지 않도록 하기 위한 작업입니다.
버전별 설치 디렉토리를 사용하는 경우 이전 클러스터를 이동할 필요가 없습니다.
설치 디렉토리가 특정 버전이 아닌 경우 새 PostgreSQL 설치를 방해하지 않도록 현재 PostgreSQL 설치 디렉토리를 바꾸어줘야 합니다.
현재 PostgreSQL 서버를 종료한 뒤 PostgreSQL 설치 디렉토리의 이름을 바꾸는 것이 안전합니다.
이전 디렉토리가 /usr/local/pgsql 이라고 가정하면 다음을 수행할 수 있습니다.

mv /usr/local/pgsql /usr/local/pgsql.old

2. 소스 설치의 경우 새 버전을 빌드

새 버전을 빌드할 때 이전 클러스터와 호환되는 설정 플래그를 사용하여 PostgreSQL 소스를 빌드해야 합니다.
pg_upgrade 는 pg_controldata 를 확인하여 업그레이드를 시작하기 전에 모든 설정이 호환되는지 확인합니다.

3. 새로운 PostgreSQL 설치

새로운 PostgreSQL 의 바이너리 및 파일을 설치합니다.
pg_upgrade 는 기본 설치에 포함되어 있습니다.
소스 설치의 경우 사용자 정의 위치에 새 서버를 설치하려면 아래와 같이 prefix 를 사용하여 설치 합니다.

make prefix=/usr/local/pgsql.new install

4. 새로운 PostgreSQL 클러스터 초기화

initdb 바이너리를 사용하여 새로운 클러스터를 초기화합니다.
이전 클러스터와 일치하는 호환 가능한 initdb 설정을 사용합니다.
새로운 클러스터를 시작할 필요는 없습니다.

5. extension 및 shared object files 설치

이전 클러스터가 extension, shared object files 및 사용자 정의 모듈 등을 사용했다면
일반적으로 운영 체제 명령을 통해 새 서버 바이너리와 호환되게 끔 동일하게 설치해야합니다.
스키마 정의(CREATE SCHEMA …) 등은 하지 마십시오. 해당 내용 등은 이전 클러스터에서 복제되기 때문입니다.

6. 사용자 지정 full text search file 복사

사용자 지정 전체 텍스트 검색 파일 ( dictionary, synonym, thesaurus, stop words ) 등을 이전 클러스터에서 새 클러스터로 복사합니다.

7. 인증 설정

pg_upgrade 는 실행되면 이전 클러스터와 새로운 클러스터에 몇번씩 접속합니다.
따라서 양 서버에 접속이 수월하도록 pg_hba.conf 파일 설정에 peer 인증을 하거나 ~/.pgpass 파일을 사용할 수도 있습니다.

8. 양쪽 클러스터 다운

ex)

pg_ctl -D /var/lib/pgsql/9.6/data stop
pg_ctl -D /var/lib/pgsql/14/data stop

위와 같은 예시로 양쪽 클러스터를 모두 정상 종료합니다.

9. 만약 Replication 업그레이드면? Standby 서버 업그레이드 준비!

11단계의 섹션에 설명된 방법을 사용하여 Standby 서버를 업그레이드하는 경우 pg_controldata 바이너리를 실행하여 Standby 서버가 실행 중인지 확인합니다.

“Lastest checkpoint location” 값이 모든 클러스터에서 일치하는 지 확인합니다.

(Standby 서버가 Primary 서버보다 먼저 종료되었거나 이전 대기 서버가 계속 실행 중인 경우 불일치가 발생합니다.)
또한 Primary 서버에서 postgresql.conf 파일에서 wal_level 이 minimum 으로 설정되지 않았는지 확인합니다.

10. pg_upgrade 실행

pg_upgrade 를 실행할 땐 항상 이전 클러스터의 바이너리가 아닌 새로운 클러스터의 바이너리를 실행합니다.
pg_upgrade 는 이전 클러스터의 데이터 및 실행 디렉토리가 필요합니다.
또한 사용자 및 포트 값을 지정하고 기본 복사 동작 대신 데이터 파일을 연결하거나 복제할 지 여부를 지정할 수 있습니다.

Link 모드를 사용하면 업그레이드가 훨씬 빨라지고 디스크 공간을 덜 사용하지만 업그레이드 후 새로운 클러스터를 시작하면 이전 클러스터에 액세스할 수 없습니다.
또한 Link 모드에서는 이전 클러스터 데이터 디렉토리와 새로운 클러스터 데이터 디렉토리가 동일한 파일 시스템에 있어야 합니다.
테이블 스페이스와 pg_wal 은 서로 다른 파일 시스템에 있을 수 있습니다.

Clone 모드는 동일한 속도 및 디스크 공간 이점을 제공하지만 새로운 클러스터가 시작된 후 이전 클러스터를 사용할 수 없게 만들지 않습니다.
Clone 모드는 이전 데이터 디렉토리와 새로운 데이터 디렉토리가 동일한 파일 시스템에 있어야 합니다.

해당 모드는 특정 운영 체제 및 파일 시스템에서만 사용할 수 있습니다.
–jobs 옵션을 사용하면 여러 CPU 코어를 파일 복사 / 링크에 사용하고 데이터베이스 스키마를 병렬로 덤프 및 복원할 수 있습니다.
테이블 스페이스 수에 맞춰 코어수를 지정해주는 것이 좋습니다.

해당 옵션은 멀티 프로세서 시스템에서 실행되는 다중 데이터베이스 서버를 업그레이드하는 시간을 크게 줄일 수 있습니다.
Windows 사용자의 경우 관리 계정에 로그인한 다음 postgres 사용자로 셸을 시작하고 적절한 경로를 설정해야 합니다.

RUNAS /USER:postgres “CMD.EXE”
SET PATH=%PATH%;C:Program FilesPostgreSQL15bin;

그런 다음 인용된 디렉토리로 pg_upgrade를 실행합니다.

pg_upgrade.exe
–old-datadir “C:/Program Files/PostgreSQL/9.6/data”
–new-datadir “C:/Program Files/PostgreSQL/15/data”
–old-bindir “C:/Program Files/PostgreSQL/9.6/bin”
–new-bindir “C:/Program Files/PostgreSQL/15/bin”

바이너리를 실행하면, pg_upgrade 는 두 클러스터가 호환되는지 확인한 다음 업그레이드를 수행합니다.
이전 서버가 실행 중인 경우에도 pg_upgrade –check 옵션을 사용하여 수행이 가능할지 확인만 할 수도 있습니다.

Link 모드 또는 Clone 모드를 사용하려는 경우 –link 또는 –clone 옵션을 –check 옵션과 함께 사용하여 모드별 체크를 활성화해야 합니다.
당연히 업그레이드 중에는 아무도 클러스터에 액세스하지 않아야 합니다.

pg_upgrade는 의도하지 않은 클라이언트 연결을 방지하기 위해 기본적으로 포트 50432에서 서버를 실행합니다.
이전 클러스터와 새 클러스터가 동시에 실행되지 않으므로 업그레이드를 수행할 때 두 클러스터에 대해 동일한 포트 번호를 사용할 수 있습니다.

단, 실행 중인 이전 서버를 확인할 때는 이전 포트 번호와 새 포트 번호가 달라야 합니다.
데이터베이스 스키마를 복원하는 동안 오류가 발생하면 pg_upgrade가 종료되고 아래 17단계에 설명된 대로 이전 클러스터로 되돌려야 합니다.

pg_upgrade를 다시 시도하려면 pg_upgrade 스키마 복원이 성공하도록 이전 클러스터를 수정해야 합니다.
문제가 contrib 모듈인 경우 모듈이 사용자 데이터를 저장하는 데 사용되지 않는다고 가정하고 업그레이드 후 이전 클러스터에서 contrib 모듈을 제거하고 새 클러스터에 설치해야 할 수 있습니다.

11. Streaming Replication 와 Log-shipping Standby 서버 업그레이드

Link 모드를 사용하지 않았거나 rsync 를 사용하지 않으려는 경우 또는 더 쉬운 수행을 원하는 경우 해당 섹션을 건너뛰고 pg_upgrade 가 완료된 후 Primary 서버가 실행되면 Standby 서버를 다시 구축하세요.

Link 모드를 사용했고 Streaming Replication 나 Log-shipping 의 Standby 서버가 있는 경우 다음 단계에 따라 빠르게 업그레이드할 수 있습니다. Standby 서버에서 pg_upgrade 를 실행하지 않고 Primary 서버에서 rsync 를 실행합니다.

아직 Primary 서버를 시작하지 마세요.

11-1. Standby 서버에 새로운 PostgreSQL 바이너리 설치

• Standby 서버에 새로운 바이너리나 파일들이 설치되어 있는지 확인합니다.

11-2. Standby 서버에 데이터 디렉토리 확인하기

• Standby 서버에 데이터 디렉터리가 존재하지 않거나 비어있는지 확인합니다.
• initdb가 실행된 경우 대기 서버의 새 데이터 디렉토리를 삭제하십시오.

11-3. extension 및 shared object files 설치

• 새로운 Primary 클러스터에 설치한 동일한 파일들이 있다면, 새로운 Standby 서버에도 설치해주세요.

11-4. Configuration file 백업

• 예를 들어, postgresql.conf , postgresql.auto.conf , pg_hba.conf 파일 등 이전 디렉토리에서 유지해야하는 파일들을 백업합니다.

11-5. rsync 실행

• Link 모드를 사용할 때 Standby 서버는 rsync 를 사용하여 빠르게 업그레이드할 수 있습니다.
• 수행을 위해서 이전 Primary 서버 클러스터에서 아래와 같이 실행합니다.

rsync –archive –delete –hard-links –size-only –no-inc-recursive old_cluster new_cluster remote_dir

• old_cluster 및 new_cluster 는 Primary 의 현재 디렉토리에 상대적입니다,
• Primary 및 Standby 서버에 지정된 디렉토리 구조는 일치해야 합니다.
• 원격 디렉토리 지정에 대한 자세한 내용은 rsync 메뉴얼 페이지를 참조하십시오.

테이블 스페이스나 데이터 디렉토리 외부에 pg_wal 파일을 재배치한 경우 해당 디렉토리들도 rsync 실행해야 합니다.

rsync 가 완료되었다면 Streaming replication 또는 log shipping standby 서버를 구성하면 됩니다.

12. configuration 파일 구성

이전 클러스터와 일치하도록 새로운 클러스터의 구성 파일을 적용합니다.
ex) postgresql.conf , pg_hba.conf , postgresql.auto.conf 파일 등

13. 새로운 서버를 기동

새로운 서버를 기동합니다. 11단계에서 Standby 서버를 구성했다면 시작할 수 있습니다.

14. 업그레이드 후 작업

업그레이드 후 작업이 필요한 경우 pg_upgrade 는 실행을 마치면서 경고를 발생합니다.
또한, 관리자가 실행해야 하는 스크립트 파일도 생성합니다.

스크립트 파일은 업그레이드 후 처리가 필요한 각 데이터베이스에 연결됩니다.
스크립트는 임의의 순서로 실행할 수 있으며 실행된 후에는 삭제할 수 있습니다.

ex) psql –username=postgres –file=script.sql postgres

15. 통계

옵티마이저 통계는 pg_upgrade에 의해 전송되지 않기 때문에 업그레이드 종료 시 해당 정보를 재생성하는 명령을 실행하라는 지시가 표시됩니다.
새 클러스터와 일치하도록 연결 매개변수를 설정해야 할 수도 있습니다.

16. 이전 클러스터 삭제

업그레이드에 만족하면 pg_upgrade가 완료될 때 언급된 스크립트를 실행하여 이전 클러스터의 데이터 디렉토리를 삭제할 수 있습니다. (이전 데이터 디렉터리 내에 사용자 정의 테이블스페이스가 있는 경우 자동 삭제가 불가능합니다.)
이전 설치 디렉터리(예: bin, share)를 삭제할 수도 있습니다.

17. 이전 클러스터로 되돌리기

pg_upgrade 를 실행한 후 이전 클러스터로 되돌리려는 경우 몇가지 방법이 있습니다.

–check 옵션이 사용된 경우 이전 클러스터가 변경되지 않았기 때문에 다시 시작할 수 있습니다.

–link 옵션을 사용하지 않은 경우 이전 클러스터가 변경되지 않았기 때문에 다시 시작할 수 있습니다.

–link 옵션이 사용된 경우 데이터 파일은 이전 클러스터와 새로운 클러스터 간에 공유될 수 있습니다.

pg_upgrade 가 연결이 시작되기 전에 중단된 경우 이전 클러스터가 변경되지 않았기 때문에 다시 시작할 수 있습니다.

새 클러스터를 시작하지 않은 경우 링크가 시작될 때 .old 접미사가 $PGDATA/global/pg_control에 추가되었다는 점을 제외하고 이전 클러스터는 수정되지 않았습니다.
이전 클러스터를 재사용하려면 $PGDATA/global/pg_control에서 .old 접미사를 제거합니다. 그런 다음 이전 클러스터를 다시 시작할 수 있습니다.

새 클러스터를 시작한 경우 공유 파일에 기록되었으며 이전 클러스터를 사용하는 것이 안전하지 않습니다. 이 경우 이전 클러스터를 백업에서 복원해야 합니다.

출처 : https://www.postgresql.org/docs/current/pgupgrade.html

새 클러스터를 시작한 경우 공유 파일에 기록되었으며 이전 클러스터를 사용하는 것이 안전하지 않습니다. 이 경우 이전 클러스터를 백업에서 복원해야 합니다.

지금까지 ’PostgreSQL pg_upgrade’에 관해 알아보았습니다

‘PostgreSQL postgres_fdw’를 바로 이어서 확인해보세요!