PostgreSQL용 Cloud SQL로의 동질한 마이그레이션 문제 진단

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

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

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

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

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

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

문제 설명	문제 원인	해결 방법
기존 대상 인스턴스로 이전하면 다음과 같은 오류 메시지가 표시됩니다. The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job.	대상 Cloud SQL 인스턴스에 추가 데이터가 포함되어 있습니다. 비어 있는 기존 인스턴스로만 이전할 수 있습니다. 알려진 제한사항을 참고하세요.	대상 인스턴스를 읽기/쓰기 인스턴스로 승격하고, 추가 데이터를 삭제한 후, 마이그레이션 작업을 다시 시도합니다. 기존 대상 인스턴스에서 추가 데이터 삭제를 참고하세요.
소스 데이터베이스 인스턴스에 연결할 수 없습니다.	소스 데이터베이스 인스턴스와 대상 인스턴스 간에 연결 문제가 있습니다.	연결 디버깅의 단계를 따릅니다.
소스 및 대상 데이터베이스 버전이 호환되지 않아 마이그레이션 작업을 실행할 수 없음	소스 및 대상 데이터베이스 버전의 조합이 지원되지 않습니다. 특히 제공된 소스 데이터베이스 버전이 대상 데이터베이스 버전과 호환되지 않습니다.	대상 데이터베이스 버전이 소스 데이터베이스 버전과 동일하거나 한 단계 상위의 주 버전인지 확인합니다. 그런 다음 새 마이그레이션 작업을 만듭니다.
소스에서 데이터 정의 언어 (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로 이전할 때 후속 연결 재시도 횟수가 여러 번 반복되면 다음 증상 중 하나가 발생합니다. Cannot connect to invalid database 오류 메시지가 표시됩니다. 마이그레이션 작업이 전체 데이터베이스 덤프를 실행하는 데 시간이 오래 걸리면 스토리지 사용량 마이그레이션 작업 측정항목에 진행률이 표시되지 않습니다.	이 문제는 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로 설정합니다.
오류 메시지: 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.	구성된 소스가 복구 모드입니다.	복구 모드가 아닌 소스를 구성합니다.
전체 덤프가 느립니다.	Cloud SQL 대상에서 소스 데이터베이스에서 대용량 데이터를 가져오는 속도가 느릴 수 있습니다.	대상을 만들 때 데이터 디스크 크기를 최종 크기에 가깝게 설정합니다. 전체 덤프 단계에서는 I/O 쓰기 집약적인 워크로드를 사용하며 디스크 크기가 클수록 I/O 성능이 향상됩니다. 자세한 내용은 블록 스토리지 성능을 참고하세요. Cloud SQL 대상의 등급을 더 높여 사용 가능한 최대 네트워크 및 디스크 대역폭을 확보합니다. Cloud SQL 대상의 max_wal_size 플래그를 조정합니다. 일반적으로 이 플래그에는 32GB 또는 64GB를 설정하는 것이 좋습니다. 이 플래그를 업데이트해도 서버를 다시 시작할 필요가 없습니다.
오류 메시지: subscriber {subscriber_name} initialization failed during nonrecoverable step (d), please try the setup again	전체 덤프 단계에서 마이그레이션 작업이 실패했으며 작업을 복구할 수 없습니다. 소스 데이터베이스 인스턴스가 다시 시작되었거나 복구 모드이거나 wal_sender_timeout 매개변수에 설정된 값이 충분하지 않아 복제 연결이 종료되었습니다. 문제의 근본 원인을 찾으려면 다음 단계를 따르세요. Google Cloud 콘솔의 로그 탐색기로 이동합니다. 리소스 목록에서 Cloud SQL 복제본을 선택합니다. 복제본의 최근 로그 목록이 표시됩니다. 로그 파일 이름에서 postgres.log를 선택합니다. 로그의 심각도 수준을 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로 설정하여 제한 시간 메커니즘을 사용 중지하는 것이 좋습니다.
경고 메시지: migration job test configuration has returned the following warnings: Some table(s) have limited support.	소스에 기본 키가 없는 테이블과 같이 제한적으로 지원되는 테이블이 있습니다.	경고 메시지입니다. 마이그레이션을 진행할 수 있지만 지원되지 않는 항목 (예: 기본 키가 없는 테이블)은 마이그레이션되지 않습니다. 자세한 내용은 소스 데이터베이스 구성을 참고하세요.
선택한 데이터베이스를 마이그레이션했는데 마이그레이션 작업에서 하나 이상의 데이터베이스에 데이터를 복제할 수 없는 경우 데이터베이스 목록에 실패 상태가 표시됩니다.	다양한 마이그레이션 작업 오류	오류 열에서 오류 보기를 클릭하고 오류를 수정합니다. 이전 작업에서 실패한 데이터베이스를 삭제할 수도 있습니다. 마이그레이션 작업에서 실패한 데이터베이스를 삭제하는 방법에 관한 자세한 내용은 마이그레이션 작업 관리를 참고하세요.

기존 대상 인스턴스에서 추가 데이터 삭제

기존 대상 인스턴스로 이전하면 다음과 같은 오류 메시지가 표시됩니다. The destination instance contains existing data or user defined entities (for example databases, tables, or functions). You can only migrate to empty instances. Clear your destination instance and retry the migration job.

이 문제는 대상 인스턴스에 추가 데이터가 포함되어 있을 때 발생할 수 있습니다. 비어 있는 기존 인스턴스로만 이전할 수 있습니다. 알려진 제한사항을 참고하세요.

해결 방법

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

1. 마이그레이션 작업을 중지합니다.
2. 이 시점에서 대상 Cloud SQL 인스턴스는 `읽기 전용` 모드입니다. 대상 인스턴스를 승격하여 쓰기 액세스 권한을 얻습니다.
3. 대상 Cloud SQL 인스턴스에 연결합니다.
4. 대상 인스턴스 데이터베이스에서 추가 데이터를 삭제합니다. 대상에는 시스템 구성 데이터만 포함할 수 있습니다. 대상 데이터베이스에는 사용자 데이터 (예: 테이블)가 포함될 수 없습니다. 데이터베이스에서 실행하여 시스템 외 데이터를 찾을 수 있는 다양한 SQL 문이 있습니다. 예를 들면 다음과 같습니다.

   시스템 외 데이터베이스를 검색하는 SQL 문의 예시 (클릭하여 펼치기)

   SELECT datname FROM pg_catalog.pg_database
   WHERE datname NOT IN ('cloudsqladmin', '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 != 'plpgsql';
       

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.

문제 원인

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

해결 방법

각 데이터베이스에 대해 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 '%cloudsql%' and active = 'f';

3. 소스 인스턴스를 사용하는 Cloud SQL 복제본이 없는 경우 다음 명령어를 실행하여 pglogical 설정을 정리합니다.

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

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

   DROP EXTENSION IF EXISTS pglogical;

---

오류 메시지: Cannot connect to invalid database

PostgreSQL 버전 15로 이전할 때 후속 연결 재시도 횟수가 여러 번 반복되면 다음 증상 중 하나가 발생합니다.

• Cannot connect to invalid database 오류 메시지가 표시됩니다.
• 마이그레이션 작업이 전체 데이터베이스 덤프를 실행하는 데 시간이 오래 걸리면 스토리지 사용량 마이그레이션 작업 측정항목에 진행률이 표시되지 않습니다.

문제 원인

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

해결 방법

새 대상 인스턴스로 마이그레이션 작업 다시 실행

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

1. 문제가 발생한 대상 인스턴스를 삭제합니다. PostgreSQL용 Cloud SQL 문서의 인스턴스 삭제를 참고하세요.
2. 실패한 마이그레이션 작업을 삭제합니다. 마이그레이션 작업 검토를 참고하세요.
3. 마이그레이션 작업을 다시 만듭니다. 마이그레이션 작업 만들기를 참고하세요.

중간 버전으로 이전

이전 PostgreSQL 버전(예: PostgreSQL 14)으로 이전하는 것이 좋습니다. 마이그레이션이 완료되면 원하는 PostgreSQL 15 인스턴스로 업그레이드해 볼 수 있습니다. PostgreSQL용 Cloud SQL 문서에서 데이터를 이전하여 데이터베이스 주 버전 업그레이드를 참고하세요.

사용자 및 역할 관리

기존 사용자 이전

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

cloudsqlexternalsync 사용자 정보

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

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

새 Cloud SQL 인스턴스로 데이터 가져오기

먼저 Database Migration Service가 Cloud Storage로 마이그레이션한 Cloud SQL 인스턴스에서 데이터를 내보내고 그런 다음 Cloud Storage에서 독립형 Cloud SQL 인스턴스로 데이터를 가져오면 대상 인스턴스에 cloudsqlexternalsync 사용자가 없으므로 가져오기에 실패할 수 있습니다.

이 문제를 완화하려면 대상 인스턴스에서 cloudsqlexternalsync 사용자를 만들거나 이전된 인스턴스에서 사용자를 삭제하세요.