Back up and restore databases using the gcloud CLI

This page describes how to use Spanner backup and restore with the Google Cloud CLI.

Prerequisites

The examples in this page make the following assumptions:

  • You have already set up gcloud CLI for use with Spanner. If you are new to using Google Cloud CLI with Spanner, see Getting started with Spanner using Google Cloud CLI.

  • You have configured Google Cloud CLI with a default project. For example:

    gcloud config set core/project my-project
    
  • You have an instance named test-instance and a database named example-db.

Create a backup

To create a backup named example-db-backup-6 and have it expire in 1 year, use gcloud spanner backups create:

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

Here are some usage notes:

  • To set the backup's expiration date, specify either the --retention-period or --expiration-date flag. For information on date syntax , see gcloud topic datetimes.
  • The backup's name must be unique in the instance.
  • The command returns immediately because of the --async flag. Without the flag, the command will wait for the backup operation to complete.
  • Specify the --help flag to get help for any command.

    The output looks similar to the following:

    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.
    

    To check the progress of a backup operation, see Check the operation progress.

Copy a backup

To copy a backup to a different instance in the same project:

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

To copy a backup to a different instance in a different project:

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

Usage notes:

  • If you choose to copy the backup to a different instance in the same project, you must create a new instance (or have one ready) for the copied backup. In the previous example, backup-instance is used. You are not able to create a new instance as part of the backup copy operation.
  • If you choose to copy the backup to a different project, you must have another project with its own instance ready for the copied backup. In the previous example, backup-project is used. You are not able to create a new project as part of the backup copy operation.
  • Expiration time of the backup must be at least six hours from the time the current copy request is processed and at most 366 days after the source backup create_time.

The output looks similar to the following:

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'

To check the progress of a copy operation, see Check the operation progress.

Restore a database from a backup

To restore a database, 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

Usage notes:

  • The command returns immediately because of the --async flag. Without the flag, the command will wait for the restore operation to complete.
  • If the source and destination instances are different, they must have the same instance configuration.
  • If the destination database already exists, the operation will fail.

The output looks similar to the following:

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

To track the progress of a restore operation, see Check the operation progress.

Check the operation progress

Use gcloud spanner operations describe to check the progress of an operation.

  1. Get the operation ID:

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

    Replace the following:

    • INSTANCE-NAME with the Spanner instance name.
    • DATABASE-NAME with the name of the database.

    Usage notes:

    • To limit the list, specify the --filter flag. For example:

      • --filter="metadata.name:example-db" only lists the operations on a specific database.
      • --filter="error:*" only lists the backup operations that failed.

      For information on filter syntax, see gcloud topic filters. For information on filtering backup operations, see the filter field in ListBackupOperationsRequest.

    • The --type flag is not case sensitive.

    The output looks similar to the following:

    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. Run gcloud spanner operations describe:

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

    Replace the following:

    • OPERATION-ID: The operation ID of the operation that you want to check.
    • INSTANCE-NAME: The Spanner instance name.
    • BACKUP-NAME: The Spanner backup name.

    The progress section in the output shows the percentage of the operation that's complete. The output looks similar to the following:

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

If the operation takes too long, you can cancel it. For more information, see Cancel a long-running backup operation.

Get backup information

To get information about a backup:

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

The output looks similar to the following:

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

For more details about this command, see gcloud spanner backups describe.

List backups

To list all the backups in an instance:

gcloud spanner backups list --instance=test-instance

The output looks similar to the following:

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

To limit the list, specify the --filter flag. For example --filter="state:creating" lists just the backups that are still being created. For information on filter syntax, see gcloud topic filters. For information on filtering backups, see the filter field in ListBackupsRequest.

For more details about this command, see gcloud spanner backups list.

Update backup metadata

To update a backup's expiration date:

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

The output looks similar to the following:

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

For more details about this command, see gcloud spanner backups update-metadata.

Delete backup

To delete a backup:

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

You must confirm the operation:

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

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

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

For more details about this command, see gcloud spanner backups delete.