Usar recuperação pontual (PITR)

Nesta página, descrevemos como usar a recuperação pontual (PITR, na sigla em inglês) para restaurar a instância principal do Cloud SQL.

Para saber mais sobre a PITR, consulte este link.

Por padrão, a PITR é ativada quando você cria uma instância do Cloud SQL edição Enterprise Plus, independentemente se você criar a instância usando o console do Google Cloud, a gcloud CLI, o Terraform ou a API Cloud SQL Admin.

Se você criar uma instância do Cloud SQL edição Enterprise no console do Google Cloud, a PITR será ativada por padrão. Caso contrário, se você criar a instância usando a gcloud CLI, o Terraform ou a API Cloud SQL Admin, será necessário ativar a PITR manualmente.

Armazenamento de registros para PITR

O Cloud SQL usa o arquivamento de registro prévio de escrita (WAL) para PITR.

Em 9 de janeiro de 2023, lançamos o armazenamento de registros prévios de escrita para PITR no Cloud Storage. Desde este lançamento, estas condições se aplicam:

  • Todas as instâncias da edição Cloud SQL Enterprise Plus armazenam os registros prévios de escrita no Cloud Storage. Apenas as instâncias da edição Cloud SQL Enterprise Plus que você fez upgrade da edição Cloud SQL Enterprise e ativou a PITR antes de 9 de janeiro de 2023 continuam armazenando registros no disco.
  • As instâncias da edição Cloud SQL Enterprise criadas com a PITR ativada antes de 9 de janeiro de 2023 continuam armazenando os registros no disco.
  • Todas as instâncias da edição Cloud SQL Enterprise criadas com a PITR ativada após 9 de janeiro de 2023 armazenam registros no Cloud Storage.

Para instâncias que armazenam registros de gravação antecipada apenas no disco, é possível mover os registros do disco para o Cloud Storage desativando e depois reativando a PITR.

Período de armazenamento de registros

Para ver se uma instância armazena os registros usados para a PITR no Cloud Storage, use Verificar o local de armazenamento dos registros de transações usados para a PITR.

Depois de usar um cliente PostgreSQL, como psql ou pgAdmin, para se conectar a um banco de dados da instância, execute o comando show archive_command: Se algum registro prévio de escrita for arquivado no Cloud Storage, você verá -async_archive -remote_storage.

Todas as outras instâncias atuais com a PITR ativada continuam com os registros armazenados no disco. A alteração para armazenar registros no Cloud Storage estará disponível posteriormente.

Se os registros estiverem armazenados no Cloud Storage, serão enviados pelo Cloud SQL a cada cinco minutos ou menos. Como resultado, se uma instância do Cloud SQL estiver disponível, ela poderá ser recuperada para o horário mais recente. No entanto, se a instância não estiver disponível, o objetivo do ponto de recuperação normalmente será de cinco minutos ou menos. Use a CLI gcloud ou a API Admin para verificar o momento mais recente em que é possível restaurar a instância e executar a recuperação para esse momento.

Os registros de gravação antecipada usados com a PITR são excluídos automaticamente com o backup automático associado, o que geralmente acontece após o valor definido para transactionLogRetentionDays for atendida. Esse é o número de dias de registros de transação que o Cloud SQL mantém para a PITR. Para a edição Cloud SQL Enterprise Plus, o número de dias de registros de transação retidos pode ser definido de 1 a 35 e, para a edição Cloud SQL Enterprise, o valor pode ser definido de 1 a 7.

Ao restaurar um backup em uma instância do Cloud SQL antes de ativar a PITR, você perde os registros de gravação antecipada que permitem a operabilidade da PITR.

Para instâncias ativadas por chave de criptografia gerenciada pelo cliente (CMEK, na sigla em inglês), os registros de gravação antecipada são criptografados usando a versão mais recente da CMEK. Para realizar uma restauração, todas as versões da chave que foram as mais recentes para o número de dias que você configurou para o parâmetro retained-transaction-log-days estarão disponíveis.

Para as instâncias que têm registros de gravação antecipada no Cloud Storage, os registros são armazenados na mesma região da instância principal. Esse armazenamento de registros (até 35 dias para o Cloud SQL Enterprise Plus e sete dias para o Cloud SQL Enterprise, a duração máxima para a PITR) não gera custo extra por instância.

Registros e uso do disco

