Work with point-in-time recovery (PITR)

This page describes how to use point-in-time recovery (PITR) to retain and recover data in Cloud Firestore with MongoDB compatibility.

To understand PITR concepts, see Point-in-time recovery .

Permissions

To get the permissions that you need to manage PITR settings, ask your administrator to grant you the following IAM roles on the project where you want to enable PITR:

• Cloud Datastore Owner ( roles/datastore.owner )

For custom roles, ensure that the following permissions are granted:

• To enable PITR when creating a database: datastore.databases.create
• To update PITR settings on existing database: datastore.databases.update , datastore.databases.list
• To perform reads from PITR data: datastore.databases.get , datastore.entities.get , datastore.entities.list
• To export PITR data: datastore.databases.export
• To import PITR data: datastore.databases.import
• To clone a database: datastore.databases.clone

Before you begin

Note the following points before you start using PITR:

• You can't start reading from seven days in the past immediately after you enable PITR.
• If you want to enable PITR when you create a database, you must use the gcloud firestore databases create command. Enabling PITR while creating a database using the Google Cloud console is not supported.
• Cloud Firestore with MongoDB compatibility starts retaining versions from the point forward after enabling PITR.
• You cannot read PITR data in the PITR window after you disable PITR.
• If you re-enable PITR immediately after disabling it, the past PITR data is no longer available. Any PITR data created before disabling PITR will be deleted after the PITR expiration date.
• If you accidentally deleted data in the last hour and PITR is disabled, you can restore your data by enabling PITR within one hour of deletion.
• Any read performed on expired PITR data fails.

Enable PITR

Before using PITR, enable billing for your Google Cloud project . Only Google Cloud projects with billing enabled can use the PITR functionality.

To enable PITR for your database:

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

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

Get the retention period and earliest version time

 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 

Read PITR data

   
 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 
 ()) 
  
 ... 
 

Clone from a database

You can clone an existing database at a selected timestamp into a new database:

• The cloned database is a new database that will be created in the same location as the source database.

  To make a clone, Cloud Firestore uses point-in-time recovery (PITR) data of the source database. The cloned database includes all data and indexes.

• By default, the cloned database will be encrypted in the same way as the source database, using either Google's default encryption or CMEK encryption . You can specify a different encryption type or use a different key for CMEK encryption.

• The timestamp has a granularity of one minute and specifies a point of time in the past, in the period defined by the PITR window :

  • If PITR is enabled for your database, you select any minute in the last 7 days (or less if PITR was enabled less than 7 days ago).
  • If PITR isn't enabled, you can select any minute in the past hour.
  • You can check the earliest timestamp that you can pick in your database's description .

 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' 
 

Limitations

A clone operation does not clone App Engine search data or blob entities from a (default) database. This data is only valid for the (default) database, and it won't be useful if you clone from (default) to a database which does not support such data, so it is excluded from clones.

Export and import from PITR data

You can export your database to Cloud Storage from PITR data using the gcloud firestore export command. You can export PITR data where the timestamp is a whole minute timestamp within the past seven days, but not earlier than the earliestVersionTime . If data no longer exists at the specified timestamp, the export operation fails.

The PITR export operation supports all filters, including export of all documents and export of specific collections.

1. Export the database, specifying the snapshot-time parameter to the chosen recovery timestamp.

   gcloud

   Run the following command to export the database to your bucket.

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

   Where,

   • BUCKET_NAME_PATH - a valid Cloud Storage bucket with an optional path prefix where export files are stored.
   • PITR_TIMESTAMP - a PITR timestamp at the minute granularity, for example, 2023-05-26T10:20:00.00Z or 2023-10-19T10:30:00.00-07:00 .
   • COLLECTION_IDS - a list of collection IDs or collection group IDs, for example- 'specific-collection-group1','specific-collection-group2' .
   • NAMESPACE_IDS - a list of namespace IDs, for example- 'customer','orders' .

   Note the following points before exporting PITR data:

   • Specify the timestamp in RFC 3339 format . For example, 2023-05-26T10:20:00.00Z or 2023-10-19T10:30:00.00-07:00 .
   • Make sure that the timestamp you specify is a whole minute timestamp within the past seven days, but not earlier than the earliestVersionTime . If data no longer exists at the specified timestamp, an error is generated. The timestamp must be a whole minute, even if the specified time is within the past hour.
   • You are not charged for a failed PITR export.

2. Import to a database.

   Use the steps in Import all documents to import your exported database. If any document already exists in your database, it will be overwritten.