ポイントインタイム リカバリ（PITR）の操作

このページでは、ポイントインタイム リカバリ（PITR）を使用して、MongoDB 互換の Cloud Firestore でデータを保持および復元する方法について説明します。

PITR のコンセプトを理解するには、ポイントインタイム リカバリをご覧ください。

権限

PITR 設定を管理するために必要な権限を取得するには、PITR を有効にするプロジェクトに対して次の IAM ロールを付与するよう管理者に依頼します。

• Cloud Datastore オーナー（roles/datastore.owner）

カスタムロールの場合は、次の権限を付与してください。

• データベース作成時の PITR を有効にするには: datastore.databases.create
• 既存のデータベースの PITR 設定を更新するには: datastore.databases.update、datastore.databases.list
• PITR データからの読み取りを実行するには: datastore.databases.get、datastore.entities.get、datastore.entities.list
• PITR データをエクスポートするには: datastore.databases.export
• PITR データをインポートするには: datastore.databases.import
• データベースのクローンを作成するには: datastore.databases.clone

始める前に

PITR の使用を開始する前に、次の点に注意してください。

• PITR を有効にした直後は、7 日前からの読み取りを開始できません。
• データベース作成時の PITR を有効にする場合は、gcloud firestore databases create コマンドを使用する必要があります。Google Cloud コンソールを使用してデータベースを作成するときに PITR を有効にすることはできません。
• MongoDB 互換の Cloud Firestore で PITR を有効にすると、その時点からのバージョンの保持が開始されます。
• PITR を無効にすると、PITR データの保持期間内であっても PITR データを読み取ることができなくなります。
• PITR を無効にした直後に再度有効にした場合、過去の PITR データは使用できなくなります。PITR を無効にする前に作成された PITR データは、PITR の有効期限の後に削除されます。
• 過去 1 時間以内に誤ってデータを削除し、PITR が無効になっている場合は、削除後 1 時間以内であれば PITR を有効にするとデータを復元できます。
• 期限切れの PITR データに対する読み取りはすべて失敗します。

PITR を有効にする

PITR を使用する前に、Google Cloud プロジェクトに対する課金を有効にします。PITR 機能を使用できるのは、課金が有効になっている Google Cloud プロジェクトのみです。

データベースの PITR を有効にするには:

gcloud firestore databases create\
  --location=LOCATION\
  --database=DATABASE_ID\
  --type=firestore-native\
  --enable-pitr

gcloud firestore databases update\
  --database=DATABASE_ID\
  --no-enable-pitr

保持期間と最短版の時間を取得する

gcloud firestore databases describe --database=DATABASE_ID

    appEngineIntegrationMode: ENABLED
    concurrencyMode: PESSIMISTIC
    createTime: '2021-03-24T17:02:35.234Z'
    deleteProtectionState: DELETE_PROTECTION_DISABLED
    earliestVersionTime: '2023-06-12T16:17:25.222474Z'
    etag: IIDayqOevv8CMNTvyNK4uv8C
    keyPrefix: s
    locationId: nam5
    name: projects/PROJECT_ID/databases/DATABASE_ID
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: FIRESTORE_NATIVE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

PITR データを読み取る

  Firestore firestore = …

  TransactionOptions options =
          TransactionOptions.createReadOnlyOptionsBuilder()
              .setReadTime(
                  com.google.protobuf.Timestamp.newBuilder()
                      .setSeconds(1684098540L)
                      .setNanos(0))
              .build();

  ApiFuture<Void> futureTransaction = firestore.runTransaction(
              transaction -> {
                // Does a snapshot read document lookup
                final DocumentSnapshot documentResult =
                    transaction.get(documentReference).get();

                // Executes a snapshot read query
                final QuerySnapshot queryResult =
                  transaction.get(query).get();
              },
              options);

  // Blocks on transaction to complete
  futureTransaction.get();

const documentSnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(documentRef),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

const querySnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(query),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

  Instant readTime = Instant.ofEpochSecond(1684098540L);

  PCollection<Document> documents =
      pipeline
          .apply(Create.of(collectionId))
          .apply(
              new FilterDocumentsQuery(
                  firestoreOptions.getProjectId(), firestoreOptions.getDatabaseId()))
          .apply(FirestoreIO.v1().read().runQuery().withReadTime(readTime).withRpcQosOptions(rpcQosOptions).build())
  ...