Se a instância tiver a PITR ativada e o tamanho dos registros prévios de escrita no disco estiver causando um problema na instância:

  • É possível desativar a PITR e reativá-la para garantir que os novos registros sejam armazenados no Cloud Storage na mesma região da instância. No entanto, os registros de gravação antecipada existentes são excluídos. Portanto, não é possível executar uma restauração pontual antes do momento em que você reativou a PITR.

  • É possível aumentar o tamanho do armazenamento da instância, mas o aumento no tamanho do registro write-ahead no uso do disco pode ser temporário.

  • Recomendamos que você ative o aumento automático de armazenamento para evitar problemas de armazenamento inesperados. Essa recomendação se aplica somente se a instância tiver a PITR ativada e seus registros estiverem armazenados no disco.

  • Desative a PITR se quiser excluir registros e recuperar o armazenamento. A redução dos registros de gravação antecipada usados não diminui o tamanho do disco provisionado para a instância.

  • Os registros são limpados uma vez por dia, e não continuamente. Configurar a retenção de registros para dois dias significa que no mínimo dois dias de registros, e no máximo três, serão mantidos. Recomendamos que você defina o número de backups como sendo maior do que o número de dias de retenção de registros. Dessa forma, é possível garantir um mínimo de dias especificados para a retenção.

Ativar a PITR

Quando você cria uma instância no Console do Google Cloud, as opções Backups automatizados e Ativar a recuperação pontual são ativadas automaticamente.

O procedimento a seguir ativa a PITR em uma instância principal existente.

Console

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse "Instâncias do Cloud SQL"

  2. Abra o menu de mais ações Ícone mais ações. da instância em que você quer ativar a PITR e clique em Editar.
  3. Em Personalizar sua instância, expanda a seção Proteção de dados.
  4. Marque a caixa de seleção Ativar recuperação pontual.
  5. Expanda Opções avançadas.
  6. Digite o número de dias em que os registros serão retidos, de 1 a 35 para a edição do Cloud SQL Enterprise Plus ou de 1 a 7 para a edição do Cloud SQL Enterprise.
  7. Clique em Save.

gcloud

  1. Exiba a visão geral da instância: 
    gcloud sql instances describe INSTANCE_NAME
  2. Se você vir enabled: false na seção backupConfiguration, ative os backups programados: 
    gcloud sql instances patch INSTANCE_NAME \
--backup-start-time=HH:MM

    Especifique o parâmetro backup-start-time usando o horário de 24 horas no fuso horário UTC±00.

  3. Ative a PITR: 
    gcloud sql instances patch INSTANCE_NAME \
--enable-point-in-time-recovery

    Se você estiver ativando a PITR em uma instância principal, também poderá configurar o número de dias para manter os registros de transações adicionando o seguinte parâmetro:

    --retained-transaction-log-days=RETAINED_TRANSACTION_LOG_DAYS
  4. Confirme a mudança: 
    gcloud sql instances describe INSTANCE_NAME

    Quando a operação é realizada, é exibido pointInTimeRecoveryEnabled: true na seção backupConfiguration.

Terraform

Para ativar a PITR, use um recurso do Terraform. 

