Utiliser la récupération à un moment précis (PITR)

Cette page explique comment utiliser la récupération à un moment précis (PITR) pour conserver et récupérer des données dans Cloud Firestore.

Pour comprendre les concepts de la récupération PITR, consultez la section Récupération à un moment précis.

Autorisations

Pour obtenir les autorisations nécessaires pour gérer les paramètres de la récupération PITR, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet dans lequel vous souhaitez activer la récupération PITR :

• Propriétaire Cloud Datastore (roles/datastore.owner)

Pour les rôles personnalisés, assurez-vous que les autorisations suivantes sont accordées :

• Pour activer la récupération PITR lors de la création d'une base de données : datastore.databases.create
• Pour mettre à jour les paramètres de la récupération PITR dans une base de données existante : datastore.databases.update,datastore.databases.list
• Pour effectuer des lectures à partir de données de récupération PITR : datastore.databases.get,datastore.entities.get,datastore.entities.list
• Pour exporter des données de récupération PITR : datastore.databases.export
• Pour importer des données de récupération PITR : datastore.databases.import
• Pour cloner une base de données : datastore.databases.clone

Avant de commencer

Avant de commencer à utiliser la récupération PITR, tenez compte des points suivants :

• Vous ne pouvez pas commencer à lire les données des sept derniers jours immédiatement après avoir activé la récupération PITR.
• Si vous souhaitez activer la récupération PITR lorsque vous créez une base de données, vous devez utiliser la gcloud firestore databases create commande. L'activation de la récupération PITR lors de la création d'une base de données à l'aide de la console Google Cloud n'est pas prise en charge.
• Cloud Firestore commence à conserver les versions à partir du moment où la récupération PITR est activée.
• Vous ne pouvez pas lire les données de récupération PITR dans la fenêtre de récupération PITR après avoir désactivé la récupération PITR.
• Si vous réactivez la récupération PITR immédiatement après l'avoir désactivée, les données de récupération PITR précédentes ne sont plus disponibles. Toutes les données de récupération PITR créées avant la désactivation de la récupération PITR seront supprimées après la date d'expiration de la récupération PITR.
• Si vous avez supprimé des données par erreur au cours de la dernière heure et que la récupération PITR est désactivée, vous pouvez restaurer vos données en activant la récupération PITR dans l'heure suivant la suppression.
• Toute lecture effectuée sur des données de récupération PITR expirées échoue.

Activer la récupération PITR

Avant d'utiliser la récupération PITR, activez la facturation pour votre projet Google Cloud. Seuls les projets Google Cloud pour lesquels la facturation est activée peuvent utiliser la fonctionnalité de récupération PITR.

Pour activer la récupération PITR pour votre base de données :

Console

1. Dans la console Google Cloud, accédez à la page Bases de données.

   Accéder à la page "Bases de données"

2. Sélectionnez la base de données requise dans la liste des bases de données.

3. Dans le menu de navigation, cliquez sur Reprise après sinistre.

4. Cliquez sur Modifier pour modifier les paramètres.

5. Cochez la case Activer la récupération à un moment précis, puis cliquez sur Enregistrer.

L'activation de la récupération PITR entraîne des frais de stockage. Consultez la page Tarifs pour en savoir plus.

Pour désactiver la récupération PITR, décochez la case Activer la récupération à un moment précis sur la page "Reprise après sinistre" de la console Google Cloud.

gcloud

Activez la récupération PITR lors de la création de la base de données avec le gcloud firestore databases create et la commande --enable-ptir, comme suit :

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

Remplacez les valeurs comme suit :

• LOCATION : emplacement où vous souhaitez créer votre base de données.
• DATABASE_ID : défini sur un ID de base de données.

Vous pouvez désactiver la récupération PITR à l'aide de la gcloud firestore databases update commande, comme suit :

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

Remplacez les valeurs comme suit :

• DATABASE_ID : défini sur l'ID de la base de données ou `'(default)'` (valeur par défaut).

