PostgreSQL에서 PostgreSQL용 AlloyDB로 마이그레이션하는 과정에서 발생하는 문제 진단

런타임 중에 마이그레이션 작업 프로세스에 오류가 발생할 수 있습니다.

  • 소스 데이터베이스의 잘못된 비밀번호와 같은 일부 오류는 복구할 수 있으므로 수정할 수 있으며 마이그레이션 작업이 자동으로 재개됩니다.
  • 데이터 손상이나 스키마 비호환성과 같은 일부 오류는 복구할 수 없으므로 마이그레이션 작업을 처음부터 다시 시작해야 합니다.

오류가 발생하면 마이그레이션 작업 상태가 Failed로 변경되고 하위 상태는 실패 전 마지막 상태를 반영합니다.

오류 문제를 해결하려면 실패한 이전 작업으로 이동하여 오류를 확인하고 오류 메시지에 설명된 단계를 따릅니다.

오류에 대한 자세한 내용을 보려면 마이그레이션 작업의 링크를 사용하여 Cloud Monitoring으로 이동합니다. 로그가 특정 마이그레이션 작업으로 필터링됩니다.

다음 표에는 일반적인 문제와 해결 방법이 나와 있습니다.

문제 설명 문제 원인 해결 방법
기존 대상 클러스터로 마이그레이션하면 다음 오류 메시지가 표시됩니다. The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job. 대상 PostgreSQL용 AlloyDB 클러스터에 추가 사용자 데이터가 포함되어 있습니다.를 참조하세요. 비어 있는 기존 클러스터로만 마이그레이션할 수 있습니다. 알려진 제한사항을 참조하세요. 대상 클러스터에서 충돌하거나 추가 데이터를 삭제하고 마이그레이션 작업을 다시 시도합니다. 기존 대상 클러스터에서 추가 데이터 삭제를 참조하세요.
소스 데이터베이스 인스턴스 연결 실패 소스 데이터베이스 인스턴스와 대상 PostgreSQL용 AlloyDB 클러스터 간에 연결 문제가 발생했습니다. 연결 디버깅의 단계를 따릅니다.
소스 및 대상 데이터베이스 버전이 호환되지 않아 마이그레이션 작업을 실행할 수 없습니다. 소스 및 대상 데이터베이스 버전이 지원되는 조합이 아닙니다. 구체적으로, 제공된 소스 데이터베이스 버전이 대상 데이터베이스 버전과 호환되지 않습니다. 대상 데이터베이스 버전이 소스 데이터베이스 버전과 동일하거나 지원되는 이후 메이저 버전인지 확인합니다. 그런 다음 새 마이그레이션 작업을 만듭니다.
소스에서 데이터 정의 언어 (DDL) 또는 데이터 조작 언어 (DML)가 차단됩니다. ACCESS EXCLUSIVE 잠금이 필요하고 전체 덤프 단계 중에 실행되는 DDL은 차단됩니다.

초기 동기화 프로세스 (전체 덤프) 중에는 테이블에서 ALTER TABLE 또는 DROP TABLE와 같은 ACCESS EXCLUSIVE 잠금이 필요한 DDL 또는 프로그램을 사용하지 않아야 합니다. 그렇지 않으면 초기 동기화가 완료될 때까지 DDL 또는 프로그램이 대기합니다.

