CSV ファイルをエクスポートする

このページでは、AlloyDB for PostgreSQL クラスタから Cloud Storage バケットにデータをエクスポートする方法について説明します。データは、他のツールや環境で使用可能な CSV 形式でエクスポートします。

サポートされているデータベースサーバーから新しい AlloyDB インスタンスにデータベース全体を移行する方法については、Database Migration Service を使用してデータベースを AlloyDB に移行するをご覧ください。エクスポートしたファイルから新しいインスタンスを作成することが目的の場合は、保存されているバックアップからクラスタを復元することを検討してください。

AlloyDB for PostgreSQL クラスタからのデータのエクスポートはキャンセルが可能です。詳細については、データのエクスポートをキャンセルするをご覧ください。

始める前に

エクスポートオペレーションを開始する前に: エクスポートオペレーションではデータベースリソースが使用されることにご注意ください。ただし、インスタンスのプロビジョニングが不十分である場合を除き、標準的なデータベースオペレーションが妨げられることはありません。
SELECT_QUERY にはコメントや先頭と末尾の空白文字を含めることができます。コメントは無視され、空白文字はエクスポートクエリを実行する前に削除されます。
ターゲットバケットがソースクラスタとは異なるリージョンにある場合、リージョン間のデータ転送料金が適用されます。詳細については、AlloyDB for PostgreSQL の料金をご覧ください。
複数のエクスポートオペレーションを並行して実行できます。
オブジェクト名が .gz 拡張子で終わっている場合は圧縮が有効になります。このオブジェクトは .gz 形式で Cloud Storage にエクスポートされます。
field_delimiter、quote_character、escape_character などの CSV オプションの文字値には、（0x 接頭辞の有無にかかわらず）16 進数コードの ASCII 文字のみを使用できます。

AlloyDB からのエクスポートに必要なロールと権限

AlloyDB から Cloud Storage にデータをエクスポートするには、エクスポートを開始するユーザーに次のいずれかの Identity and Access Management（IAM）ロールが必要です。

Cloud AlloyDB 管理者（roles/alloydb.admin）ロール
次の権限を含むカスタムロール:
- alloydb.clusters.get
- alloydb.clusters.export

また、AlloyDB クラスタのサービスアカウントには、次のいずれかのロールが必要です。

storage.objectAdmin IAM ロール
次の権限を含むカスタムロール:
- storage.objects.create

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

CSV ファイルにデータをエクスポートする

CSV をエクスポートするときに、エクスポートするスキーマを指定できます。データベースレベルのスキーマはすべてエクスポート可能です。

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

gcloud

Cloud Storage バケットを作成します。
エクスポートオペレーション用の Cloud Storage バケットに対する権限をサービスアカウントに付与します。サービスアカウントの形式を使用して、エクスポート元のプロジェクトのサービスアカウントを特定します。サービスアカウントの形式は次のとおりです。
```
service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
gcloud storage buckets add-iam-policy-binding を使用して、storage.objectAdmin IAM ロールをサービスアカウントに付与します。IAM 権限の設定については、IAM 権限の使用をご覧ください。

注: エクスポートするオブジェクトと同じ名前のオブジェクトが Cloud Storage バケットにすでに存在する場合、サービスアカウントに objectAdmin ロールを付与すると、古いオブジェクトが置き換えられます。これを回避するには、権限の低い storage.objectCreator 権限をサービスアカウントに付与します。この権限では、既存のオブジェクトを置き換えることはできません。
データベースを Cloud Storage バケットにエクスポートします。

CSV をエクスポートするコマンド（gcloud alloydb clusters export）を実行します。

CSV 形式でデータをエクスポートするためのオプションは、次の表に示すとおりです。
- --select-query（必須）: データを抽出するために使用する select クエリ。
注: 転送中は、クエリがターゲットインスタンスのロケーション以外の中間ロケーションで処理されることがあります。
- --async（省略可）: 処理中のオペレーションの完了を待たずに、直ちに戻ります。
- --field-delimiter（省略可）: ファイルの各行の列を区切る文字を指定します。デフォルトはカンマです。この引数の値は、16 進数の ASCII コードで指定する必要があります。
- --quote-character（省略可）: データ値を引用符で囲むときに使用する引用符文字を指定します。デフォルトは二重引用符です。この引数の値は、16 進数の ASCII コードで指定する必要があります。
- --escape-character（省略可）: エスケープが必要なデータ文字の前に付ける文字を指定します。デフォルトは --quote-character と同じです。この引数の値は、16 進数の ASCII コードで指定する必要があります。
これらの機能を使用するには、該当するオプションを gcloud CLI コマンドに含めます。

使用しない機能については、該当するパラメータを次のコマンドから削除します。
```
gcloud alloydb clusters export CLUSTER_NAME
  --region=REGION
  --database=DATABASE_NAME
  --gcs-uri="gs://BUCKET_NAME/OBJECT_NAME"
  --select-query=SELECT_QUERY
  --field-delimiter=FIELD_DELIMITER
  --quote-character=QUOTE_CHARACTER
  --escape-character=ESCAPE_CHARACTER
  --csv
