从 XtraBackup 物理文件迁移到 Cloud SQL

MySQL | PostgreSQL | SQL Server

本页面介绍了如何使用 Percona XtraBackup for MySQL 物理文件将 MySQL 数据库从外部服务器迁移到 Cloud SQL。

Cloud SQL 支持使用 Percona XtraBackup 将外部服务器上的 MySQL 数据库迁移到 Cloud SQL for MySQL 实例。您可以使用 XtraBackup 实用程序生成物理文件，然后将其上传到 Cloud Storage。与基于逻辑转储文件的常规迁移相比，使用物理文件最多可以将迁移的整体速度提高 10 倍。

Cloud SQL 支持对 MySQL 5.7 和 8.0 进行基于文件的物理迁移。不支持 MySQL 5.6。不支持从 Amazon Aurora 或 MySQL on Amazon RDS 数据库进行迁移。此外，Cloud SQL for MySQL 中的目标副本实例必须使用与外部服务器相同的 MySQL 主要版本进行安装。但是，目标副本可以使用更高的次要版本。例如，如果外部数据库使用 MySQL 8.0.31，则目标副本必须是 Cloud SQL for MySQL 8.0.31 版或更高版本。

本文档中的过程使用 Cloud SQL for MySQL Admin API。您也可以使用 Database Migration Service 执行此迁移。如需详细了解如何使用 Database Migration Service，请参阅使用 Percona XtraBackup 物理文件迁移数据库。

准备工作

本部分介绍了在将 MySQL 数据库迁移到 Google Cloud 之前需要执行的步骤。

设置 Google Cloud 项目

登录您的 Google Cloud 账号。如果您是 Google Cloud 新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

转到“项目选择器”

确保您的 Google Cloud 项目已启用结算功能。

启用 Cloud SQL Admin API。

启用 API

在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

转到“项目选择器”

确保您的 Google Cloud 项目已启用结算功能。

启用 Cloud SQL Admin API。

启用 API

确保您的用户账号具有 Cloud SQL Admin、Storage Admin、Compute Viewer 角色。

转到 IAM 页面

设置 Cloud Storage 存储桶

如果您尚未创建 Cloud Storage 存储桶，请创建一个。

安装 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 虚拟机上自行管理的 MySQL 数据库。不支持从 Amazon Aurora 或 MySQL on Amazon RDS 数据库进行迁移。
- 您必须仅通过一个使用默认数据文件名 ibdata1 的数据文件来配置 innodb_data_file_path 参数。如果数据库配置了两个数据文件或具有使用不同名称的数据文件，则您无法使用 XtraBackup 物理文件迁移数据库。例如，该迁移不支持配置了 innodb_data_file_path=ibdata01:50M:autoextend 的数据库。
- 源外部数据库的 innodb_page_size 参数必须使用默认值 16384 进行配置。
如果您尚未设置复制用户账号，请创建一个复制用户账号。您需要使用此用户账号的用户名和密码。

执行迁移

完成以下部分中的所有步骤，以将外部 MySQL 数据库迁移到 Cloud SQL。

创建并准备 XtraBackup 物理文件

在外部服务器上，使用 XtraBackup 对源数据库执行完整备份。如需详细了解如何进行完整备份，请参阅 Percona XtraBackup 文档中的创建完整备份。

不支持其他类型的备份，例如增量备份和部分备份。

例如：
```
sudo xtrabackup --backup \
--target-dir=XTRABACKUP_PATH \
--user=USERNAME \
--password=PASSWORD
```
执行以下变量替换操作：
- XTRABACKUP_PATH：输出备份文件的位置
- USERNAME：拥有对源数据库的 BACKUP_ADMIN 权限的用户
- PASSWORD：用户的密码
使用 XtraBackup 实用程序准备备份文件。该文件必须处于一致的状态。如需详细了解如何准备完整备份，请参阅准备完整备份。例如：
```
sudo xtrabackup --prepare --target-dir=XTRABACKUP_PATH
```
将 XTRABACKUP_PATH 替换为输出备份文件的位置。此命令可能需要几分钟才能完成，具体取决于数据库的大小。

将 XtraBackup 物理文件上传到 Cloud Storage

