Fazer backup e restaurar bancos de dados usando a CLI gcloud

Nesta página, descrevemos como usar o backup e restauração do Spanner com a Google Cloud CLI.

Pré-requisitos

Os exemplos nesta página fazem as seguintes suposições:

• Você já configurou a CLI gcloud para uso com o Spanner. Se você é iniciante no uso da Google Cloud CLI com o Spanner, consulte Primeiros passos com o Spanner usando a Google Cloud CLI.

• Você configurou a Google Cloud CLI com um projeto padrão. Exemplo:

  gcloud config set core/project my-project

• Você já tem uma instância chamada test-instance e um banco de dados chamado example-db.

Criar backup

Para criar um backup chamado example-db-backup-6 e que ele expire em um ano, use gcloud spanner backups create:

   gcloud spanner backups create example-db-backup-6 --instance=test-instance \
      --database=example-db --retention-period=1y --async

Veja algumas observações de uso:

• Para definir a data de validade do backup, especifique a sinalização --retention-period ou --expiration-date. Para informações sobre a sintaxe de datas , consulte gcloud topic datetimes.
• O nome do backup precisa ser exclusivo na instância.
• O comando retorna imediatamente por causa da sinalização --async. Sem a sinalização, o comando vai aguardar a conclusão da operação de backup.

• Especifique a sinalização --help para receber ajuda para qualquer comando.

  A resposta será semelhante a:

  Create request issued for: [example-db-backup-6]
  Check operation [projects/my-project/instances/test-instance/backups/example-db-backup-6/operations/_auto_op_234567] for status.
  

  Para verificar o andamento de uma operação de backup, consulte Verificar o progresso da operação.

Copiar um backup

Para copiar um backup para uma instância diferente no mesmo projeto:

gcloud spanner backups copy \
    --source-instance=test-instance \
    --source-backup=example-db \
    --destination-instance=backup-instance \
    --destination-backup=copied-backup \
    --expiration-date=2022-03-30T10:49:41Z

Para copiar um backup para uma instância diferente em um projeto diferente:

gcloud spanner backups copy \
  --source-backup=projects/my-project/instances/test-instance/backups/example-db \
  --destination-backup=projects/backup-project/instances/backup-instance-eu/backups/copied-backup \
  --expiration-date=2022-03-30T10:49:41Z

Observações de uso:

• Se você optar por copiar o backup para uma instância diferente no mesmo projeto, crie uma nova instância (ou tenha uma pronta) para o backup copiado. No exemplo anterior, backup-instance é usado. Não é possível criar uma nova instância como parte da operação de cópia de backup.
• Se você optar por copiar o backup para um projeto diferente, será necessário ter outro projeto com a própria instância pronto para o backup copiado. No exemplo anterior, backup-project é usado. Não é possível criar um novo projeto como parte da operação de cópia de backup.
• O prazo de validade do backup precisa ser de pelo menos seis horas a partir do momento em que a solicitação de cópia atual é processada e no máximo 366 dias após o create_time do backup de origem.

A resposta será semelhante a:

createTime: '2022-03-29T22:06:05.905823Z'
database: projects/my-project/instances/test-instance/databases/example-db
databaseDialect: GOOGLE_STANDARD_SQL
encryptionInfo:
  encryptionType: GOOGLE_DEFAULT_ENCRYPTION
expireTime: '2022-03-30T10:49:41Z'
maxExpireTime: '2023-03-17T20:46:33.479336Z'
name: projects/backup-project/instances/backup-instance-eu/backups/copied-backup
sizeBytes: '7957667'
state: READY
versionTime: '2022-03-16T20:46:33.479336Z'

Para verificar o progresso de uma operação de cópia, consulte Verificar o progresso da operação.

Restaurar um banco de dados a partir de um backup

Para restaurar um banco de dados, use gcloud spanner databases restore:

gcloud spanner databases restore --async \
    --destination-instance=test-instance --destination-database=example-db-restored \
    --source-instance=test-instance --source-backup=example-db-backup-6

Observações de uso:

• O comando retorna imediatamente por causa da sinalização --async. Sem a sinalização, o comando aguardará a conclusão da operação de restauração.
• Se as instâncias de origem e de destino forem diferentes, elas precisarão ter a mesma configuração de instância.
• Se o banco de dados de destino já existir, a operação falhará.

A resposta será semelhante a:

Restore database in progress. Operation name=projects/my-project/instances/test-instance/databases/example-db-restored-1/operations/_auto_op_bb8e360b256b04bf

Para acompanhar o progresso de uma operação de restauração, consulte Verificar o progresso da operação.

Verificar o progresso da operação

Use gcloud spanner operations describe para verificar o progresso de uma operação.

