Utilizzare il recupero point-in-time (PITR)

Questa pagina descrive come utilizzare il recupero point-in-time (PITR) per conservare e recuperare i dati in Firestore con compatibilità MongoDB.

Per comprendere i concetti di PITR, consulta Recupero point-in-time.

Autorizzazioni

Per ottenere le autorizzazioni necessarie per gestire le impostazioni PITR, chiedi all'amministratore di concederti il ruolo IAM Proprietario di Cloud Datastore (roles/datastore.owner) sul progetto di cui vuoi abilitare le impostazioni PITR. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per gestire le impostazioni PITR. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per gestire le impostazioni PITR sono necessarie le seguenti autorizzazioni:

  • Per abilitare PITR durante la creazione di un database: datastore.databases.create
  • Per aggiornare le impostazioni PITR sul database esistente: datastore.databases.update,datastore.databases.list
  • Per eseguire letture dai dati PITR: datastore.databases.get,datastore.entities.get,datastore.entities.list
  • Per esportare i dati PITR: datastore.databases.export
  • Per importare i dati PITR: datastore.databases.import
  • Per clonare un database: datastore.databases.clone

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Prima di iniziare

Prima di iniziare a utilizzare PITR, tieni presente i seguenti punti:

  • Non puoi iniziare a leggere i dati di sette giorni prima immediatamente dopo aver abilitato PITR.
  • Se vuoi abilitare PITR quando crei un database, devi utilizzare il comando gcloud firestore databases create. L'abilitazione di PITR durante la creazione di un database utilizzando la Google Cloud console non è supportata.
  • Firestore con compatibilità MongoDB inizia a conservare le versioni dal momento in cui viene abilitato PITR.
  • Non puoi leggere i dati PITR nella finestra PITR dopo aver disabilitato PITR.
  • Se riabiliti PITR immediatamente dopo averlo disabilitato, i dati PITR precedenti non sono più disponibili. Tutti i dati PITR creati prima della disabilitazione di PITR verranno eliminati dopo la data di scadenza di PITR.
  • Se hai eliminato accidentalmente i dati nell'ultima ora e PITR è disabilitato, puoi ripristinarli abilitando PITR entro un'ora dall'eliminazione.
  • Qualsiasi lettura eseguita sui dati PITR scaduti non riesce.

Abilitare PITR

Prima di utilizzare PITR, abilita la fatturazione per il tuo progetto Google Cloud. Solo i progetti Google Cloud con la fatturazione abilitata possono utilizzare la funzionalità PITR.

Per abilitare PITR per il tuo database:

Console

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

    Vai a Database

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

  3. Nel menu di navigazione, fai clic su Ripristino di emergenza.

  4. Fai clic su Modifica per modificare le impostazioni.

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

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

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

gcloud

Abilita PITR durante la creazione del database con il gcloud firestore databases create e il --enable-ptir comando nel seguente modo:

gcloud firestore databases create\
  --location=LOCATION\
  --database=DATABASE_ID\
  --edition=enterprise\
  --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 nel seguente modo:

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

Sostituisci i valori come segue:

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

Ottenere il periodo di conservazione e l'ora della versione più recente

Console

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

    Vai a Database

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

  3. Nel menu di navigazione, fai clic su Ripristino di emergenza.

  4. Nella sezione Impostazioni, prendi nota di Periodo di conservazione e Ora della versione più recente.

    • Periodo di conservazione: il periodo in cui Firestore con compatibilità MongoDB 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 versione più recente: il timestamp più recente in cui è possibile leggere le versioni precedenti di dati nella finestra PITR. Questo valore viene aggiornato continuamente da Firestore con compatibilità MongoDB 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 nel seguente modo:

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 dati PITR più recenti 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.

Leggere i dati PITR

Puoi leggere i dati PITR utilizzando la sessione di snapshot in vari driver client MongoDB. Imposta un snapshotTimestamp nella sessione. L'esempio seguente utilizza il driver Java MongoDB e una funzionalità simile è disponibile in altri driver:

Java

    var session =
        mongoClient.startSession(ClientSessionOptions.builder().snapshot(true).build());
  session.setSnapshotTimestamp(new BsonTimestamp(seconds, nanos));

  // run a find query with PITR timestamp
  collection.find(session, <filter>).toList();

  // run an aggregation query pipeline with PITR timestamp
  collection.aggregate(session, <aggregation pipeline stages>).toList();

  // run distinct command with PITR timestamp
  collection.distinct(session, <field>, <return value type class>).toList();