resource "google_sql_database_instance" "postgres_instance_pitr" {
  name             = ""
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
    backup_configuration {
      enabled                        = true
      point_in_time_recovery_enabled = true
      start_time                     = "20:55"
      transaction_log_retention_days = "3"
    }
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Aplique as alterações

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

    Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

  1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

    Copie o exemplo de código no main.tf recém-criado.

    Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

  3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
  4. Salve as alterações.
  5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório. 
    terraform init

    Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade: 

    terraform init -upgrade

Aplique as alterações

  1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas: 
    terraform plan

    Faça as correções necessárias na configuração.

  2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

    Aguarde até que o Terraform exiba a mensagem "Apply complete!".

  3. Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud, navegue até seus recursos na IU para verificar se foram criados ou atualizados pelo Terraform.

Excluir as alterações

Para excluir as mudanças, faça o seguinte:

  1. Para desativar a proteção contra exclusão, no arquivo de configuração do Terraform, defina o argumento deletion_protection como false. 
    deletion_protection =  "false"
  2. Para aplicar a configuração atualizada do Terraform, execute o comando a seguir e digite yes no prompt: 
    terraform apply

  1. Remova os recursos aplicados anteriormente com a configuração do Terraform executando o seguinte comando e inserindo yes no prompt:

    terraform destroy

REST v1

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
  • INSTANCE_NAME: o nome da instância primária ou de réplica de leitura que você está configurando para alta disponibilidade
  • START_TIME: a hora (em horas e minutos)

Método HTTP e URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME

Corpo JSON da solicitação:

{
  "settings":
  {
    "backupConfiguration":
    {
      "startTime": "START_TIME",
      "enabled": true,
      "pointInTimeRecoveryEnabled": true
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

REST v1beta4

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID ou número do projeto do Google Cloud que contém a instância
  • INSTANCE_NAME: o nome da instância primária ou de réplica de leitura que você está configurando para alta disponibilidade
  • START_TIME: a hora (em horas e minutos)

Método HTTP e URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME

Corpo JSON da solicitação:

{
  "settings":
  {
    "backupConfiguration":
    {
      "startTime": "START_TIME",
      "enabled": true,
      "pointInTimeRecoveryEnabled": true
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

Confira o tempo de recuperação mais recente

Para uma instância disponível, execute a PITR para o horário mais recente. Se a instância não estiver disponível e os registros da instância estiverem armazenados no Cloud Storage, recupere o tempo de recuperação mais recente e execute a PITR para esse momento. Em ambos os casos, é possível restaurar a instância em uma zona diferente fornecendo um valor para a zona preferencial.

gcloud

Confira o momento mais recente em que é possível recuperar uma instância do Cloud SQL que não está disponível.

Substitua INSTANCE_NAME pelo nome da instância que você está consultando.

gcloud sql instances get-latest-recovery-time INSTANCE_NAME

REST v1

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto;
  • INSTANCE_NAME: o nome da instância que você está consultando para saber o tempo de recuperação mais recente

Método HTTP e URL: 

GET https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/INSTANCE_NAME/getLatestRecoveryTime

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#getLatestRecoveryTime",
  "latestRecoveryTime": "2023-06-20T17:23:59.648821586Z"
}

REST v1beta4

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto;
  • INSTANCE_NAME: o nome da instância que você está consultando para saber o tempo de recuperação mais recente

Método HTTP e URL: 

GET https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME/getLatestRecoveryTime

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "kind": "sql#getLatestRecoveryTime",
  "latestRecoveryTime": "2023-06-20T17:23:59.648821586Z"
}

Execute o PITR

Console

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse "Instâncias do Cloud SQL"

  2. Abra o menu "Mais ações" Ícone mais ações. para a instância a ser recuperada e clique em Criar clone.
  3. Na página Criar um clone, é possível atualizar o ID do novo clone.
  4. Selecione Clonar de um momento anterior.
  5. Insira um horário de PITR.
  6. Clique em Criar clone.

gcloud

Criar um clone usando a PITR.

Substitua:

  • SOURCE_INSTANCE_NAME: nome da instância de que você está restaurando;
  • NEW_INSTANCE_NAME: nome do clone;
  • TIMESTAMP: fuso horário UTC para a instância de origem no formato RFC 3339. Por exemplo, 2012-11-15T16:19:00.094Z.
gcloud sql instances clone SOURCE_INSTANCE_NAME \
NEW_INSTANCE_NAME \
--point-in-time 'TIMESTAMP'

REST v1

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • project-id: o ID do projeto
  • target-instance-id: o ID da instância de destino
  • source-instance-id: o ID da instância de origem
  • restore-timestamp: o momento em que a restauração será interrompida.

Método HTTP e URL:

POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/source-instance-id/clone

Corpo JSON da solicitação:

{
  "cloneContext":
  {
    "kind": "sql#cloneContext",
    "destinationInstanceName": "target-instance-id",
    "pointInTime": "restore-timestamp"
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

REST v1beta4

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • project-id: o ID do projeto
  • target-instance-id: o ID da instância de destino
  • source-instance-id: o ID da instância de origem
  • restore-timestamp: o momento em que a restauração será interrompida.

Método HTTP e URL:

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/source-instance-id/clone

Corpo JSON da solicitação:

{
  "cloneContext":
  {
    "kind": "sql#cloneContext",
    "destinationInstanceName": "target-instance-id",
    "pointInTime": "restore-timestamp"
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

Desativar PITR

Console

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse "Instâncias do Cloud SQL"

  2. Abra o menu "Mais ações" Ícone mais ações. para a instância a ser desativada e selecione Editar.
  3. Em Personalizar sua instância, expanda a seção Proteção de dados.
  4. Desmarque a opção Ativar recuperação pontual.
  5. Clique em Salvar.
  6. Na página Visão geral da instância, em Configuração, a configuração da PITR é listada como desativada.

gcloud

  1. Desative a recuperação pontual: 
    gcloud sql instances patch INSTANCE_NAME \
--no-enable-point-in-time-recovery
  2. Confirme a alteração:
    gcloud sql instances describe INSTANCE_NAME

    Quando a operação é realizada, é exibido pointInTimeRecoveryEnabled: false na seção backupConfiguration.

REST v1

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • project-id: o ID do projeto
  • instance-id: o ID da instância

Método HTTP e URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Corpo JSON da solicitação:

{
  "settings":
  {
    "backupConfiguration":
    {
      "enabled": false,
      "pointInTimeRecoveryEnabled": false
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

REST v1beta4

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • project-id: o ID do projeto
  • instance-id: o ID da instância

Método HTTP e URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Corpo JSON da solicitação:

{
  "settings":
  {
    "backupConfiguration":
    {
      "enabled": false,
      "pointInTimeRecoveryEnabled": false
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

Verificar o local de armazenamento dos registros de transações usados para a PITR

É possível verificar onde sua instância do Cloud SQL está armazenando os registros de transações usados para a PITR.

gcloud

Para determinar se a instância armazena registros para a PITR no disco ou no Cloud Storage, use o seguinte comando:

   gcloud sql instances describe INSTANCE_NAME

Substitua INSTANCE_NAME pelo nome da instância.

Na saída do comando, o campo transactionalLogStorageState mostra informações sobre onde os registros de transações da PITR são armazenados para a instância. Os estados de armazenamento de registros de transações possíveis são estes:

  • DISK: a instância armazena os registros de transação usados para a PITR no disco.
  • CLOUD_STORAGE: a instância armazena os registros de transações usados para a PITR no Cloud Storage.

Definir a retenção do registro de transações

Para definir o número de dias em que os registros de gravação antecipada serão guardados:

Console

  1. No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

    Acesse "Instâncias do Cloud SQL"

  2. Abra o menu "Mais ações" Ícone mais ações. para a instância em que você quer definir o registro das transações e selecione Editar.
  3. Em Personalizar sua instância, expanda a seção Proteção de dados.
  4. Na seção Ativar recuperação pontual, expanda Opções avançadas.
  5. Digite o número de dias em que os registros serão retidos, de 1 a 35 para a edição do Cloud SQL Enterprise Plus ou de 1 a 7 para a edição do Cloud SQL Enterprise.
  6. Clique em Save.

gcloud

Edite a instância para definir o número de dias de retenção dos registros em tempo de gravação:

Substitua:

  • INSTANCE-NAME: o nome da instância em que você quer definir o registro de transações;
  • DAYS-TO-RETAIN: o número de dias de registros de transações a serem mantidos. Para o Cloud SQL edição Enterprise Plus, o intervalo válido é de 1 a 35 dias, com um padrão de 14 dias. Para o Cloud SQL edição Enterprise, o intervalo válido é de um a sete dias, com um padrão de sete dias. Se nenhum valor for especificado, o valor padrão será usado. Só é válido quando a PITR está ativada. A especificação de mais dias de registros de transações requer um tamanho de armazenamento maior. 

  gcloud sql instances patch INSTANCE-NAME \
    --retained-transaction-log-days=DAYS-TO-RETAIN

REST v1

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • days-to-retain: o número de dias para armazenar registros de transação, de 1 a 7
  • project-id: o ID do projeto
  • instance-id: o ID da instância

Método HTTP e URL: 

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

Corpo JSON da solicitação:

{
  "settings":
  {
    "backupConfiguration":
    {
      "transactionLogRetentionDays": "days-to-retain"
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

REST v1beta4

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • days-to-retain: o número de dias para armazenar registros de transação, de 1 a 7
  • project-id: o ID do projeto
  • instance-id: o ID da instância

Método HTTP e URL: 

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

Corpo JSON da solicitação:

{
  "settings":
  {
    "backupConfiguration":
    {
      "transactionLogRetentionDays": "days-to-retain"
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

A seguir