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 il recupero point-in-time, quindi fai clic su Salva.

L'abilitazione del PITR comporta costi di archiviazione. Per saperne di più, consulta la sezione Prezzi.

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

gcloud

Attiva il PITR durante la creazione del database con gcloud firestore databases create e il comando --enable-ptir 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: impostato su un ID database.

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

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

Sostituisci i valori come segue:

• DATABASE_ID: impostato 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 versione meno recente.

   • Periodo di conservazione: il periodo in cui Cloud Firestore conserva tutte le versioni dei dati per il database. Il valore è un'ora quando il PITR è disabilitato e sette giorni quando il PITR è abilitato.
   • Ora versione più vecchia: il timestamp più vecchio in cui è possibile leggere le versioni precedenti dei dati nella finestra PITR. Questo valore viene aggiornato continuamente da Cloud Firestore e diventa inattivo nel momento in cui viene eseguita la query. Se utilizzi questo valore per recuperare i dati, assicurati di tenere conto del tempo che intercorre tra il momento in cui viene eseguita la query sul valore e il momento in cui avvii il recupero.
   • Recupero point-in-time: mostra Enabled se il PITR è abilitato. Se il PITR è disattivato, 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 del 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 dati PITR più vecchi archiviati.
• pointInTimeRecoveryEnablement: mostra POINT_IN_TIME_RECOVERY_ENABLED se il PITR è abilitato. Se il PITR è disattivato, vedrai POINT_IN_TIME_RECOVERY_DISABLED o il campo pointInTimeRecoveryEnablement potrebbe non essere visualizzato.
• versionRetentionPeriod: periodo di tempo per il quale i dati PITR vengono conservati in millisecondi. Il valore può essere un'ora se il PITR è disabilitato o sette giorni se il 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 metodi di lettura Cloud Firestore, 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, passa il valore readTime come timestamp PITR supportato nel metodo readOptions. Un timestamp PITR può essere un timestamp con precisione al microsecondo nell'ultima ora o un timestamp di un minuto intero oltre l'ultima ora, ma non prima di earliestVersionTime.

2. Utilizza il parametro readTime insieme al metodo BeginTransaction nell'ambito di una transazione ReadOnly per più letture PITR.

Apache Beam

Utilizza il connettore Apache Beam di I/O Cloud Firestore 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 connettore Cloud FirestoreIO. 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 comando gcloud firestore databases clone 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 di un database esistente che vuoi clonare. Il nome utilizza il formato projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

• PITR_TIMESTAMP: un timestamp PITR nel formato RFC 3339, con granularità al 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 l'associazione ad alcuni tag durante la clonazione di un database, utilizza il comando precedente con il flag --tags, che è un elenco facoltativo di coppie CHIAVE=VALORE 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 della crittografia, utilizza l'argomento --encryption-type:

• (Predefinito) 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 di un database esistente che vuoi clonare. Il nome utilizza il formato projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

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

• PITR_TIMESTAMP: un timestamp PITR nel formato RFC 3339, con granularità al 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 per difetto al minuto.

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

• (Predefinito) 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