```
以前に設定した IAM ロールを保持する必要がない場合は、直ちに取り消します。

REST v1

エクスポート先のバケットを作成します。

gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME>

サービスアカウントの形式を使用して、エクスポート元のプロジェクトのサービスアカウントを特定します。

サービスアカウントの形式は次のとおりです。
```
 service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
この操作を行うには、Cloud Storage バケットに対してエクスポートオペレーションを行える権限が付与されている必要があります。
gcloud storage buckets add-iam-policy-binding を使用して、サービスアカウントに storage.objectAdminIAM ロールを付与します。IAM 権限の設定については、IAM 権限の使用をご覧ください。

注: エクスポートするオブジェクトと同じ名前のオブジェクトが Cloud Storage バケットにすでに存在する場合、サービスアカウントに objectAdmin ロールを付与すると、古いオブジェクトが置き換えられます。これを回避するには、権限の低い storage.objectCreator 権限をサービスアカウントに付与します。この権限では、既存のオブジェクトを置き換えることはできません。
データベースをエクスポートします。

次の HTTP メソッドと URL を使用します。
```
POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export
```
リクエストのデータを使用する前に、次のように置き換えます。
- PROJECT_ID: プロジェクト ID。
- REGION: AlloyDB クラスタがデプロイされているリージョン。
- CLUSTER_ID: クラスタ ID。
- BUCKET_NAME: Cloud Storage バケット名。
- PATH_TO_CSV_FILE: CSV ファイルのパス。
- DATABASE_NAME: AlloyDB クラスタ内のデータベースの名前。
- SELECT_QUERY: エクスポート用の SQL クエリ。
  
  注: 転送中は、クエリがターゲットインスタンスのロケーション以外の中間ロケーションで処理されることがあります。
- ESCAPE_CHARACTER（省略可）: エスケープが必要なデータ文字の前に付ける文字。この引数の値は、16 進数の ASCII コードで指定する必要があります。たとえば、22 は二重引用符を表します。
- QUOTE_CHARACTER（省略可）: 文字列データ型を持つ列の値を囲む文字。この引数の値は、16 進数の ASCII コードで指定する必要があります。たとえば、22 は二重引用符を表します。
- FIELD_DELIMITER（省略可）: 列の値を分割する文字。この引数の値は、16 進数の ASCII コードで指定する必要があります。たとえば、2C はカンマを表します。
リクエストの本文（JSON）:
```
{
  "gcs_destination": {
    "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE"
  },
  "database": "DATABASE_NAME",
  "csv_export_options": {
    "select_query": "SELECT_QUERY",
    "escape_character": "ESCAPE_CHARACTER",
    "quote_character": "QUOTE_CHARACTER",
    "field_delimiter": "FIELD_DELIMITER"
  }
}
```
リクエストを送信するには、次のいずれかのオプションを使用します。

curl（Linux、macOS、Cloud Shell）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

       curl -X POST \
             -H "Authorization: Bearer $(gcloud auth print-access-token)" \
             -H "Content-Type: application/json; charset=utf-8" \
             -d @request.json \
             "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"

PowerShell（Windows）

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
      -Method POST `
      -Headers $headers `
      -ContentType: "application/json; charset=utf-8" `
      -InFile request.json `
      -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"| Select-Object -Expand Content

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

レスポンス

    {
     "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
     "metadata": {
      "@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata",
      "createTime": "2024-09-17T06:05:31.244428646Z",
      "target": "projects/PROJECT_ID/locations/REGION/clusters/TARGET_CLUSTER",
      "verb": "export",
      "requestedCancellation": false,
      "apiVersion": "v1"
     },
     "done": false
    }

以前に設定した IAM 権限を保持する必要がない場合は、直ちに削除してください。

リクエストのパラメータの一覧については、clusters:export をご覧ください。

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

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

CSV のオプション	デフォルト値	gcloud フラグ	REST API プロパティ	説明
エスケープ	デフォルトは `QUOTE` 値と同じです。	`--escape-character`	`escape_character`	エスケープが必要なデータ文字の前に付ける文字。
引用符	`"22"` 二重引用符の ASCII 16 進数コード。	`--quote-character`	`quote_character`	データ値を引用符で囲むときに使用する引用符文字を指定します。
フィールド区切り文字	`"2C"` カンマを表す ASCII 16 進数コード。	`--field-delimiter`	`field_delimiter`	列の値を区切る文字。

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

gcloud alloydb clusters export CLUSTER_NAME \
--region=REGION \
--database=DATABASE_NAME \
--gcs-uri='gs://BUCKET_NAME/PATH_TO_CSV_FILE' \
--select-query=SELECT_QUERY \
--field-delimiter='2C' \
--quote-character='22' \
--escape-character='5C'
--csv

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

{
 "exportContext":
   {
      "gcs_destination": {
        "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE",
      },
      "database": "DATABASE_NAME",
      "csv_export_options":
       {
           "select_query": "SELECT_QUERY",
           "escape_character": "5C",
           "quote_character": "22",
           "field_delimiter": "2C",
       }
   }
}

デフォルトでは、CSV エクスポートによって標準の CSV 出力が作成されます。AlloyDB で提供されるオプションよりも多くのオプションが必要な場合は、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');

次のステップ

SQL ダンプファイルをエクスポートする方法を確認する。
エクスポートオペレーションをキャンセルする。