このページでは、ポイントインタイム リカバリ（PITR）を使用して 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 を有効にすることはできません。 - Cloud Firestore で PITR を有効にすると、その時点からのバージョンの保持が開始されます。
- PITR を無効にすると、PITR データの保持期間内であっても PITR データを読み取ることができなくなります。
- PITR を無効にした直後に再度有効にした場合、過去の PITR データは使用できなくなります。PITR を無効にする前に作成された PITR データは、PITR の有効期限の後に削除されます。
- 過去 1 時間以内に誤ってデータを削除し、PITR が無効になっている場合は、削除後 1 時間以内であれば PITR を有効にするとデータを復元できます。
- 期限切れの PITR データに対する読み取りはすべて失敗します。
PITR を有効にする
PITR を使用する前に、Google Cloud プロジェクトに対する課金を有効にします。PITR 機能を使用できるのは、課金が有効になっている Google Cloud プロジェクトのみです。
データベースの PITR を有効にするには:
コンソール
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
ナビゲーション メニューで、[障害復旧] をクリックします。
[編集] をクリックして設定を編集します。
[ポイントインタイム リカバリを有効にする] チェックボックスをオンにして、[保存] をクリックします。
PITR を有効にすると、ストレージの費用が発生します。詳細は料金をご覧ください。
PITR を無効にするには、Google Cloud コンソールの [障害復旧] ページで [ポイントインタイム リカバリを有効にする] チェックボックスをオフにします。
gcloud
次のように gcloud firestore databases create コマンドと --enable-ptir コマンドを使用して、データベース作成時の PITR を有効にします。
gcloud firestore databases create\
--location=LOCATION\
--database=DATABASE_ID\
--type=firestore-native\
--enable-pitr
次のように置き換えます。
LOCATION- データベースを作成するロケーション。DATABASE_ID- データベース ID に設定します。
PITR を無効にするには、次のように gcloud firestore databases update コマンドを使用します。
gcloud firestore databases update\
--database=DATABASE_ID\
--no-enable-pitr
次のように置き換えます。
DATABASE_ID- データベース ID または（default）に設定します。
保持期間と最短版の時間を取得する
コンソール
Google Cloud コンソールで [データベース] ページに移動します。
データベースのリストから、必要なデータベースを選択します。
ナビゲーション メニューで、[障害復旧] をクリックします。
[設定] セクションの [保持期間] と [最も古いバージョンの時刻] をメモします。
- 保持期間: Cloud Firestore がデータベースのすべてのバージョンのデータを保持する期間。この値は、PITR が無効になっている場合は 1 時間、PITR が有効になっている場合は 7 日間です。
- 最も古いバージョンの時刻: PITR 期間で古いバージョンのデータを読み取ることができる最も古いタイムスタンプ。この値は Cloud Firestore によって継続的に更新されますが、クエリが行われるとその時点で最新ではなくなります。この値を使用してデータを復元する場合、値がクエリされてから復元を行うまでの間に経過した時間を考慮する必要があります。
- ポイントインタイム リカバリ: PITR が有効になっている場合は、
Enabledが表示されます。PITR が無効になっていると、Disabledが表示されます。
gcloud
gcloud firestore databases describe コマンドを次のように実行します。
gcloud firestore databases describe --database=DATABASE_ID
DATABASE_ID を、データベース ID または '(default)' に置き換えます。
出力は次のとおりです。
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
ここで
earliestVersionTime: 保存されている最も古い PITR データのタイムスタンプ。pointInTimeRecoveryEnablement: PITR が有効になっている場合は、POINT_IN_TIME_RECOVERY_ENABLEDが表示されます。PITR が無効になっている場合は、POINT_IN_TIME_RECOVERY_DISABLEDが表示されるか、pointInTimeRecoveryEnablementフィールドが表示されません。versionRetentionPeriod: PITR データが保持される期間（ミリ秒単位）。この値は、PITR が無効になっている場合は 1 時間、PITR が有効になっている場合は 7 日間になります。
PITR データを読み取る
PITR データを読み取るには、クライアント ライブラリ、REST API メソッド、または FirestoreIO Apache Beam コネクタを使用します。クライアント ライブラリ
Java
PITR データを読み取るには、ReadOnly トランザクションを使用する必要があります。読み取りで readTime を直接指定することはできません。詳細については、トランザクションとバッチ書き込みをご覧ください。
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();
ノード
PITR データを読み取るには、ReadOnly トランザクションを使用する必要があります。読み取りで readTime を直接指定することはできません。詳細については、トランザクションとバッチ書き込みをご覧ください。
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)}
);
REST API
PITR の読み取りは Cloud Firestore のすべての読み取りメソッドでサポートされています（get、list、batchGet、listCollectionIds、listDocuments、runQuery、runAggregationQuery、partitionQuery）。
REST のメソッドを使用して読み取りを実行するには、次の方法があります。
読み取りメソッド リクエストで、サポートされている PITR タイムスタンプとして
readOptionsメソッドでreadTime値を渡します。PITR タイムスタンプには、過去 1 時間以内のマイクロ秒精度のタイムスタンプ、または過去 1 時間を超え、earliestVersionTime以降の 1 分単位のタイムスタンプを指定できます。複数の PITR 読み取りの
ReadOnlyトランザクションの一環として、readTimeパラメータをBeginTransactionメソッドに使用します。
Apache Beam
Cloud FirestoreIO Apache Beam コネクタを使用して、Dataflow で Cloud Firestore データベース内のドキュメントを大規模に読み書きできます。
PITR 読み取りは、Cloud FirestoreIO コネクタの次の読み取りメソッドでサポートされています。次の読み取りメソッドは、PITR 読み取りに使用できる withReadTime(@Nullable Instant readTime) メソッドをサポートしています。
- FirestoreV1.BatchGetDocuments
- FirestoreV1.ListCollectionIds
- FirestoreV1.ListDocuments
- FirestoreV1.PartitionQuery
Java
次のコードは、Dataflow パイプラインのコード例で一括読み取りまたは一括書き込みのオペレーションに使用できます。この例では、PITR の読み取りに withReadTime(@Nullable Instant readTime) メソッドを使用しています。
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())
...
Dataflow パイプラインの readTime の例の一覧については、GitHub リポジトリをご覧ください。
PITR データからエクスポートおよびインポートする
gcloud firestore export コマンドを使用すると、PITR データから Cloud Storage にデータベースをエクスポートできます。タイムスタンプが過去 7 日間以内（ただし earliestVersionTime 以降）の 1 分単位の場合に、PITR データをエクスポートできます。指定したタイムスタンプにデータがもう存在しない場合、エクスポート オペレーションは失敗します。
PITR エクスポート オペレーションでは、すべてのドキュメントのエクスポート、特定のコレクションのエクスポートなど、すべてのフィルタがサポートされています。
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 エクスポートについては課金されません。
データベースにインポートします。
すべてのドキュメントをインポートする手順に沿って、エクスポートしたデータベースをインポートします。データベースにすでにドキュメントが存在する場合は上書きされます。
データベースからクローンを作成する
選択したタイムスタンプの既存のデータベースを新しいデータベースに複製できます。
クローン作成されたデータベースは、ソース データベースと同じロケーションに作成される新しいデータベースです。
クローンを作成するために、Cloud Firestore はソース データベースのポイントインタイム リカバリ（PITR）データを使用します。クローンデータベースには、すべてのデータとインデックスが含まれます。
デフォルトでは、クローン データベースは、Google のデフォルトの暗号化または CMEK 暗号化を使用して、ソース データベースと同じ方法で暗号化されます。別の暗号化タイプを指定するか、CMEK 暗号化に別の鍵を使用できます。
タイムスタンプの粒度は 1 分で、PITR ウィンドウで定義された期間内の過去の時点を指定します。
- データベースで PITR が有効になっている場合は、過去 7 日間の任意の分を選択します（PITR が 7 日未満前に有効になった場合は、それより短い期間になります）。
- PITR が有効になっていない場合は、過去 1 時間以内の任意の時刻（分）を選択できます。
- 選択できる最も古いタイムスタンプは、データベースの説明で確認できます。
コンソール
Firebase コンソールでは、データベースのクローン作成はサポートされていません。Google Cloud CLI の手順を使用して、データベースのクローンを作成できます。
gcloud
gcloud alpha firestore databases clone コマンドを使用して、データベースのクローンを作成します。
gcloud alpha firestore databases clone \
--source-database='SOURCE_DATABASE_ID' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'
以下を置き換えます。
SOURCE_DATABASE_ID: クローンを作成する既存のデータベースのデータベース ID。
PITR_TIMESTAMP: 分単位の RFC 3339 形式の PITR タイムスタンプ。たとえば、
2025-06-01T10:20:00.00Zや2025-06-01T10:30:00.00-07:00です。DESTINATION_DATABASE_ID: 新しいクローン データベースのデータベース ID。このデータベース ID は、既存のデータベースに関連付けられていてはなりません。
例:
gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='projects/example-project/databases/example-dest-db'
クローン作成されたデータベースの暗号化構成を変更する
デフォルトでは、クローン データベースはソース データベースと同じ暗号化構成になります。暗号化構成を変更するには、--encryption-type 引数を使用します。
- （デフォルト）
use-source-encryption: 移行元データベースと同じ暗号化構成を使用します。 google-default-encryption: Google のデフォルトの暗号化を使用customer-managed-encryption: CMEK 暗号化を使用します。--kms-key-name引数でキー ID を指定します。
次の例は、クローン作成されたデータベースの CMEK 暗号化を構成する方法を示しています。
gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='projects/example-project/databases/example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'