データのエクスポート

このページでは、Cloud SQL インスタンスから、または Cloud SQL で管理されていないデータベース サーバーからデータをエクスポートする方法について説明します。

エクスポートではデータベース リソースが使用されますが、インスタンスがプロビジョニングされていない限り、エクスポートによって通常のデータベース オペレーションが妨げられることはありません。

データのエクスポートのベスト プラクティスについては、データのインポートとエクスポートのベスト プラクティスをご覧ください。

始める前に

必要なロールと権限を構成済みであることを確認してください。

Cloud Storage にデータをエクスポートするには、インスタンスのサービス アカウントまたはユーザーに Cloud SQL 編集者のロールまたは cloudsql.instances.export 権限を含むカスタムロールと、少なくとも roles/storage.legacyBucketWriter IAM ロールが必要です。

サービス アカウントまたはユーザーがインポート オペレーションも実行している場合は、プロジェクトで設定された storage.objectAdmin IAM ロールをアカウントに付与できます。

IAM ロールについては、Cloud Storage の Cloud Identity and Access Management をご覧ください。

インスタンスのサービス アカウント名は、Google Cloud Console のインスタンスの [概要] ページで確認できます。Cloud Storage バケットのロールは、バケットを検査する gsutil ツールを使用して確認できます。

gsutil iam get gs://[BUCKET_NAME]

バケットでの IAM 使用について詳しくは、こちらをご覧ください。

Cloud SQL から Cloud Storage の SQL ダンプファイルにデータをエクスポートする

Cloud Console、gcloud コマンドライン ツール、または API から Cloud SQL を使用してエクスポートを実行する場合、pg_dump ユーティリティを使用します。このとき、生成されるエクスポート ファイルを Cloud SQL に確実に再インポートできるようにするオプションを指定します。

Cloud SQL で管理されていないデータベースにエクスポートする場合は、psql クライアントを使用して pg_dump を手動で実行できます。

ただし、Cloud SQL にデータをインポートする場合は、SQL ダンプファイルが Cloud SQL 用に正しくフォーマットされるように、外部データベース サーバーからのデータのエクスポートの手順に従ってください。

Cloud SQL インスタンス上のデータベースから Cloud Storage バケットの SQL ダンプファイルにデータをエクスポートするには:

Console

  1. Google Cloud Console の [Cloud SQL インスタンス] ページに移動します。

    [Cloud SQL インスタンス] ページに移動

  2. データのエクスポート元となるインスタンスをクリックして、[概要] ページを開きます。
  3. ボタンバーで [エクスポート] をクリックします。
  4. [ファイル形式] で [SQL] をクリックして、SQL ダンプファイルを作成します。
  5. [エクスポートするデータ] でプルダウン メニューを使用して、エクスポートするデータベースを選択します。
  6. [送信先] で [参照] を選択して、エクスポート先の Cloud Storage バケットまたはフォルダを検索します。
  7. [エクスポート] をクリックしてエクスポートを開始します。

gcloud

  1. Cloud Storage バケットをまだ作成していない場合は、作成します。

    バケットの作成方法については、ストレージ バケットの作成をご覧ください。

  2. ファイルをバケットにアップロードします。

    ファイルをバケットにアップロードする方法については、オブジェクトのアップロードをご覧ください。

  3. エクスポート元のインスタンスを記述します。
      gcloud sql instances describe [INSTANCE_NAME]
      
  4. serviceAccountEmailAddress フィールドをコピーします。
  5. gsutil iam を使用して、バケットのサービス アカウントに storage.objectAdmin IAM ロールを付与します。IAM 権限の設定については、IAM 権限の使用をご覧ください。
  6. データベースをエクスポートします。
      gcloud sql export sql [INSTANCE_NAME] gs://[BUCKET_NAME]/sqldumpfile.gz \
                                  --database=[DATABASE_NAME] --offload
      

    export sql コマンドでは、トリガーとストアド プロシージャは含まれませんが、ビューは含まれます。トリガーまたはストアド プロシージャをエクスポートするには、pg_dump ツールを使用します。

    export sql コマンドの使用方法について詳しくは、sql export sql コマンドのリファレンス ページをご覧ください。

  7. 以前に設定した IAM ロールを保持する必要がない場合は、この時点で取り消してください。