예를 들어 테이블이 아직 초기 동기화 프로세스에 있고 동일한 테이블에서 ALTER TABLE 명령어가 실행되면 명령어가 실행되지 않고 초기 동기화가 완료될 때까지 후속 DDL 및 DML 명령어가 차단됩니다.
오류 메시지: No pglogical extension installed on databases (X) 하나 이상의 소스 데이터베이스에 pglogical가 설치되어 있지 않습니다. 이 가이드라인에 따라 소스 인스턴스의 데이터베이스에 pglogical를 설치합니다.
PostgreSQL 버전 15로 마이그레이션할 때 여러 번의 후속 연결 재시도 시도 후 다음 증상 중 하나가 발생합니다. 이 문제는 pglogical 확장 프로그램의 교착 상태 문제로 인해 발생하는 경우가 많습니다. 자세한 내용은 GitHub의 pglogical Issue Tracker를 참고하세요. 마이그레이션 작업을 다시 시도하거나 먼저 중간 PostgreSQL 버전으로 마이그레이션합니다. 자세한 내용은 오류 메시지: Cannot connect to invalid database를 참고하세요.
오류 메시지: Replication user 'x' doesn't have sufficient privileges. Database Migration Service를 사용하는 사용자에게 지정된 작업을 수행하는 데 필요한 권한이 없습니다. 이 가이드라인에 따라 이 사용자에게 필요한 권한이 있는지 확인합니다.
오류 메시지: Unable to connect to source database server. Database Migration Service에서 소스 데이터베이스 서버에 연결할 수 없습니다. 소스 및 대상 데이터베이스 인스턴스가 서로 통신할 수 있고 마이그레이션 작업 설정을 정의할 때 표시된 모든 필수 기본 요건을 완료했는지 확인합니다.
오류 메시지: The source database 'wal_level' configuration must be equal to 'logical'. 소스 데이터베이스의 wal_level가 logical 이외의 값으로 설정되어 있습니다. wal_level를 logical로 설정합니다. WAL 수준 구성을 참조하세요.
오류 메시지: The source database 'max_replication_slots' configuration is not sufficient. max_replication_slots 매개변수가 올바르게 구성되지 않았습니다. 이 가이드라인에 따라 이 매개변수를 올바르게 설정하세요.
오류 메시지: The source database 'max_wal_senders' configuration is not sufficient. max_wal_senders 매개변수가 올바르게 구성되지 않았습니다. 이 가이드라인에 따라 이 매개변수를 올바르게 설정하세요.
오류 메시지: The source database 'max_worker_processes' configuration is not sufficient. max_worker_processes 매개변수가 올바르게 구성되지 않았습니다. 이 가이드라인에 따라 이 매개변수를 올바르게 설정하세요.

오류 메시지: Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.

또는

오류 메시지: Error promoting EM replica: finished drop replication with errors.

마이그레이션 작업을 승격하는 동안 복제에 필요한 설정을 정리할 수 없습니다.

각 데이터베이스에 대해 superuser 권한이 있는 사용자로 명령어를 실행합니다.

실행할 명령어에 대한 자세한 내용은 복제 슬롯 삭제를 참조하세요.

오류 메시지: x509 certificate signed by unknown authority.

Database Migration Service에 제공된 소스 CA 인증서에 루트 인증서만 포함되어 있을 수 있습니다. 하지만 소스 인증서에는 루트 인증서와 중간 인증서가 모두 필요합니다.

예를 들어 Amazon RDS의 경우 인증서 번들 대신 독립형 루트 인증서를 사용하면 이 문제가 발생할 수 있습니다.

루트 인증서와 필요한 모든 중간 인증서를 포함하는 결합된 소스 CA 인증서를 만듭니다.

Amazon RDS 소스의 경우 중간 인증서와 루트 인증서가 모두 포함된 인증서 번들을 사용합니다. 자세한 내용은 Amazon RDS 문서의 인증서 번들 다운로드를 참조하세요.

오류 메시지: ERROR: Out of shared memory HINT: You might need to increase max_locks_per_transaction.

max_locks_per_transaction 매개변수에 설정된 값이 충분하지 않습니다. 이 매개변수의 값을 {max_number_of_tables_per_database}/(max_connections + max_prepared_transactions) 이상으로 설정하세요.

오류 메시지: ERROR: no data left in message.

pglogical 패키지가 소스 인스턴스에 올바르게 설치되지 않았습니다. 이 패키지를 올바르게 설치하는 방법에 대한 자세한 내용은 소스 데이터베이스 구성을 참조하세요.

오류 메시지: Cannot assign TransactionIds during recovery.

구성된 소스가 복구 모드입니다. 복구 모드가 아닌 소스를 구성합니다.
전체 덤프가 느립니다. PostgreSQL용 AlloyDB 대상 클러스터 기본 인스턴스에서 소스 데이터베이스의 대용량 데이터를 가져오는 속도가 느릴 수 있습니다.
  • 대상 PostgreSQL용 AlloyDB 기본 인스턴스에 더 높은 머신 등급을 선택하여 사용 가능한 최대 네트워크 대역폭과 CPU 용량을 확보합니다.
  • 대상 위치의 max_wal_size 플래그를 조정합니다. 일반적으로 이 플래그에는 32GB 또는 64GB를 설정하는 것이 좋습니다. 이 플래그를 업데이트해도 데이터베이스 서버를 다시 시작할 필요가 없습니다.
