소스 데이터베이스의 잘못된 비밀번호와 같은 일부 오류는 복구할 수 있으므로 수정할 수 있으며 마이그레이션 작업이 자동으로 재개됩니다.
데이터 복제 오류와 같이 복구할 수 없는 오류도 있습니다. 이 경우 마이그레이션 작업을 처음부터 다시 시작해야 합니다.
오류가 발생하면 이전 작업 상태가 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 인스턴스에 추가 데이터가 포함되어 있습니다. 비어 있는 기존 인스턴스로만 이전할 수 있습니다.
알려진 제한사항을 참고하세요.
대상 인스턴스를 읽기/쓰기 인스턴스로 승격하고, 추가 데이터를 삭제한 후, 마이그레이션 작업을 다시 시도합니다.
기존 대상 인스턴스에서 추가 데이터 삭제를 참고하세요.
로그의 심각도 수준을 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.
이 문제는 대상 인스턴스에 추가 데이터가 포함되어 있을 때 발생할 수 있습니다.
비어 있는 기존 인스턴스로만 이전할 수 있습니다.
알려진 제한사항을 참고하세요.
해결 방법
다음 단계를 수행하여 대상 인스턴스에서 추가 데이터를 삭제하고 마이그레이션 작업을 다시 시작합니다.
대상 인스턴스 데이터베이스에서 추가 데이터를 삭제합니다. 대상에는 시스템 구성 데이터만 포함할 수 있습니다. 대상 데이터베이스에는 사용자 데이터 (예: 테이블)가 포함될 수 없습니다. 데이터베이스에서 실행하여 시스템 외 데이터를 찾을 수 있는 다양한 SQL 문이 있습니다. 예를 들면 다음과 같습니다.
postgres 데이터베이스에서 시스템 외 데이터를 검색하는 SQL 문 예시 (클릭하여 펼치기)
postgres 데이터베이스는 시스템 데이터베이스이지만 시스템 외부 데이터를 포함할 수 있습니다. postgres 데이터베이스에서 이 문을 실행해야 합니다. psql 클라이언트를 사용하여 대상 인스턴스에 연결하는 경우 \connect {database_name_here} 명령어를 사용하여 연결을 재설정하지 않고도 다른 데이터베이스로 전환할 수 있습니다.
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 권한이 있는 사용자로 다음 명령어를 실행합니다.
오류 메시지에서 복제 슬롯 이름을 가져온 다음 다음 명령어를 실행하여 슬롯을 하나씩 삭제합니다.
select pg_drop_replication_slot({slot_name});
오류 메시지에서 복제 슬롯 이름을 사용할 수 없는 경우 다음 명령어를 실행하여 기존 복제 슬롯을 쿼리합니다.
select pg_drop_replication_slot(slot_name) from pg_replication_slots where slot_name like '%cloudsql%' and active = 'f';
소스 인스턴스를 사용하는 Cloud SQL 복제본이 없는 경우 다음 명령어를 실행하여 pglogical 설정을 정리합니다.
select pglogical.drop_node(node_name) from pglogical.node where node_name like 'cloudsql';
pglogical 확장 프로그램이 더 이상 필요하지 않으면 다음 명령어를 실행하여 확장 프로그램을 제거합니다.
DROP EXTENSION IF EXISTS pglogical;
오류 메시지:
Cannot connect to invalid database
PostgreSQL 버전 15로 이전할 때 후속 연결 재시도 횟수가 여러 번 반복되면 다음 증상 중 하나가 발생합니다.
이전 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 사용자가 없으므로 가져오기에 실패할 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-08-18(UTC)"],[[["\u003cp\u003eMigration jobs can encounter recoverable errors, which allow for automatic resumption after being fixed, or unrecoverable errors that necessitate a complete restart of the migration job.\u003c/p\u003e\n"],["\u003cp\u003eTroubleshooting errors involves navigating to the failed migration job to examine the error message and follow the provided steps, as well as consulting Cloud Monitoring logs for more details.\u003c/p\u003e\n"],["\u003cp\u003eCommon issues during migration include connectivity problems, incompatible database versions, data conflicts with existing destination instances, and issues with required settings and privileges.\u003c/p\u003e\n"],["\u003cp\u003eTo resolve issues where a destination instance has extra data, the migration job must be stopped, the destination instance promoted to read/write, extra data cleared, and then the migration job restarted.\u003c/p\u003e\n"],["\u003cp\u003eCertain errors, like those involving replication slots, require manual cleanup via specific commands executed by a user with superuser privileges, while others, like a deadlock issue in the \u003ccode\u003epglogical\u003c/code\u003e extension in PostgreSQL version 15, may require deleting the instance and starting a new migration job, or migrating to an intermediate PostgreSQL version.\u003c/p\u003e\n"]]],[],null,["# Diagnose issues for homogeneous migrations to Cloud SQL for PostgreSQL\n\n\u003cbr /\u003e\n\nThe migration job process might incur errors during runtime.\n\n- Some errors, such as a bad password on the source database, are recoverable, meaning they can be fixed and the migration job resumes automatically.\n- Some are unrecoverable, such as errors in data replication, meaning the migration job needs to be restarted from the beginning.\n\nWhen an error occurs, the migration job status changes to `Failed`, and the substatus reflects the last status before failure.\n\nTo troubleshoot an error, navigate to the failed migration job to view the error and follow the steps outlined in the error message.\n\nTo view more details about the error, navigate to Cloud Monitoring using the link on the migration job. The logs are filtered to the specific migration job.\n\nIn the following table, you can find some examples of issues and how they can be solved:\n\n### Clear extra data from your existing\ndestination instance\n\nWhen you migrate to [an existing destination instance](/database-migration/docs/postgres/create-migration-job-existing-instance), you receive the following error message:\n`The destination instance contains existing data or user defined\nentities (for example databases, tables, or functions). You can only\nmigrate to empty instances. Clear your destination instance and retry\nthe migration job.`\n\nThis issue can occur if your destination instance contains extra data.\nYou can only migrate to existing instances that are empty. See\n[Known limitations](/database-migration/docs/postgres/known-limitations#existing-instance-limitations).\n\n#### Things to try\n\nClear extra data from your destination instance and start the migration job\nagain by performing the following steps:\n\n1. [Stop the migration job](/database-migration/docs/postgres/migration-job-actions).\n2. At this point, your destination Cloud SQL instance is in \\`read-only\\` mode. [Promote the destination instance](/sql/docs/postgres/replication/configure-replication-from-external#promote_the_replica) to gain write access.\n3. [Connect to your destination Cloud SQL instance](/sql/docs/postgres/connect-overview).\n4. Remove extra data from your destination instance databases. Your destination can only contain system configuration data. Destination databases can't contain user data (such as tables). There are different SQL statements you can run on your databases to find non-system data, for example: \n\n #### Example SQL statement to retrieve non-system databases (click to expand)\n\n ```sql\n SELECT datname FROM pg_catalog.pg_database\n WHERE datname NOT IN ('cloudsqladmin', 'template1', 'template0', 'postgres');\n ``` \n\n #### Example SQL statement to retrieve non-system data in the `postgres` database (click to expand)\n\n The `postgres` database is a system database, but it can\n contain non-system data. Make sure you run these statements on the\n `postgres` database. If you use the `psql` client\n to connect to the destination instance, you can switch to another\n database without resetting your connection by using the\n [`\\connect {database_name_here}`](https://www.postgresql.org/docs/current/app-psql.html#APP-PSQL-META-COMMAND-C-LC) command. \n\n ```sql\n SELECT table_schema, table_name FROM information_schema.tables\n WHERE table_schema != 'information_schema' AND table_schema not like 'pg\\_%';\n\n SELECT routine_schema, routine_name FROM information_schema.routines\n WHERE routine_schema != 'information_schema' AND routine_schema not like 'pg\\_%';\n\n SELECT extname FROM pg_extension WHERE extname != 'plpgsql';\n \n ```\n5. [Start the migration job](/database-migration/docs/postgres/migration-job-actions).\n\n*** ** * ** ***\n\n\n### Clean up replication slots\n\nYou see one of the following messages:\n\n- `Cleanup may have failed on source due to error: generic::unknown: failed to connect to on-premises database.`\n- `Error promoting EM replica: finished drop replication with errors.`\n\n\u003cbr /\u003e\n\n#### The issue might be\n\nWhen promoting a Cloud SQL instance, if the source instance isn't reachable from the Cloud SQL instance (for example, the source instance isn't running, or you removed the Cloud SQL instance from the allow list of source instances), then the settings needed for the replication can't be cleaned up during the promotion of a migration job. You must clean up the replication slots manually.\n\n#### Things to try\n\nFor each database, run the following commands as a user with the `superuser` privilege:\n\n1. Get the replication slot names from the error message, and then run the following command to drop the slots, one by one:\n\n ```\n select pg_drop_replication_slot({slot_name});\n ```\n2. If the replication slot names aren't available in the error message, then run the following command to query for the existing replication slots:\n\n ```\n select pg_drop_replication_slot(slot_name) from pg_replication_slots where slot_name like '%cloudsql%' and active = 'f';\n ```\n3. If there are no Cloud SQL replicas using the source instance, then run the following command to clean up `pglogical` settings:\n\n select pglogical.drop_node(node_name) from pglogical.node where node_name like 'cloudsql';\n\n4. If the `pglogical` extension isn't needed anymore, then run the following command to uninstall the extension:\n\n ```\n DROP EXTENSION IF EXISTS pglogical;\n ```\n\n\u003cbr /\u003e\n\n*** ** * ** ***\n\n### Error message:\n`Cannot connect to invalid database`\n\nWhen migrating to PostgreSQL version 15, after multiple subsequent connection\nretry attempts one of the following symptoms occur:\n\n- You receive a `Cannot connect to invalid database` error message.\n- The [Storage usage\n migration job metric](/database-migration/docs/postgres/migration-job-metrics) shows no progress after a long time when the migration job is performing the full database dump.\n\n\u003cbr /\u003e\n\n#### The issue might be\n\nThis problem is often attributed to\nthe deadlock issue in the `pglogical` extension. For more\ninformation, see the\n[`pglogical` issue tracker in GitHub](https://github.com/2ndQuadrant/pglogical/issues/418).\n\n#### Things to try\n\n##### Perform the migration job again with a new destination instance\n\nTry deleting the destination database where you experienced the issue\nand re-create your migration job. Follow these steps:\n\n1. Delete the destination instance where you experienced the problems. See [Delete instances](/sql/docs/postgres/delete-instance) in Cloud SQL for PostgreSQL documentation.\n2. Delete the failed migration job. See [Review a migration job](/database-migration/docs/postgres/review-migration-job).\n3. Re-create your migration job. See [Create a migration job](/database-migration/docs/postgres/create-migration-job).\n\n\u003cbr /\u003e\n\n##### Migrate to an intermediate version\n\nConsider migrating to an earlier PostgreSQL version, such as PostgreSQL 14.\nAfter a successful migration, you can try upgrade to the desired PostgreSQL 15\ninstance. See\n[Upgrade the database major version by migrating data](/sql/docs/postgres/upgrade-major-db-version-migrate) in Cloud SQL for PostgreSQL documentation.\n\n\n### Manage users and roles\n\n\u003cbr /\u003e\n\n#### Migrate existing users\n\nCurrently, Database Migration Service doesn't support migrating existing users from a source instance into a destination Cloud SQL instance. You can manage this migration by [creating the users in Cloud SQL](/sql/docs/postgres/create-manage-users) manually.\n\n#### About the `cloudsqlexternalsync` user\n\nDuring the migration, all objects on the Cloud SQL replica are owned by the `cloudsqlexternalsync` user. After the data is migrated, you can modify the ownership of the objects to other users by completing the following steps:\n\n- Run the `GRANT cloudsqlexternalsync to `\u003cvar translate=\"no\"\u003e{USER}\u003c/var\u003e command.\n- On each database, run the `reassign owned by cloudsqlexternalsync to `\u003cvar translate=\"no\"\u003e{USER}\u003c/var\u003e`;` command.\n- To remove the `cloudsqlexternalsync` user, run the `drop role cloudsqlexternalsync` command.\n\n#### Import data into a new Cloud SQL instance\n\nIf you first [export data](/sql/docs/postgres/import-export/import-export-sql) from a Cloud SQL instance that Database Migration Service migrated into Cloud Storage, and then [import the data](/sql/docs/postgres/import-export/import-export-sql) from Cloud Storage into a stand-alone Cloud SQL instance, the import might fail because the `cloudsqlexternalsync` user doesn't exist on the destination instance.\n\nTo mitigate the issue, either [create the `cloudsqlexternalsync` user](/sql/docs/postgres/create-manage-users) on the destination instance or [remove the user](#about-the-cloudsqlexternalsync-user) from the migrated instance."]]
