데이터베이스 주 버전 인플레이스 업그레이드

이 페이지에서는 데이터를 마이그레이션하는 대신 Cloud SQL 인스턴스를 인플레이스 업그레이드하여 데이터베이스 주 버전을 업그레이드하는 방법을 설명합니다.

소개

데이터베이스 소프트웨어 제공업체는 새로운 기능, 성능 개선, 보안 개선사항이 포함된 새로운 주 버전을 주기적으로 출시합니다. Cloud SQL은 이러한 주 버전이 출시된 후 새 버전을 채택합니다. Cloud SQL에서 새로운 주 버전에 대한 지원이 제공된 후 인스턴스를 업그레이드하여 데이터베이스를 업데이트된 상태로 유지할 수 있습니다.

인스턴스 데이터베이스 버전을 인플레이스로 또는 데이터 마이그레이션을 통해 업그레이드할 수 있습니다. 인플레이스 업그레이드는 인스턴스의 주 버전을 업그레이드하기 위한 더 간단한 방법입니다. 데이터를 마이그레이션하거나 애플리케이션 연결 문자열을 변경할 필요가 없습니다. 인플레이스 업그레이드의 경우 업그레이드 후 현재 인스턴스의 이름, IP 주소, 기타 설정을 유지할 수 있습니다. 인플레이스 업그레이드는 데이터 파일을 이동할 필요가 없고 더 빠르게 완료할 수 있습니다. 일부 경우에는 데이터 마이그레이션보다 다운타임이 짧습니다.

주 버전 업그레이드 계획

1. 대상 주 버전을 선택합니다.

   gcloud

   gcloud CLI 설치 및 시작에 대한 자세한 내용은 gcloud CLI 설치를 참조하세요. Cloud Shell 시작 방법에 대한 자세한 내용은 Cloud Shell 사용을 참조하세요.

   인스턴스에서 인플레이스 업그레이드의 대상으로 지정할 수 있는 데이터베이스 버전을 확인하려면 다음을 수행합니다.

   1. 다음 명령어를 실행합니다.

   gcloud sql instances describe INSTANCE_NAME
      

   INSTANCE_NAME을 인스턴스 이름으로 바꿉니다.

   2. 명령어의 출력에서 upgradableDatabaseVersions 라벨이 지정된 섹션을 찾습니다.
   3. 각 하위 섹션에서 업그레이드할 수 있는 데이터베이스 버전을 반환합니다. 각 하위 섹션에서 다음 필드를 검토합니다.
   • majorVersion: 인플레이스 업그레이드의 대상으로 지정할 수 있는 주 버전입니다.
   • name: 주 버전을 포함하는 데이터베이스 버전 문자열입니다.
   • displayName: 데이터베이스 버전의 표시 이름입니다.

   REST v1

   주 버전 인플레이스 업그레이드에 사용할 수 있는 대상 데이터베이스 버전을 확인하려면 Cloud SQL Admin API의 instances.get 메서드를 사용합니다.

   요청 데이터를 사용하기 전에 다음을 바꿉니다.

   • INSTANCE_NAME: 인스턴스 이름입니다.

   HTTP 메서드 및 URL:

   GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

   요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

   cURL(Linux, macOS, Cloud Shell)

   다음 명령어를 실행합니다.

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell(Windows)

   다음 명령어를 실행합니다.

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   다음과 비슷한 JSON 응답이 표시됩니다.

   
   upgradableDatabaseVersions:
   
   {
     major_version: "POSTGRES_15_0"
     name: "POSTGRES_15_0"
     display_name: "PostgreSQL 15.0"
   }
   
   

   REST v1beta4

   인스턴스의 주 버전 인플레이스 업그레이드에 사용할 수 있는 대상 데이터베이스 버전을 확인하려면 Cloud SQL Admin API의 instances.get 메서드를 사용합니다.

   요청 데이터를 사용하기 전에 다음을 바꿉니다.

   • INSTANCE_NAME: 인스턴스 이름입니다.

   HTTP 메서드 및 URL:

   GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

   요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

   cURL(Linux, macOS, Cloud Shell)

   다음 명령어를 실행합니다.

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME"

   PowerShell(Windows)

   다음 명령어를 실행합니다.

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME" | Select-Object -Expand Content

   다음과 비슷한 JSON 응답이 표시됩니다.

   
   upgradableDatabaseVersions:
   
   {
     major_version: "POSTGRES_15_0"
     name: "POSTGRES_15_0"
     display_name: "PostgreSQL 15.0"
   }
   
   

   Cloud SQL이 지원하는 데이터베이스 버전의 전체 목록은 데이터베이스 버전 및 버전 정책을 참조하세요.

