Trabajar con la recuperación de un momento determinado (PITR)

Trabajar con la recuperación de un momento determinado (PITR)

En esta página, se describe cómo usar la recuperación de un momento determinado (PITR) para retener y recuperar datos en Firestore con compatibilidad con MongoDB.

Para comprender los conceptos de la PITR, consulta Recuperación de un momento determinado.

Permisos

Para obtener los permisos que necesitas para administrar la configuración de la PITR, pídele a tu administrador que te otorgue el rol de IAM de Propietario de Cloud Datastore (roles/datastore.owner) en el proyecto cuya configuración de la PITR quieres habilitar. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para administrar la configuración de la PITR. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para administrar la configuración de la PITR:

• Para habilitar la PITR cuando creas una base de datos, haz lo siguiente: datastore.databases.create
• Para actualizar la configuración de la PITR en una base de datos existente, sigue estos pasos: datastore.databases.update,datastore.databases.list
• Para realizar lecturas desde datos de la PITR: datastore.databases.get,datastore.entities.get,datastore.entities.list
• Para exportar datos de la PITR, sigue estos pasos: datastore.databases.export
• Para importar datos de la PITR, sigue estos pasos: datastore.databases.import
• Para clonar una base de datos, haz lo siguiente: datastore.databases.clone

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Antes de comenzar

Ten en cuenta los siguientes puntos antes de comenzar a usar la PITR:

• No puedes comenzar a leer desde siete días en el pasado inmediatamente después de habilitar la PITR.
• Si quieres habilitar la PITR cuando creas una base de datos, debes usar el comando gcloud firestore databases create. No se admite la habilitación de la PITR mientras se crea una base de datos con la consola de Google Cloud .
• Firestore con compatibilidad con MongoDB comienza a retener versiones a partir de un momento después de habilitar la PITR.
• No puedes leer los datos de la PITR en la ventana de la PITR después de inhabilitarla.
• Si vuelves a habilitar la PITR inmediatamente después de inhabilitarla, los datos de la PITR anteriores ya no estarán disponibles. Cualquier dato de la PITR creado antes de inhabilitar la PITR se borrará después de la fecha de vencimiento de la PITR.
• Si borraste datos de forma accidental en la última hora y la PITR está inhabilitada, puedes habilitar la PITR dentro de la hora posterior a la eliminación para restablecer los datos.
• Cualquier lectura realizada en datos de PITR vencidos falla.

Habilita la PITR

Antes de usar la PITR, habilita la facturación para tu proyecto de Google Cloud. Solo los proyectos de Google Cloud que tengan la facturación habilitada pueden usar la funcionalidad de la PITR.

Sigue estos pasos para habilitar la PITR en tu base de datos:

Console

1. En la consola de Google Cloud , ve a la página Bases de datos.

   Ir a Bases de datos

2. Selecciona la base de datos requerida de la lista.

3. En el menú de navegación, haga clic en Recuperación ante desastres.

4. Haz clic en Editar para editar la configuración.

5. Selecciona la casilla de verificación Habilitar la recuperación de un momento determinado y, luego, haz clic en Guardar.

Habilitar la PITR genera costos de almacenamiento. Consulta Precios para obtener más información.

Para inhabilitar la PITR, desmarca la casilla de verificación Habilitar la recuperación de un momento determinado de la página Recuperación ante desastres en la Google Cloud consola.

gcloud

Habilita la PITR durante la creación de la base de datos con los comandos gcloud firestore databases create y --enable-ptir de la siguiente manera:

gcloud firestore databases create\
  --location=LOCATION\
  --database=DATABASE_ID\
  --edition=enterprise\
  --enable-pitr

Reemplaza los valores de la siguiente manera:

• LOCATION: La ubicación en la que quieres crear tu base de datos.
• DATABASE_ID: Se establece en un ID de base de datos.

Puedes inhabilitar la PITR con el comando gcloud firestore databases update de la siguiente manera:

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

Reemplaza los valores de la siguiente manera:

• DATABASE_ID: Se establece en el ID de la base de datos o en “(predeterminado)”.

Obtén el período de retención y la fecha de la versión más antigua

Console

1. En la consola de Google Cloud , ve a la página Bases de datos.

   Ir a Bases de datos

2. Selecciona la base de datos requerida de la lista.

3. En el menú de navegación, haga clic en Recuperación ante desastres.

