Utilizzare il recupero point-in-time (PITR)

Console

1. Nella console Google Cloud, vai alla pagina Database.

   Vai a Database

2. Seleziona il database richiesto dall'elenco dei database.

3. Nel menu di navigazione, fai clic su Disaster Recovery.

4. Fai clic su Modifica per modificare le impostazioni.

5. Seleziona la casella di controllo Abilita recupero point-in-time e poi fai clic su Salva.

L'abilitazione di PITR comporta costi di archiviazione. Per ulteriori informazioni, consulta la pagina Prezzi.

Per disabilitare PITR, deseleziona la casella di controllo Abilita recupero point-in-time dalla pagina Disaster Recovery nella console Google Cloud.

gcloud

Abilita PITR durante la creazione del database con il gcloud firestore databases create e il --enable-ptir comando come segue:

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

Sostituisci i valori come segue:

• LOCATION - la località in cui vuoi creare il database.
• DATABASE_ID - impostalo su un ID database.

Puoi disabilitare PITR utilizzando il gcloud firestore databases update comando come segue:

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

Sostituisci i valori come segue:

• DATABASE_ID - impostalo sull'ID database o su `'(default)'`.

Console

1. Nella console Google Cloud, vai alla pagina Database.

   Vai a Database

2. Seleziona il database richiesto dall'elenco dei database.

3. Nel menu di navigazione, fai clic su Disaster Recovery.

4. Nella sezione Impostazioni, prendi nota del Periodo di conservazione e dell' Ora della prima versione.

   • Periodo di conservazione: il periodo in cui Cloud Firestore conserva tutte le versioni dei dati per il database. Il valore è di un'ora quando PITR è disabilitato e di sette giorni quando PITR è abilitato.
   • Ora della prima versione: il primo timestamp in cui è possibile leggere le versioni precedenti di dati nella finestra PITR. Questo valore viene aggiornato continuamente da Cloud Firestore e diventa obsoleto nel momento in cui viene eseguita una query. Se utilizzi questo valore per recuperare i dati, assicurati di tenere conto del tempo trascorso dal momento in cui viene eseguita la query sul valore al momento in cui avvii il recupero.
   • Recupero point-in-time: mostra Enabled se PITR è abilitato. Se PITR è disabilitato, vedrai Disabled.

gcloud

Esegui il comando gcloud firestore databases describe come segue:

gcloud firestore databases describe --database=DATABASE_ID

Sostituisci DATABASE_ID con l'ID database o '(default)'.

Ecco l'output:

    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

dove

• earliestVersionTime: timestamp dei primi dati PITR archiviati.
• pointInTimeRecoveryEnablement: mostra POINT_IN_TIME_RECOVERY_ENABLED se PITR è abilitato. Se PITR è disabilitato, vedrai POINT_IN_TIME_RECOVERY_DISABLED oppure il campo pointInTimeRecoveryEnablement potrebbe non essere visualizzato.
• versionRetentionPeriod: periodo di tempo per cui i dati PITR vengono conservati in millisecondi. Il valore può essere di un'ora quando PITR è disabilitato o di sette giorni se PITR è abilitato.

Librerie client

  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)}
);

API REST

Le letture PITR sono supportate in tutti i Cloud Firestore metodi di lettura, ovvero get, list, batchGet, listCollectionIds, listDocuments, runQuery, runAggregationQuery e partitionQuery.

Per eseguire una lettura utilizzando i metodi REST, prova una delle seguenti opzioni:

1. Nella richiesta del metodo di lettura, trasmetti il valore readTime come timestamp PITR supportato nel metodo readOptions. Un timestamp PITR può essere un timestamp con precisione in microsecondi nell'ultima ora o un timestamp di un minuto intero oltre l'ultima ora, ma non precedente a earliestVersionTime.

2. Utilizza il parametro readTime insieme al metodo BeginTransaction come parte di una transazione ReadOnly per più letture PITR.

Apache Beam

Utilizza il connettore Apache Beam Cloud FirestoreIO per leggere o scrivere documenti in un database Cloud Firestore su larga scala con Dataflow.

