pg_upgrade 사용

이 가이드는 pg_upgrade를 사용하여 AgensGraph 클러스터의 주 버전(major-version) 업그레이드를 수행하는 방법을 설명합니다. 예를 들어 AgensGraph 2.16 (PostgreSQL 16) 에서 **AgensGraph 2.17 (PostgreSQL 17)**로의 업그레이드입니다. 아래 단계는 그래프를 포함한 2.16 클러스터를 업그레이드한 후 그래프, 레이블, 정점, 간선, 속성이 보존되었음을 확인하여 검증되었습니다. 실제 명령과 출력이 포함된 완전한 실습 예제는 데모를 참고하십시오.

pg_upgrade의 동작 방식

pg_upgrade는 데이터를 덤프하고 다시 로드하지 않고 주 버전 업그레이드를 제자리에서 (in-place) 수행합니다. 새 클러스터의 시스템 카탈로그를 생성한 다음 기존 사용자 데이터 파일을 재사용하므로, 대용량 데이터베이스에서도 업그레이드가 빠릅니다. AgensGraph는 그래프를 일반 PostgreSQL 스키마와 테이블로 저장하기 때문에, 그래프 데이터는 관계형 데이터와 동일한 방식으로 마이그레이션됩니다.

시작하기 전에

AgensGraph 2.17을 기존 2.16 설치와 별도의 위치에 설치하십시오. 기존 설치를 덮어쓰지 마십시오. pg_upgrade는 양쪽 바이너리가 모두 필요하며, 2.16을 그대로 유지하면 롤백이 가능합니다.
디스크 공간. 기본적으로 pg_upgrade는 데이터 파일을 복사하므로, 두 번째 복사본을 위한 공간이 필요합니다. --link 옵션은 대신 하드 링크를 사용하여(거의 즉시 완료되며 추가 공간이 거의 필요 없음) 동작하지만, 두 데이터 디렉터리가 같은 파일 시스템에 있어야 하며 새 서버가 시작된 후에는 더 이상 롤백할 수 없습니다.
새 설치를 기존 설치와 일치시키십시오. 기존 클러스터가 사용하는 외부 모듈(예: pgvector)은 업그레이드 전에 2.17 설치에도 설치되어 있어야 합니다. AgensGraph의 그래프 기능은 서버 자체에 내장되어 있으므로, 다시 생성해야 할 익스텐션은 없습니다.
모든 명령은 데이터 디렉터리를 소유한 운영 체제 사용자(AgensGraph를 설치/실행한 사용자)로 실행하십시오.

아래 명령은 다음 변수를 사용합니다. 사용 환경에 맞게 설정하십시오:

# old (2.16) and new (2.17) installation directories
export OLD=/usr/local/agensgraph-2.16
export NEW=/usr/local/agensgraph-2.17
# data directories
export OLDDATA=$OLD/data
export NEWDATA=$NEW/data

1단계 — 기존 서버 중지

pg_upgrade는 실행되는 동안 두 클러스터가 모두 중지되어 있어야 합니다.

$OLD/bin/pg_ctl -D $OLDDATA stop

2단계 — 새 클러스터 초기화

빈 2.17 클러스터를 생성합니다. 기존 클러스터와 동일한 슈퍼유저, 인코딩, 로케일을 사용하십시오(여기서 슈퍼유저는 postgres입니다):

$NEW/bin/initdb -D $NEWDATA -U postgres --encoding=UTF8

3단계 — 호환성 확인

먼저 --check 옵션과 함께 pg_upgrade를 실행합니다. 이는 두 클러스터를 검증하며 아무것도 변경하지 않습니다:

$NEW/bin/pg_upgrade \
  -b $OLD/bin -B $NEW/bin \
  -d $OLDDATA -D $NEWDATA \
  -U postgres --check

확인이 성공하면 다음과 같이 끝납니다:

Performing Consistency Checks
-----------------------------
Checking cluster versions                                     ok
...
Checking for new cluster tablespace directories               ok

*Clusters are compatible*

pg_upgrade를 데이터베이스 슈퍼유저로 실행하십시오. -U 옵션으로 슈퍼유저 롤을 전달하십시오. 예를 들어 클러스터의 슈퍼유저가 postgres라면 -U postgres를 사용하십시오. 기본적으로 pg_upgrade는 운영 체제 사용자로 연결하는데, 이는 보통 데이터베이스 롤이 아닙니다.

4단계 — 업그레이드 실행

--check 없이 동일한 명령을 실행합니다:

$NEW/bin/pg_upgrade \
  -b $OLD/bin -B $NEW/bin \
  -d $OLDDATA -D $NEWDATA \
  -U postgres

다음과 같이 완료됩니다:

Upgrade Complete
----------------

데이터 파일을 복사하는 대신 하드 링크를 사용하려면, 확인 명령과 업그레이드 명령 모두에 --link를 추가하십시오.

5단계 — 새 서버 시작

$NEW/bin/pg_ctl -D $NEWDATA -l $NEW/logfile start

6단계 — 업그레이드 후 작업

pg_upgrade는 옵티마이저 통계를 이전하지 않으므로, 통계가 다시 생성되기 전까지는 실행 계획 품질이 저하됩니다. 통계를 다시 생성하십시오:

$NEW/bin/vacuumdb -U postgres --all --analyze-in-stages

업그레이드된 클러스터가 올바르게 동작하는 것을 확인한 후에는, pg_upgrade를 실행한 디렉터리에 생성된 스크립트를 사용하여 기존 클러스터의 데이터 파일을 삭제하십시오:

./delete_old_cluster.sh

롤백

기본(복사) 모드로 업그레이드했고 아직 delete_old_cluster.sh를 실행하지 않았다면, 기존 2.16 데이터 디렉터리는 변경되지 않은 상태입니다. 롤백하려면 새 서버를 중지하고 기존 서버를 다시 시작하십시오:

$NEW/bin/pg_ctl -D $NEWDATA stop
$OLD/bin/pg_ctl -D $OLDDATA -l $OLD/logfile start

--link으로 업그레이드한 경우, 두 클러스터가 데이터 파일을 공유하기 때문에 새 서버가 시작된 후에는 롤백이 불가능합니다. 대신 백업에서 복원하십시오.

pg_upgrade 옵션 참조

옵션	설명
`-b, --old-bindir`	기존 AgensGraph의 `bin` 디렉터리 (환경 변수: `PGBINOLD`)
`-B, --new-bindir`	새 AgensGraph의 `bin` 디렉터리 (환경 변수: `PGBINNEW`)
`-d, --old-datadir`	기존 클러스터 데이터 디렉터리 (환경 변수: `PGDATAOLD`)
`-D, --new-datadir`	새 클러스터 데이터 디렉터리 (환경 변수: `PGDATANEW`)
`-U, --username`	연결에 사용할 설치 슈퍼유저 (환경 변수: `PGUSER`)
`-c, --check`	호환성만 확인하며 아무것도 변경하지 않음
`-k, --link`	데이터 파일을 복사하는 대신 하드 링크
`-j, --jobs`	동시에 사용할 프로세스 수
`-p` / `-P`	실행 중 기존 / 새 클러스터에 사용할 포트
`-r, --retain`	성공적으로 실행된 후 SQL 및 로그 파일 유지
`-v, --verbose`	자세한 출력

디렉터리 및 연결 옵션은 위에 표시된 환경 변수를 통해서도 제공할 수 있으며, 이 경우 해당 명령줄 플래그는 생략할 수 있습니다.