使用 gsutil 实用程序将备份文件上传到 Cloud Storage。

  time gsutil -m rsync -r XTRABACKUP_PATH CLOUD_STORAGE_BUCKET

将 XTRABACKUP_PATH 替换为输出备份文件的位置，并将 CLOUD_STORAGE_BUCKET 替换为 Cloud Storage 存储桶的路径。

XtraBackup 文件没有大小限制。不过，您可以上传到 Cloud Storage 存储桶的每个文件的大小不能超过 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 存储桶的名称。
`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：使用现有副本实例

确保现有副本实例的可用磁盘空间至少与您上传到 Cloud Storage 存储桶的物理文件相同。该实例必须具有足够的磁盘空间，才能从 Cloud Storage 下载相同数量的数据。
如需使用现有副本实例，请使用以下示例 replica.json 文件：
```
{
"demoteContext": {
    "sourceRepresentativeInstanceName": "SOURCE_NAME"
  }
}
```
属性说明

SOURCE_NAME 您分配给源表示形式实例的名称。

属性	说明
`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/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
              [email protected]
              is missing necessary permissions storage.objects.list and
              storage.objects.get to access Google Cloud Storage bucket"
}

向返回的服务账号添加 Cloud Storage 权限

如需添加所需的权限，请执行以下操作：

在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

进入“存储桶”
点击权限标签页。
点击授予访问权限。
在新的主账号字段中，输入验证响应中返回的服务账号的名称。例如，在上一步的示例输出中，返回的服务账号名称为 [email protected]。
在选择角色下拉列表中，选择 Storage Object Viewer 角色。
点击保存。

再次运行验证

向服务账号添加所需的权限后，请重新运行验证步骤以确保服务账号有权访问 Cloud Storage 存储桶。

验证步骤会检查以下内容：

存在 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": "[email protected]",
 "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 存储桶中的 XtraBackup 物理文件。保留您的外部服务器，直到完成必要的验证。

限制

本部分列出了 XtraBackup 迁移过程的限制：

您必须使用 Percona XtraBackup 将数据备份到 Cloud Storage 存储桶。不支持其他备份实用程序。
不支持迁移到早期的数据库主要版本或次要版本。例如，您无法从 MySQL 8.0 迁移到 5.7 或从 MySQL 8.0.36 迁移到 8.0.16。
只有本地 MySQL 数据库或在 Compute Engine 虚拟机上运行的自行管理的 MySQL 数据库支持从 XtraBackup 物理文件迁移数据库。不支持从 Amazon Aurora 或 MySQL on Amazon RDS 数据库进行迁移。
您只能从完整备份进行迁移。不支持其他备份类型，例如增量备份或部分备份。
数据库迁移不包括数据库用户或特权。
您必须将二进制日志格式设置为 ROW。如果将二进制日志配置为任何其他格式（例如 STATEMENT 或 MIXED），则复制可能会失败。
Cloud Storage 将您可以上传到存储桶的文件大小限制为 5 TB。
您无法从外部数据库迁移任何插件。
如果您为实例配置了高可用性，则在迁移的初始阶段完成之后，才能应用服务等级协议 (SLA)。在 XtraBackup 物理文件中的所有数据都导入到 Cloud SQL 实例后，此阶段会被视为完成。

问题排查

本部分列出了常见的问题排查场景。

导入失败

如果您在迁移时遇到类似于 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`	您分配给目标副本实例的名称。

从 XtraBackup 物理文件迁移到 Cloud SQL

准备工作

设置 Google Cloud 项目

设置 Cloud Storage 存储桶

安装 Google Cloud SDK

为外部服务器做好迁移准备

执行迁移

创建并准备 XtraBackup 物理文件

将 XtraBackup 物理文件上传到 Cloud Storage

定义源表示形式实例

标识目标副本实例

选项 1：创建副本实例

选项 2：使用现有副本实例

验证迁移设置

向返回的服务账号添加 Cloud Storage 权限

再次运行验证

将用户添加到 Cloud SQL 副本

开始迁移

监控迁移

监控复制

限制

问题排查

导入失败

取消或停止迁移

后续步骤