从 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 项目

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud SQL Admin API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Cloud SQL Admin API.

   Enable the API

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

   转到 IAM 页面

设置 Cloud Storage 存储桶

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

安装 Google Cloud SDK

如需在外部服务器上使用 gcloud CLI 命令，请安装 Google Cloud SDK。

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

1. 在外部服务器上安装以下版本的 XtraBackup 实用程序之一。

   • 对于 MySQL 5.7，请安装 Percona XtraBackup 2.4。
   • 对于 MySQL 8.0，请安装 Percona XtraBackup 8.0.x。

   对于 MySQL 8.0，您必须安装等于或高于源服务器版本的 XtraBackup 版本。如需了解详情，请参阅 Percona XtraBackup 文档中的服务器版本和备份版本比较。

2. 确保外部服务器满足复制的所有必要要求。如需了解详情，请参阅设置外部服务器以进行复制。

   除了复制的外部服务器要求之外，从 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 进行配置。

3. 如果您尚未设置复制用户账号，请创建一个复制用户账号。您需要使用此用户账号的用户名和密码。

执行迁移

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

创建并准备 XtraBackup 物理文件

1. 在外部服务器上，使用 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：在创建备份的同时复制多个数据文件时使用的线程数

2. 使用 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 存储桶的路径。

XtraBackup 文件没有大小限制。不过，您可以上传到 Cloud Storage 存储桶的每个文件的大小不能超过 5 TB。

定义源表示形式实例

1. 创建一个 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 时，才应包含此字段。

2. 通过使用以下 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：创建副本实例

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	您分配给源表示形式实例的名称。

2. 通过使用以下 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：使用现有副本实例

1. 确保现有副本实例的可用磁盘空间至少与您上传到 Cloud Storage 存储桶的物理文件相同。该实例必须具有足够的磁盘空间，才能从 Cloud Storage 下载相同数量的数据。

2. 如需使用现有副本实例，请使用以下示例 replica.json 文件：

   {
   "demoteContext": {
       "sourceRepresentativeInstanceName": "SOURCE_NAME"
     }
   }
   

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

3. 通过使用以下 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。

验证迁移设置

通过运行以下命令检查实例是否已正确设置用于迁移。

重要提示：在 migrationType 字段中，您必须指定值 PHYSICAL。如果您未指定此值，则验证会失败。

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
              [e-mail]
              is missing necessary permissions storage.objects.list and
              storage.objects.get to access Google Cloud Storage bucket"
}

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

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

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

   进入“存储桶”

2. 点击权限标签页。

3. 点击授予访问权限。

4. 在新的主账号字段中，输入验证响应中返回的服务账号的名称。例如，在上一步的示例输出中，返回的服务账号名称为 [e-mail]。

5. 在选择角色下拉列表中，选择 Storage Object Viewer 角色。

6. 点击保存。

再次运行验证

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

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

• 存在 Cloud SQL 副本和外部服务器之间的连接，但前提是迁移是持续过程
• 复制用户权限已足够
• 版本兼容
• Cloud SQL 副本尚未执行复制操作
• 在外部服务器上启用二进制日志

如果检测到任何问题，Cloud SQL 会返回错误消息。

将用户添加到 Cloud SQL 副本

注意：如果您不需要将任何数据库用户账号添加到 Cloud SQL 副本，则可以跳过此步骤。

您无法从外部服务器导入或迁移数据库用户账号。如果您需要将任何数据库用户账号添加到 Cloud SQL 副本，请在开始复制之前添加这些账号。如需了解详情，请参阅使用内置身份验证管理用户。

开始迁移

完成验证并且未返回任何错误后，您就可以开始迁移了。如需迁移外部服务器，请使用 startExternalSync API。

重要提示：在 migrationType 字段中，您必须指定值 PHYSICAL。如果您未指定此值，迁移会失败。

使用以下命令：

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	您分配给目标副本实例的名称。

监控迁移

如需检查迁移状态，您可以执行以下操作：

1. 从 startExternalSync API 的响应中检索迁移作业的操作 ID。例如：

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

2. 在以下命令中使用操作 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	您分配给目标副本实例的名称。

后续步骤

• 将副本升级为主实例
• 向实例添加读取副本
• 配置实例以实现高可用性 (HA)