검토해야 할 확장 기능 및 논리적 복제 개체

업그레이드 전에 다음 사항을 확인하십시오:

확장기능

• pg_repack
• old_snapshot
• wal2json
• anon
• PostGIS

복제 슬롯

• Logical replication slots

애플리케이션 종속성 애플리케이션이 의존하는 확장 기능이나 복제 개체를 제거하는 경우, 업그레이드를 진행하기 전에 데이터 흐름과 애플리케이션 동작을 확인하십시오. 또한 특정 PostgreSQL 기능에 의존하는 애플리케이션 로직에 발생할 수 있는 장애 가능성도 고려하십시오.

pg_repack

업그레이드 전에 pg_repack 를 삭제하고, 업그레이드 후에 다시 생성하십시오. pg_repack 는 버전별 확장자를 사용하며, 클라이언트/서버 구성 요소는 PostgreSQL 의 주요 버전과 일치해야 합니다.

DROP EXTENSION pg_repack;

업그레이드 후에도 해당 확장 기능이 여전히 필요한 경우에만 이를 다시 생성하십시오.

CREATE EXTENSION pg_repack;

old_snapshot

업그레이드 전에 old_snapshot 를 삭제하십시오. PostgreSQL 18로 업그레이드한 후에는 더 이상 지원되지 않으므로 이를 다시 생성 하지 마십시오.

DROP EXTENSION old_snapshot;

wal2json 복제 슬롯

wal2json 를 논리적 디코딩에 사용하는 경우, 업그레이드 전에 관련 복제 슬롯을 모두 삭제해야 합니다. pg_upgrade 유틸리티는 복제 슬롯이 존재하는 동안 주요 버전 업그레이드를 엄격히 금지하며, 이 경우 치명적인 오류를 발생시키고 업그레이드를 중단합니다.

업그레이드 전:

1. 보류 중인 모든 WAL 데이터가 처리되었는지 확인하십시오.
2. 복제 슬롯을 사용하는 애플리케이션을 중지하십시오.
3. 복제 슬롯을 삭제하십시오:

SELECT pg_drop_replication_slot('your_slot_name');

업그레이드 후에는 필요에 따라 복제 슬롯을 다시 생성할 수 있습니다. wal2json 는 CREATE EXTENSION 를 통해 설치되는 것이 아니라, 데이터베이스 매개변수(wal_level, max_replication_slots, max_wal_senders) 및 테이블 권한을 통해 구성되며, 이러한 설정은 업그레이드를 방해하지 않는다는 점에 유의하십시오.

anon

업그레이드 전에 ‘ anon ’ 확장 프로그램을 제거하고, 업그레이드 후에도 여전히 필요한 경우 다시 활성화하십시오. anon 를 삭제하기 전에 몇 가지 추가 절차가 필요합니다.

anon 확장 프로그램이 설치되어 있는 경우, 업그레이드를 수행하기 전에 아래 단계를 따르고 관리자 권한으로 명령어를 실행하십시오.

1. (활성화된 경우) 모든 마스킹 규칙을 제거합니다.

   SELECT anon.remove_masks_for_all_columns();
   

2. 마스크된 역할 비활성화 (마스크된 역할이 있는 경우 업그레이드가 실패할 수 있습니다).

   SECURITY LABEL FOR anon ON ROLE <role_name> IS NULL;
   

3. cascade 옵션을 사용하여 anon 확장자를 제거하십시오.

   DROP EXTENSION anon CASCADE;
   

4. anon 확장 기능이 인스턴스 내의 여러 데이터베이스에 설치된 경우, 각 데이터베이스에 대해 설명된 단계를 따르십시오.

5. 업그레이드가 완료된 후, ‘ anon ’ 확장 기능을 다시 활성화하고 필요에 따라 마스킹 규칙을 다시 적용하십시오.

업그레이드를 수행하기 전에 마스킹의 일관성을 보장하기 위해, 확장자를 삭제하기 전과 후 모두 데이터를 검증할 것을 강력히 권장합니다.

PostGIS

PostGIS, 를 사용 중이라면, PostgreSQL 을 업그레이드하기 전에 먼저 PostGIS 을 업그레이드하십시오.

SELECT postgis_extensions_upgrade();

다음 쿼리를 사용하여 ‘ PostGIS ’ 확장 프로그램의 업그레이드 상태를 확인하십시오.

SELECT postgis_full_version();

Logical replication slots

업그레이드 전에 모든 논리적 복제 슬롯을 삭제하고, 업그레이드 후에 다시 생성하십시오. 논리적 슬롯은 소스 서버의 상태와 연동되어 있으므로, 업그레이드된 인스턴스에서 완전히 새로 생성해야 합니다.

SELECT pg_drop_replication_slot('<slot_name>');

논리적 복제 슬롯

