Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

從 XtraBackup 實體檔案遷移至 Cloud SQL

MySQL | PostgreSQL | SQL Server

本頁面說明如何使用 Percona XtraBackup for MySQL 實體檔案，將 MySQL 資料庫從外部伺服器遷移至 Cloud SQL。

Cloud SQL 支援使用 Percona XtraBackup，將外部伺服器上的 MySQL 資料庫遷移至 MySQL 適用的 Cloud SQL 執行個體。您可以使用 XtraBackup 公用程式產生實體檔案，然後上傳至 Cloud Storage。使用實體檔案，整體遷移速度最多可比一般邏輯 dump 檔案遷移快 10 倍。

Cloud SQL 支援 MySQL 5.7 和 8.0 的實體檔案遷移作業。不支援 MySQL 5.6 和 8.4。不支援從 Amazon Aurora 或 Amazon RDS MySQL 資料庫遷移。此外，MySQL 適用的 Cloud SQL 中的目標副本執行個體，必須安裝與外部伺服器相同的 MySQL 主要版本。不過，目標副本可以使用較新的子版本。舉例來說，如果外部資料庫使用 MySQL 8.0.31，目標副本必須是 MySQL 適用的 Cloud SQL 8.0.31 以上版本。

事前準備

本節說明將 MySQL 資料庫遷移至 Google Cloud前，需要採取的步驟。

設定 Google Cloud 專案

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Cloud SQL Admin API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Enable the API

確認您的使用者帳戶具備 Cloud SQL 管理員、Storage 管理員和 Compute 檢視者角色。

前往「IAM」頁面

設定 Cloud Storage bucket

如果尚未建立 Cloud Storage bucket，請先建立。

安裝 Google Cloud SDK

如要在外部伺服器上使用 gcloud CLI 指令，請安裝 Google Cloud SDK。

為遷移作業準備外部伺服器

在外部伺服器上安裝下列其中一個版本的 XtraBackup 公用程式。
- 如為 MySQL 5.7，請安裝 Percona XtraBackup 2.4。
- 如為 MySQL 8.0，請安裝 Percona XtraBackup 8.0.x。
如果是 MySQL 8.0，您必須安裝與來源伺服器版本相同或更新的 XtraBackup 版本。詳情請參閱 Percona XtraBackup 說明文件中的伺服器版本和備份版本比較。
請確認外部伺服器符合所有必要的複製作業需求。詳情請參閱「設定用於複製作業的外部伺服器」。

除了複製作業的外部伺服器需求外，從 XtraBackup 實體檔案遷移時，還須符合下列需求：
- MySQL 資料庫必須是地端部署資料庫，或是在 Compute Engine VM 上自行管理的 MySQL 資料庫。不支援從 Amazon Aurora 或 Amazon RDS 資料庫上的 MySQL 遷移。
- 來源外部資料庫的 innodb_page_size 參數必須設為預設值 16384。
如果尚未設定，請建立複製使用者帳戶。您需要這個使用者帳戶的使用者名稱和密碼。

執行遷移作業

請完成下列各節的所有步驟，將外部 MySQL 資料庫遷移至 Cloud SQL。

建立及準備 XtraBackup 實體檔案

在外部伺服器上，使用 XtraBackup 完整備份來源資料庫。如要進一步瞭解如何建立完整備份，請參閱 Percona XtraBackup 說明文件中的「建立完整備份」。

不支援其他類型的備份，例如增量和部分備份。

如要提升備份程序的效能，請按照下列步驟操作：
- 使用 --parallel=threads，在備份步驟中平行複製多個檔案
- 在準備步驟中，使用 --use-memory=size 增加記憶體配置
例如：
```
sudo xtrabackup --backup \
--target-dir=XTRABACKUP_PATH \
--user=USERNAME \
--password=PASSWORD \
--parallel=THREADS
```
請替換下列變數：
- XTRABACKUP_PATH：輸出備份檔案的位置
- USERNAME：在來源資料庫中具備 BACKUP_ADMIN 權限的使用者
- PASSWORD：使用者的密碼
- THREADS：建立備份時，同時複製多個資料檔案要使用的執行緒數量
使用 XtraBackup 公用程式準備備份檔案。檔案必須處於一致狀態。如要進一步瞭解如何準備完整備份，請參閱「準備完整備份」。例如：
```
sudo xtrabackup --prepare --target-dir=XTRABACKUP_PATH \
    --use-memory=MEMORY
```
請替換下列變數：
- XTRABACKUP_PATH：輸出備份檔案的位置
- MEMORY：為準備階段分配的記憶體。請指定 1 GB 到 2 GB。如要進一步瞭解 -use-memory 選項，請參閱 Percona XtraBackup 說明文件。
備份檔案的準備時間會因資料庫大小而異。