データベースからクローンを作成する

選択したタイムスタンプの既存のデータベースを新しいデータベースにクローン作成できます。

• クローン作成されたデータベースは、ソース データベースと同じロケーションに作成される新しいデータベースです。

  クローンを作成するために、Cloud Firestore はソース データベースのポイントインタイム リカバリ（PITR）データを使用します。クローンデータベースには、すべてのデータとインデックスが含まれます。

• デフォルトでは、クローン作成されたデータベースは、Google のデフォルトの暗号化または CMEK 暗号化を使用して、ソース データベースと同じ方法で暗号化されます。別の暗号化タイプを指定することも、CMEK 暗号化に別の鍵を使用することもできます。

• タイムスタンプは 1 分単位で、PITR 期間で定義した期間内の過去の時点を指定します。

  • データベースで PITR が有効になっている場合は、過去 7 日間の任意の分を選択します（PITR が 7 日前より短い時点で有効になった場合は、それより短い期間になります）。
  • PITR が有効になっていない場合は、過去 1 時間の任意の分を選択できます。
  • 選択できる最も古いタイムスタンプは、データベースの説明で確認できます。

gcloud alpha firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--tags=key1=value1,key2=value2

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

制限事項

クローン オペレーションでは、(default) データベースの App Engine 検索データまたは blob エンティティのクローンは作成されません。このデータは (default) データベースでのみ有効です。(default) からこのようなデータをサポートしていないデータベースにクローンを作成しても役に立たないため、クローンから除外されます。

PITR データからエクスポートおよびインポートする

gcloud firestore export コマンドを使用すると、PITR データから Cloud Storage にデータベースをエクスポートできます。タイムスタンプが過去 7 日間以内（ただし earliestVersionTime 以降）の 1 分単位の場合に、PITR データをエクスポートできます。指定したタイムスタンプにデータがもう存在しない場合、エクスポート オペレーションは失敗します。

PITR エクスポート オペレーションでは、すべてのドキュメントのエクスポート、特定のコレクションのエクスポートなど、すべてのフィルタがサポートされています。

1. snapshot-time パラメータを選択したリカバリ タイムスタンプに指定して、データベースをエクスポートします。

   gcloud

   次のコマンドを実行して、データベースをバケットにエクスポートします。

   gcloud firestore export gs://BUCKET_NAME_PATH \
       --snapshot-time=PITR_TIMESTAMP \
       --collection-ids=COLLECTION_IDS \
       --namespace-ids=NAMESPACE_IDS
   

   ここで

   • BUCKET_NAME_PATH - エクスポート ファイルが保存されている有効な Cloud Storage バケット（パス接頭辞は省略可）。
   • PITR_TIMESTAMP - 分単位の PITR タイムスタンプ（例: 2023-05-26T10:20:00.00Z または 2023-10-19T10:30:00.00-07:00）。
   • COLLECTION_IDS - コレクション ID またはコレクション グループ ID のリスト（例: 'specific-collection-group1','specific-collection-group2'）。
   • NAMESPACE_IDS - 名前空間 ID のリスト（例: 'customer','orders'）。

   PITR データをエクスポートする前に、次の点に注意してください。

   • RFC 3339 形式でタイムスタンプを指定しますたとえば、2023-05-26T10:20:00.00Z や 2023-10-19T10:30:00.00-07:00 です。
   • タイムスタンプは、過去 7 日間以内（ただし earliestVersionTime 以降）の 1 分単位のタイムスタンプを指定する必要があります。指定したタイムスタンプにデータが存在しない場合、エラーが発生します。指定した時間が過去 1 時間以内の場合でも、タイムスタンプは 1 分単位にする必要があります。
   • 失敗した PITR エクスポートについては課金されません。

2. データベースにインポートします。

   すべてのドキュメントをインポートする手順に沿って、エクスポートしたデータベースをインポートします。データベースにすでにドキュメントが存在する場合は上書きされます。