In MongoDB, BsonTimestamp è un tipo BSON interno di MongoDB di 64 bit. I primi 32 bit rappresentano i secondi del timestamp dell'epoca e gli ultimi 32 bit rappresentano un conteggio ordinale delle operazioni all'interno di un cluster MongoDB.

In Firestore con compatibilità MongoDB, il timestamp dello snapshot, che utilizza ancora un tipo di valore BsonTimestamp, interpreta i primi 32 bit come secondi del timestamp dell'epoca, ma gli ultimi 32 bit come nanosecondi all'interno del secondo. Tieni presente che non tutti gli snapshot PITR in nanosecondi sono supportati. Sono consentiti i timestamp in microsecondi nell'ultima ora e i timestamp di minuti interi degli ultimi 7 giorni. Per informazioni sui timestamp di lettura supportati, consulta la panoramica del recupero point-in-time (PITR).

Clonare da un database

Puoi clonare un database esistente in un timestamp selezionato in un nuovo database:

  • Il database clonato è un nuovo database che verrà creato nella stessa località del database di origine.

    Per creare un clone, Firestore utilizza i dati di recupero point-in-time (PITR) del database di origine. Il database clonato include tutti i dati e gli indici.

  • Per impostazione predefinita, il database clonato verrà criptato nello stesso modo del database di origine, utilizzando la crittografia predefinita di Google o la crittografia CMEK. Puoi specificare un tipo di crittografia diverso o utilizzare una chiave diversa per la crittografia CMEK.

  • Il timestamp ha una granularità di un minuto e specifica un punto nel tempo nel passato, nel periodo definito dalla finestra PITR:

    • Se PITR è abilitato per il tuo database, seleziona un minuto qualsiasi degli ultimi 7 giorni (o meno se PITR è stato abilitato meno di 7 giorni fa).
    • Se PITR non è abilitato, puoi selezionare un minuto qualsiasi nell'ultima ora.
    • Puoi controllare il timestamp più recente che puoi scegliere nella descrizione del database.

Console

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

    Vai a Database

  2. Fai clic su Visualizza altro nella riga della tabella per il database che vuoi clonare. Fai clic su Clona. Viene visualizzata la finestra di dialogo Crea un clone.

  3. Nella finestra di dialogo Crea un clone, fornisci i parametri per la clonazione del database:

    1. Nel campo Assegna un ID al clone, un ID database per un nuovo database clonato. Questo ID database non deve essere associato a un database esistente.

    2. Nel campo Clona da, seleziona un punto nel tempo da utilizzare per la clonazione. L'ora selezionata corrisponde a un timestamp PITR, con granularità al minuto.

  4. Fai clic su Crea clone.

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 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 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 a cui eseguire il binding.

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

Esportare e importare da dati PITR

Puoi esportare il database in Cloud Storage dai dati PITR utilizzando il gcloud firestore export comando. Puoi esportare i dati PITR in cui il timestamp è un timestamp di un minuto intero negli ultimi sette giorni, ma non prima di earliestVersionTime. Se i dati non esistono più al timestamp specificato, l'operazione di esportazione non riesce.

L'operazione di esportazione PITR supporta tutti i filtri, inclusa l'esportazione di tutti i documenti e l'esportazione di raccolte specifiche.

  1. Esporta il database, specificando il parametro snapshot-time nel timestamp di recupero scelto.

    gcloud

    Esegui il comando seguente per esportare il database nel bucket. 

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

    Sostituisci quanto segue:

    • BUCKET_NAME_PATH - un bucket Cloud Storage valido con un prefisso di percorso facoltativo in cui vengono archiviati i file di esportazione.
    • PITR_TIMESTAMP - un timestamp PITR con granularità al minuto, ad esempio 2023-05-26T10:20:00.00Z o 2023-10-19T10:30:00.00-07:00.
    • COLLECTION_IDS - un elenco di ID raccolta o ID gruppo di raccolte, ad esempio 'specific-collection-group1','specific-collection-group2'.

    Prima di esportare i dati PITR, tieni presente i seguenti punti:

    • Specifica il timestamp nel formato RFC 3339. Ad esempio, 2023-05-26T10:20:00.00Z o 2023-10-19T10:30:00.00-07:00.
    • Assicurati che il timestamp specificato sia un timestamp di un minuto intero negli ultimi sette giorni, ma non prima di earliestVersionTime. Se i dati non esistono più al timestamp specificato, viene generato un errore. Il timestamp deve essere un minuto intero, anche se l'ora specificata è nell'ultima ora.
    • Non ti vengono addebitati costi per un'esportazione PITR non riuscita.

  2. Importa in un database.

    Segui i passaggi descritti in Importare tutti i documenti per importare il database esportato. Se un documento esiste già nel database, verrà sovrascritto.