2. 각 데이터베이스 주 버전에 제공된 기능을 고려해서 비호환성 문제를 해결합니다.

   • PostgreSQL 17
   • PostgreSQL 16
   • PostgreSQL 15
   • PostgreSQL 14
   • PostgreSQL 13
   • PostgreSQL 12
   • PostgreSQL 11
   • PostgreSQL 10

   새로운 주 버전에는 애플리케이션 코드, 스키마, 데이터베이스 설정을 수정해야 할 수 있는 호환되지 않는 변경사항이 포함됩니다. 데이터베이스 인스턴스를 업그레이드하려면 먼저 대상 주 버전의 출시 노트를 검토하여 해결이 필요한 비호환성 문제를 확인하세요.

3. 시험 이전을 통해 업그레이드를 테스트합니다.

   프로덕션 데이터베이스를 업그레이드하기 전 테스트 환경에서 엔드 투 엔드 업그레이드 프로세스의 시험 이전을 수행합니다. 인스턴스를 클론하여 업그레이드 프로세스를 테스트할 동일한 데이터 사본을 만들 수 있습니다.

   업그레이드가 성공적으로 완료되는지 검증하는 것 외에도 업그레이드된 데이터베이스에서 애플리케이션이 예상한 대로 작동하는지 확인하는 테스트를 실행합니다.

4. 업그레이드 시간을 결정합니다.

   업그레이드하려면 일정 기간 동안 인스턴스가 사용 중지되어야 합니다. 데이터베이스 활동이 적은 기간에 업그레이드를 계획합니다.

주 버전 업그레이드 준비

업그레이드하기 전 다음 단계를 완료합니다.

1. template 및 postgres 데이터베이스의 LC_COLLATE 값을 확인합니다. 각 데이터베이스의 문자 집합은 en_US.UTF8이어야 합니다.

   template 및 postgres 데이터베이스의 LC_COLLATE 값이 en_US.UTF8이 아니면 주 버전 업그레이드가 실패합니다. 이 문제를 해결하려면 두 데이터베이스 중 하나에 en_US.UTF8 이외의 문자 집합이 있는 경우 업그레이드를 수행하기 전에 LC_COLLATE 값을 en_US.UTF8로 변경합니다.

   데이터베이스의 인코딩을 변경하려면 다음 안내를 따르세요.

   1. 데이터베이스를 덤프합니다.
   2. 데이터베이스를 삭제합니다.
   3. 인코딩이 다른 새 데이터베이스를 만듭니다(이 예시에서는 en_US.UTF8).
   4. 데이터를 새로고침합니다.

   데이터베이스 이름을 바꾸는 방법도 있습니다.

   1. 데이터베이스에 대한 모든 연결을 종료합니다.
   2. 데이터베이스 이름을 바꿉니다.
   3. 새 데이터베이스 이름을 사용하도록 애플리케이션 구성을 업데이트합니다.
   4. 기본 인코딩으로 새로운 빈 데이터베이스를 만듭니다.

   프로덕션 인스턴스에 적용하기 전에 클론된 인스턴스에서 이 단계를 실행하는 것이 좋습니다.

2. 읽기 복제본을 관리합니다.

   PostgreSQL용 Cloud SQL은 버전 간 복제를 지원하지 않습니다. 즉, 인스턴스가 읽기 복제본에 복제되는 동안 기본 인스턴스를 업그레이드할 수 없습니다. 업그레이드하기 전 각 읽기 복제본에 대해 복제를 중지하거나 읽기 복제본을 삭제합니다.

3. Cloud SQL이 논리 복제 소스인 경우 다음과 같이 pglogical 확장 프로그램 복제를 중지합니다. 업그레이드 후 다시 사용 설정할 수 있습니다. Cloud SQL이 논리 복제 대상인 경우 이 단계가 필요하지 않습니다.
   1. 다음 명령어를 사용하여 구독을 중지하고 제공업체의 복제본을 연결 해제합니다.

      SELECT * FROM pglogical.alter_subscription_disable(subscription_name name, immediate bool);

      name을 기존 구독의 이름으로 바꿉니다.

      구독을 즉시 중지해야 하는 경우 immediate 매개변수의 값을 true로 설정합니다. 기본적으로 값은 false이며 현재 트랜잭션이 종료된 후에만 구독이 중지됩니다.

      예를 들면 다음과 같습니다.

      postgres=> SELECT * FROM pglogical.alter_subscription_disable('test_sub', true);
       alter_subscription_disable
      ----------------------------
       t
      (1 row)

   2. 게시자 또는 Cloud SQL 기본 인스턴스에 연결하고 다음 명령어를 실행하여 복제 슬롯을 삭제합니다.

      SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
        WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);

      예를 들면 다음과 같습니다.

      postgres=> SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots
      postgres->    WHERE slot_name IN (SELECT slot_name FROM pg_replication_slots);
      -[ RECORD 1 ]------------+-
      pg_drop_replication_slot |
      
      postgres=>

