CSV ファイルを使用したエクスポートとインポート

このページでは、Cloud SQL インスタンスで CSV ファイルを使用してデータのエクスポートとインポートを行う方法について説明します。

始める前に

エクスポートまたはインポート オペレーションを開始する前に、次のことを行います。

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

  • CSV ファイルに目的のデータがあり、正しい形式であることを確認します。CSV ファイルは、データの行ごとに 1 行を使用する必要があります。
  • データのエクスポートとインポートのベスト プラクティスに従います。

エクスポート

エクスポートに必要なロールと権限

Cloud Storage にデータをエクスポートするには、サービス アカウントまたはユーザーに次のいずれかのロールが必要です。

  • Cloud SQL 編集者のロールと roles/storage.legacyBucketWriter IAM ロール。
  • 次の権限を含むカスタムロール:
    • cloudsql.instances.get
    • cloudsql.instances.export
    • storage.buckets.create
    • storage.objects.create

サービス アカウントまたはユーザーがインポート オペレーションも実行する場合は、Storage Object Admin IAM ロールを付与して、インポートとエクスポートの両方に必要なすべての権限を付与すると便利な場合があります。

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

CSV ファイルへのデータのエクスポート

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

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

Console

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

    Cloud SQL の [インスタンス] に移動

  2. インスタンス名をクリックして [概要] ページを開きます。
  3. [エクスポート] をクリックします。
  4. [Offload export] を選択して、エクスポートの進行中に他のオペレーションを実行できるようにします。
  5. [Cloud Storage export location] セクションで、エクスポートするバケット、フォルダ、ファイルを追加するか、[参照] をクリックしてバケット、フォルダ、ファイルを検索または作成します。

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

    1. [ロケーション] セクションで、エクスポート先の Cloud Storage バケットまたはフォルダを選択します。
    2. [名前] ボックスで、CSV ファイルの名前を追加するか、[ロケーション] セクションのリストから既存のファイルを選択します。

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

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

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

    SELECT * FROM guestbook.entries;
    指定したデータベース内のテーブルをクエリで指定する必要があります。データベース全体を CSV 形式でエクスポートすることはできません。
  9. [エクスポート] をクリックしてエクスポートを開始します。
  10. [データベースをエクスポートしますか?] ボックスが開き、大規模なデータベースの場合、エクスポート プロセスに 1 時間以上かかることがあるという内容のメッセージが表示されます。エクスポート時、インスタンスで実行できる操作は情報の閲覧のみです。一度開始したエクスポートは停止できません。エクスポートを開始してもよい場合は、[エクスポート] をクリックします。それ以外の場合は、[キャンセル] をクリックします。

gcloud

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

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

  3. エクスポート元の Cloud SQL インスタンスのサービス アカウントを見つけます。これを行うには、gcloud sql instances describe コマンドを実行します。出力で serviceAccountEmailAddress フィールドを探します。
    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 v1

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

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

  2. バケットに対する legacyBucketWriter 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 クエリ(省略可)
    • escape_character: エスケープが必要なデータ文字の前に表示する文字。この引数の値は 16 進数 ASCII コード内の文字である必要があります。たとえば、22 は二重引用符を表します。(省略可)
    • quote_character: 文字列データ型を持つ列の値を囲む文字。この引数の値は 16 進数 ASCII コード内の文字である必要があります。たとえば、22 は二重引用符を表します。(省略可)
    • fields_terminated_by: 列の値を分割する文字。この引数の値は 16 進数 ASCII コード内の文字である必要があります。たとえば、2C はカンマを表します。(省略可)
    • lines_terminated_by: 行レコードを分割した文字。この引数の値は 16 進数 ASCII コード内の文字である必要があります。たとえば、0A は新しい行を表します。(省略可)

    HTTP メソッドと URL:

    POST https://sqladmin.googleapis.com/v1/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",
               "escapeCharacter":"escape_character",
               "quoteCharacter":"quote_character",
               "fieldsTerminatedBy":"fields_terminated_by",
               "linesTerminatedBy":"lines_terminated_by"
           }
       }
    }
    

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

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

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

  4. 以前に設定した IAM の権限を保持する必要がない場合は、今すぐ削除してください。
このリクエストのパラメータの一覧については、instances:export ページをご覧ください。

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 クエリ(省略可)
    • escape_character: エスケープが必要なデータ文字の前に表示する文字。この引数の値は、ASCII の 16 進数形式にする必要があります。たとえば、22 は二重引用符を表します。(省略可)
    • quote_character: 文字列データ型を持つ列の値を囲む文字。この引数の値は、ASCII の 16 進数形式にする必要があります。たとえば、22 は二重引用符を表します。(省略可)
    • fields_terminated_by: 列の値を分割する文字。この引数の値は、ASCII の 16 進数形式にする必要があります。たとえば、2C はカンマを表します。(省略可)
    • lines_terminated_by: 行レコードを分割した文字。この引数の値は、ASCII の 16 進数形式にする必要があります。たとえば、0A は新しい行を表します。(省略可)

    HTTP メソッドと URL:

    POST https://sqladmin.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",
               "escapeCharacter":  "escape_character",
               "quoteCharacter": "quote_character",
               "fieldsTerminatedBy": "fields_terminated_by",
               "linesTerminatedBy": "lines_terminated_by"
           }
       }
    }
    

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

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

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

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

