データのインポートとエクスポート

このドキュメントでは、Avro 形式と CSV 形式を使用して Spanner Omni でデータを移行、バックアップ、転送する方法について説明します。Spanner Omni CLI を使用して、Spanner Omni と Cloud Storage、Amazon Simple Storage Service（Amazon S3）、S3 互換のローカル ストレージ、ローカル ファイル システム（NFS）などのストレージ ソリューション間でデータベース コンテンツを移動します。Spanner Omni のインポートとエクスポートのデータフローは、モデル、ローカリティ グループ、プレースメントをサポートしていません。

インポート オペレーションとエクスポート オペレーションは Spanner Omni サーバーで実行され、使用可能なシステム リソースを共有します。インポートはリソースを大量に消費するため、RAM、CPU、ディスクの使用率が高くなり、アクティブなワークロードに影響する可能性があります。これらのタスクは通常、通常のトラフィックよりも低い優先度で実行されますが、デプロイのパフォーマンスへの影響を監視する必要があります。

ファイル形式の比較

次の表は、Spanner データのインポートとエクスポートにおける Avro ファイル形式と CSV ファイル形式の機能の違いを示しています。

能力 Avro CSV
データベース全体をインポートまたはエクスポートする はい ×
以前にエクスポートしたテーブルをインポートする ○ はい
過去のタイムスタンプでエクスポートする はい ○
Spanner を使用してインポートまたはエクスポートする ○ ○
他のデータベースからデータをインポートする × ○

Avro 形式と CSV 形式の両方で、データベース内のすべてのテーブルがエクスポートされます。Avro 形式ではスキーマもエクスポートされるため、再度インポートできます。CSV 形式ではスキーマはエクスポートされません。

始める前に

インポートまたはエクスポート オペレーションを開始する前に、権限を確認し、データ ストレージの場所にアクセスできるように構成します。

権限

始める前に、次の権限があることを確認してください。

  • spanner.databases.import
  • spanner.databases.export

Spanner Omni の Identity and Access Management（IAM）の詳細については、IAM の概要をご覧ください。ユーザーのロールを更新する方法については、ユーザーを更新するをご覧ください。

データソースと宛先

データは、Amazon Simple Storage Service（Amazon S3）バケット、Cloud Storage バケット、Amazon S3 互換のローカル ストレージ（MinIO など）、またはローカル ファイル システム（NFS）に保存できます。ローカル ファイル システムを使用する場合は、デプロイ内のすべてのサーバーで同じパスでデータが使用可能であることを確認します。

データストアへのアクセス権を付与する方法は 2 つあります。

  • 外部ストレージをデプロイに追加する: バケットを再利用する場合は、この方法をおすすめします。

  • 1 回限りの認証情報を作成する: これらの認証情報がインポート オペレーションまたはエクスポート オペレーションの期間（48 時間など）よりも長く存続するようにします。

認証情報には、インポート用にバケット内のオブジェクトを一覧表示して読み取る権限が必要です。Amazon S3 にエクスポートするには、次の追加の Amazon S3 権限が必要です。

  • s3:PutObject
  • s3:AbortMultipartUpload
  • s3:ListBucketMultipartUploads

詳細については、IAM 権限をご覧ください。

Spanner Avro ファイルをインポートする

以前に別の Spanner データベース（Spanner または Spanner Omni）から Avro 形式でエクスポートしたデータをインポートする手順は次のとおりです。

Avro インポートの前提条件

Avro のインポートを開始する前に、環境が次の要件を満たしていることを確認してください。

  • 移行先データベースを作成しました。

  • インポートするスキーマ オブジェクトがデータベースにまだ存在していない。Avro インポート プロセスでは、データをインポートする前にこれらのテーブルが作成されます。

Avro インポートの手順

エクスポートされたデータを含むフォルダのパスを特定します。このフォルダには次のものが含まれています。

  • spanner-export.json ファイル

  • エクスポートされたエンティティ（テーブル、シーケンス、スキーマなど）ごとに 1 つの ENTITY_NAME-manifest.json ファイル。

  • マニフェスト ファイルにリストされているすべての Avro ファイル。

データストアを外部ストレージとして追加済みの場合は、パスに認証情報を含める必要はありません。パスを直接指定できます。ワンタイム認証情報を使用している場合は、次の URL 形式を使用します。

  • Cloud Storage: gs://BUCKET_NAME/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY]。HMAC 認証情報を使用します。詳細については、HMAC キーをご覧ください。

  • Amazon S3: s3://S3_BUCKET/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY[&sessiontoken=SESSION_TOKEN]]

  • ローカル ファイル フォルダ*: file:///PATH_TO_DIR

