XtraBackup 物理ファイルから Cloud SQL に移行する

MySQL | PostgreSQL | SQL Server

このページでは、Percona XtraBackup for MySQL の物理ファイルを使用して MySQL データベースを外部サーバーから Cloud SQL に移行する方法について説明します。

Cloud SQL では、外部サーバー上の MySQL データベースを Cloud SQL for MySQL インスタンスに移行する方法として Percona XtraBackup の使用がサポートされています。ユーザーは XtraBackup ユーティリティを使用して物理ファイルを生成し、そのファイルを Cloud Storage にアップロードします。物理ファイルを使用すると、通常の論理ダンプファイルによる移行と比較して移行の全体的な速度が最大 10 倍に向上します。

Cloud SQL では、MySQL 5.7 と 8.0 に対して物理ファイルによる移行がサポートされています。MySQL 5.6 はサポートされていません。Amazon Aurora や Amazon RDS 上の MySQL のデータベースからの移行はサポートされていません。加えて、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 プロジェクトを設定する

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.

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 管理者、ストレージ管理者、Compute 閲覧者のロールがあることを確認します。

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 VM 上のセルフマネージド MySQL データベースであることが必要です。Amazon Aurora や Amazon RDS 上の MySQL のデータベースからの移行はサポートされていません。
- innodb_data_file_path パラメータは、デフォルトのデータファイル名 ibdata1 を使用するデータファイルを 1 つだけ指定して構成されている必要があります。データベースの構成で 2 つのデータファイルが指定されている場合や、データファイルの名前が異なる場合は、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 バケットにアップロードできるファイル 1 つあたりのサイズについては 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 のマシンタイプの 1 つを指定する必要があります。サポートされているマシンタイプの一覧については、マシンタイプをご覧ください。
`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 ソース表現インスタンスに割り当てた名前。
次の 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。

プロパティ	説明
`SOURCE_NAME`	ソース表現インスタンスに割り当てた名前。

移行設定を検証する

次のコマンドを実行して、インスタンスが移行用に正しく設定されていることを検証します。

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`	この移行を 1 回限りのプロセスとして構成する場合は、`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.iam.gserviceaccount.com
              is missing necessary permissions storage.objects.list and
              storage.objects.get to access Google Cloud Storage bucket"
}

返されたサービスアカウントに Cloud Storage の権限を追加する

必要な権限を追加する手順は次のとおりです。

Google Cloud コンソールで、Cloud Storage の [バケット] ページに移動します。

[バケット] に移動
[権限] タブをクリックします。
[アクセス権を付与] をクリックします。
[新しいプリンシパル] フィールドに、検証のレスポンスで返されたサービスアカウントの名前を入力します。前のステップの出力の例では、返されたサービスアカウント名は p703314288590-df3om0@my-project.iam.gserviceaccount.com です。
[ロールを選択] プルダウンで、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`	この移行を 1 回限りのプロセスとして構成する場合は、`offline` を指定します。外部サーバーからの継続的なレプリケーションを設定するには、`online` を指定します。
`PROJECT_ID`	Google Cloud のプロジェクトの ID。
`REPLICA_NAME`	ターゲットレプリカインスタンスに割り当てた名前。

移行をモニタリングする

移行のステータスを確認する手順は次のとおりです。

移行ジョブのオペレーション ID を startExternalSync API のレスポンスから取得します。次に例を示します。

{
"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 バケット内の XtraBackup 物理ファイルを削除してかまいません。外部サーバーは、必要な検証が完了するまで維持してください。

制限事項

このセクションでは、XtraBackup 移行プロセスに関する制限事項を示します。

Percona XtraBackup を使用してデータを Cloud Storage バケットにバックアップする必要があります。他のバックアップユーティリティはサポートされていません。
以前のデータベースメジャーバージョンまたはマイナーバージョンへの移行はサポートされていません。たとえば、MySQL 8.0 から 5.7 に移行することや、MySQL 8.0.36 から 8.0.16 に移行することはできません。
XtraBackup 物理ファイルからのデータベース移行がサポートされるのは、オンプレミス MySQL データベース、または Compute Engine VM 上で実行されるセルフマネージド MySQL データベースのみです。Amazon Aurora や Amazon RDS 上の MySQL のデータベースからの移行はサポートされていません。
フルバックアップからの移行のみが可能です。他のバックアップタイプ（増分バックアップや部分バックアップなど）はサポートされていません。
データベースの移行には、データベースユーザーや権限は含まれません。
バイナリログ形式を 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`	ターゲットレプリカインスタンスに割り当てた名前。

プロパティ	説明
`PROJECT_ID`	Google Cloud のプロジェクトの ID。
`EXISTING_INSTANCE_ID`	移行に使用する既存のレプリカインスタンスの ID。

XtraBackup 物理ファイルから Cloud SQL に移行する

始める前に

Google Cloud プロジェクトを設定する

Cloud Storage バケットを設定する

Google Cloud SDK をインストールする

外部サーバーを移行用に準備する

移行を実行する

XtraBackup 物理ファイルを作成して整備する

XtraBackup 物理ファイルを Cloud Storage にアップロードする

ソース表現インスタンスを定義する

ターゲット レプリカ インスタンスを指定する

オプション 1: レプリカ インスタンスを作成する

オプション 2: 既存のレプリカ インスタンスを使用する

移行設定を検証する

返されたサービス アカウントに Cloud Storage の権限を追加する

検証を再度実行する

Cloud SQL レプリカへのユーザーの追加

移行を開始する

移行をモニタリングする

レプリケーションをモニタリングする

制限事項

トラブルシューティング

インポートに失敗する

移行をキャンセルまたは停止する

次のステップ

ターゲットレプリカインスタンスを指定する

オプション 1: レプリカインスタンスを作成する

オプション 2: 既存のレプリカインスタンスを使用する

返されたサービスアカウントに Cloud Storage の権限を追加する