將 XtraBackup 實體檔案上傳至 Cloud Storage

使用 gcloud CLI 將備份檔案上傳至 Cloud Storage。

  gcloud storage rsync XTRABACKUP_PATH CLOUD_STORAGE_BUCKET --recursive

將 XTRABACKUP_PATH 替換為輸出備份檔案的位置，並將 CLOUD_STORAGE_BUCKET 替換為 Cloud Storage bucket 的路徑。

XtraBackup 檔案的大小沒有限制。不過，上傳至 Cloud Storage bucket 的單一檔案大小上限為 5 TB。

定義來源表示法執行個體

建立 source.json 檔案，定義外部伺服器的來源表示法執行個體。來源代表執行個體會為 Cloud SQL 中的外部伺服器提供中繼資料。

在 source.json 檔案中，提供下列有關外部伺服器的基本資訊。

{
"name": "SOURCE_NAME",
 "region": "REGION",
 "databaseVersion": "DATABASE_VERSION",
 "onPremisesConfiguration": {
    "hostPort": "SOURCE_HOST:3306",
    "username": "REPLICATION_USER_NAME",
    "password": "REPLICATION_USER_PASSWORD",
    "dumpFilePath": "CLOUD_STORAGE_BUCKET"
    "caCertificate": "SOURCE_CERT",
    "clientCertificate": "CLIENT_CERT",
    "clientKey": "CLIENT_KEY"
  }
}

屬性	說明
`SOURCE_NAME`	要建立的來源表示法執行個體名稱。
`REGION`	要存放來源代表執行個體的區域。指定要建立目標 Cloud SQL 副本執行個體的區域。
`DATABASE_VERSION`	外部伺服器上執行的資料庫版本。僅支援 `MYSQL_5_7` 或 `MYSQL_8_0`。
`SOURCE_HOST`	外部伺服器的 IPv4 位址和通訊埠，或外部伺服器的 DNS 位址。如果使用 DNS 位址，則最多可包含 60 個字元。
`USERNAME`	外部伺服器上的複製使用者帳戶。
`PASSWORD`	複製使用者帳戶的密碼。
`CLOUD_STORAGE_BUCKET`	包含 XtraBackup 實體檔案的 Cloud Storage bucket 名稱。
`CLIENT_CA_CERT`	外部伺服器上的 CA 憑證。只有在外部伺服器使用 SSL/TLS 時，才需要加入這個欄位。
`CLIENT_CERT`	外部伺服器上的用戶端憑證。僅適用於伺服器與用戶端驗證。只有在外部伺服器使用 SSL/TLS 時，才需要加入這個欄位。
`CLIENT_KEY`	外部伺服器上用戶端憑證的私密金鑰檔案。僅適用於伺服器與用戶端驗證。只有在外部伺服器使用 SSL/TLS 時，才需要加入這個欄位。

使用下列 curl 指令向 Cloud SQL Admin API 發出要求，建立來源代表執行個體。在要求資料中，提供您建立的 source.json 檔案。

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    --data @./source.json \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

屬性	說明
`PROJECT_ID`	Google Cloud中的專案 ID。

找出目標副本執行個體

建立檔案，找出 Cloud SQL 中要遷移的目標副本。您可以建立副本，將資料遷移至新的執行個體，也可以降級副本，使用現有的 Cloud SQL 執行個體。

選項 1：建立副本執行個體

如要建立副本執行個體，請使用下列 replica.json 檔案範例：

{
"name": "REPLICA_NAME",
"region": "REGION",
"databaseVersion": "DB_VERSION",
"settings": {
   "tier": "INSTANCE_TIER",
   "dataDiskSizeGb": "DISK_SIZE_GB",
   "edition": "EDITION_NAME"
},
"masterInstanceName": "SOURCE_NAME"
}

