PostgreSQL에서 AlloyDB로의 마이그레이션 문제 진단

마이그레이션 오류 문제 해결

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

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

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

오류 문제를 해결하려면 실패한 마이그레이션 작업으로 이동하여 오류를 확인하고 오류 메시지에 설명된 단계를 따르세요.

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

다음 표에서 문제의 몇 가지 예와 해결 방법을 확인할 수 있습니다.

증상 가능한 원인 해결 방법
소스 데이터베이스 인스턴스에 연결하지 못함 소스 데이터베이스 인스턴스와 대상 인스턴스 간에 연결 문제가 있었습니다. 연결 디버깅의 단계를 따르세요.
소스 및 대상 데이터베이스 버전이 호환되지 않아 마이그레이션 작업을 실행하지 못함 소스 및 대상 데이터베이스 버전이 지원되는 조합이 아닙니다. 특히 제공된 소스 데이터베이스 버전이 대상 데이터베이스 버전과 호환되지 않습니다. 대상 데이터베이스 버전이 소스 데이터베이스 버전과 동일하거나 한 단계 상위의 메이저 버전인지 확인합니다. 그런 다음 새 마이그레이션 작업을 만듭니다.
소스에서 데이터 정의 언어 (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을 설치하세요.
오류 메시지: 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로 설정합니다.
오류 메시지: 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 Relational Database Service의 경우 rds-ca-2019-root.pem 인증서를 사용하면 이 문제가 발생할 수 있습니다.

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

Amazon Relational Database Service 사용 사례의 경우 rds-ca-2019-root.pem 인증서 대신 rds-combined-ca-bundle.pem 인증서를 사용하세요.

오류 메시지: 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 패키지가 올바르게 설치되어 있지 않습니다. 이 패키지를 올바르게 설치하는 방법에 대한 자세한 내용은 소스 인스턴스에 pglogical 패키지 설치를 참고하세요.

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

구성된 소스가 복구 모드에 있습니다. 복구 모드가 아닌 소스를 구성합니다.
전체 덤프가 느림 AlloyDB 대상이 소스 데이터베이스에서 대용량 데이터를 가져오는 데 시간이 오래 걸릴 수 있습니다.
  • 사용 가능한 최대 네트워크 및 디스크 대역폭을 얻으려면 AlloyDB 대상의 상위 등급을 선택하세요.
  • AlloyDB 대상의 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. 리소스 목록에서 AlloyDB 인스턴스를 선택합니다. 인스턴스의 가장 최근 로그 목록이 표시됩니다.
  3. 로그 파일 이름에서 postgres.log를 선택합니다.
  4. 로그의 심각도 수준을 Warning 위의 모든 수준으로 설정합니다. 첫 번째 오류 로그가 실패의 근본 원인일 수 있습니다.
  • 전체 덤프 단계 중에 Database Migration Service가 항상 소스 데이터베이스 인스턴스에 연결할 수 있는지 확인합니다.
  • 소스 데이터베이스 인스턴스에서 wal_sender_timeout 매개변수의 값이 더 큰 수 (예: 0)로 설정되어 있는지 확인합니다.
  • 마이그레이션 작업을 다시 시작한 후 다시 시도합니다.
오류 메시지: ERROR: unknown column name {column_name}

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

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

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

    • 연속 마이그레이션에서 pglogical.replicate_ddl_command 사용 예를 확인하세요.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 parameter에 설정된 값이 부족하여 복제 연결이 종료되었습니다. 이 오류는 일반적으로 초기 덤프가 성공한 후 복제 단계 중에 발생합니다.

소스 데이터베이스 인스턴스에서 wal_sender_timeout 파라미터 값를 늘리거나 값을 0으로 설정하여 제한 시간 메커니즘을 사용 중지하는 것이 좋습니다.
선택한 데이터베이스를 마이그레이션하고 마이그레이션 작업이 하나 이상의 데이터베이스에 데이터를 복제할 수 없는 경우 데이터베이스 목록에 실패 상태가 표시됩니다. 다양한 마이그레이션 작업 오류

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

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

복제 슬롯 정리

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

  • 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.

가능한 원인

AlloyDB 인스턴스를 승격할 때 AlloyDB 인스턴스에서 소스 인스턴스에 연결할 수 없는 경우 (예: 소스 인스턴스가 실행되고 있지 않거나 소스 인스턴스의 허용 목록에서 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. 소스 인스턴스를 사용하는 AlloyDB 복제본이 없는 경우 다음 명령어를 실행하여 pglogical 설정을 정리합니다.

    select pglogical.drop_node(node_name) from pglogical.node where node_name like 'alloydb';

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

    DROP EXTENSION IF EXISTS pglogical;

부트스트랩 모드에서 종속 AlloyDB 클러스터 삭제

드물게 마이그레이션 작업이 삭제되었지만 연결된 AlloyDB 클러스터는 삭제되지 않고 여전히 부트스트랩 모드에 있는 경우가 있습니다. AlloyDB의 클러스터 삭제 gcloud 명령어와--force 옵션을 결합하여 클러스터를 삭제할 수 있습니다.

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

사용자 및 역할 관리

기존 사용자 마이그레이션

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

alloydbexternalsync 사용자 정보

마이그레이션 중에 AlloyDB 기본 인스턴스의 모든 객체는 alloydbexternalsync 사용자가 소유합니다. 데이터가 마이그레이션된 후 다음 단계를 완료하여 객체의 소유권을 다른 사용자에게 수정할 수 있습니다.

  • GRANT alloydbexternalsync to {USER} 명령어를 실행합니다.
  • 각 데이터베이스에서 reassign owned by alloydbexternalsync to {USER}; 명령어를 실행합니다.
  • alloydbexternalsync 사용자를 삭제하려면 drop role alloydbexternalsync 명령어를 실행합니다.