REST v1beta4

  1. エクスポート先のバケットを作成します。
    gsutil mb -p [PROJECT_NAME] -l [LOCATION_NAME] gs://[BUCKET_NAME]
    

    このステップは必須ではありませんが、他のデータへ一切アクセスできないようにするために、実行することを強く推奨します。

  2. バケットに対する storage.objectAdmin IAM ロールをインスタンスに付与します。IAM 権限の設定については、IAM 権限の使用をご覧ください。
  3. データベースをエクスポートします。

    後述のリクエスト データは、次のように置き換えてから使用します。

    • project-id: プロジェクト ID
    • instance-id: インスタンス ID
    • bucket_name: Cloud Storage バケット名
    • path_to_dump_file: SQL ダンプファイルへのパス
    • database_name_1: Cloud SQL インスタンス内のデータベースの名前
    • database_name_2: Cloud SQL インスタンス内のデータベースの名前
    • offload: サーバーレス エクスポートを有効にします。サーバーレス エクスポートを使用するには true に設定します。

    HTTP メソッドと URL:

    POST https://www.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/export

    JSON 本文のリクエスト:

    {
     "exportContext":
       {
          "fileType": "SQL",
          "uri": "gs://bucket_name/path_to_dump_file",
          "databases": ["database_name"]
          "offload": true | false
        }
    }
    

    リクエストを送信するには、次のいずれかのオプションを展開します。

    次のような JSON レスポンスが返されます。

  4. 以前に設定した IAM ロールを保持する必要がない場合は、この時点で取り消してください。
このリクエストのパラメータの一覧については、instances:export ページをご覧ください。

Cloud SQL から Cloud Storage の CSV ファイルにデータをエクスポートする

他のツールや環境で使用可能な CSV 形式でデータをエクスポートできます。エクスポートはデータベース レベルで行われます。CSV をエクスポートするときに、エクスポートするスキーマを指定できます。データベース レベルのスキーマはすべてエクスポート可能です。

Cloud SQL インスタンス上のデータベースから Cloud Storage バケットの SQL ダンプファイルにデータをエクスポートするには:

Console

  1. Google Cloud Console の [Cloud SQL インスタンス] ページに移動します。

    [Cloud SQL インスタンス] ページに移動

  2. インスタンスをクリックして [概要] ページを開きます。
  3. [エクスポート] をクリックします。
  4. [Cloud Storage エクスポートのロケーション] で、エクスポート先の Cloud Storage バケットまたはフォルダを選択します。
  5. [名前] フィールドにエクスポート ファイルの名前を入力し、[選択] をクリックします。

    ファイル拡張子 .gz を使用して、エクスポート ファイルを圧縮します。

  6. [形式] を [CSV] に設定します。
  7. [Cloud Storage エクスポートのロケーション] で、エクスポートするバケット、フォルダ、ファイルを追加するか、[参照] をクリックしてバケット、フォルダ、ファイルを検索または作成します。

    [参照] をクリックした場合:

    1. [ロケーション] で、エクスポート先の Cloud Storage バケットまたはフォルダを選択します。
    2. [名前] テキスト ボックスに、CSV ファイルの名前を追加します。以前にファイルを作成したことがある場合は、[ロケーション] のリストから選択します。

      .gz のファイル拡張子(完全な拡張子は .csv.gz)を使用して、エクスポート ファイルを圧縮できます。

    3. [選択] をクリックします。
  8. [形式] で [CSV] をクリックします。
  9. [エクスポートするデータベース] で、プルダウン メニューからデータベースの名前を選択します。
  10. [SQL クエリ] に、SQL クエリを入力して、データのエクスポート元のテーブルを指定します。

    たとえば、guestbook データベースの entries テーブルの内容全体をエクスポートするには、次のように入力します。

    SELECT * FROM guestbook.entries;
    指定したデータベース内のテーブルをクエリで指定する必要があります。データベース全体を CSV 形式でエクスポートすることはできません。

  11. [エクスポート] をクリックしてエクスポートを開始します。
  12. [データベースをエクスポートしますか?] というダイアログ ボックスが開き、大規模なデータベースの場合、エクスポート プロセスに 1 時間以上かかることがあるという内容のメッセージが表示されます。エクスポート時、インスタンスで実行できる操作は情報の閲覧のみです。一度開始したエクスポートは停止できません。エクスポートを開始してもよい場合は、[エクスポート] をクリックします。それ以外の場合は、[キャンセル] をクリックします。

