Trabalhar com recuperação pontual (PITR)

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

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ê o papel do IAM de Proprietário do Cloud Datastore (roles/datastore.owner) no projeto em que você quer ativar as configurações da PITR. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para gerenciar as configurações de PITR. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para gerenciar as configurações de PITR:

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

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

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. A ativação da PITR ao criar um banco de dados usando o console do Google Cloud não é compatível.
  • O Firestore 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:

Console

  1. No Console do Google Cloud, acesse a página Bancos de Dados.

    Acessar "Bancos de dados"

  2. Selecione o banco de dados necessário na lista de bancos de dados.

  3. No menu de navegação, clique em Recuperação de desastres.

  4. Clique em Editar para editar as configurações.

  5. Marque a caixa de seleção Ativar recuperação pontual e clique em Salvar.

A ativação da PITR incorre em custos de armazenamento. Para mais informações, consulte Preços.

Para desativar a PITR, desmarque a caixa de seleção Ativar recuperação pontual na página "Recuperação de desastres" do console do Google Cloud.

gcloud

Ative a PITR durante a criação do banco de dados com o comando gcloud firestore databases create da seguinte maneira:

gcloud firestore databases create\
  --location=LOCATION\
  [--database=DATABASE_ID; default="(default)"]\
  [--type=TYPE; default="firestore-native"]\
  --enable-pitr

Substitua os valores da seguinte forma:

  • Location: local em que você quer criar o banco de dados.
  • DATABASE_ID: definido como o ID do banco de dados ou (padrão).
  • TYPE: definido como firestore-native.

É possível desativar a PITR usando o comando gcloud firestore databases update da seguinte maneira:

gcloud firestore databases update\
  [--database=DATABASE_ID; default="(default)"]\
  --no-enable-pitr

Substitua os valores da seguinte forma:

  • DATABASE_ID: definido como o ID do banco de dados ou (padrão).

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

Console

  1. No Console do Google Cloud, acesse a página Bancos de Dados.

    Acessar "Bancos de dados"

  2. Selecione o banco de dados necessário na lista de bancos de dados.

  3. No menu de navegação, clique em Recuperação de desastres.

  4. Na seção Configurações, anote o Período de retenção e o Horário da versão mais antiga.

    • Período de retenção: o período em que o Firestore retém todas as versões de dados do banco de dados. O valor é de uma hora quando a PITR está desativada e de sete dias quando a PITR está ativada.
    • Horário da versão mais antigo: o carimbo de data/hora mais antigo em que as versões mais antigas dos dados podem ser lidas na janela da PITR. Este valor é atualizado continuamente pelo Firestore e fica obsoleto no momento em que é consultado. Se você estiver usando esse valor para recuperar dados, não deixe de considerar o momento entre o momento em que o valor é consultado e o momento em que você inicia a recuperação.
    • Recuperação pontual: mostra Enabled se a PITR estiver ativada. Se a PITR estiver desativada, você verá Disabled.

gcloud

Execute o comando gcloud firestore database describe da seguinte maneira:

gcloud firestore databases describe --database=DATABASE_ID

Substitua DATABASE_ID pelo ID do banco de dados ou default.

Esta é a saída:

    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/(default)
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: FIRESTORE_NATIVE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

Em que:

  • earliestVersionTime: carimbo de data/hora dos dados da PITR mais antigos armazenados.
  • pointInTimeRecoveryEnablement: mostra POINT_IN_TIME_RECOVERY_ENABLED, se a PITR estiver ativada. Se a PITR estiver desativada, você verá POINT_IN_TIME_RECOVERY_DISABLED ou o campo pointInTimeRecoveryEnablement pode não ser exibido.
  • versionRetentionPeriod: período em que os dados da PITR são retidos em milissegundos. O valor pode ser uma hora quando a PITR estiver desativada ou sete dias se a PITR estiver ativada.

Ler dados da PITR

Leia dados da PITR usando as bibliotecas de cliente, os métodos da API REST ou o conector do FirestoreIO Apache Beam.

Bibliotecas de cliente

Java

Use a transação ReadOnly para ler dados PITR. Não é possível especificar diretamente readTime em leituras. Consulte Transações e gravações em lote para mais informações.

  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ó

Use uma transação ReadOnly para ler dados PITR. Não é possível especificar diretamente readTime em leituras. Consulte Transações e gravações em lote para mais informações.

  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

As leituras PITR têm suporte em todos os métodos de leitura do Firestore, que são get, list, batchGet, listCollectionIds, listDocuments, runQuery, runAggregationQuery e partitionQuery.

Para realizar uma leitura usando os métodos REST, tente uma das seguintes opções:

  1. Na solicitação do método de leitura, transmita o valor readTime como um carimbo de data/hora da PITR compatível no método readOptions. Um carimbo de data/hora da PITR pode ser um carimbo de precisão de microssegundos na última hora ou um carimbo de data/hora de um minuto inteiro além da última hora, mas não antes da earliestVersionTime.

  2. Use o parâmetro readTime com o método BeginTransaction como parte de uma transação ReadOnly para várias leituras de PITR.

Apache Beam

Use o conector Apache Beam do FirestoreIO para ler ou gravar documentos em um banco de dados do Firestore em grande escala com o Dataflow.

As leituras da PITR são compatíveis com o seguinte método de leitura do conector do FirestoreIO. Esses métodos de leitura são compatíveis com o método withReadTime(@Nullable Instant readTime) que você pode usar para leituras da PITR:

Java

O código a seguir pode ser usado com o exemplo de código de pipeline do Dataflow para operações de leitura ou gravação em massa. O exemplo usa o método withReadTime(@Nullable Instant readTime) para leituras da 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())
  ...

Para uma lista completa de exemplos de readTime no pipeline do Dataflow, consulte o repositório do GitHub.

Exportar e importar dados da PITR

É possível exportar seu banco de dados para o Cloud Storage de dados PITR consistentes 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 desejado.

    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 válido do Cloud Storage 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.