4. En la sección Configuración, observa el Período de retención y la Fecha de la versión más antigua.

   • Período de retención: Es el período en el que Firestore con compatibilidad con MongoDB retiene todas las versiones de los datos de la base de datos. El valor es una hora cuando la PITR está inhabilitada y siete días cuando está habilitada.
   • Fecha de la versión más antigua: Es la primera marca de tiempo en la que se pueden leer las versiones anteriores de los datos en la ventana de PITR. Firestore con compatibilidad con MongoDB actualiza este valor de forma continua y se vuelve inactivo en el momento en que se consulta. Si usas este valor para recuperar datos, asegúrate de tener en cuenta el tiempo desde el momento en que se consulta el valor hasta el momento en que inicias la recuperación.
   • Recuperación de un momento determinado: Muestra Enabled si la PITR está habilitada. Si la PITR está inhabilitada, verás Disabled.

gcloud

Ejecuta el comando gcloud firestore databases describe de la siguiente manera:

gcloud firestore databases describe --database=DATABASE_ID

Reemplaza DATABASE_ID por el ID de la base de datos o '(default)'.

Esta es la salida:

    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

En este ejemplo:

• earliestVersionTime: La marca de tiempo de los primeros datos de PITR almacenados.
• pointInTimeRecoveryEnablement: Muestra POINT_IN_TIME_RECOVERY_ENABLED si la PITR está habilitada. Si la PITR está inhabilitada, verás POINT_IN_TIME_RECOVERY_DISABLED o es posible que no se muestre el campo pointInTimeRecoveryEnablement.
• versionRetentionPeriod: Período en milisegundos para el que se retienen los datos de la PITR. El valor puede ser de una hora cuando la PITR está inhabilitada o de siete días si la PITR está habilitada.

Lee datos de la PITR

Puedes leer los datos de PITR con la sesión de instantánea en varios controladores de cliente de MongoDB. Establece un snapshotTimestamp en la sesión. En el siguiente ejemplo, se usa el controlador de Java de MongoDB, y una función similar está disponible en otros controladores:

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

Nota: Firestore interpreta la marca de tiempo de la instantánea de manera diferente a MongoDB.

A excepción de esta diferencia, Firestore con compatibilidad con MongoDB admite esta función del controlador de cliente de MongoDB y no requiere que uses un cliente no estándar para acceder a tu base de datos.

En MongoDB, BsonTimestamp es un tipo BSON interno de MongoDB de 64 bits. Los primeros 32 bits representan la marca de tiempo de época en segundos, y los últimos 32 bits representan un recuento ordinal de operaciones dentro de un clúster de MongoDB.

En Firestore con compatibilidad con MongoDB, la marca de tiempo de la instantánea, que aún usa un tipo de valor BsonTimestamp, interpreta los primeros 32 bits como segundos de la marca de tiempo de la época, pero los últimos 32 bits como nanosegundos dentro del segundo. Ten en cuenta que no se admiten todas las instantáneas de PITR en nanosegundos. Se permiten marcas de tiempo de microsegundos de la última hora y marcas de tiempo de minutos enteros de los últimos 7 días. Consulta la descripción general de la recuperación de un momento determinado (PITR) para conocer las marcas de tiempo de lectura admitidas.

Clona desde una base de datos

Vista previa — Database cloning

Esta función está sujeta a las "Condiciones de la oferta de la fase previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles "sin modificaciones" y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Puedes clonar una base de datos existente en una marca de tiempo seleccionada en una base de datos nueva:

• La base de datos clonada es una base de datos nueva que se creará en la misma ubicación que la base de datos fuente.

  Para crear un clon, Firestore usa datos de recuperación de un momento determinado (PITR) de la base de datos de origen. La base de datos clonada incluye todos los datos y los índices.

• De forma predeterminada, la base de datos clonada se encriptará de la misma manera que la base de datos de origen, ya sea con la encriptación predeterminada de Google o con la encriptación de CMEK. Puedes especificar un tipo de encriptación diferente o usar una clave diferente para la encriptación con CMEK.

• La marca de tiempo tiene una granularidad de un minuto y especifica un punto en el tiempo pasado, en el período definido por la ventana de PITR:

  • Si la PITR está habilitada para tu base de datos, puedes seleccionar cualquier minuto de los últimos 7 días (o menos si la PITR se habilitó hace menos de 7 días).
  • Si la PITR no está habilitada, puedes seleccionar cualquier minuto de la última hora.
  • Puedes consultar la marca de tiempo más antigua que puedes elegir en la descripción de tu base de datos.

Nota: Para clonar bases de datos, tu Cuenta de Google debe tener el permiso de IAM datastore.databases.clone.

Console

