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