gcloud

  1. Cloud Storage バケットをまだ作成していない場合は、作成します。

    バケットの作成方法については、ストレージ バケットの作成をご覧ください。

  2. ファイルをバケットにアップロードします。

    ファイルをバケットにアップロードする方法については、オブジェクトのアップロードをご覧ください。

  3. エクスポート元のインスタンスを記述します。
    gcloud sql instances describe [INSTANCE_NAME]
    
  4. gsutil iam を使用して、バケットのサービス アカウントに storage.objectAdmin IAM ロールを付与します。IAM 権限の設定については、IAM 権限の使用をご覧ください。
  5. データベースをエクスポートします。
    gcloud sql export csv [INSTANCE_NAME] gs://[BUCKET_NAME]/[FILE_NAME] \
                                --database=[DATABASE_NAME] \
                                --offload \
                                --query=[SELECT_QUERY]
    

    export csv コマンドの使用方法については、sql export csv コマンドのリファレンス ページをご覧ください。

  6. 以前に設定した IAM ロールを保持する必要がない場合は、この時点で取り消してください。

REST v1beta4

  1. エクスポート先のバケットを作成します。
    gsutil mb -p [PROJECT_NAME] -l [LOCATION_NAME] gs://[BUCKET_NAME]
    

    このステップは必須ではありませんが、他のデータへ一切アクセスできないようにするために、実行することを強く推奨します。

  2. バケットに対する storage.objectAdmin IAM ロールをインスタンスに付与します。IAM 権限の設定については、IAM 権限の使用をご覧ください。
  3. データベースをエクスポートします。

    後述のリクエスト データは、次のように置き換えてから使用します。

    • project-id: プロジェクト ID
    • instance-id: インスタンス ID
    • bucket_name: Cloud Storage バケット名
    • path_to_csv_file: CSV ファイルへのパス
    • database_name: Cloud SQL インスタンス内のデータベースの名前
    • offload: サーバーレス エクスポートを有効にします。サーバーレス エクスポートを使用するには true に設定します。
    • select_query: エクスポート用の SQL クエリ

    HTTP メソッドと URL:

    POST https://www.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/export

    JSON 本文のリクエスト:

    {
     "exportContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "databases": ["database_name"],
          "offload": true | false
          "csvExportOptions":
           {
               "selectQuery":"select_query"
           }
       }
    }
    

    リクエストを送信するには、次のいずれかのオプションを展開します。

    次のような JSON レスポンスが返されます。

    databases プロパティでデータベースを 1 つだけ指定する必要があります。select クエリでデータベースを指定する場合は、同じデータベースを使用する必要があります。

  4. 以前に設定した IAM ロールを保持する必要がない場合は、この時点で取り消してください。
このリクエストのパラメータの一覧については、instances:export ページをご覧ください。

CSV エクスポートでは、標準の CSV 出力が作成されます。標準以外の CSV 形式が必要な場合は、psql クライアントで次のステートメントを使用します。

      \copy [table_name] TO '[csv_file_name].csv' WITH
          (FORMAT csv, ESCAPE '[escape_character]', QUOTE '[quote_character]',
          DELIMITER '[delimiter_character]', ENCODING 'UTF8', NULL '[null_marker_string]');
このリクエストのパラメータの一覧については、instances:export ページをご覧ください。

pg_dump を使用してオンプレミスの PostgreSQL サーバーからデータをエクスポートする

Cloud SQL で管理されていないデータベースをエクスポートする場合は、後で Cloud SQL にインポートするため、次のフラグを指定して pg_dump ユーティリティを使用します。

  • --no-owner

    SQL ダンプファイルに所有権の変更コマンドを含めることはできません。

  • --format

    Cloud SQL Admin API でサポートされているのは、plain SQL 形式のみです。

    ダンプファイルが pg_restore で使用するためのものである場合、custom 形式を使用できます。

  • --no-acl

    このフラグは、SUPERUSER ロールのメンバーシップを付与または取り消すステートメントがダンプに含まれている場合に必要です。

また、次のものをすべて削除する必要があります。

  • 拡張関連のステートメント(Cloud SQL がその拡張機能をサポートしていない場合)。サポートされている拡張機能のリストについては、PostgreSQL の拡張機能をご覧ください。
  • plpgsql を参照する CREATE EXTENSION または DROP EXTENSION ステートメント。この拡張機能は、Cloud SQL Postgres インスタンスにプリインストールされています。
  • COMMENT ON EXTENSION ステートメント。