CSV ファイルのエクスポート形式をカスタマイズする

CSV ファイル形式は、gcloud または REST API を使用してカスタマイズできます。エクスポートを実行するときに、次のフォーマット オプションを指定できます。

CSV のオプション デフォルト値 gcloud フラグ REST API プロパティ 説明
エスケープ

"22"

二重引用符の ASCII 16 進数コード。

--escape escapeCharacter

エスケープする必要があるデータ文字の前に表示される文字。

MySQL と PostgreSQL でのみ使用できます。

引用符

"22"

二重引用符の ASCII 16 進数コード。

--quote quoteCharacter

文字列データ型を持つ列の値を囲む文字。

MySQL と PostgreSQL でのみ使用できます。

フィールド区切り文字

"2C"

カンマを表す ASCII 16 進数コード。

--fields-terminated-by fieldsTerminatedBy

列の値を分割する文字。

MySQL と PostgreSQL でのみ使用できます。

改行文字

"0A"

改行を表す ASCII 16 進数コード。

--lines-terminated-by linesTerminatedBy

行レコードを分割する文字。

MySQL でのみ使用できます。

たとえば、これらの引数をすべて使用する gcloud コマンドは次のようになります。

gcloud sql export csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--offload \
--query=SELECT_QUERY \
--quote="22" \
--escape="5C" \
--fields-terminated-by="2C" \
--lines-terminated-by="0A"

同等の REST API リクエストの本文は次のようになります。

{
 "exportContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "databases": ["DATABASE_NAME"],
      "offload": true,
      "csvExportOptions":
       {
           "selectQuery": "SELECT_QUERY",
           "escapeCharacter":  "5C",
           "quoteCharacter": "22",
           "fieldsTerminatedBy": "2C",
           "linesTerminatedBy": "0A"
       }
   }
}

CSV エクスポートでは、カスタマイズされた 3 つのオプションを使用して、標準の CSV 出力がデフォルトで生成されます。Cloud SQL よりも多くのオプションが必要な場合は、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]');

インポート

インポートに必要なロールと権限

この手順では、Cloud Storage からファイルをインポートする必要があります。Cloud Storage からデータをインポートするには、サービス アカウントまたはユーザーに次のいずれかのロールセットが必要です。

  • Cloud SQL 管理者のロールと roles/storage.legacyObjectReader IAM ロール
  • 次の権限を含むカスタムロール:
    • cloudsql.instances.get
    • cloudsql.instances.import
    • storage.buckets.get
    • storage.objects.get

アカウントまたはユーザーがエクスポート オペレーションも実行する場合は、インポートとエクスポートの両方で必要な権限をすべて付与するため、Storage Object Admin IAM ロールを付与するほうが便利です。IAM ロールについては、Cloud Storage の Cloud Identity and Access Management をご覧ください。

CSV ファイルからのデータのインポート

  • インポート先のデータベースとテーブルが、Cloud SQL インスタンス上に存在している必要があります。データベースの作成方法については、データベースを作成するをご覧ください。
  • CSV ファイルは、CSV ファイル形式の要件に従う必要があります。

CSV ファイルを使用して Cloud SQL インスタンスにデータをインポートする手順は次のとおりです。

Console

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

    Cloud SQL の [インスタンス] に移動

  2. インスタンス名をクリックして [概要] ページを開きます。
  3. [インポート] をクリックします。
  4. データのインポート元となるファイルを選択するセクションで、インポートに使用するバケットと CSV ファイルのパスを入力します。または、次のようにしてファイルを参照します。
    1. [参照] をクリックします。
    2. [ロケーション] セクションで、リスト内のバケット名をダブルクリックします。
    3. リストからファイルを選択します。
    4. [選択] をクリックします。

    圧縮ファイル(.gz)または非圧縮ファイル(.csv)ファイルをインポートできます。

  5. [ファイル形式] セクションで [CSV] を選択します。
  6. CSV ファイルをインポートする Cloud SQL インスタンスの [データベース] と [テーブル] を指定します。
  7. 必要に応じて、インポート オペレーションにユーザーを指定できます。
  8. [インポート] をクリックしてインポートを開始します。

gcloud

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

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

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

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

  8. 以前に設定した IAM の権限を保持する必要がない場合は、gsutil iam を使用して削除してください。