Obtenir la durée de conservation et la date de la première version

Console

1. Dans la console Google Cloud, accédez à la page Bases de données.

   Accéder à la page "Bases de données"

2. Sélectionnez la base de données requise dans la liste des bases de données.

3. Dans le menu de navigation, cliquez sur Reprise après sinistre.

4. Dans la section Paramètres, notez la Durée de conservation et la Date de la première version.

   • Durée de conservation : période pendant laquelle Cloud Firestore conserve toutes les versions des données de la base de données. La valeur est d'une heure lorsque la récupération PITR est désactivée et de sept jours lorsqu'elle est activée.
   • Date de la première version : code temporel le plus ancien à partir duquel les anciennes versions de données peuvent être lues dans la fenêtre de récupération PITR. Cette valeur est mise à jour en continu par Cloud Firestore et devient obsolète au moment où elle est interrogée. Si vous utilisez cette valeur pour récupérer des données, veillez à tenir compte du moment où la valeur est interrogée jusqu'au moment où vous lancez la récupération.
   • Récupération à un moment précis : affiche Enabled si la récupération PITR est activée. Si la récupération PITR est désactivée, vous verrez Disabled.

gcloud

Exécutez la commande gcloud firestore databases describe comme suit :

gcloud firestore databases describe --database=DATABASE_ID

Remplacez DATABASE_ID par l'ID de la base de données ou '(default)'.

Voici le résultat :

    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

où :

• earliestVersionTime : code temporel des données de récupération PITR les plus anciennes stockées.
• pointInTimeRecoveryEnablement : affiche POINT_IN_TIME_RECOVERY_ENABLED si la récupération PITR est activée. Si la récupération PITR est désactivée, vous verrez soit POINT_IN_TIME_RECOVERY_DISABLED ou le pointInTimeRecoveryEnablement champ pourrait ne pas être affiché.
• versionRetentionPeriod : période pendant laquelle les données de récupération PITR sont conservées en millisecondes. La valeur peut être d'une heure lorsque la récupération PITR est désactivée ou de sept jours lorsqu'elle est activée.

Lire les données de récupération PITR

Vous pouvez lire les données de récupération PITR à l'aide des bibliothèques clientes, des méthodes de l'API REST ou du connecteur FirestoreIO Apache Beam.

Bibliothèques clientes

Remarque : Vous pouvez lire les données de récupération PITR dans les bibliothèques clientes du serveur, à savoir Go, Java, Node.js et PHP. Les SDK Web et mobiles, à savoir Android, iOS et Web, ne sont pas compatibles.

Java

Vous devez utiliser la transaction ReadOnly pour lire les données de récupération PITR. Vous ne pouvez pas spécifier directement readTime dans les lectures. Pour en savoir plus, consultez la section Transactions et écritures par lots.

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

Nœud

Vous devez utiliser une transaction ReadOnly pour lire les données de récupération PITR. Vous ne pouvez pas spécifier directement readTime dans les lectures. Pour en savoir plus, consultez la section Transactions et écritures par lots.

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

Les lectures de récupération PITR sont compatibles avec toutes les méthodes de lecture Cloud Firestore, à savoir get, list, batchGet, listCollectionIds, listDocuments, runQuery, runAggregationQuery, et partitionQuery.

Pour effectuer une lecture à l'aide des méthodes REST, essayez l'une des options suivantes :

1. Dans votre requête de méthode de lecture, transmettez la valeur readTime en tant que code temporel de récupération PITR compatible dans la méthode readOptions. Un code temporel de récupération PITR peut être un code temporel de précision en microsecondes au cours de la dernière heure ou un code temporel d'une minute entière au-delà de la dernière heure, mais pas avant le earliestVersionTime.

2. Utilisez le paramètre readTime avec la méthode BeginTransaction dans le cadre d'une transaction ReadOnly pour plusieurs lectures de récupération PITR.

Apache Beam

Utilisez le connecteur Cloud FirestoreIO Apache Beam pour lire ou écrire des documents à grande échelle dans une base de données Cloud Firestore avec Dataflow.