屬性	說明
`REPLICA_NAME`	要建立的 Cloud SQL 副本名稱。
`REGION`	指定您指派給來源表示法執行個體的相同區域。
`DATABASE_VERSION`	要與 Cloud SQL 副本搭配使用的資料庫版本。這個版本的選項為 `MYSQL_5_7` 或 `MYSQL_8_0`。這個資料庫主要版本必須與您為外部伺服器指定的資料庫版本相符。您也可以指定子版本，但子版本必須與外部伺服器上安裝的版本相同或更新。如需 MySQL 的可用字串清單，請參閱 SqlDatabaseVersion。
`INSTANCE_TIER`	託管副本執行個體的機器類型。您必須指定與執行個體版本和外部伺服器架構類型相符的機型。舉例來說，如果您在 `edition` 欄位中選取 `ENTERPRISE_PLUS`，就必須指定 db-perf-optimized 機型。如需支援的機器類型清單，請參閱「機器類型」。
`DISK_SIZE_GB`	Cloud SQL 副本的儲存空間大小，以 GB 為單位。重要事項：您指定的儲存空間大小，必須大於上傳至 Cloud Storage 的實體檔案大小。
`EDITION_NAME`	副本要使用的 Cloud SQL 版本。可能的值為 `ENTERPRISE_PLUS` (僅限 MySQL 8.0) 或 `ENTERPRISE`。
`SOURCE_NAME`	您指派給來源表示法執行個體的名稱。

使用下列 curl 指令向 Cloud SQL Admin API 發出要求，建立目標副本執行個體。在要求資料中，提供您建立的 JSON 檔案。

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    --data @./replica.json \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances

屬性	說明
`PROJECT_ID`	Google Cloud中的專案 ID。

方法 2：使用現有的副本執行個體

確認現有副本執行個體具有下列屬性：
- 架構類型 (x86 或 ARM) 與外部伺服器相同。
- 可用磁碟空間至少要與上傳至 Cloud Storage bucket 的實體檔案大小相同。執行個體必須有足夠的磁碟空間，才能從 Cloud Storage 下載相同數量的資料。
如要使用現有的副本執行個體，請使用下列 replica.json 檔案範例：
```
{
"demoteContext": {
    "sourceRepresentativeInstanceName": "SOURCE_NAME"
  }
}
```
屬性說明

SOURCE_NAME 您指派給來源表示法執行個體的名稱。

屬性	說明
`SOURCE_NAME`	您指派給來源表示法執行個體的名稱。

使用下列 curl 指令，向 demote Cloud SQL Admin API 提出要求，降級現有的目標副本執行個體。在要求資料中，提供您建立的 JSON 檔案。

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    --data @./replica.json \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/EXISTING_INSTANCE_ID/demote

屬性	說明
`PROJECT_ID`	Google Cloud中的專案 ID。
`EXISTING_INSTANCE_ID`	要用於遷移作業的現有副本執行個體 ID。

驗證遷移設定

執行下列指令，確認執行個體已正確設定，可進行遷移。

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{
             "syncMode": "SYNC_MODE",
             "skipVerification": false,
             "migrationType": "PHYSICAL"
               }' \
     -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/verifyExternalSyncSettings

屬性	說明
`SYNC_MODE`	指定 `offline`，將遷移作業設為一次性程序。如要設定從外部伺服器持續複製，請指定 `online`。
`PROJECT_ID`	Google Cloud中的專案 ID。
`REPLICA_NAME`	您指派給目標副本執行個體的名稱。

這項驗證步驟會先傳回服務帳戶。您必須為這個服務帳戶提供 Cloud Storage 權限，才能繼續遷移程序。系統會顯示權限不足的錯誤訊息，這是正常現象。以下是回應範例：

{
    "kind": "sql#externalSyncSettingError",
    "type": "INSUFFICIENT_GCS_PERMISSIONS",
    "detail": "Service account
              p703314288590-df3om0@my-project.
              is missing necessary permissions storage.objects.list and
              storage.objects.get to access Google Cloud Storage bucket"
}

將 Cloud Storage 權限新增至傳回的服務帳戶

如要新增必要權限，請按照下列步驟操作：

在 Google Cloud 控制台，前往「Cloud Storage bucket」頁面。

前往「Buckets」(值區) 頁面
按一下「Permissions」(權限) 分頁標籤。
點選「授予存取權」。
在「New principals」(新增主體) 欄位中，輸入驗證回應中傳回的服務帳戶名稱。舉例來說，在上一個步驟的輸出範例中，傳回的服務帳戶名稱是 p703314288590-df3om0@my-project.。
在「Select a role」(選取角色) 下拉式選單中，選取「Storage Object Viewer」角色。
按一下「儲存」。

再次執行驗證

將必要權限新增至服務帳戶後，請重新執行驗證步驟，確保服務帳戶可以存取 Cloud Storage bucket。

驗證步驟會檢查下列項目：

Cloud SQL 副本與外部伺服器之間有連線能力，但僅限持續遷移
複製功能使用者權限足夠
版本相容
Cloud SQL 副本尚未複製
外部伺服器已啟用二進位記錄

如果偵測到任何問題，Cloud SQL 會傳回錯誤訊息。

將使用者新增至 Cloud SQL 副本