インポートを開始するには、次のコマンドを実行します。

spanner databases import DATABASE_ID --url="URL" --format=avro [--avro-skip-wait-for-index-creation]

その他の情報

Avro ファイルをインポートする際は、次の情報を考慮してください。

インポート オペレーションが正常に開始されると、長時間実行オペレーション ID が返されます。この ID を使用して、オペレーションのステータスを追跡します。

CSV ファイルをインポートする

別のデータベースからエクスポートしたテキスト データをインポートする手順は次のとおりです。

CSV インポートの前提条件

CSV のインポートを開始する前に、次のことを確認してください。

  • テーブルが、BOOL、INT64、FLOAT64、NUMERIC、STRING、DATE、TIMESTAMP、BYTES、JSON のいずれかのサポートされているデータ型であることを確認します。

  • 移行先データベースを作成します。

  • データをインポートするすべてのテーブルを作成します。CSV インポート プロセスではテーブルは作成されません。

  • CSV ファイルにヘッダー行が含まれていないことを確認します。

CSV インポートの手順

CSV ファイルをインポートするには、インポートするデータを記述するマニフェスト ファイルを作成します。マニフェスト ファイルは次の構造を使用します。ここでは protobuf 形式で定義されています。

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a path or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

次にマニフェストの例を示します。

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

次の CSV ファイルにヘッダー行が含まれていないインポート コマンドの URL は、マニフェストの例で説明されているように、JSON 形式のマニフェスト ファイルを含むフォルダを指している必要があります。このファイルは、Avro のインポート手順で説明されている認証情報の URL 形式と同じ形式を使用して、Cloud Storage、Amazon S3、またはローカル ファイル フォルダに配置できます。インポートを開始するには、次のコマンドを実行します。

spanner databases import DATABASE_ID --url="URL" --format=csv

CSV インポートのオプション

次のフラグを使用して、Spanner Omni がテキスト ファイルを処理する方法をカスタマイズします。

  • --csv-date-format: 日付列の形式をオーバーライドします。デフォルト値は %Y-%m-%d です。例: %d/%m/%Y

  • --csv-timestamp-format: タイムスタンプ列の形式をオーバーライドします。これは、Spanner Omni が CSV の形式をサポートしていない場合にのみ使用します。例: %d/%m/%Y %H:%M:%S%Ez

  • --csv-delimiter: 区切り文字をオーバーライドします。デフォルトはカンマです。

  • --csv-quote-char: 引用符をオーバーライドします。デフォルトは二重引用符です。

  • --csv-escape-char: エスケープ文字をオーバーライドします。デフォルトは二重引用符です。

  • --csv-null-string: NULL 値を表す文字列をオーバーライドします。デフォルトは \N です。

  • --csv-has-trailing-delimiters: CSV ファイルに末尾の区切り文字があるかどうかを指定します。デフォルトは false です。

Avro ファイルにエクスポートする

データを Avro ファイルにエクスポートするには、Avro のインポート手順の URL 形式の手順に沿って操作します。

デプロイ内の任意のサーバーが、指定されたデータストアにデータを書き込むことができます。ローカル ファイル フォルダを宛先として使用する場合は、すべてのサーバーが同じパスにアクセスして、並行して書き込めるようにします。

データベース内のすべてのテーブルとエンティティがエクスポートされます。エクスポートされたデータの新しい空のフォルダパスを指定してください。

エクスポートを開始するには、次のコマンドを実行します。

spanner databases export DATABASE_ID --url="URL" --format=avro

CSV エクスポートはテーブルのみをサポートし、データベース スキーマはエクスポートしません。

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

CSV エクスポートでは、データベース スキーマはエクスポートされず、テーブルのみがサポートされます。データを CSV ファイルにエクスポートするには、次のコマンドを実行します。

spanner databases export DATABASE_ID --url="URL" --format=csv

トラブルシューティング

インポートが失敗した場合、スキーマの更新とインポートされたデータは自動的に元に戻りません。操作を再試行する前に、データベースを手動でクリーンアップします。

インポート オペレーションの速度は、フォルダ内のファイル数、デプロイで使用可能なコンピューティング リソース、ディスク速度など、いくつかの要因によって異なります。十分なリソースが利用可能な場合、システムはファイルを並行してインポートします。