Les lectures de récupération PITR sont compatibles avec la méthode de lecture suivante du Cloud FirestoreIO connector. Ces méthodes de lecture sont compatibles avec la méthode withReadTime(@Nullable Instant readTime) que vous pouvez utiliser pour les lectures de récupération PITR :

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

• FirestoreV1.RunQuery

Java

Le code suivant peut être utilisé avec l'exemple de code de pipeline Dataflow pour les opérations de lecture ou d'écriture groupées. L'exemple utilise la méthode withReadTime(@Nullable Instant readTime) pour les lectures de récupération PITR.

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

Pour obtenir la liste complète des readTime exemples dans le pipeline Dataflow, consultez le dépôt GitHub.

Cloner à partir d'une base de données

Vous pouvez cloner une base de données existante à un code temporel sélectionné dans une nouvelle base de données :

• La base de données clonée est une nouvelle base de données qui sera créée au même emplacement que la base de données source.

  Pour créer un clone, Cloud Firestore utilise les données de récupération à un moment précis (PITR) de la base de données source. La base de données clonée inclut toutes les données et tous les index.

• Par défaut, la base de données clonée sera chiffrée de la même manière que la base de données source, à l'aide du chiffrement par défaut de Google ou du chiffrement CMEK. Vous pouvez spécifier un autre type de chiffrement ou utiliser une autre clé pour le chiffrement CMEK.

• Le code temporel a une précision d'une minute et spécifie un moment dans le passé, au cours de la période définie par la fenêtre de récupération PITR :

  • Si la récupération PITR est activée pour votre base de données, vous pouvez sélectionner n'importe quelle minute au cours des sept derniers jours (ou moins si la récupération PITR a été activée il y a moins de sept jours).
  • Si la récupération PITR n'est pas activée, vous pouvez sélectionner n'importe quelle minute au cours de la dernière heure.
  • Vous pouvez vérifier le code temporel le plus ancien que vous pouvez choisir dans la description de votre base de données.

Remarque : Pour cloner des bases de données, votre compte Google doit disposer de l'autorisation IAM datastore.databases.clone.

Console

Firebase console n'est pas compatible avec le clonage de bases de données. Vous pouvez utiliser les instructions pour Google Cloud CLI pour cloner des bases de données.

Remarque : La base de données clonée aura la même configuration de chiffrement que la base de données source. Si vous souhaitez spécifier une configuration de chiffrement différente pour la base de données clonée, vous pouvez utiliser les commandes.

Google Cloud CLI

gcloud

Utilisez la gcloud firestore databases clone commande pour cloner une base de données :

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

Remplacez les éléments suivants :

• SOURCE_DATABASE : nom de base de données d'une base de données existante que vous souhaitez cloner. Le nom utilise le format projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

• PITR_TIMESTAMP : code temporel de récupération PITR au format RFC 3339, avec une précision d'une minute. Par exemple : 2025-06-01T10:20:00.00Z ou 2025-06-01T10:30:00.00-07:00.

• DESTINATION_DATABASE_ID : ID de base de données pour une nouvelle base de données clonée. Cet ID de base de données ne doit pas être associé à une base de données existante.

Exemple :

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

Si vous souhaitez lier des tags lors du clonage d'une base de données, utilisez la commande précédente avec l'option --tags, qui est une liste facultative de paires de tags KEY=VALUE à lier.

Exemple :

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

Par défaut, la base de données clonée aura la même configuration de chiffrement que la base de données source. Pour modifier la configuration de chiffrement, utilisez l' --encryption-type argument :

• (Par défaut) use-source-encryption : utilise la même configuration de chiffrement que la base de données source.
• google-default-encryption : utilise le chiffrement par défaut de Google.
• customer-managed-encryption : utilise le chiffrement CMEK. Spécifiez un ID de clé dans l'argument --kms-key-name.

L'exemple suivant montre comment configurer le chiffrement CMEK pour la base de données clonée :

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'

