이러한 호출에서 sql#externalSyncSettingErrorList 유형 목록을 반환합니다.
목록이 비어 있으면 오류가 없는 것입니다. 오류가 없는 응답은 다음과 같이 표시됩니다.
{"kind":"sql#externalSyncSettingErrorList"}
속성
설명
SYNC_MODE
복제가 설정된 후 Cloud SQL 복제본과 외부 서버를 동기화 상태로 유지할 수 있는지 확인합니다. 동기화 모드에는 EXTERNAL_SYNC_MODE_UNSPECIFIED, ONLINE, OFFLINE이 있습니다.
SYNC_PARALLEL_LEVEL
데이터베이스 테이블의 데이터가 전송되는 속도를 제어하는 설정을 확인합니다. 사용할 수 있는 값은 다음과 같습니다.
min: 데이터베이스에서 가장 낮은 양의 컴퓨팅 리소스를 사용합니다. 데이터 전송 속도가 가장 느립니다.
optimal: 최적의 데이터베이스 부하로 균형 잡힌 성능을 제공합니다.
max: 데이터 전송 속도가 가장 빠르지만 데이터베이스 부하가 증가할 수 있습니다.
참고: 이 매개변수의 기본값은 optimal입니다. 이 설정은 데이터 전송 속도가 양호하고 데이터베이스에 합리적인 수준의 영향을 미치기 때문입니다. 이 값을 사용하는 것이 좋습니다.
SELECTED_OBJECTS
소스 표현 인스턴스에서 대상 Cloud SQL 인스턴스로 마이그레이션하는 쉼표로 구분된 데이터베이스 목록입니다. 이 파라미터를 사용하지 않거나 빈 목록을 파라미터 값으로 제공하면 모든 데이터베이스가 소스에서 대상으로 마이그레이션됩니다.
PROJECT_ID
개발자 Google Cloud 프로젝트의 ID입니다.
REPLICA_INSTANCE_ID
Cloud SQL 복제본의 ID입니다.
소스 표현 인스턴스 업데이트
소스 표현 인스턴스에서 대상 Cloud SQL 인스턴스로 마이그레이션하려는 데이터베이스를 업데이트하려면 selectedObjects 파라미터와 연결된 데이터베이스 이름 목록을 업데이트합니다. 이 파라미터를 사용하지 않거나 빈 목록을 파라미터 값으로 제공하면 모든 데이터베이스가 소스에서 대상으로 마이그레이션됩니다.
복제가 설정된 후 Cloud SQL 복제본과 외부 서버를 동기화 상태로 유지할 수 있는지 확인합니다.
SKIP_VERIFICATION
데이터를 동기화하기 전에 기본 제공 확인 단계를 건너뛸지 여부입니다. 이 매개변수는 이미 복제 설정을 확인한 경우에만 권장됩니다.
SYNC_PARALLEL_LEVEL
데이터베이스 테이블의 데이터가 전송되는 속도를 제어하는 설정을 제공합니다. 사용할 수 있는 값은 다음과 같습니다.
min: 데이터베이스에서 가장 낮은 양의 컴퓨팅 리소스를 사용합니다. 데이터 전송 속도가 가장 느립니다.
optimal: 최적의 데이터베이스 부하로 균형 잡힌 성능을 제공합니다.
max: 데이터 전송 속도가 가장 빠르지만 데이터베이스 부하가 증가할 수 있습니다.
참고: 이 매개변수의 기본값은 optimal입니다. 이 설정은 데이터 전송 속도가 양호하고 데이터베이스에 합리적인 수준의 영향을 미치기 때문입니다. 이 값을 사용하는 것이 좋습니다.
PROJECT_ID
개발자 Google Cloud 프로젝트의 ID입니다.
REPLICA_INSTANCE_ID
Cloud SQL 복제본의 ID입니다.
마이그레이션 모니터링
외부 서버에서 복제를 시작하면 복제를 모니터링해야 합니다. 자세한 내용은 복제 모니터링을 참조하세요.
그러면 마이그레이션을 완료할 수 있습니다.
문제 해결
다음 문제 해결 옵션을 고려하세요.
문제
문제 해결
생성 시 읽기 복제본이 복제를 시작하지 않음
로그 파일에 더 구체적인 오류가 있을 수 있습니다.
Cloud Logging의 로그를 검사하여 실제 오류를 찾으세요.
읽기 복제본을 만들 수 없음 - invalidFlagValue 오류
요청의 플래그 중 하나가 잘못되었습니다. 명시적으로 제공한 플래그 또는 기본값으로 설정된 플래그일 수 있습니다.
먼저 max_connections 플래그의 값이 기본 값보다 크거나 같은지 확인하세요.
max_connections 플래그가 적절하게 설정된 경우 Cloud Logging에서 로그를 검사하여 실제 오류를 확인하세요.
읽기 복제본을 만들 수 없음 - 알 수 없는 오류
로그 파일에 더 구체적인 오류가 있을 수 있습니다.
Cloud Logging의 로그를 검사하여 실제 오류를 찾으세요.
오류가 set Service Networking service account as
servicenetworking.serviceAgent role on consumer project이면 Service
Networking API를 사용 중지했다가 다시 사용 설정합니다. 이렇게 하면 프로세스를 계속 진행하는 데 필요한 서비스 계정이 생성됩니다.
디스크가 가득 참
복제본을 만드는 동안 기본 인스턴스 디스크 크기가 가득 찰 수 있습니다.
기본 인스턴스를 수정하여 더 큰 디스크 크기로 업그레이드합니다.
디스크 공간이 현저하게 증가함
데이터를 추적하는 데 적극적으로 사용되지 않는 슬롯이 있으면 PostgreSQL이 WAL 세그먼트를 무기한 저장합니다. 그로 인해 디스크 공간도 무제한으로 증가합니다. Cloud SQL에서 논리적 복제 및 디코딩 기능을 사용하는 경우 복제 슬롯이 자동으로 생성 및 삭제됩니다. 사용되지 않는 복제 슬롯은 pg_replication_slots 시스템 뷰를 쿼리하고 active 열로 필터링을 수행하여 확인할 수 있습니다. pg_drop_replication_slot 명령어를 사용하여 WAL 세그먼트를 삭제하기 위해 사용하지 않는 슬롯을 삭제할 수 있습니다.
복제본 인스턴스가 너무 많은 메모리를 사용하고 있습니다.
복제본은 임시 메모리를 사용하여 자주 요청되는 읽기 작업을 캐시하므로 기본 인스턴스보다 더 많은 메모리를 사용할 수 있습니다.
쓰기 부하가 너무 높아 복제본이 처리할 수 없습니다. 복제본의 SQL 스레드가 IO 스레드를 따라잡을 수 없는 경우 복제 지연이 발생합니다. 일부 쿼리 또는 워크로드로 인해 특정 스키마에서 일시적이거나 영구적인 복제 지연이 발생할 수 있습니다. 복제 지연이 발생하는 일반적인 원인은 다음과 같습니다.
복제본에 대한 쿼리의 속도가 느립니다. 문제를 찾아 수정하세요.
모든 테이블에 고유/기본 키가 있어야 합니다. 테이블에 고유/기본 키가 없으면 업데이트할 때마다 복제본에서 전체 테이블 검사를 수행해야 합니다.
DELETE ... WHERE field < 50000000과 같은 쿼리의 경우 복제본에 다수의 업데이트가 쌓이게 되므로 행 기준 복제에서 복제 지연이 발생합니다.
PostgreSQL에서 특정 색인을 다시 빌드해야 한다는 오류 메시지가 표시됩니다. 이 작업은 기본 인스턴스에서만 수행할 수 있습니다. 새 복제본 인스턴스를 만들면 곧 같은 오류가 다시 발생합니다.
PostgreSQL 10 미만의 PostgreSQL에서는 해시 색인이 복제본에 전파되지 않습니다.
해시 색인을 사용해야 하는 경우 PostgreSQL 10 이상으로 업그레이드하세요. 그러지 않고 복제본도 사용하려면 PostgreSQL 9.6에서 해시 색인을 사용하지 마세요.
기본 인스턴스에 대한 쿼리는 항상 실행됨
복제본을 만든 후에는 기본 인스턴스에서 SELECT * from pg_stat_activity where state = 'active' and pid = XXXX and username = 'cloudsqlreplica' 쿼리를 계속 실행해야 합니다.
제한 시간으로 인해 복제본을 만들지 못함
기본 인스턴스에서 커밋되지 않은 장기 실행 트랜잭션으로 인해 읽기 복제본을 만들지 못할 수 있습니다.
실행 중인 모든 쿼리를 중지한 후 복제본을 다시 만듭니다.
기본 인스턴스와 복제본의 vCPU 크기가 다른 경우 쿼리 최적화 도구에서 vCPU 크기를 고려하므로 쿼리 성능 문제가 발생할 수 있습니다.
이 문제를 해결하려면 다음 단계를 완료하시기 바랍니다.
log_duration 플래그를 사용 설정하고 log_statement 매개변수를 ddl로 설정합니다. 이렇게 하면 데이터베이스의 쿼리와 실행 시간 모두 제공됩니다. 그러나 워크로드에 따라 성능 문제가 발생할 수 있습니다.
기본 인스턴스와 읽기 복제본 모두에서 쿼리에 explain analyze를 실행합니다.
쿼리 계획을 비교하고 차이점을 확인합니다.
특정 쿼리이면 쿼리를 수정합니다. 예를 들어 조인 순서를 변경하여 성능이 향상되는지 확인할 수 있습니다.
[[["이해하기 쉬움","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)"],[],[],null,["# Use a managed import to set up replication from external databases\n\n\u003cbr /\u003e\n\n[MySQL](/sql/docs/mysql/replication/managed-import-replication-from-external \"View this page for the MySQL database engine\") \\| PostgreSQL \\| SQL Server\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis page describes how to set up and use a managed import for data when\nreplicating from an external server to Cloud SQL.\n\nYou must complete all the steps on this page. When finished, you can\nadminister and monitor the source representation instance the same way as you\nwould any other Cloud SQL instance.\n\nBefore you begin\n----------------\n\nBefore you begin, complete these steps:\n\n1. [Configure the external server](/sql/docs/postgres/replication/configure-replication-from-external#setting_up_the_external_server_for_replication).\n\n2. [Create the source representation instance](/sql/docs/postgres/replication/configure-replication-from-external#setup-source-instance).\n\n3. [Set up the Cloud SQL replica](/sql/docs/postgres/replication/configure-replication-from-external#setup-replica-instance).\n\nVerify your replication settings\n--------------------------------\n\nAfter your setup is complete, ensure that the Cloud SQL replica\ncan replicate from the external server.\n\nThe following external sync settings must be correct.\n\n- Connectivity between the Cloud SQL replica and external server\n- Replication user privileges\n- Version compatibility\n- The Cloud SQL replica is not already replicating\n\nTo verify these settings, open a Cloud Shell terminal and enter the following\ncommands: \n\n### curl\n\n gcloud auth login\n ACCESS_TOKEN=\"$(gcloud auth print-access-token)\"\n curl --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"syncMode\": \"\u003cvar translate=\"no\"\u003eSYNC_MODE\u003c/var\u003e\",\n \"syncParallelLevel\": \"\u003cvar translate=\"no\"\u003eSYNC_PARALLEL_LEVEL\u003c/var\u003e\",\n \"selectedObjects\": \"\u003cvar translate=\"no\"\u003eSELECTED_OBJECTS\u003c/var\u003e\"\n }' \\\n -X POST \\\n https://sqladmin.googleapis.com/sql/v1beta4/projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/instances/\u003cvar translate=\"no\"\u003eREPLICA_INSTANCE_ID\u003c/var\u003e/verifyExternalSyncSettings\n\n### example\n\n gcloud auth login\n ACCESS_TOKEN=\"$(gcloud auth print-access-token)\"\n curl --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"syncMode\": \"online\",\n \"syncParallelLevel\": \"optimal\",\n \"selectedObjects\":[{\"database\":\"db1\"}, {\"database\":\"db2\"}]\n }' \\\n -X POST \\\n https://sqladmin.googleapis.com/sql/v1beta4/projects/myproject/instances/myreplica/verifyExternalSyncSettings\n\nThese calls return a list of type `sql#externalSyncSettingErrorList`.\n\nIf the list is empty, then there are no errors. A response without errors appears like this: \n\n```bash\n {\n \"kind\": \"sql#externalSyncSettingErrorList\"\n }\n```\n\nUpdate a source representation instance\n---------------------------------------\n\nTo update the databases that you want to migrate from the source representation\ninstance to the destination Cloud SQL instance, update the list of\ndatabase names that are associated with the `selectedObjects` parameter. If you\ndon't use this parameter or provide an empty list as the value for the parameter,\nthen all databases are migrated from the source to the destination. \n\n### source.json\n\n\n```bash\n {\n \"name\": \"\u003cvar translate=\"no\"\u003eSOURCE_NAME\u003c/var\u003e\",\n \"region\": \"\u003cvar translate=\"no\"\u003eREGION\u003c/var\u003e\",\n \"databaseVersion\": \"\u003cvar translate=\"no\"\u003eDATABASE_VERSION\u003c/var\u003e\",\n \"onPremisesConfiguration\": {\n \"selectedObjects\": \"\u003cvar translate=\"no\"\u003eSELECTED_OBJECTS\u003c/var\u003e\",\n \"username\": \"\u003cvar translate=\"no\"\u003eUSERNAME\u003c/var\u003e\",\n \"password\": \"\u003cvar translate=\"no\"\u003ePASSWORD\u003c/var\u003e\"\n }\n }\n```\n\n\u003cbr /\u003e\n\n### example\n\n // example of source.json for external server that\n // - initiates replication from a Cloud SQL managed import\n // - doesn't use SSL/TLS\n\n {\n \"name\": \"cloudsql-source-instance\",\n \"region\": \"us-central1\",\n \"databaseVersion\": \"POSTGRES_9_6\",\n \"onPremisesConfiguration\": {\n \"selectedObjects\":[{\"database\":\"db1\"}, {\"database\":\"db3\"}],\n \"username\": \"newReplicationUser\",\n \"password\": \"525#@%*@\"\n }\n }\n\nThen, to modify the source representation instance in Cloud SQL, open\na Cloud Shell terminal and enter the following commands: \n\n### curl\n\n gcloud auth login\n ACCESS_TOKEN=\"$(gcloud auth print-access-token)\"\n curl --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n --header 'Content-Type: application/json' \\\n --data @\u003cvar translate=\"no\"\u003eJSON_PATH\u003c/var\u003e \\\n -X PATCH \\\n https://sqladmin.googleapis.com/sql/v1beta4/projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/instances/\u003cvar translate=\"no\"\u003eSOURCE_NAME\u003c/var\u003e\n\n### example\n\n gcloud auth login\n ACCESS_TOKEN=\"$(gcloud auth print-access-token)\"\n curl --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n --header 'Content-Type: application/json' \\\n --data @./source.json \\\n -X PATCH \\\n https://sqladmin.googleapis.com/sql/v1beta4/projects/MyProject/instances/cloudsql-source-instance\n\nStart replication on the external server\n----------------------------------------\n\nAfter verifying that you can replicate from the external server, start the replication. The speed for performing the replication for the initial import process is up to 500 GB per hour. However, this speed can vary based on the machine tier, data disk size, network throughput, and nature of your database. \n\n### curl\n\n gcloud auth login\n ACCESS_TOKEN=\"$(gcloud auth print-access-token)\"\n curl --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"syncMode\": \"\u003cvar translate=\"no\"\u003eSYNC_MODE\u003c/var\u003e\",\n \"skipVerification\": \"\u003cvar translate=\"no\"\u003eSKIP_VERIFICATION\u003c/var\u003e\",\n \"syncParallelLevel\": \"\u003cvar translate=\"no\"\u003eSYNC_PARALLEL_LEVEL\u003c/var\u003e\"\n }' \\\n -X POST \\\n https://sqladmin.googleapis.com/sql/v1beta4/projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/instances/\u003cvar translate=\"no\"\u003eREPLICA_INSTANCE_ID\u003c/var\u003e/startExternalSync\n\n### example\n\n gcloud auth login\n ACCESS_TOKEN=\"$(gcloud auth print-access-token)\"\n curl --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"syncMode\": \"online\",\n \"syncParallelLevel\": \"optimal\"\n }' \\\n -X POST \\\n https://sqladmin.googleapis.com/sql/v1beta4/projects/MyProject/instances/replica-instance/startExternalSync\n\nMonitor the migration\n---------------------\n\nOnce you start replication from the external server, you need to monitor\nreplication. To learn more, see\n[Monitoring replication](/sql/docs/postgres/replication/configure-replication-from-external#monitor_replication).\nYou can then complete your migration.\n\nTroubleshoot\n------------\n\nConsider the following troubleshooting options:\n\n### Review your replication logs\n\nWhen you [verify your replication settings](#verify-replication), logs are\nproduced.\n\nYou can view these logs by following these steps:\n\n1.\n Go to the Logs Viewer in the Google Cloud console.\n\n [Go to the Logs Viewer](https://console.cloud.google.com/logs?resource=cloudsql_database)\n2. Select the Cloud SQL replica from the **Instance** dropdown.\n3. Select the `replication-setup.log` log file.\n\nIf the Cloud SQL replica is unable to connect to the external server,\nconfirm the following:\n\n- Any firewall on the external server is configured to allow connections from the Cloud SQL replica's [outgoing IP address](#outgoing-ip).\n- Your SSL/TLS configuration is correct.\n- Your replication user, host, and password are correct.\n\nWhat's next\n-----------\n\n- Learn about [updating an instance](/sql/docs/postgres/edit-instance).\n- Learn about [managing replicas](/sql/docs/postgres/replication/manage-replicas).\n- Learn about [monitoring instances](/sql/docs/postgres/monitor-instance).\n- Learn about [promoting your Cloud SQL replica](/sql/docs/postgres/replication/manage-replicas#promote-replica)."]]