오류 메시지: subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again

전체 덤프 단계 중에 마이그레이션 작업이 실패했으며 작업을 복구할 수 없습니다. 소스 데이터베이스 인스턴스가 다시 시작되었거나 복구 모드에 있거나 wal_sender_timeout 파라미터에 설정된 값이 부족하여 복제 연결이 종료되었습니다.

문제의 근본 원인을 찾으려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔의 로그 탐색기 페이지로 이동합니다.
  2. 리소스 목록에서 PostgreSQL용 AlloyDB 인스턴스를 선택합니다. 인스턴스의 최근 로그 목록이 표시됩니다.
  3. 로그 파일 이름에서 postgres.log를 선택합니다.
  4. 로그의 심각도 수준을 Warning 이상의 모든 수준으로 설정합니다. 첫 번째 오류 로그가 실패의 근본 원인일 수 있습니다.
  • 전체 덤프 단계 중에 Database Migration Service가 항상 소스 데이터베이스 인스턴스에 연결할 수 있는지 확인합니다.
  • 소스 데이터베이스 인스턴스에서 wal_sender_timeout 매개변수 값이 더 큰 숫자 (예: 0)로 설정되어 있는지 확인합니다.
  • 마이그레이션 작업을 다시 시작한 후 다시 시도합니다.
오류 메시지: ERROR: unknown column name {column_name}

기본 노드의 복제된 테이블에 열이 추가되었지만 복제본 노드에는 추가되지 않았습니다.

연속 마이그레이션 중에는 데이터 조작 언어 (DML) 변경사항만 자동으로 업데이트됩니다. 소스 데이터베이스와 대상 데이터베이스가 호환되도록 데이터 정의 언어 (DDL) 변경사항을 관리해야 합니다. 다음 두 가지 방법으로 이 작업을 수행할 수 있습니다.

  • 소스 데이터베이스에 대한 쓰기를 중지하고 소스와 대상 모두에서 DDL 명령어를 실행합니다. 대상에서 DDL 명령어를 실행하기 전에 DDL 변경사항을 적용하는 PostgreSQL용 AlloyDB 사용자에게 alloydbexternalsync 역할을 부여합니다.
  • pglogical.replicate_ddl_command를 사용하여 일관된 지점에서 소스 및 대상에서 DDL 명령어를 실행할 수 있습니다. 명령어를 실행하는 사용자는 소스와 대상 모두에서 동일한 사용자 이름을 가져야 하며, 마이그레이션되는 아티팩트 (예: 테이블, 시퀀스, 뷰 또는 데이터베이스)의 수퍼유저 또는 소유자여야 합니다.

pglogical.replicate_ddl_command 사용 예시는 연속 마이그레이션을 참조하세요.
오류 메시지: ERROR: cannot truncate a table referenced in a foreign key constraint

사용자가 외래 키 제약 조건이 있는 테이블을 자르려고 했습니다.

외래 키 제약조건을 먼저 삭제한 후 테이블을 자릅니다.
오류 메시지: ERROR: connection to other side has died

wal_sender_timeout 파라미터에 설정된 값이 부족하여 복제 연결이 종료되었습니다. 이 오류는 일반적으로 초기 덤프가 성공한 후 복제 단계에서 발생합니다.

wal_sender_timeout 파라미터 값을 늘리거나 소스 데이터베이스 인스턴스에서 값을 0로 설정하여 제한 시간 메커니즘을 사용 중지하세요.
경고 메시지: migration job test configuration has returned the following warnings: Some table(s) have limited support.

소스에 기본 키가 없는 테이블과 같이 지원이 제한된 테이블이 있습니다.

경고 메시지입니다. 마이그레이션을 진행할 수 있지만 표준 마이그레이션에서는 기본 키가 없는 테이블이 변경 데이터 캡처 (CDC) 단계 중에 초기 스냅샷과 INSERT 문만 복제하고 UPDATE 및 DELETE 문은 복제되지 않습니다. 자세한 내용은 소스 데이터베이스 구성을 참조하세요.