CLI Firebase

Utilisez la commande firebase firestore:databases:clone pour cloner une base de données :

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

Remplacez les éléments suivants :

• SOURCE_DATABASE : nom de base de données d'une base de données existante que vous souhaitez cloner. Le nom utilise le format projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

• DESTINATION_DATABASE : nom de base de données pour une nouvelle base de données clonée. Le nom utilise le format projects/PROJECT_ID/databases/DESTINATION_DATABASE_ID. Ce nom de base de données ne doit pas être associé à une base de données existante.

• PITR_TIMESTAMP : code temporel de récupération PITR au format RFC 3339, avec une précision d'une minute. Par exemple : 2025-06-01T10:20:00.00Z ou 2025-06-01T10:30:00.00-07:00. Si aucune valeur n'est spécifiée, l'instantané choisi correspond à l'heure actuelle, arrondie à la minute inférieure.

Par défaut, la base de données clonée aura la même configuration de chiffrement que la base de données source. Pour modifier la configuration de chiffrement, utilisez l' --encryption-type argument :

• (Par défaut) USE_SOURCE_ENCRYPTION : utilise la même configuration de chiffrement que la base de données source.
• GOOGLE_DEFAULT_ENCRYPTION : utilise le chiffrement par défaut de Google.
• CUSTOMER_MANAGED_ENCRYPTION : utilise le chiffrement CMEK. Spécifiez un ID de clé dans l'argument --kms-key-name.

L'exemple suivant montre comment configurer le chiffrement CMEK pour la base de données clonée :

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

Limites

Une opération de clonage ne clone pas les App Engine données de recherche ni les entités blob d'une base de données (default). Ces données ne sont valides que pour la base de données (default) et ne sont pas utiles si vous clonez des données de (default) vers une base de données qui n'est pas compatible avec ces données. Elles sont donc exclues des clones.

Exporter et importer des données de récupération PITR

Vous pouvez exporter votre base de données vers Cloud Storage à partir de données de récupération PITR à l'aide de la commande gcloud firestore export. Vous pouvez exporter des données de récupération PITR dont le code temporel est un code temporel d'une minute entière au cours des sept derniers jours, mais pas avant earliestVersionTime. Si les données n'existent plus au code temporel spécifié, l'opération d'exportation échoue.

L'opération d'exportation de récupération PITR est compatible avec tous les filtres, y compris l'exportation de tous les documents et l'exportation de collections spécifiques.

1. Exportez la base de données en spécifiant le snapshot-time paramètre vers le code temporel de récupération choisi.

   gcloud

   Exécutez la commande suivante pour exporter la base de données vers votre bucket.

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

   Où :

   • BUCKET_NAME_PATH : bucket Cloud Storage valide avec un préfixe de chemin facultatif où les fichiers d'exportation sont stockés.
   • PITR_TIMESTAMP : code temporel de récupération PITR avec une précision d'une minute, par exemple 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00.
   • COLLECTION_IDS : liste d'ID de collection ou d'ID de groupe de collections, par exemple 'specific-collection-group1','specific-collection-group2'.
   • NAMESPACE_IDS : liste d'ID d'espace de noms, par exemple 'customer','orders'.

   Avant d'exporter des données de récupération PITR, tenez compte des points suivants :

   • Spécifiez l'horodatage au format RFC 3339 format. Par exemple, 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00.
   • Assurez-vous que le code temporel que vous spécifiez est un code temporel d'une minute entière au cours des sept derniers jours, mais pas avant le earliestVersionTime. Si les données n'existent plus au code temporel spécifié, une erreur est générée. Le code temporel doit être une minute entière, même si l'heure spécifiée se situe au cours de la dernière heure.
   • L'échec d'une exportation de récupération PITR n'est pas facturé.

2. Importez dans une base de données.

   Suivez les étapes décrites dans Importer tous les documents pour importer votre base de données exportée. Si un document existe déjà dans votre base de données, il sera remplacé.