1. Consiga o ID da operação:

   gcloud spanner operations list --instance=INSTANCE-NAME \
   --database=DATABASE-NAME --type=BACKUP

   Substitua:

   • INSTANCE-NAME pelo nome da instância do Spanner.
   • DATABASE-NAME pelo nome do banco de dados.

   Observações de uso:

   • Para limitar a lista, especifique a sinalização --filter. Exemplo:

     • --filter="metadata.name:example-db" lista apenas as operações em um banco de dados específico.
     • --filter="error:*" lista apenas as operações de backup que falharam.

     Para informações sobre a sintaxe do filtro, consulte gcloud topic filtros. Para informações sobre como filtrar operações de backup, consulte o campo filter em ListBackupOperationsRequest.

   • A sinalização --type não diferencia maiúsculas de minúsculas.

   A resposta será semelhante a:

   OPERATION_ID               DONE  @TYPE                 BACKUP               SOURCE_DATABASE  START_TIME                   END_TIME
   _auto_op_123456  True  CreateBackupMetadata  example-db-backup-7  example-db       2020-02-04T02:12:38.075515Z  2020-02-04T02:22:40.581170Z
   _auto_op_234567  True  CreateBackupMetadata  example-db-backup-6  example-db       2020-02-04T02:05:43.920377Z  2020-02-04T02:07:59.089820Z
     ```
   

2. Execute gcloud spanner operations describe:

   gcloud spanner operations describe OPERATION-ID \
   --instance=INSTANCE-NAME \
   --backup=BACKUP-NAME \

   Substitua:

   • OPERATION-ID: o ID da operação que você quer verificar.
   • INSTANCE-NAME: o nome da instância do Spanner.
   • BACKUP-NAME: o nome do backup do Spanner.

   A seção progress na saída mostra a porcentagem da operação concluída. A resposta será semelhante a:

   done: true
   metadata:
   ...
   progress:
   - endTime: '2022-03-01T00:28:06.691403Z'
     progressPercent: 100
     startTime: '2022-03-01T00:28:04.221401Z'
   - endTime: '2022-03-01T00:28:17.624588Z'
     startTime: '2022-03-01T00:28:06.691403Z'
     progressPercent: 100
   ...

Se a operação demorar muito, será possível cancelá-la. Para mais informações, consulte Cancelar uma operação de backup de longa duração.

Receber informações de backup

Para receber informações sobre um backup:

gcloud spanner backups describe example-db-backup-6 --instance=test-instance

A resposta será semelhante a:

createTime: '2020-02-04T02:05:43.920377Z'
database: projects/my-project/instances/test-instance/databases/example-db
expireTime: '2021-02-04T02:05:43.268327Z'
name: projects/my-project/instances/test-instance/backups/example-db-backup-6
sizeBytes: '1000000000'
state: READY

Para mais detalhes sobre esse comando, consulte gcloud spanner backups describe.

Listar backups

Para listar todos os backups em uma instância:

gcloud spanner backups list --instance=test-instance

A resposta será semelhante a:

BACKUP               SOURCE_DATABASE  CREATION_TIME                EXPIRATION_TIME              STATE  BACKUP_SIZE_IN_BYTES  IN_USE_BY
example-db-backup-6  example-db       2020-02-04T02:05:43.920377Z  2021-02-04T02:05:43.268327Z  CREATING
example-db-backup-4  example-db       2020-02-04T01:21:20.873839Z  2021-02-04T01:21:20.530151Z  READY  32
example-db-backup-3  example-db       2020-02-03T23:59:18.936433Z  2021-02-03T23:59:18.203083Z  READY  32
example-db-backup-5  example-db       2020-02-03T23:48:06.259296Z  2021-02-03T23:48:05.830937Z  READY  32
example-db-backup-2  example-db       2020-01-30T19:49:00.616338Z  2021-01-30T19:49:00.283917Z  READY  32
example-db-backup-1  example-db       2020-01-30T19:47:09.492551Z  2021-01-30T19:47:09.097804Z  READY  32

Para limitar a lista, especifique a sinalização --filter. Por exemplo, --filter="state:creating" lista apenas os backups que ainda estão sendo criados. Para informações sobre a sintaxe do filtro, consulte gcloud topic filtros. Para informações sobre como filtrar backups, consulte o campo filter em ListBackupsRequest.

Para mais detalhes sobre esse comando, consulte gcloud spanner backups list.

Atualizar metadados de backup

Para atualizar a data de validade de um backup:

gcloud spanner backups update-metadata example-db-backup-6 \
    --instance=test-instance --expiration-date=2020-05-05T00:00:00Z

A resposta será semelhante a:

createTime: '2020-02-04T02:05:43.920377Z'
database: projects/my-project/instances/test-instance/databases/example-db
expireTime: '2020-05-05T00:00:00Z'
name: projects/my-project/instances/test-instance/backups/example-db-backup-6
sizeBytes: '1000000000'
state: READY

Para mais detalhes sobre esse comando, consulte gcloud spanner backups update-metadata.

Excluir backup

Para excluir um backup:

gcloud spanner backups delete example-db-backup-1 --instance=test-instance

Confirme a operação:

You are about to delete backup [example-db-backup-1]

Do you want to continue (Y/n)?  Y

Deleted backup [example-db-backup-1].

Para mais detalhes sobre esse comando, consulte gcloud spanner backups delete.