Le letture PITR sono supportate nel seguente metodo di lettura del Cloud FirestoreIO connector. Questi metodi di lettura supportano il metodo withReadTime(@Nullable Instant readTime) che puoi utilizzare per le letture PITR:

• FirestoreV1.BatchGetDocuments
• FirestoreV1.ListCollectionIds
• FirestoreV1.ListDocuments
• FirestoreV1.PartitionQuery

• FirestoreV1.RunQuery

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

Per un elenco completo degli esempi di readTime nella pipeline Dataflow, consulta il repository GitHub.

Console

La console Firebase non supporta la clonazione dei database. Puoi utilizzare le istruzioni per Google Cloud CLI per clonare i database.

gcloud

Utilizza il gcloud firestore databases clone comando per clonare un database:

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

Sostituisci quanto segue:

• SOURCE_DATABASE: il nome del database di un database esistente che vuoi clonare. Il nome utilizza il formato projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

• PITR_TIMESTAMP: un timestamp PITR in formato RFC 3339, con granularità di un minuto. Ad esempio: 2025-06-01T10:20:00.00Z o 2025-06-01T10:30:00.00-07:00.

• DESTINATION_DATABASE_ID: un ID database per un nuovo database clonato. Questo ID database non deve essere associato a un database esistente.

Esempio:

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

Se vuoi eseguire il binding ad alcuni tag durante la clonazione di un database, utilizza il comando precedente con il flag --tags, che è un elenco facoltativo di coppie KEY=VALUE di tag da associare.

Esempio:

gcloud 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

Per impostazione predefinita, il database clonato avrà la stessa configurazione di crittografia del database di origine. Per modificare la configurazione di crittografia, utilizza l'argomento --encryption-type:

• (Impostazione predefinita) use-source-encryption: utilizza la stessa configurazione di crittografia del database di origine.
• google-default-encryption: utilizza la crittografia predefinita di Google.
• customer-managed-encryption: utilizza la crittografia CMEK. Specifica un ID chiave nell'argomento --kms-key-name.

L'esempio seguente mostra come configurare la crittografia CMEK per il database clonato:

gcloud 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'

Interfaccia a riga di comando di Firebase

Utilizza il comando firebase firestore:databases:clone per clonare un database:

firebase firestore:databases:clone \
'SOURCE_DATABASE' \
'DESTINATION_DATABASE' \
--snapshot-time 'PITR_TIMESTAMP'

Sostituisci quanto segue:

• SOURCE_DATABASE: il nome del database di un database esistente che vuoi clonare. Il nome utilizza il formato projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

• DESTINATION_DATABASE: il nome del database di un nuovo database clonato. Il nome utilizza il formato projects/PROJECT_ID/databases/DESTINATION_DATABASE_ID. Questo nome del database non deve essere associato a un database esistente.

• PITR_TIMESTAMP: un timestamp PITR in formato RFC 3339, con granularità di un minuto. Ad esempio: 2025-06-01T10:20:00.00Z o 2025-06-01T10:30:00.00-07:00. Se non specificato, lo snapshot scelto sarà l'ora corrente, arrotondata al minuto.

Per impostazione predefinita, il database clonato avrà la stessa configurazione di crittografia del database di origine. Per modificare la configurazione di crittografia, utilizza l'argomento --encryption-type:

• (Impostazione predefinita) USE_SOURCE_ENCRYPTION: utilizza la stessa configurazione di crittografia del database di origine.
• GOOGLE_DEFAULT_ENCRYPTION: utilizza la crittografia predefinita di Google.
• CUSTOMER_MANAGED_ENCRYPTION: utilizza la crittografia CMEK. Specifica un ID chiave nell'argomento --kms-key-name.

L'esempio seguente mostra come configurare la crittografia CMEK per il database clonato:

firebase firestore:databases:clone \
'projects/example-project/databases/(default)' \
'projects/example-project/databases/example-dest-db' \
--snapshot-time 'PITR_TIMESTAMP' \
--encryption-type CUSTOMER_MANAGED_ENCRYPTION