4. 남은 PostgreSQL 확장 프로그램을 관리합니다.

   대부분의 확장 프로그램은 업그레이드된 데이터베이스 주 버전에서 작동합니다. 대상 버전에서 더 이상 지원되지 않는 모든 확장 프로그램을 삭제합니다. 예를 들어 PostgreSQL 11 이상 버전으로 업그레이드하는 경우 chkpass 확장 프로그램을 삭제합니다.

   PostGIS 및 관련 확장 프로그램을 지원되는 최신 버전으로 수동 업그레이드할 수 있습니다.

   PostGIS 버전 2.x에서 업그레이드하면 PostGIS 확장 프로그램과 연결되지 않은 잔여 데이터베이스 객체가 발생하는 경우가 있습니다. 이로 인해 업그레이드 작업이 중단될 수 있습니다. 이 문제를 해결하는 방법은 손상된 postgis 래스터 설치 해결을 참조하세요.

   지원 중단된 함수를 사용하는 객체로 인해 PostGIS 버전 3.1.7 이상으로 업그레이드할 수 없는 경우가 있습니다. 이로 인해 업그레이드 작업이 중단될 수 있습니다. 업그레이드 상태를 확인하려면 SELECT PostGIS_full_version();을 실행합니다. 경고가 있으면 지원 중단된 함수를 사용하는 모든 객체를 삭제하고 PostGIS 확장 프로그램을 중간 버전 이상으로 업데이트합니다. 이 작업을 완료한 후 SELECT PostGIS_full_version(); 명령어를 다시 실행합니다. 경고가 표시되지 않는지 확인합니다. 그런 다음 업그레이드 작업을 진행합니다.

   PostGIS 확장 프로그램 업그레이드에 대한 자세한 내용은 PostGIS 업그레이드를 참조하세요. PostGIS 업그레이드와 관련된 문제는 PostgreSQL 인스턴스 버전 확인을 참조하세요.
5. 커스텀 데이터베이스 플래그를 관리합니다. PostgreSQL 인스턴스에 구성한 커스텀 데이터베이스 플래그의 이름을 확인합니다. 이러한 플래그와 관련된 문제는 PostgreSQL 인스턴스의 커스텀 플래그 확인을 참조하세요.
6. 한 주 버전에서 다른 주 버전으로 업그레이드할 때는 각 데이터베이스에 연결하여 호환성 문제가 있는지 확인합니다. 데이터베이스가 서로 연결할 수 있는지 확인합니다. 각 데이터베이스의 datallowconn 필드를 확인하여 연결이 허용되는지 확인합니다. t 값은 허용됨을 의미하고 f 값은 연결을 설정할 수 없음을 나타냅니다.
7. Datadog 설치를 사용하여 Cloud SQL 인스턴스를 PostgreSQL 10 이상 버전으로 업그레이드하는 경우 업그레이드를 수행하기 전에 pg_stat_activity() 함수를 삭제합니다.

알려진 제한사항

다음 제한사항은 PostgreSQL용 Cloud SQL의 인플레이스(In-Place) 주 버전 업그레이드에 영향을 줍니다.

• 외부 복제본에서는 인플레이스 주 버전 업그레이드를 수행할 수 없습니다.
• 1,000개가 넘는 데이터베이스가 있는 인스턴스를 한 버전에서 다른 버전으로 업그레이드하는 경우 시간이 오래 걸리고 시간이 초과될 수 있습니다.
• select * from pg_largeobject_metadata; 문을 사용하여 Cloud SQL 인스턴스의 각 PostgreSQL 데이터베이스에 있는 대형 객체의 수를 쿼리합니다. 모든 데이터베이스의 결과가 1,000만 개가 넘는 대형 객체인 경우 업그레이드가 실패합니다. Cloud SQL이 이전 버전의 데이터베이스로 롤백합니다.
• PostgreSQL 16 이상으로 인플레이스 주 버전 업그레이드를 수행하기 전에 모든 데이터베이스의 PostGIS 확장 프로그램을 버전 3.4.0으로 업그레이드하세요.
• PostgreSQL 버전 9.6, 10, 11 또는 12를 사용하는 경우 PostGIS 확장 프로그램 버전 3.4.0은 지원되지 않습니다. 따라서 PostgreSQL 16 이상으로 인플레이스 주 버전 업그레이드를 수행하려면 먼저 PostgreSQL의 중간 버전 (버전 13, 14, 15)으로 업그레이드해야 합니다.

• 인스턴스에 pgRouting 및 pg_squeeze 확장 프로그램을 설치하면 주 버전 업그레이드를 실행할 수 없습니다. 이 문제를 해결하려면 이러한 확장 프로그램을 제거한 다음 업그레이드를 실행하세요. 확장 프로그램에 대한 자세한 내용은 PostgreSQL 확장 프로그램 구성을 참조하세요.

• vacuum_defer_cleanup_age 및 force_parallel_mode 플래그를 사용 설정하면 주 버전 업그레이드를 실행할 수 없습니다. 이 문제를 해결하려면 이러한 플래그를 삭제한 후 업그레이드를 실행합니다. 플래그 삭제 방법을 비롯한 플래그에 관한 자세한 내용은 데이터베이스 플래그 구성을 참고하세요.

