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

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

始める前に

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

  • データベースに十分な空き容量があることを確認します。

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

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

Cloud SQL for PostgreSQL からデータをエクスポートする

Cloud SQL for PostgreSQL からエクスポートするために必要なロールと権限

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

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

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

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

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

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

Console

  1. Google Cloud コンソールで 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 を使用して、Cloud SQL インスタンスのサービス アカウントに 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 プロパティ 説明
エスケープ

"5C"

ファイル区切り文字の 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 エクスポートでは、標準の 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 SQL for PostgreSQL にデータをインポートする

Cloud SQL for PostgreSQL へのインポートに必要なロールと権限

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

  • 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 for PostgreSQL にデータをインポートする

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

CSV ファイル形式の要件

CSV ファイルは、データの行ごとに 1 行を使用し、カンマ区切りのフィールドが含まれている必要があります。

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

Console

  1. Google Cloud コンソールで 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. エクスポート元の Cloud SQL インスタンスのサービス アカウントを確認します。そのためには、インスタンス名を指定して gcloud sql instances describe コマンドを実行します。出力で serviceAccountEmailAddress フィールドを探します。
    gcloud sql instances describe INSTANCE_NAME
  5. serviceAccountEmailAddress フィールドをコピーします。
  6. gsutil iam を使用して、バケットの Cloud SQL インスタンス サービス アカウントに 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. バケットに対する legacyBucketWriter と objectViewer の 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: エスケープが必要なデータ文字の前に表示する文字。この引数の値は 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 権限を保持する必要がない場合は、権限を削除します。

Cloud SQL for PostgreSQL の 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 をご覧ください。

次のステップ