書式なしテキスト形式の場合: コマンドラインから pg_dump を実行します。

pg_dump -U [USERNAME] --format=plain --no-owner --no-acl [DATABASE_NAME] \
    | sed -E 's/(DROP|CREATE|COMMENT ON) EXTENSION/-- \1 EXTENSION/g' > [SQL_FILE].sql

カスタム形式の場合: コマンドラインから pg_dump を実行します。

pg_dump -U [USERNAME] --format=custom --no-owner --no-acl [DATABASE_NAME] > [DATABASE_NAME].dmp

sed 後処理により、SQL ダンプファイル内のすべての拡張ステートメントがコメントアウトされます。

pg_restore を使用してインポートする場合は、コマンドライン引数「--use-list=[DATABASE_NAME].toc」で、処理された目次を指定します。

データベースの設定で指定されているデフォルトのエンコードがデータに適していることを確認します。必要に応じて、--encoding フラグを使用してデフォルトをオーバーライドできます。

並行してエクスポートするには、-j NUM_CORES フラグを使用します。NUM_CORES は、ソース インスタンスのコア数です。並行してインポートするには、pg_restore で同じフラグを使用します。

pg_dump については、pg_dump のリファレンスをご覧ください。

エクスポート オペレーションの自動化

Cloud SQL にはデータベースのエクスポートを自動化するための組み込みの機能はありませんが、いくつかの Google Cloud コンポーネントを使用して、独自の自動化ツールを構築できます。詳細については、このチュートリアルをご覧ください。

トラブルシューティング

表内のリンクをクリックすると、詳細が表示されます。

この問題については... 次のような問題が考えられます... 次のことを試します...
オペレーションのステータスを確認できない。 ユーザー インターフェースには成功または失敗のみが表示されます。 詳細については、これらのデータベース コマンドをご覧ください。
エクスポート中の 408 Error (Timeout) データベースのサイズとエクスポート コンテンツによっては、SQL のエクスポートに時間がかかることがあります。 複数の CSV エクスポートを使用して各オペレーションのサイズを減らします
CSV のエクスポートは機能したが、SQL エクスポートに失敗した。 SQL のエクスポートでは、Cloud SQL との互換性の問題が発生する可能性が高くなります。 CSV のエクスポートを使用して必要なものだけをエクスポートします
エクスポートに時間がかかりすぎる。 Cloud SQL では同時実行オペレーションの同期がサポートされません。 エクスポートのオフロードを使用します。詳細
拡張機能の作成のエラー。 ダンプファイルには、サポートされていない拡張機能への参照が含まれています。 ダンプファイルを編集して参照を削除します
pg_dumpall の使用中にエラーが発生した。 このツールにはスーパーユーザーのロールが必要です。 スーパーユーザーのロールはサポートされていません
エクスポート オペレーションが、エクスポート完了前にタイムアウトする。 クエリで最初の 7 分以内にデータを生成する必要があります。 pg_dump ツールを使用して手動でエクスポートしてみてください
エクスポート オペレーション中に接続が切断した。 クエリで最初の 7 分以内にデータを生成する必要があります。 クエリを手動でテストします。詳細については、こちらをご覧ください。
エクスポート中に不明なエラーが発生した。 帯域幅の問題である可能性があります。 インスタンスと Cloud Storage バケットの両方が同じリージョンに存在することを確認します
エクスポートを自動化する場合。 Cloud SQL には、エクスポートを自動化する方法がありません。 この機能を実行する独自のパイプラインを構築します。詳細

オペレーションのステータスを確認できない

進行中のオペレーションのステータスが表示されません。

次のような問題が考えられます

Google Cloud Console では、完了時に成功または失敗のみが表示され、警告は返されません。

次の方法をお試しください

データベースに接続し、SHOW WARNINGS を実行します。


エクスポート中の 408 エラー(タイムアウト)

Cloud SQL でエクスポート ジョブを実行しているときに、エラー メッセージ 408 Error (Timeout) が表示されます。

次のような問題が考えられます

CSV 形式と SQL 形式ではエクスポート方法が異なります。SQL 形式ではデータベース全体がエクスポートされるため、完了までに時間がかかります。CSV 形式ではエクスポートに含めるデータベースの要素を定義できます。

