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 プロジェクトを設定する

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

   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 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 を指定して構成されている必要があります。

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～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 バケットにアップロードできるファイル 1 つあたりのサイズについては 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 のマシンタイプの 1 つを指定する必要があります。サポートされているマシンタイプの一覧については、マシンタイプをご覧ください。
   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 コマンドを使用して 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。

移行設定を検証する

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

重要: 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	この移行を 1 回限りのプロセスとして構成する場合は、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	この移行を 1 回限りのプロセスとして構成する場合は、offline を指定します。外部サーバーからの継続的なレプリケーションを設定するには、online を指定します。
PROJECT_ID	Google Cloud のプロジェクトの ID。
REPLICA_NAME	ターゲット レプリカ インスタンスに割り当てた名前。

移行をモニタリングする

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

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

   {
   "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 に移行することはできません。
• 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	ターゲット レプリカ インスタンスに割り当てた名前。

次のステップ

• レプリカをプライマリ インスタンスに昇格させる
• リードレプリカをインスタンスに追加する
• インスタンスを高可用性（HA）向けに構成する