Trabalhar com recuperação pontual (PITR, na sigla em inglês)

Nesta página, descrevemos como usar a recuperação pontual (PITR, na sigla em inglês) para reter e recuperar dados no Cloud Firestore com compatibilidade com o MongoDB.

Para entender os conceitos da PITR, consulte Recuperação pontual.

Permissões

Para receber as permissões necessárias para gerenciar as configurações da PITR, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto em que você quer ativar a PITR:

• Proprietário do Cloud Datastore (roles/datastore.owner)

Para papéis personalizados, verifique se as seguintes permissões foram concedidas:

• Para ativar a PITR ao criar um banco de dados: datastore.databases.create
• Para atualizar as configurações da PITR no banco de dados: datastore.databases.update,datastore.databases.list
• Para realizar leituras de dados PITR: datastore.databases.get,datastore.entities.get,datastore.entities.list
• Para exportar dados PITR: datastore.databases.export
• Para importar dados PITR: datastore.databases.import
• Para clonar um banco de dados: datastore.databases.clone

Antes de começar

Observe os seguintes pontos antes de começar a usar a PITR:

• Não é possível iniciar leituras de sete dias anteriores imediatamente depois de ativar a PITR.
• Se você quiser ativar a PITR ao criar um banco de dados, use o comando gcloud firestore databases create. Não há suporte para a ativação da PITR ao criar um banco de dados usando o console do Google Cloud.
• O Cloud Firestore com compatibilidade com o MongoDB começa a reter versões a partir do ponto depois de ativar a PITR.
• Não é possível ler dados PITR na janela PITR depois de desativar a PITR.
• Se você reativar a PITR imediatamente após desativá-la, os dados da PITR anteriores não estarão mais disponíveis. Os dados da PITR criados antes da desativação serão excluídos após a data de validade.
• Se você excluiu dados acidentalmente na última hora e a PITR está desativada, é possível restaurar seus dados ativando a PITR dentro de uma hora após a exclusão.
• Qualquer leitura realizada em dados PITR expirados falha.

Ativar a PITR

Antes de usar a PITR, ative o faturamento do projeto do Google Cloud. Somente projetos do Google Cloud com faturamento ativado podem usar a funcionalidade PITR.

Para ativar a PITR no banco de dados:

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

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

Conseguir o período de armazenamento e o horário da versão mais antiga

gcloud firestore databases describe --database=DATABASE_ID

    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

Ler dados da PITR

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

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

Clonar de um banco de dados

É possível clonar um banco de dados existente em um carimbo de data/hora selecionado para um novo banco de dados:

• O banco de dados clonado é um novo banco de dados que será criado no mesmo local do banco de dados de origem.

  Para criar um clone, o Cloud Firestore usa dados de recuperação pontual (PITR) do banco de dados de origem. O banco de dados clonado inclui todos os dados e índices.

• Por padrão, o banco de dados clonado será criptografado da mesma forma que o banco de dados de origem, usando a criptografia padrão do Google ou CMEK. É possível especificar um tipo de criptografia diferente ou usar outra chave para a criptografia CMEK.

• O carimbo de data/hora tem uma granularidade de um minuto e especifica um ponto no tempo no passado, no período definido pela janela de PITR:

  • Se a PITR estiver ativada para seu banco de dados, selecione qualquer minuto nos últimos sete dias (ou menos, se a PITR foi ativada há menos de sete dias).
  • Se a PITR não estiver ativada, você poderá selecionar qualquer minuto na última hora.
  • Você pode verificar o carimbo de data/hora mais antigo que pode escolher na descrição do seu banco de dados.

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

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

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

Limitações

Uma operação de clonagem não clona dados de pesquisa do App Engine nem entidades de blob de um banco de dados (default). Esses dados são válidos apenas para o banco de dados (default) e não serão úteis se você clonar do (default) para um banco de dados que não oferece suporte a eles. Por isso, eles são excluídos das clonagens.

Exportar e importar dados da PITR

É possível exportar seu banco de dados para o banco de dados do Cloud Storage a partir dos dados da PITR usando o comando gcloud firestore export. É possível exportar dados PITR em que o carimbo de data/hora é um minuto inteiro nos últimos sete dias, mas não anterior ao earliestVersionTime. Se os dados não existirem mais no carimbo de data/hora especificado, a operação de exportação falhará.

A operação de exportação da PITR oferece suporte a todos os filtros, incluindo a exportação de todos os documentos e a exportação de coleções específicas.

1. Exporte o banco de dados, especificando o parâmetro snapshot-time para o carimbo de data/hora de recuperação escolhido.

   gcloud

   Execute o comando a seguir para exportar o banco de dados para o bucket.

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

   Em que,

   • BUCKET_NAME_PATH: um bucket do Cloud Storage válido com um prefixo de caminho opcional em que os arquivos de exportação são armazenados.
   • PITR_TIMESTAMP: um carimbo de data/hora da PITR na granularidade de minutos, por exemplo, 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00.
   • COLLECTION_IDS: uma lista de IDs de coleções ou de grupos de coleções, por exemplo, 'specific-collection-group1','specific-collection-group2'.
   • NAMESPACE_IDS: uma lista de IDs de namespace, por exemplo, 'customer','orders'.

   Observe os seguintes pontos antes de exportar dados PITR:

   • Especifique o carimbo de data/hora no formato RFC 3339. Por exemplo, 2023-05-26T10:20:00.00Z ou 2023-10-19T10:30:00.00-07:00.
   • Verifique se o carimbo de data/hora especificado é de um minuto inteiro nas últimas 7 horas, mas não antes do earliestVersionTime. Se os dados não existirem mais no carimbo de data/hora especificado, será gerado um erro. O carimbo de data/hora precisa ser um minuto inteiro, mesmo que o horário especificado seja anterior à hora anterior.
   • Você não vai receber cobranças por uma falha na exportação da PITR.

2. Importar para um banco de dados.

   Use as etapas em Importar todos os documentos para importar seu banco de dados exportado. Se algum documento já existir no seu banco de dados, ele será substituído.