데이터베이스 주 버전 인플레이스 업그레이드

업그레이드 작업을 시작하면 Cloud SQL이 먼저 인스턴스 구성이 업그레이드와 호환되는지 확인합니다. 구성이 확인된 후에는 Cloud SQL이 인스턴스를 사용 중지하고, 업그레이드 전 백업을 만들고, 업그레이드를 수행하고, 인스턴스를 사용하도록 설정하고, 업그레이드 후 백업을 만듭니다.

resource "google_sql_database_instance" "instance" {
  name             = "postgres-instance"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

인플레이스 업그레이드 요청을 실행하면 Cloud SQL이 먼저 업그레이드 전 검사를 수행합니다. Cloud SQL에서 인스턴스 업그레이드가 준비되지 않은 것으로 확인하면 업그레이드 요청이 실패하고 문제 해결 방법을 제안하는 메시지가 표시됩니다. 또한 주 버전 업그레이드 문제 해결을 참조하세요.

자동 업그레이드 백업

주 버전 업그레이드를 수행할 때 Cloud SQL은 업그레이드 백업이라고 부르는 2개의 주문형 백업을 자동으로 만듭니다.

• 첫 번째 업그레이드 백업은 업그레이드 시작 직전에 수행되는 업그레이드 전 백업입니다. 이 백업을 사용하면 데이터베이스 인스턴스를 이전 버전 상태로 복원할 수 있습니다.
• 두 번째 업그레이드 백업은 업그레이드된 데이터베이스 인스턴스에서 새로운 쓰기 작업이 허용되는 즉시 수행되는 업그레이드 후 백업입니다.

백업 목록을 보면 업그레이드 백업이 On-demand 유형으로 나열된 것을 알 수 있습니다. 업그레이드 백업은 빠르게 식별할 수 있도록 라벨이 지정되어 있습니다. 예를 들어 PostgreSQL 14에서 PostgreSQL 15로 업그레이드하는 경우 업그레이드 전 백업에는 Pre-upgrade backup, POSTGRES_14 to POSTGRES_15. 라벨이 지정되고 업그레이드 후 백업에는 Post-upgrade backup, POSTGRES_14 to POSTGRES_15. 라벨이 지정됩니다.

다른 주문형 백업에서와 같이 백업을 삭제하거나 인스턴스를 삭제할 때까지 업그레이드 백업이 보존됩니다. PITR을 사용 설정한 경우 보관 기간 동안 업그레이드 백업을 삭제할 수 없습니다. 업그레이드 백업을 삭제해야 할 경우에는 PITR을 사용 중지하거나 업그레이드 백업이 더 이상 보관 기간이 아니게 될 때까지 기다려야 합니다.

주 버전 업그레이드 완료

기본 인스턴스 업그레이드를 완료한 후 다음 단계를 수행해서 업그레이드를 완료합니다.

1. 업그레이드 전 인스턴스에 사용된 경우 pglogical 복제를 사용 설정합니다. 이렇게 하면 필요한 복제 슬롯이 자동으로 생성됩니다.
   1. 다음 명령어를 사용하여 대상 복제본에서 pglogical 구독을 삭제합니다.

      select pglogical.drop_subscription(subscription_name name);

      name을 기존 구독의 이름으로 바꿉니다.

      예를 들면 다음과 같습니다.

      postgres=> select pglogical.drop_subscription(subscription_name := 'test_sub');
      -[ RECORD 1 ]-----+--
      drop_subscription | 1

   2. 다음과 같이 연결 세부정보를 Cloud SQL 기본 인스턴스에 제공하여 대상(복제본)에 pglogical 구독을 다시 만듭니다.

      SELECT pglogical.create_subscription(
          subscription_name := 'test_sub',
          provider_dsn := 'host=primary-ip port=5432 dbname=postgres user=replication_user password=replicapassword'
      ); 

      예를 들면 다음과 같습니다.

      postgres=> SELECT pglogical.create_subscription(
      postgres(>     subscription_name := 'test_sub',
      postgres(>     provider_dsn := 'host=10.58.64.90 port=5432 dbname=postgres user=postgres password=postgres'
      postgres(> );
      -[ RECORD 1 ]-------+-----------
      create_subscription | 2769129391

   3. 다음 명령어를 사용하여 구독 상태를 확인합니다.

      SELECT * FROM pglogical.show_subscription_status('test_sub');

   4. 쓰기 트랜잭션을 수행하고 변경사항이 대상에 표시되는지 확인하여 복제를 테스트합니다.

2. 읽기 복제본을 업그레이드합니다.

   읽기 복제본에 대한 복제를 중지한 경우 이를 하나씩 업그레이드합니다. 기본 인스턴스를 업그레이드하는 데 사용되는 모든 방법을 사용할 수 있습니다. 복제본을 업그레이드하면 Cloud SQL이 이를 다시 만들 때 IP 주소를 보존하고, 기본 인스턴스의 최신 데이터로 새로고침하고 복제본을 다시 시작합니다.

   기본 인스턴스를 업그레이드하기 전 읽기 복제본을 삭제한 경우 새 읽기 복제본을 만들 수 있습니다. 그러면 업그레이드된 데이터베이스 버전에서 새 읽기 복제본이 자동으로 프로비저닝됩니다.

3. 데이터베이스 통계를 새로고침합니다.

   기본 인스턴스에서 ANALYZE를 실행하여 업그레이드 후 시스템 통계를 업그레이드합니다. 정확한 통계는 PostgreSQL 쿼리 플래너가 쿼리를 최적의 방식으로 처리할 수 있게 해줍니다. 통계가 없으면 쿼리 계획이 잘못되고, 그 결과 업그레이드 성능이 저하되고 메모리가 과도하게 사용될 수 있습니다.

4. 수락 테스트를 수행합니다.

   테스트를 실행하여 업그레이드된 시스템이 예상한 대로 작동하는지 확인해야 합니다.

주 버전 업그레이드 문제 해결

예를 들어 인스턴스에 새 버전에 대한 잘못된 데이터베이스 플래그가 포함된 경우 등 잘못된 업그레이드 명령어를 시도하면 Cloud SQL에서 오류 메시지가 반환됩니다.

업그레이드 요청이 실패하면 업그레이드 요청의 문법을 확인합니다. 요청의 구조가 유효하다면 다음 추천 조치를 살펴보세요.

업그레이드 전 검사 실패 보기

업그레이드 전 검사 실패는 업그레이드 전 확인 또는 검증 프로세스 중에 Cloud SQL이 감지하는 문제 또는 오류를 의미합니다. 이러한 실패는 실제 업그레이드 프로세스가 시작되기 전에 발생하며 업그레이드 성공에 영향을 줄 수 있는 잠재적인 문제나 비호환성을 식별하기 위한 것입니다.

업그레이드 전 검사 실패는 다음 카테고리에 표시됩니다.

• 호환되지 않는 확장 프로그램: 인스턴스의 대상 버전과 호환되지 않는 PostgreSQL 확장 프로그램을 감지합니다.
• 지원되지 않는 종속 항목: 더 이상 지원되지 않거나 업데이트가 필요한 종속 항목을 식별합니다.
• 데이터 형식 비호환성: 버전별 데이터 구조의 차이, 인코딩 및 콜레이션 수정, 데이터 유형 수정, 시스템 카탈로그 조정 등 다양한 요인으로 인해 발생하는 데이터 불일치를 확인합니다.

다음 표에는 업그레이드 전 검사 실패 및 오류 메시지가 나와 있습니다.

빈 검색 경로 문제 해결

이는 earthdistance 확장 프로그램이 함수의 검색 경로를 지정하지 않고 earth 및 cube 유형을 사용하기 때문입니다. 업그레이드 프로세스 중에 필요한 이 경로를 지정해야 합니다.

이 문제를 해결하려면 다음 쿼리를 실행하여 ll_to_earth 함수의 검색 경로를 수정합니다. ALTER FUNCTION ll_to_earth SET search_path = public;

업그레이드 로그 보기

업그레이드 요청이 올바른 경우에도 문제가 발생하면 Cloud SQL이 projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log에 오류 로그를 게시합니다. 각 로그 항목에는 업그레이드 오류가 발생한 인스턴스를 식별할 수 있도록 인스턴스 식별자와 함께 라벨이 포함되어 있습니다. 이러한 업그레이드 오류를 찾아 해결합니다.

오류 로그를 보려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 Cloud SQL 인스턴스 페이지로 이동합니다.

   Cloud SQL 인스턴스로 이동

2. 인스턴스의 개요 페이지를 열려면 인스턴스 이름을 클릭합니다.

3. 인스턴스 개요 페이지의 작업 및 로그 창에서 PostgreSQL 오류 로그 보기 링크를 클릭합니다.

   로그 탐색기 페이지가 열립니다.

4. 다음과 같이 로그를 확인합니다.

   • 한 프로젝트의 모든 오류 로그를 나열하려면 로그 이름 로그 필터에서 로그 이름을 선택합니다.

   쿼리 필터에 대한 자세한 내용은 고급 쿼리를 참조하세요.

   • 단일 인스턴스의 업그레이드 오류 로그를 필터링하려면 모든 필드 검색 상자에 다음 쿼리를 입력합니다. 이때 DATABASE_ID를

   프로젝트 ID와 인스턴스 이름으로 바꿉니다. 형식은 project_id:instance_name과 같습니다.

   resource.type="cloudsql_database"
   resource.labels.database_id="DATABASE_ID"
   logName : "projects/PROJECT_ID/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

   예를 들어 buylots 프로젝트에서 실행되는 인스턴스 이름 shopping-db로 업그레이드 오류 로그를 필터링하려면 다음 쿼리 필터를 사용합니다.

    resource.type="cloudsql_database"
    resource.labels.database_id="buylots:shopping-db"
    logName : "projects/buylots/logs/cloudsql.googleapis.com%2Fpostgres-upgrade.log"

pg_upgrade_dump 프리픽스가 있는 로그 항목은 업그레이드 오류가 발생했음을 의미합니다. 예를 들면 다음과 같습니다.

pg_upgrade_dump: error: query failed: ERROR: out of shared memory
HINT: You might need to increase max_locks_per_transaction.

또한 .txt 보조 파일 이름으로 라벨이 지정된 로그 항목에는 업그레이드를 다시 시도하기 전에 해결해야 할 다른 오류가 나열될 수 있습니다.

모든 파일 이름은 postgres-upgrade.log 파일에서 찾을 수 있습니다. 파일 이름을 찾으려면 labels.FILE_NAME 필드를 확인합니다.

해결해야 할 오류가 포함된 파일 이름은 다음과 같습니다.

• tables_with_oids.txt: 이 파일에는 객체 식별자(OID)와 함께 나열된 테이블이 포함되어 있습니다. OID를 사용하지 않도록 테이블을 삭제하거나 수정합니다.
• tables_using_composite.txt: 이 파일에는 시스템 정의 복합 유형을 사용하여 나열된 테이블이 포함되어 있습니다. 테이블을 삭제하거나 이러한 복합 유형을 사용하지 않도록 수정합니다.
• tables_using_unknown.txt: 이 파일에는 UNKNOWN 데이터 유형을 사용하여 나열된 테이블이 포함되어 있습니다. 테이블을 삭제하거나 이 데이터 유형을 사용하지 않도록 수정합니다.
• tables_using_sql_identifier.txt: 이 파일에는 SQL_IDENTIFIER 데이터 유형을 사용하여 나열되는 테이블이 포함되어 있습니다. 테이블을 삭제하거나 이 데이터 유형을 사용하지 않도록 수정합니다.
• tables_using_reg.txt: 이 파일에는 REG* 데이터 유형(예: REGCOLLATION 또는 REGNAMESPACE)을 사용하여 나열된 테이블이 포함되어 있습니다. 테이블을 삭제하거나 이 데이터 유형을 사용하지 않도록 수정합니다.
• postfix_ops.txt: 이 파일에는 Postfix(오른쪽 단항) 연산자를 사용하여 나열된 테이블이 포함되어 있습니다. 이러한 연산자를 사용하지 않도록 테이블을 삭제하거나 수정합니다.

메모리 확인

인스턴스의 공유 메모리가 부족하면 ERROR: out of shared memory.라는 오류 메시지가 표시될 수 있습니다. 이 오류는 테이블이 10,000개 이상일 때 발생할 가능성이 높습니다.

업그레이드를 시도하기 전 max_locks_per_transaction 플래그 값을 인스턴스에 있는 테이블 수의 약 2배로 설정합니다. 이 플래그 값을 변경하면 인스턴스가 다시 시작됩니다.

연결 용량 확인

인스턴스의 연결 용량이 부족하면 다음 오류 메시지가 표시될 수 있습니다. ERROR: Insufficient connections.

Cloud SQL에서는 max_connections 플래그 값을 인스턴스의 데이터베이스 수만큼 늘리는 것을 권장합니다. 이 플래그 값을 변경하면 인스턴스가 다시 시작됩니다.

모호한 열 참조 확인

뷰에 모호한 열 참조가 있으면 ERROR: column reference "<column_name>" is ambiguous 오류 메시지가 표시될 수 있습니다. 이 문제는 새 PostgreSQL 버전에서 pg_stat_activity 및 pg_stat_replication와 같은 시스템 카탈로그 뷰의 구조를 변경할 때 발생합니다. 이로 인해 열 순서를 사용하는 맞춤 뷰가 중단될 수 있습니다.

이 오류 메시지를 확인하려면 쿼리 편집기에 다음 쿼리를 추가합니다. textPayload =~ "ERROR: column reference .+ is ambiguous at character \d+"

다음과 같은 방법으로 이 문제를 해결할 수 있습니다.

1. 맞춤 뷰를 조정합니다.

   대상 PostgreSQL 버전의 새 시스템 카탈로그 뷰 (예: pg_stat_activity 및 pg_stat_replication) 정의에 맞게 맞춤 뷰의 열 참조를 업데이트합니다.

2. 뷰를 다시 만듭니다.

   메이저 버전 업그레이드를 실행하기 전에 맞춤 뷰를 삭제합니다. 업그레이드가 완료된 후 뷰를 다시 만들어 새 구조와 호환되도록 합니다.

이 문제의 자세한 예와 추가 정보는 이 스택 오버플로 토론을 참고하세요.

CASE 구문에서 SRF 확인

버전 9.6에서 인스턴스를 업그레이드하고 CASE 문에 set 반환 함수를 사용하는 경우 ERROR: set-returning functions are not allowed in CASE 오류 메시지가 표시될 수 있습니다. 이 문제는 버전 10부터 CASE 문에 세트 반환 함수를 사용하는 것이 허용되지 않기 때문에 발생합니다.

이 문제를 해결하고 인스턴스를 성공적으로 업그레이드하려면 업그레이드를 다시 시도하기 전에 세트 반환 함수를 사용하는 모든 CASE 문을 수정하여 사용하지 않도록 하세요. 일반적으로 사용되는 SRF는 다음과 같습니다.

• unnest()
• generate_series()
• array_agg()
• regexp_split_to_table()
• jsonb_array_elements()
• json_array_elements()
• sonb_each()
• json_each()

맞춤 전송에서 생성된 조회수 확인

맞춤 전송에서 뷰를 만든 경우 다음과 유사한 오류 메시지(ERROR: cannot cast type <type_1> to <type_2>)가 표시됩니다. 이 문제는 맞춤으로 만든 전송의 권한 문제로 인해 발생합니다.

이 문제를 해결하려면 인스턴스를 [PostgreSQL version].R20240910.01_02로 업데이트하세요.

자세한 내용은 셀프서비스 유지보수를 참조하세요.

이벤트 트리거 소유권 확인

cloudsqlsuperuser 역할이 없는 사용자가 이벤트 트리거를 소유한 경우 ERROR: permission denied to change owner of event trigger "<trigger_name>"와 같은 오류 메시지가 표시될 수 있습니다. 이 문제는 업그레이드 중에 이러한 트리거를 다시 만들려고 할 때 권한 문제로 인해 발생합니다. 쿼리 편집기에 다음 쿼리를 추가하여 이 오류 메시지가 표시되는지 확인할 수 있습니다. textPayload =~ "ERROR: permission denied to change owner of event trigger .+ "

이 문제를 해결하려면 인스턴스 내의 모든 이벤트 트리거의 소유권을 확인하세요. 각 트리거의 소유자가 cloudsqlsuperuser인지 확인합니다. 다른 사용자가 트리거의 소유권을 보유한 경우 업그레이드를 다시 시도하기 전에 소유권을 cloudsqlsuperuser로 업데이트합니다. 다음 쿼리를 사용하여 소유권을 변경할 수 있습니다. ALTER EVENT TRIGGER <trigger_name> OWNER TO <cloudsqlsuperuser>;

다음 쿼리를 사용하여 이벤트 트리거 목록과 소유자 세부정보를 가져올 수 있습니다. SELECT evtname AS trigger_name, evtowner::regrole AS owner FROM pg_event_trigger;

로깅되지 않은 테이블에서 생성된 열 확인

생성된 열이 있는 로깅되지 않은 테이블이 있으면 ERROR: unexpected request for new relfilenumber in binary upgrade mode 오류 메시지가 표시될 수 있습니다. 이 문제는 테이블과 생성된 열의 시퀀스 간의 지속성 특성 불일치로 인해 발생합니다.

이 문제를 해결하려면 다음 단계를 따르세요.

1. 로깅되지 않은 테이블 삭제: 가능한 경우 생성된 열에 연결된 로깅되지 않은 테이블을 삭제합니다. 계속하기 전에 데이터 손실을 안전하게 완화할 수 있는지 확인하세요.
2. 영구 테이블로 변환: 다음 단계에 따라 로깅되지 않은 테이블을 일시적으로 영구 테이블로 변환합니다.
   1. 테이블을 로깅된 테이블로 변환합니다. ALTER TABLE SET LOGGED;
   2. 주 버전 업그레이드 수행
   3. 테이블을 로깅되지 않은 테이블로 다시 변환합니다. ALTER TABLE SET UNLOGGED

다음 쿼리를 사용하여 이러한 모든 테이블을 식별할 수 있습니다.

SELECT
  relnamespace::regnamespace,
  c.relname AS table_name,
  a.attname AS column_name,
  a.attidentity AS identity_type
FROM
  pg_catalog.pg_class c
  JOIN pg_catalog.pg_attribute a ON a.attrelid = c.oid
WHERE
  a.attidentity IN ('a', 'd') AND c.relkind = 'r' AND c.relpersistence = 'u'
ORDER BY c.relname, a.attname;

PostgreSQL 인스턴스의 커스텀 플래그 확인

PostgreSQL 인스턴스 14 버전 이상으로 업그레이드하는 경우 인스턴스에 구성한 커스텀 데이터베이스 플래그의 이름을 확인합니다. 이는 PostgreSQL이 커스텀 매개변수의 허용되는 이름에 추가 제한을 적용했기 때문입니다.

커스텀 데이터베이스 플래그의 첫 번째 문자는 알파벳(A-Z 또는 a-z)이어야 합니다. 이후의 모든 문자는 영숫자, 밑줄(_) 특수문자, 달러 기호($) 특수문자일 수 있습니다.

확장 프로그램 삭제

Cloud SQL 인스턴스를 업그레이드하는 경우 다음 오류 메시지가 표시될 수 있습니다. pg_restore: error: could not execute query: ERROR: role "16447" does not exist.

이 문제를 해결하려면 다음 단계를 따르세요.

1. pg_stat_statements 및 pgstattuple 확장 프로그램을 삭제합니다.
2. 업그레이드를 수행합니다.
3. 확장 프로그램을 다시 설치합니다.

이전 주 버전으로 복원

업그레이드된 데이터베이스 시스템이 예상한 대로 작동하지 않으면 인스턴스를 이전 버전으로 복원해야 할 수 있습니다. 이렇게 하려면 업그레이드 전 버전을 실행하는 새 인스턴스인 Cloud SQL 복구 인스턴스로 업그레이드 전 백업을 복원합니다.

이전 버전으로 복원하려면 다음 단계를 수행합니다.

1. 업그레이드 전 백업을 식별합니다.

   자동 업그레이드 백업을 참조하세요.

2. 복구 인스턴스를 만듭니다.

   업그레이드 전 백업이 수행될 때 Cloud SQL에서 실행하던 주 버전을 사용하여 새 Cloud SQL 인스턴스를 만듭니다. 원래 인스턴스에서 사용되는 동일한 플래그 및 인스턴스 설정을 지정합니다.

3. 업그레이드 전 백업을 복원합니다.

   업그레이드 전 백업을 복구 인스턴스로 복원합니다. 완료되는 데 몇 분 정도 걸릴 수 있습니다.

4. 읽기 복제본을 추가합니다.

   읽기 복제본을 사용하는 경우 이를 개별적으로 추가합니다.

5. 애플리케이션을 연결합니다.

   데이터베이스 시스템이 복구되었으면 복구 인스턴스 및 읽기 복제본에 대한 세부정보로 애플리케이션을 업데이트합니다. 데이터베이스의 업그레이드 전 버전에서 트래픽 제공을 재개할 수 있습니다.

FAQ

데이터베이스 주 버전을 업그레이드할 때는 다음과 같은 질문을 고려해야 할 수 있습니다.

업그레이드 중에 인스턴스를 사용할 수 없나요?

예. Cloud SQL이 업그레이드를 수행하는 동안 인스턴스를 사용할 수 없습니다.

업그레이드하는 데 시간이 얼마나 걸리나요?

단일 인스턴스를 업그레이드할 때는 일반적으로 10분 미만이 걸립니다. 인스턴스 구성에서 소량의 vCPU 또는 메모리를 사용하는 경우 업그레이드 시간이 길어질 수 있습니다.

업그레이드 시간은 데이터베이스의 객체 수에 상응하므로 인스턴스에서 데이터베이스 또는 테이블을 너무 많이 호스팅하거나 데이터베이스가 매우 큰 경우 업그레이드에 몇 시간이 걸리거나 타임아웃이 발생할 수도 있습니다. 업그레이드해야 하는 인스턴스가 여러 개인 경우 그에 비례하여 총 업그레이드 시간이 증가합니다.

업그레이드 프로세스에서 각 단계를 모니터링할 수 있나요?

Cloud SQL에서는 업그레이드 작업이 진행 중인지 여부를 모니터링할 수 있지만, 각 업그레이드의 개별 단계는 추적할 수 없습니다.

업그레이드를 시작한 후 취소할 수 있나요?

아니요. 업그레이드가 시작된 다음에는 이를 취소할 수 없습니다. 업그레이드가 실패하면 Cloud SQL이 인스턴스를 이전 버전으로 자동으로 복구합니다.

업그레이드 도중 내 설정은 어떻게 되나요?

인플레이스 주 버전 업그레이드를 수행하는 경우에는 인스턴스 이름, IP 주소, 명시적으로 구성된 플래그 값, 사용자 데이터와 같은 데이터베이스 설정이 Cloud SQL에서 보존됩니다. 그러나 시스템 변수의 기본값은 변경될 수 있습니다. 예를 들어 PostgreSQL 13 이하에서 password_encryption 플래그의 기본값은 md5입니다. PostgreSQL 14로 업그레이드하면 이 플래그의 기본값이 scram-sha-256으로 변경됩니다.

자세한 내용은 데이터베이스 플래그 구성을 참조하세요. 특정 플래그 또는 값이 대상 버전에서 더 이상 지원되지 않는 경우에는 Cloud SQL에서 업그레이드하는 동안 해당 플래그가 자동으로 삭제됩니다.

다음 단계

• 인스턴스 연결 옵션 알아보기
• 데이터 가져오기 및 내보내기 자세히 알아보기
• 데이터베이스 플래그 설정 자세히 알아보기