REST v1

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

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

  3. バケットに対する legacyBucketWriterobjectViewerIAM ロールをインスタンスに付与します。IAM 権限の設定については、IAM 権限の使用をご覧ください。
  4. ファイルをインポートします。

    リクエストのデータを使用する前に、次のように置き換えます。

    • project-id: プロジェクト ID
    • instance-id: インスタンス ID
    • bucket_name: Cloud Storage バケット名
    • path_to_csv_file: CSV ファイルへのパス
    • database_name: Cloud SQL インスタンス内のデータベースの名前
    • table_name: データベース テーブルの名前
    • escape_character: エスケープが必要なデータ文字の前に表示する文字。この引数の値は 16 進数 ASCII コード内の文字である必要があります。たとえば、22 は二重引用符を表します。(省略可)
    • quote_character: 文字列データ型を持つ列の値を囲む文字。この引数の値は 16 進数 ASCII コード内の文字である必要があります。たとえば、22 は二重引用符を表します。(省略可)
    • fields_terminated_by: 列の値を分割する文字。この引数の値は 16 進数 ASCII コード内の文字である必要があります。たとえば、2C はカンマを表します。(省略可)
    • lines_terminated_by: 行レコードを分割した文字。この引数の値は 16 進数 ASCII コード内の文字である必要があります。たとえば、0A は新しい行を表します。(省略可)

    HTTP メソッドと URL:

    POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id/import

    JSON 本文のリクエスト:

    {
     "importContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "database": "database_name",
          "csvImportOptions":
           {
             "table": "table_name",
             "escapeCharacter": "escape_character",
             "quoteCharacter": "quote_character",
             "fieldsTerminatedBy": "fields_terminated_by",
             "linesTerminatedBy": "lines_terminated_by"
           }
       }
    }
    
    

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

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

    このリクエストのパラメータの完全な一覧については、instances:import ページをご覧ください。
  5. 以前に設定した IAM 権限を保持する必要がない場合は、権限を削除します。

REST v1beta4

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

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

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

    リクエストのデータを使用する前に、次のように置き換えます。

    • project-id: プロジェクト ID
    • instance-id: インスタンス ID
    • bucket_name: Cloud Storage バケット名
    • path_to_csv_file: CSV ファイルへのパス
    • database_name: Cloud SQL インスタンス内のデータベースの名前
    • table_name: データベース テーブルの名前
    • escape_character: エスケープが必要なデータ文字の前に表示する文字。この引数の値は、ASCII の 16 進数形式にする必要があります。たとえば、22 は二重引用符を表します。(省略可)
    • quote_character: 文字列データ型を持つ列の値を囲む文字。この引数の値は、ASCII の 16 進数形式にする必要があります。たとえば、22 は二重引用符を表します。(省略可)
    • fields_terminated_by: 列の値を分割する文字。この引数の値は、ASCII の 16 進数形式にする必要があります。たとえば、2C はカンマを表します。(省略可)
    • lines_terminated_by: 行レコードを分割した文字。この引数の値は、ASCII の 16 進数形式にする必要があります。たとえば、0A は新しい行を表します。(省略可)

    HTTP メソッドと URL:

    POST https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id/import

    JSON 本文のリクエスト:

    {
     "importContext":
       {
          "fileType": "CSV",
          "uri": "gs://bucket_name/path_to_csv_file",
          "database": "database_name",
          "csvImportOptions":
           {
             "table": "table_name",
             "escapeCharacter": "escape_character",
             "quoteCharacter": "quote_character",
             "fieldsTerminatedBy": "fields_terminated_by",
             "linesTerminatedBy": "lines_terminated_by"
           }
       }
    }
    
    

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

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

    このリクエストのパラメータの完全な一覧については、instances:import ページをご覧ください。
  5. 以前に設定した IAM 権限を保持する必要がない場合は、権限を削除します。

CSV ファイルのインポート形式をカスタマイズする

CSV ファイル形式は、gcloud または REST API を使用してカスタマイズできます。

gcloud コマンドの例を次に示します。

gcloud sql import csv INSTANCE_NAME gs://BUCKET_NAME/FILE_NAME \
--database=DATABASE_NAME \
--table=TABLE_NAME \
--quote="22" \
--escape="5C" \
--fields-terminated-by="2C" \
--lines-terminated-by="0A"

同等の REST API リクエストの本文は次のようになります。

{
 "importContext":
   {
      "fileType": "CSV",
      "uri": "gs://bucket_name/path_to_csv_file",
      "database": ["DATABASE_NAME"],
      "csvImportOptions":
       {
           "table": "TABLE_NAME",
           "escapeCharacter":  "5C",
           "quoteCharacter": "22",
           "fieldsTerminatedBy": "2C",
           "linesTerminatedBy": "0A"
       }
   }
}

ERROR_RDBMS のようなエラーが発生した場合、テーブルが存在することを確認してください。存在している場合は、バケットに対して正しい権限があることを確認します。Cloud Storage のアクセス制御の構成について詳しくは、アクセス制御リストの作成と管理をご覧ください。

このタスクのために基盤となる REST API リクエストがどのように作成されるかについては、instances: import ページの API Explorer をご覧ください。

次のステップ