1. En la consola de Google Cloud , ve a la página Bases de datos.

   Ir a Bases de datos

2. Haz clic en Ver más en la fila de la tabla de la base de datos que quieras clonar. Haz clic en Clonar. Aparecerá el diálogo Crear una clonación.

3. En el diálogo Crear una clonación, proporciona parámetros para clonar la base de datos:

   1. En el campo Asigna un ID a la clonación, se muestra un ID de base de datos para una nueva base de datos clonada. Este ID de base de datos no debe estar asociado a una base de datos existente.

   2. En el campo Clonar desde, selecciona un momento para usarlo en la clonación. La hora seleccionada corresponde a una marca de tiempo de la PITR, en el nivel de detalle por minuto.

4. Haz clic en Crear clon.

Nota: La base de datos clonada tendrá la misma configuración de encriptación que la base de datos de origen. Si deseas especificar una configuración de encriptación diferente para la base de datos clonada, puedes usar comandos de Google Cloud CLI.

gcloud

Usa el comando gcloud alpha firestore databases clone para clonar una base de datos:

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

Reemplaza lo siguiente:

• SOURCE_DATABASE: Es el nombre de la base de datos existente que quieres clonar. El nombre utiliza el formato projects/PROJECT_ID/databases/SOURCE_DATABASE_ID.

• PITR_TIMESTAMP: Es una marca de tiempo de PITR en el formato RFC 3339, con un nivel de detalle por minuto. Por ejemplo, 2025-06-01T10:20:00.00Z, 2025-06-01T10:30:00.00-07:00 o .

• DESTINATION_DATABASE_ID: Es un ID de base de datos para una base de datos clonada nueva. Este ID de base de datos no debe estar asociado a una base de datos existente.

Ejemplo:

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

Cambia la configuración de encriptación de la base de datos clonada

De forma predeterminada, la base de datos clonada tendrá la misma configuración de encriptación que la base de datos de origen. Para cambiar la configuración de encriptación, usa el argumento --encryption-type:

• (Predeterminado) use-source-encryption: Usa la misma configuración de encriptación que la base de datos de origen.
• Usar la encriptación predeterminada de Google
• customer-managed-encryption: Usa la encriptación con CMEK. Especifica un ID de clave en el argumento --kms-key-name.

En el siguiente ejemplo, se muestra cómo configurar el CMEK para la base de datos clonada:

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='projects/example-project/databases/example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

Importa y exporta datos de PITR

Puedes exportar tu base de datos a Cloud Storage desde datos de PITR coherentes con el comando gcloud firestore export. Puedes exportar datos de PITR en los que la marca de tiempo sea una de un minuto completo dentro de los últimos siete días, pero no antes que la earliestVersionTime. Si los datos ya no existen en la marca de tiempo especificada, fallará la operación de exportación.

La operación de exportación de la PITR admite todos los filtros, incluida la exportación de todos los documentos y la exportación de colecciones específicas.

1. Exporta la base de datos y especifica el parámetro snapshot-time en la marca de tiempo de recuperación elegida.

   gcloud

   Ejecuta el siguiente comando para exportar la base de datos a tu bucket.

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

   Reemplaza lo siguiente:

   • BUCKET_NAME_PATH: Un bucket de Cloud Storage válido con un prefijo de ruta de acceso opcional en el que se almacenan los archivos de exportación.
   • PITR_TIMESTAMP: Es una marca de tiempo de la PITR en el nivel de detalle por minuto, por ejemplo, 2023-05-26T10:20:00.00Z o 2023-10-19T10:30:00.00-07:00.
   • COLLECTION_IDS: Una lista de los IDs de colección o de grupos de colecciones, por ejemplo, 'specific-collection-group1','specific-collection-group2'.

   Ten en cuenta los siguientes puntos antes de exportar los datos de la PITR:

   • Especifica la marca de tiempo en formato RFC 3339. Por ejemplo, 2023-05-26T10:20:00.00Z o 2023-10-19T10:30:00.00-07:00.
   • Asegúrate de que la marca de tiempo que especifiques sea de un minuto completo en los últimos siete días, pero no antes de la earliestVersionTime. Si los datos ya no existen en la marca de tiempo especificada, se generará un error. La marca de tiempo debe ser un minuto entero, incluso si la hora especificada corresponde a la última hora.
   • No se te cobra por una exportación de la PITR con errores.

2. Importa a una base de datos

   Sigue los pasos que se indican en Importa todos los documentos para importar la base de datos exportada. Si ya existe un documento en tu base de datos, se reemplazará.