선택한 데이터베이스를 마이그레이션하고 마이그레이션 작업에서 하나 이상의 데이터베이스에 데이터를 복제할 수 없는 경우 데이터베이스 목록에 실패 상태가 표시됩니다. 다양한 마이그레이션 작업 오류

오류 열에서 오류 보기를 클릭하고 오류를 수정합니다. 마이그레이션 작업에서 실패한 데이터베이스를 삭제할 수도 있습니다.

마이그레이션 작업에서 실패한 데이터베이스를 삭제하는 방법에 대한 자세한 내용은 마이그레이션 작업 관리를 참조하세요.

기존 대상 클러스터에서 추가 데이터 삭제

기존 대상 클러스터로 마이그레이션하면 다음 오류 메시지가 표시됩니다. The destination cluster contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty clusters. Clear your destination cluster and retry the migration job.을 참고하세요.

이 문제는 대상 클러스터에 추가 데이터가 포함된 경우에 발생할 수 있습니다. 비어 있는 기존 클러스터로만 마이그레이션할 수 있습니다. 알려진 제한사항을 참조하세요.

해결 방법

다음 단계를 수행하여 대상 클러스터에서 충돌하거나 추가 데이터를 삭제하고 마이그레이션 작업을 다시 시작합니다.

  1. 마이그레이션 작업을 중지합니다.
  2. psql 또는 AlloyDB Studio를 사용하여 대상 PostgreSQL용 AlloyDB 클러스터 기본 인스턴스에 연결합니다.
  3. 대상 클러스터 데이터베이스에서 추가 데이터를 삭제합니다. 대상에는 시스템 구성 데이터만 포함될 수 있습니다. 대상 데이터베이스에는 사용자 데이터 (예: 사용자 정의 테이블 또는 루틴)가 포함될 수 없습니다. 데이터베이스에서 실행하여 비시스템 데이터를 찾을 수 있는 다양한 SQL 문이 있습니다.

    비시스템 데이터베이스를 검색하는 SQL 문 예시 (확대하려면 클릭)

    SELECT datname FROM pg_catalog.pg_database
WHERE datname NOT IN ('alloydbadmin', 'template1', 'template0', 'postgres');

    postgres 데이터베이스에서 비시스템 데이터를 검색하는 SQL 문 예시 (확대하려면 클릭)

    postgres 데이터베이스는 시스템 데이터베이스이지만 비시스템 데이터를 포함할 수 있습니다. postgres 데이터베이스에서 이러한 문을 실행해야 합니다. psql 클라이언트를 사용하여 대상 클러스터에 연결하는 경우 \connect {database_name_here} 명령어를 사용하여 연결을 재설정하지 않고 다른 데이터베이스로 전환할 수 있습니다.

    SELECT table_schema, table_name FROM information_schema.tables
WHERE table_schema != 'information_schema' AND table_schema not like 'pg\_%';

SELECT routine_schema, routine_name FROM information_schema.routines
WHERE routine_schema != 'information_schema' AND routine_schema not like 'pg\_%';

SELECT extname FROM pg_extension WHERE extname NOT IN ('plpgsql', 'alloydb_utility');
  4. 이전 단계에서 식별된 비시스템 데이터베이스, 사용자 테이블, 사용자 정의 함수를 삭제합니다.
  5. 마이그레이션 작업을 시작합니다.

복제 슬롯 정리

다음 메시지 중 하나가 표시됩니다.

  • Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.
  • Error promoting EM replica: finished drop replication with errors.

문제 원인

PostgreSQL용 AlloyDB 대상 클러스터를 승격할 때 PostgreSQL용 AlloyDB 클러스터에서 소스 인스턴스에 연결할 수 없는 경우 (예: 소스 인스턴스가 실행 중이 아니거나 PostgreSQL용 AlloyDB 클러스터를 소스 인스턴스의 허용 목록에서 삭제한 경우) 마이그레이션 작업을 승격하는 동안 복제에 필요한 설정을 삭제할 수 없습니다. 복제 슬롯을 수동으로 정리해야 합니다.

해결 방법