次の方法をお試しください

CSV 形式を使用して複数の小規模なエクスポート ジョブを実行し、各オペレーションのサイズと長さを減らします。


CSV のエクスポートは機能したが、SQL エクスポートに失敗した

CSV のエクスポートは機能したが、SQL エクスポートに失敗した。

次のような問題が考えられます

CSV 形式と SQL 形式ではエクスポート方法が異なります。SQL 形式ではデータベース全体がエクスポートされるため、完了までに時間がかかります。CSV 形式ではエクスポートに含めるデータベースの要素を定義できます。

次の方法をお試しください

CSV エクスポートを使用して必要なものだけをエクスポートします。


エクスポートに時間がかかりすぎる

エクスポートに時間がかかりすぎるため、他のオペレーションをブロックします。

次のような問題が考えられます

Cloud SQL では同時実行オペレーションの同期がサポートされません。

次の方法をお試しください

サイズの小さい多数のデータセットを一度にエクスポートしてみてください。



pg_dumpall の使用中のエラー

外部の pg_dumpall コマンドライン ツールを使用しようとすると、エラーが発生します。

次のような問題が考えられます

このツールにはスーパーユーザーのロールが必要です。

次の方法をお試しください

Cloud SQL はマネージド サービスであり、ユーザーにスーパーユーザーのロールや権限を付与することはありません。


ピアによって接続がリセットされた

エクスポート オペレーションが、エクスポート完了前にタイムアウトします。エラー メッセージ Could not receive data from client: Connection reset by peer. が表示されます。

次のような問題が考えられます

Cloud Storage が特定の期間内にデータを受信しない場合、接続がリセットされる。

次の方法をお試しください

pg_dump ツールを使用して手動でエクスポートします。


エクスポート オペレーション中に接続が切断された

エクスポート オペレーション中に接続が切断しました。

次のような問題が考えられます

エクスポートが開始されてから最初の 7 分以内に、エクスポートで実行されているクエリでデータが生成されないため、Cloud Storage への接続がタイムアウトする可能性があります。

次の方法をお試しください

次のコマンドを使用して任意のクライアントから接続し、クエリの出力を標準出力に送信して、クエリを手動でテストします。

COPY (INSERT_YOUR_QUERY_HERE) TO STDOUT WITH ( FORMAT csv, DELIMITER ',', ENCODING 'UTF8', QUOTE '"', ESCAPE '"' )

これは、エクスポートが開始されるとすぐにクライアントからデータの送信が開始されるためです。データが送信されていない接続を維持すると、最終的に接続が切断されてエクスポートが失敗し、操作が不確定な状態になります。また、gcloud からのエラー メッセージは次のように表示されます。

operation is taking longer than expected


エクスポート中に不明なエラーが発生した

データベースを Cloud Storage バケットにエクスポートしようとすると、エラー メッセージ Unknown error が表示されます。

次のような問題が考えられます

帯域幅の問題が原因で転送が失敗する可能性があります。

次の方法をお試しください

Cloud SQL インスタンスが Cloud Storage バケットとは異なるリージョンに存在している可能性があります。ある大陸から別の大陸へのデータの読み取りと書き込みではネットワークの使用量が多く、このような断続的な問題を引き起こす可能性があります。インスタンスとバケットのリージョンを確認します。


エクスポートを自動化する

エクスポートを自動化する場合。

次のような問題が考えられます

Cloud SQL には、エクスポートを自動化する方法がありません。

次の方法をお試しください

Google Cloud プロダクト(Cloud Scheduler、Pub/Sub、Cloud Functions)を使用して、独自の自動エクスポート システムを構築できます。


ERROR_RDBMS システムエラーが発生した

エラー メッセージ [ERROR_RDBMS] system error occurred が表示されます。

次のような問題が考えられます

  • ユーザーが必要なすべての Cloud Storage 権限を持っていない可能性があります。
  • データベース テーブルが存在しない可能性があります。

次の方法をお試しください

  1. バケットに対して少なくとも WRITER 権限があり、エクスポート ファイルに対して READER 権限があることを確認してください。Cloud Storage のアクセス制御の構成について詳しくは、アクセス制御リストの作成と管理をご覧ください。
  2. テーブルが存在していることを確認します。存在している場合は、バケットに対して正しい権限があることを確認します。

次のステップ