업그레이드 전에 모든 논리적 복제 슬롯을 삭제하고, 업그레이드 후에 다시 생성하십시오. 논리적 복제 슬롯은 소스 서버의 상태와 연동되어 있으므로, 업그레이드된 인스턴스에서 다시 생성해야 합니다.

SELECT pg_drop_replication_slot('<slot_name>');

시작하기 전에

업그레이드를 시작하기 전에 다음 사항을 확인하십시오:

• UI, API, CLI 또는 Terraform을 사용하여 현재 배포 환경에서 버전 업그레이드가 지원되는지 확인하십시오.

  예시 (CLI):

  ibmcloud cdb capability-show versions postgresql
  

• 사전 확인 요건을 검토하십시오. 이 업그레이드는 소스 배포 환경에서 실행되며, 위험 요소가 감지될 경우 차단됩니다. 다음을 확인하십시오.

  • 배포 상태는 양호합니다
  • 사용 가능한 디스크 공간이 최소 10% 이상 남아 있어야 합니다
  • I/O 사용률이 90% 미만입니다
  • 스키마 크기와 객체 수는 지원되는 한도 내에 있습니다
  • 필수 확장 및 논리적 복제 슬롯 정리가 완료되었습니다

• 응용 프로그램에 영향을 미칠 수 있는 호환성 변경 사항에 대해서는 ‘ https://www.postgresql.org/docs/release/ ’을 확인하십시오.

• 이전 버전으로 다운그레이드하는 기능은 지원되지 않습니다.

• 인플레이스 업그레이드는 일단 시작되면 취소할 수 없습니다.

• 업그레이드하기 전에 최신 백업이 준비되어 있는지 확인하십시오.

Gen2 PostgreSQL 18에서 시작합니다. 지원 대상이 되는 대로 최신 버전으로의 업그레이드 경로가 추가됩니다. 이전 버전(14–17)에 대해서는 /docs/databases-for-postgresql?topic=databases-for-postgresql-upgrading을 참조하십시오.

업그레이드가 완료되면 배포 환경에서는 새로운 PostgreSQL 메이저 버전이 실행됩니다. 업그레이드 이전의 백업 및 PITR 지점은 이전 버전의 타임라인에 속하므로, 업그레이드된 버전으로 복원할 수 없습니다.

새 버전에서 복원 및 PITR 기능을 유지하려면, 업그레이드 직후 백업을 수행하십시오. 이 백업은 향후 복구 작업의 기준이 됩니다.

업그레이드가 실패하더라도, 업그레이드 이전 시점의 백업을 PITR을 통해 활용하여 이전 버전을 새로운 배포 환경에 복원할 수 있습니다.

문제점 해결

업그레이드가 성공적으로 완료된 후 문제가 발생하여 이전 버전으로 되돌려야 하는 경우, IBM Cloud® 지원팀에 문의하여 안내를 받으시기 바랍니다. 지침 없이 PITR 또는 복원 작업을 수행하지 마십시오. 이는 복구 과정을 복잡하게 만들 수 있습니다.

업그레이드는 모든 사전 검사가 통과된 후에만 실행됩니다. 업그레이드가 차단된 경우 다음 사항을 확인하십시오:

• 클러스터 상태 (Patroni 상태가 안정적임)
• 충분한 여유 디스크 공간
• 허용 가능한 디스크 I/O 사용률
• 스키마 크기 및 객체 수 제한

스키마 규모가 크거나 객체 수가 많으면 업그레이드 소요 시간이 늘어날 수 있습니다.

업그레이드 시도가 계속 실패할 경우, https://cloud.ibm.com/login?redirect=%2Funifiedsupport%2Fsupportcenter 을 통해 지원 티켓을 제출해 주십시오.

승격 및 업그레이드 시범 실행

주요 버전 업그레이드의 영향을 평가하려면 모의 실행을 수행하십시오. 모의 실행은 승진 및 승급 과정을 시뮬레이션하며, 그 결과는 데이터베이스 로그에 기록됩니다. 로그 분석 통합 기능을 통해 데이터베이스 로그에 액세스하고 확인하세요. 이를 통해 현재 사용 중인 버전과 해당 확장 기능을 포함하는 버전을 원하는 버전으로 성공적으로 업그레이드할 수 있습니다.

시범 실행은 skip_initial_backup이 false로 설정되고 version이 정의된 상태에서만 실행해야 합니다.

명령어는 다음과 같습니다:

curl -X POST \
  https://api.{region}.databases.cloud.ibm.com/v5/ibm/deployments/{id}/remotes/promotion \
  -H 'Authorization: Bearer <>'  \
 -H 'Content-Type: application/json' \
 -d '{
    "promotion": {
        "version": "14",
        "skip_initial_backup": false,
        "dry_run": true
    }
}' \