Trabalhar com recuperação pontual (PITR)

Esta página descreve como usar a recuperação pontual (PITR) para reter e recuperar dados no Cloud Firestore.

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

Permissões

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

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

Para funções personalizadas, certifique-se de que as seguintes permissões sejam concedidas:

  • Para ativar o PITR ao criar um banco de dados: datastore.databases.create
  • Para atualizar as configurações de PITR no banco de dados existente: 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

Antes de você começar

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

  • Você não pode começar a ler sete dias atrás imediatamente após ativar o PITR.
  • Se quiser ativar o PITR ao criar um banco de dados, você deverá usar o comando gcloud firestore databases create . Não há suporte para ativar o PITR ao criar um banco de dados usando o Console do GCP.
  • O Cloud Firestore começa a reter versões a partir do momento em que ativa o PITR.
  • Você não pode ler dados PITR na janela PITR depois de desativar o PITR.
  • Se você reativar o PITR imediatamente após desativá-lo, os dados anteriores do PITR não estarão mais disponíveis. Quaisquer dados PITR criados antes da desativação do PITR serão excluídos após a data de expiração do PITR.
  • Se você excluiu dados acidentalmente na última hora e o PITR está desativado, você pode restaurar seus dados ativando o PITR dentro de uma hora após a exclusão.
  • Qualquer leitura realizada em dados PITR expirados falhará.

Habilitar PITR

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

Para habilitar o PITR para seu banco de dados:

Console

  1. No console do Google Cloud Platform, acesse a página Bancos de dados .

    Vá para 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 Habilitar recuperação pontual e clique em Salvar .

A ativação do PITR incorreria em custos de armazenamento. Consulte Preços para obter mais informações.

Para desativar o PITR, desmarque a caixa de seleção Habilitar recuperação pontual na página Recuperação de desastres no Console do GCP.

gcloud

Ative o 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 onde você deseja criar seu banco de dados.
  • DATABASE_ID - definido como o ID do banco de dados ou (padrão).
  • TYPE - definido como nativo do firestore.

Você pode desativar o 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).

Obtenha o período de retenção e o horário da versão mais antiga

Console

  1. No console do Google Cloud Platform, acesse a página Bancos de dados .

    Vá para 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 , observe o Período de retenção e o Tempo da versão mais antiga .

    • Período de retenção : o período em que o Cloud Firestore retém todas as versões dos dados do banco de dados. O valor é de uma hora quando o PITR está desabilitado e de sete dias quando o PITR está habilitado.
    • Hora da versão mais antiga : o carimbo de data/hora mais antigo em que versões mais antigas dos dados podem ser lidas na janela PITR. Esse valor é atualizado continuamente pelo Cloud Firestore e se torna obsoleto no momento em que é consultado. Se você estiver usando esse valor para recuperar dados, leve em consideração o tempo desde o momento em que o valor é consultado até o momento em que você inicia a recuperação.
    • Recuperação pontual : mostra Enabled , se o PITR estiver ativado. Se o PITR estiver desabilitado, você verá Disabled .

gcloud

Execute o comando gcloud firestore databases description da seguinte maneira:

gcloud firestore databases describe --database=DATABASE_ID

Substitua DATABASE_ID pelo ID do banco de dados ou default .

Aqui está o resultado:

    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

onde,

  • earliestVersionTime - carimbo de data/hora dos primeiros dados PITR armazenados.
  • pointInTimeRecoveryEnablement : mostra POINT_IN_TIME_RECOVERY_ENABLED , se PITR estiver habilitado. Se o PITR estiver desabilitado, você verá POINT_IN_TIME_RECOVERY_DISABLED ou o campo pointInTimeRecoveryEnablement poderá não ser exibido.
  • versionRetentionPeriod - período de tempo durante o qual os dados PITR são retidos em milissegundos. O valor pode ser uma hora quando o PITR estiver desabilitado ou sete dias se o PITR estiver habilitado.

Ler dados PITR

Você pode ler dados PITR usando as bibliotecas de cliente, os métodos da API REST ou o conector FirestoreIO Apache Beam.

Bibliotecas de cliente

Java

Você deve usar a transação ReadOnly para ler dados PITR. Você não pode especificar readTime diretamente nas leituras. Consulte Transações e gravações em lote para obter 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ó

Você deve usar uma transação ReadOnly para ler dados PITR. Você não pode especificar readTime diretamente nas leituras. Consulte Transações e gravações em lote para obter 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 são compatíveis com todos os métodos de leitura do Cloud Firestore, que são get , list , batchGet , listCollectionIds , listDocuments , runQuery , runAggregationQuery e partiçãoQuery .

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

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

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

Feixe Apache

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

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

Java

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

Exportar e importar de dados PITR

Você pode exportar seu banco de dados para o Cloud Storage a partir de dados PITR usando o comando gcloud firestore export . Você pode exportar dados PITR em que o carimbo de data/hora é um carimbo de data/hora de um minuto inteiro nos últimos sete dias, mas não antes do 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 PITR suporta 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 seu bucket.

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

    Onde,

    • BUCKET_NAME_PATH : um intervalo válido do Cloud Storage com um prefixo de caminho opcional onde os arquivos de exportação são armazenados.
    • PITR_TIMESTAMP - um carimbo de data/hora PITR na granularidade de minuto, 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ção ou IDs de grupo de coleção, 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 .
    • Certifique-se de que o carimbo de data/hora especificado seja um carimbo de data/hora de um minuto inteiro dos últimos sete dias, mas não anterior ao earliestVersionTime . Se os dados não existirem mais no carimbo de data/hora especificado, um erro será gerado. O carimbo de data/hora deve ser um minuto inteiro, mesmo que o horário especificado esteja na última hora.
    • Você não será cobrado por uma falha na exportação de PITR.

  2. Importe para um banco de dados.

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