각 데이터베이스에 대해 superuser 권한이 있는 사용자로 다음 명령어를 실행합니다.

  1. 오류 메시지에서 복제 슬롯 이름을 가져온 후 다음 명령어를 실행하여 슬롯을 하나씩 삭제합니다.

    SELECT pg_drop_replication_slot('slot_name');

  2. 오류 메시지에 복제 슬롯 이름을 사용할 수 없는 경우 다음 명령어를 실행하여 기존 복제 슬롯을 쿼리합니다.

    SELECT pg_drop_replication_slot(slot_name) FROM pg_replication_slots WHERE slot_name LIKE '%alloydb%' AND active = 'f';

  3. 소스 인스턴스를 사용하는 PostgreSQL용 AlloyDB 복제본이 없으면 다음 명령어를 실행하여 pglogical 설정을 삭제합니다.

    SELECT pglogical.drop_node(node_name) FROM pglogical.node WHERE node_name LIKE '%alloydb%';

  4. pglogical 확장 프로그램이 더 이상 필요하지 않으면 다음 명령어를 실행하여 확장 프로그램을 제거합니다.

    DROP EXTENSION IF EXISTS pglogical;

오류 메시지: Cannot connect to invalid database

PostgreSQL 버전 15로 마이그레이션할 때 여러 번의 후속 연결 재시도 후 다음 증상 중 하나가 발생합니다.

문제 원인

이 문제는 pglogical 확장 프로그램의 교착 상태 문제로 인해 발생하는 경우가 많습니다. 자세한 내용은 GitHub의 pglogical Issue Tracker를 참조하세요.

해결 방법

새 대상 클러스터로 마이그레이션 작업을 다시 수행합니다.

문제가 발생한 대상 클러스터를 삭제하고 마이그레이션 작업을 다시 만들어 보세요. 다음 단계를 따르세요.

  1. 실패한 마이그레이션 작업을 삭제합니다. 마이그레이션 작업 검토를 참조하세요.
  2. 문제가 발생한 대상 클러스터를 삭제합니다. AlloyDB 클러스터 관리를 참조하세요.
  3. 마이그레이션 작업을 다시 만듭니다. 마이그레이션 작업 만들기를 참조하세요.
중간 버전으로 마이그레이션

PostgreSQL 14와 같은 이전 PostgreSQL 버전으로 마이그레이션하는 것이 좋습니다. 마이그레이션이 완료되면 원하는 PostgreSQL 15 인스턴스로 업그레이드할 수 있습니다. PostgreSQL용 AlloyDB 문서의 데이터베이스 메이저 버전 업그레이드를 참조하세요.

부트스트랩 모드에서 분리된 PostgreSQL용 AlloyDB 클러스터 삭제

드문 경우지만 마이그레이션 작업이 삭제되었지만 연결된 PostgreSQL용 AlloyDB 클러스터는 삭제되지 않고 여전히 부트스트랩 모드인 경우가 있습니다. --force 옵션과 함께 gcloud alloydb clusters delete 명령어를 사용하여 클러스터를 삭제할 수 있습니다.

gcloud alloydb clusters delete CLUSTER_ID \
    --region=REGION_ID \
    --force

활성 마이그레이션 작업에서 부트스트랩 클러스터를 사용하는 동안 이를 삭제하면 정의되지 않은 동작이 발생합니다.

사용자 및 역할 관리

기존 사용자 이전

현재 Database Migration Service는 소스 인스턴스에서 대상 PostgreSQL용 AlloyDB 클러스터로 기존 사용자 및 역할을 자동으로 마이그레이션하는 것을 지원하지 않습니다. PostgreSQL용 AlloyDB에서 사용자를 수동으로 만들어 이 마이그레이션을 관리할 수 있습니다.

alloydbexternalsync 사용자 정보

표준 마이그레이션 중에 PostgreSQL용 AlloyDB 복제본의 모든 데이터베이스 객체는 alloydbexternalsync 사용자가 소유합니다 (빠른 시작 마이그레이션에서는 postgres 사용자를 사용함). 데이터가 마이그레이션되고 마이그레이션 작업이 승격된 후 다음 단계를 완료하여 객체의 소유권을 다른 애플리케이션 사용자로 수정할 수 있습니다.

  • GRANT alloydbexternalsync TO USER; 명령어를 실행합니다.
  • 각 데이터베이스에서 REASSIGN OWNED BY alloydbexternalsync TO USER; 명령어를 실행합니다.
  • alloydbexternalsync 사용자를 삭제하려면 DROP ROLE alloydbexternalsync; 명령어를 실행합니다.