您無法從外部伺服器匯入或遷移資料庫使用者帳戶。如需在 Cloud SQL 副本中新增任何資料庫使用者帳戶，請在開始複製前新增帳戶。詳情請參閱「運用內建驗證機制管理使用者」。

開始遷移

完成驗證且未傳回任何錯誤後，即可開始遷移。如要遷移外部伺服器，請使用 startExternalSync API。

使用下列指令：

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data '{
               "syncMode": "SYNC_MODE",
               "skipVerification": false,
               "migrationType": "PHYSICAL"
              }' \
     -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/startExternalSync

屬性	說明
`SYNC_MODE`	指定 `offline`，將遷移作業設為一次性程序。如要設定從外部伺服器持續複製，請指定 `online`。
`PROJECT_ID`	Google Cloud中的專案 ID。
`REPLICA_NAME`	您指派給目標副本執行個體的名稱。

監控遷移作業

如要查看遷移狀態，請按照下列步驟操作：

從 startExternalSync API 的回應中擷取遷移工作的作業 ID。例如：

{
"kind": "sql#operation",
 "targetLink": "https://sqladmin.googleapis.com/v1/projects/my-project/instances/replica-instance",
 "status": "PENDING",
 "user": "user@example.com",
 "insertTime": "******",
 "operationType": "START_EXTERNAL_SYNC",
 "name": "******",
 "targetId": "replica-instance",
 "selfLink": "https://sqladmin.googleapis.com/v1/projects/my-project/operations/OPERATION_ID",
 "targetProject": "my-project"
}

在下列指令中使用作業 ID。

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
    --header 'Content-Type: application/json' \
    -X GET \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/START_EXTERNAL_SYNC_OPERATION_ID

屬性	說明
`PROJECT_ID`	Google Cloud中的專案 ID。
`START_EXTERNAL_SYNC_OPERATION_ID`	遷移工作的作業 ID。

監控複製作業

Cloud SQL 中的目標副本執行個體完成初始資料載入後，執行個體會連線至外部伺服器，並套用匯出作業後的所有更新。

如要監控複製狀態，請參閱「確認複製狀態」。

Cloud SQL 副本收到外部伺服器的所有變更，且 Cloud SQL 副本沒有複製延遲後，請連線至資料庫。執行適當的資料庫指令，確保內容與外部伺服器相符。

將目標副本升級為獨立執行個體後，即可刪除 Cloud Storage bucket 中的 XtraBackup 實體檔案。請保留外部伺服器，直到完成必要驗證。

限制

本節列出 XtraBackup 遷移程序的限制：

您必須使用 Percona XtraBackup，將資料備份到 Cloud Storage bucket。不支援其他備份公用程式。
不支援遷移至較舊的資料庫主要或子版本。舉例來說，您無法從 MySQL 8.0 遷移至 5.7，或從 MySQL 8.0.36 遷移至 8.0.16。
只有地端部署 MySQL 資料庫，或在 Compute Engine VM 上執行的自行管理 MySQL 資料庫，才支援從 XtraBackup 實體檔案遷移資料庫。不支援從 Amazon Aurora 或 Amazon RDS 資料庫上的 MySQL 遷移。
您只能從完整備份進行遷移。不支援其他備份類型，例如增量或部分備份。
資料庫遷移不包含資料庫使用者或權限。
您必須將二進位記錄格式設為 ROW。如果將二進位記錄設為任何其他格式 (例如 STATEMENT 或 MIXED)，複製作業可能會失敗。
Cloud Storage 限制可上傳至 bucket 的檔案大小為 5 TB。
您無法從外部資料庫遷移任何外掛程式。
如果您已為執行個體設定高可用性，則在遷移作業的初始階段完成之前，服務水準協議不適用。當 XtraBackup 實體檔案中的所有資料都匯入 Cloud SQL 執行個體後，這個階段即視為完成。
無法遷移至 MySQL 8.4 資料庫，也無法從 MySQL 8.4 資料庫遷移。
不支援在架構類型不同的機器之間遷移資料庫。舉例來說，您無法將託管於 ARM 架構機器的 MySQL 資料庫，遷移至 x86 架構機器。

疑難排解

本節列出常見的疑難排解情境。

無法匯入

如果在遷移時看到類似 Attempt 1/2: import failed 的錯誤訊息，請在開始遷移時，為 migrationType 指定 PHYSICAL。

如未指定 migrationType，類型會預設為 LOGICAL。

取消或停止遷移作業

如要取消或停止遷移，請執行下列指令：

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
    -X POST \
https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/REPLICA_NAME/restart

屬性	說明
`PROJECT_ID`	Google Cloud中的專案 ID。
`REPLICA_NAME`	您指派給目標副本執行個體的名稱。