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 대상에서 소스 데이터베이스에서 대량의 데이터를 가져오는 속도가 느릴 수 있습니다.
  • 대상을 만들 때 데이터 디스크 크기를 최종 크기에 가깝게 설정합니다. 전체 덤프 단계에서는 I/O 쓰기 집약적인 워크로드를 사용하며 디스크 크기가 클수록 I/O 성능이 향상됩니다. 자세한 내용은 블록 스토리지 성능을 참고하세요.
  • 사용 가능한 최대 네트워크 및 디스크 대역폭을 얻으려면 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 Console의 로그 탐색기 페이지로 이동합니다.
  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. 사용 예시는 연속 마이그레이션을 참고하세요.
오류 메시지: 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 클러스터는 삭제되지 않고 여전히 부트스트랩 모드에 있을 수 있습니다. --force 옵션과 함께 AlloyDB의 클러스터 삭제용 gcloud 명령어를 사용하여 클러스터를 삭제할 수 있습니다.

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

사용자 및 역할 관리

기존 사용자 이전

현재 Database Migration Service는 소스 인스턴스에서 대상 AlloyDB 인스턴스로 기존 사용자를 이전하는 작업을 지원하지 않습니다. AlloyDB에서 사용자를 직접 만들어 이 이전을 관리할 수 있습니다.

alloydbexternalsync 사용자 정보

이전하는 동안 AlloyDB 기본의 모든 객체는 alloydbexternalsync 사용자가 소유합니다. 데이터가 이전된 후 다음 단계에 따라 객체의 소유권을 다른 사용자에게 수정할 수 있습니다.

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