This page offers information about Spanner backup operations. For more information about backups, see Backups overview.
Before you begin
-
To get the permissions that you need to manage backups, ask your administrator to grant you the following IAM roles on the instance:
-
Create, view, update, and delete backups:
Cloud Spanner Backup Admin (
roles/spanner.backupAdmin
) -
Create and view backups:
Cloud Spanner Backup Writer (
roles/spanner.backupWriter
)
-
Create, view, update, and delete backups:
Cloud Spanner Backup Admin (
The gcloud CLI examples on this page make the following assumptions:
- You have already set up gcloud CLI for use with Spanner. If you are new to using gcloud CLI with Spanner, see Getting started with Spanner using gcloud CLI.
You have configured gcloud CLI with your project. For example:
gcloud config set core/project PROJECT_ID
Copy a backup
Console
In the Google Cloud console, go to the Spanner Instances page.
Click the instance that contains the database that you want to copy.
Click the database.
In the navigation pane, click Backup/Restore.
In the Backups table, select Actions for your backup and click Copy.
Fill out the form by choosing a destination instance, providing a name, and selecting an expiration date for the backup copy.
Click Copy.
To check the progress of a copy operation, see Check the operation progress.
If the operation takes too long, you can cancel it. For more information, see Cancel a long-running instance operation.
gcloud
You can copy a backup to a different instance in the same project, or to a different instance in a different project.
Copy a backup in the same project
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. You
can't create a new instance as part of the backup copy operation. Also, the
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 create_time
of the source backup.
Before using any of the command data below, make the following replacements:
- PROJECT_ID: the project ID.
- SOURCE_INSTANCE_ID: the source Spanner instance ID.
- SOURCE_DATABASE_ID: the source Spanner database ID.
- SOURCE_BACKUP_NAME: the Spanner backup name.
- DESTINATION_INSTANCE_ID: the target Spanner instance ID.
- DESTINATION_BACKUP_NAME: the destination Spanner backup name.
- EXPIRATION_DATE: the expiration date time stamp.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud spanner backups copy \ --source-instance=INSTANCE_ID \ --source-backup=SOURCE_BACKUP_NAME \ --destination-instance=DESTINATION_INSTANCE_ID \ --destination-backup=DESTINATION_BACKUP_NAME \ --expiration-date=EXPIRATION_DATE
Windows (PowerShell)
gcloud spanner backups copy ` --source-instance=INSTANCE_ID ` --source-backup=SOURCE_BACKUP_NAME ` --destination-instance=DESTINATION_INSTANCE_ID ` --destination-backup=DESTINATION_BACKUP_NAME ` --expiration-date=EXPIRATION_DATE
Windows (cmd.exe)
gcloud spanner backups copy ^ --source-instance=INSTANCE_ID ^ --source-backup=SOURCE_BACKUP_NAME ^ --destination-instance=DESTINATION_INSTANCE_ID ^ --destination-backup=DESTINATION_BACKUP_NAME ^ --expiration-date=EXPIRATION_DATE
You should receive a response similar to the following:
createTime: '2022-03-29T22:06:05.905823Z' database: projects/PROJECT_ID/instances/INSTANCE_ID/databases/SOURCE_DATABASE_ID databaseDialect: GOOGLE_STANDARD_SQL encryptionInfo: encryptionType: GOOGLE_DEFAULT_ENCRYPTION expireTime: '2022-03-30T10:49:41Z' maxExpireTime: '2023-03-17T20:46:33.479336Z' name: projects/PROJECT_ID/instances/DESTINATION_INSTANCE_ID/backups/DESTINATION_BACKUP_NAME sizeBytes: '7957667' state: READY versionTime: '2022-03-16T20:46:33.479336Z'
Copy a backup in a different project
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. You can't create a
new project as part of the backup copy operation. Also, the
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
.
Before using any of the command data below, make the following replacements:
- SOURCE_PROJECT_ID: the source project ID.
- SOURCE_INSTANCE_ID: the source Spanner instance ID.
- SOURCE_DATABASE_ID: the source Spanner database ID.
- SOURCE_BACKUP_NAME: the Spanner backup name.
- DESTINATION_PROJECT_ID: the destination project ID.
- DESTINATION_INSTANCE_ID: the target Spanner instance ID.
- DESTINATION_BACKUP_NAME: the destination Spanner backup name.
- EXPIRATION_DATE: the expiration date time stamp.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud spanner backups copy \ --source-backup=projects/SOURCE_PROJECT_ID/instances/INSTANCE_ID/backups/SOURCE_BACKUP_NAME \ --destination-backup=projects/DESTINATION_PROJECT_ID/instances/DESTINATION_INSTANCE_ID/backups/DESTINATION_BACKUP_NAME \ --expiration-date=EXPIRATION_DATE
Windows (PowerShell)
gcloud spanner backups copy ` --source-backup=projects/SOURCE_PROJECT_ID/instances/INSTANCE_ID/backups/SOURCE_BACKUP_NAME ` --destination-backup=projects/DESTINATION_PROJECT_ID/instances/DESTINATION_INSTANCE_ID/backups/DESTINATION_BACKUP_NAME ` --expiration-date=EXPIRATION_DATE
Windows (cmd.exe)
gcloud spanner backups copy ^ --source-backup=projects/SOURCE_PROJECT_ID/instances/INSTANCE_ID/backups/SOURCE_BACKUP_NAME ^ --destination-backup=projects/DESTINATION_PROJECT_ID/instances/DESTINATION_INSTANCE_ID/backups/DESTINATION_BACKUP_NAME ^ --expiration-date=EXPIRATION_DATE
You should receive a response similar to the following:
createTime: '2022-03-29T22:06:05.905823Z' database: projects/SOURCE_PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID databaseDialect: GOOGLE_STANDARD_SQL encryptionInfo: encryptionType: GOOGLE_DEFAULT_ENCRYPTION expireTime: '2022-03-30T10:49:41Z' maxExpireTime: '2023-03-17T20:46:33.479336Z' name: projects/DESTINATION_PROJECT_ID/instances/DESTINATION_INSTANCE_ID/backups/DESTINATION_BACKUP_NAME sizeBytes: '7957667' state: READY versionTime: '2022-03-16T20:46:33.479336Z'
To check the progress of a copy operation, see Check the operation progress.
Client libraries
The following code sample copies an existing backup. You can copy the backup
into an instance in a different region or project. Once complete, the sample
retrieves and prints some information about the newly created copied backup,
such as its name, size, backup state, and version_time
.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Check the operation progress
Console
In the Google Cloud console, go to the Spanner Instances page.
Click the instance that contains the database that you want to view the backup operation for.
Click the database.
In the navigation pane, click Operations. The Operations page shows a list of running operations.
gcloud
Use gcloud spanner operations describe
to check the progress of an operation.
Get the operation ID:
Before using any of the command data below, make the following replacements:
- INSTANCE_NAME: the Spanner instance name.
- DATABASE_NAME: the Spanner database name.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud spanner operations list --instance=INSTANCE_NAME \ --database=DATABASE_NAME --type=backup
Windows (PowerShell)
gcloud spanner operations list --instance=INSTANCE_NAME ` --database=DATABASE_NAME --type=backup
Windows (cmd.exe)
gcloud spanner operations list --instance=INSTANCE_NAME ^ --database=DATABASE_NAME --type=backup
You should receive a response 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
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 thefilter
field inListBackupOperationsRequest
.The
--type
flag isn't case sensitive.
Run
gcloud spanner operations describe
:Before using any of the command data below, make the following replacements:
- OPERATION_ID: the operation ID.
- INSTANCE_NAME: the Spanner instance name.
- DATABASE_NAME: the Spanner database name.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud spanner operations describe OPERATION_ID \ --instance=INSTANCE_NAME \ --backup=BACKUP_NAME \
Windows (PowerShell)
gcloud spanner operations describe OPERATION_ID ` --instance=INSTANCE_NAME ` --backup=BACKUP_NAME `
Windows (cmd.exe)
gcloud spanner operations describe OPERATION_ID ^ --instance=INSTANCE_NAME ^ --backup=BACKUP_NAME ^
You should receive a response 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 ...
progress
section in the output shows the percentage of the operation that's complete.If the operation takes too long, you can cancel it. For more information, see Cancel a long-running backup operation.
Client libraries
The following code sample lists all of the ongoing operations for creating backups (operations
with CreateBackupMetadata
) and copying backups
(operations with CopyBackupMetadata
)
filtered by a given database.
For information on filtering syntax, see the filter
parameter in
backupOperations.list
.
C++
C#
To list all the create backup operations:
To list all the copy backup operations:
Go
Java
Node.js
PHP
Python
Ruby
To list all the create backup operations:
To list all the copy backup operations:
Cancel a backup operation
Console
The Google Cloud console doesn't support canceling a backup operation. However, you can cancel operations that take too long using the Google Cloud CLI, REST, or RPC API. For more information, see Cancel a long-running instance operation.
gcloud
Get the operation ID:
Before using any of the command data below, make the following replacements:
- INSTANCE_NAME: the Spanner instance name.
- DATABASE_NAME: the Spanner database name.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud spanner operations list --instance=INSTANCE_NAME \ --database=DATABASE_NAME --type=backup
Windows (PowerShell)
gcloud spanner operations list --instance=INSTANCE_NAME ` --database=DATABASE_NAME --type=backup
Windows (cmd.exe)
gcloud spanner operations list --instance=INSTANCE_NAME ^ --database=DATABASE_NAME --type=backup
You should receive a response 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
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 thefilter
field inListBackupOperationsRequest
.The
--type
flag isn't case sensitive.
Use
gcloud spanner operations cancel
to cancel a backup operation.Before using any of the command data below, make the following replacements:
- OPERATION_ID: the operation ID.
- INSTANCE_NAME: the Spanner instance name.
- DATABASE_NAME: the Spanner database name.
- BACKUP_NAME: the Spanner backup name.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud spanner operations cancel OPERATION_ID --instance=INSTANCE_NAME \ --database=DATABASE_NAME --backup=BACKUP_NAME
Windows (PowerShell)
gcloud spanner operations cancel OPERATION_ID --instance=INSTANCE_NAME ` --database=DATABASE_NAME --backup=BACKUP_NAME
Windows (cmd.exe)
gcloud spanner operations cancel OPERATION_ID --instance=INSTANCE_NAME ^ --database=DATABASE_NAME --backup=BACKUP_NAME
Client libraries
The following code sample creates a backup, cancels the backup operation, and
then waits until the backup operation is done
. If the operation was
successfully cancelled, it returns the cancelTime
and an error message. If the
backup operation was completed before it was cancelled, the backup exists, and you can delete it.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Get backup information
Console
In the Google Cloud console, go to the Spanner Instances page.
Click the instance that contains the database you want to view the backup information for.
Click the database to open its Overview page.
In the navigation pane, click Backup/Restore. You can view backup information for your selected backup in the database.
gcloud
To get information about a backup,
use gcloud spanner backups describe
.
Before using any of the command data below, make the following replacements:
- PROJECT_ID: the project ID.
- INSTANCE_ID: the Spanner instance ID.
- DATABASE_ID: the Spanner database ID.
- BACKUP_NAME: the Spanner backup name.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud spanner backups describe BACKUP_NAME --instance=INSTANCE_ID
Windows (PowerShell)
gcloud spanner backups describe BACKUP_NAME --instance=INSTANCE_ID
Windows (cmd.exe)
gcloud spanner backups describe BACKUP_NAME --instance=INSTANCE_ID
You should receive a response similar to the following:
createTime: '2020-02-04T02:05:43.920377Z' database: projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID expireTime: '2021-02-04T02:05:43.268327Z' name: projects/PROJECT_ID/instances/INSTANCE_ID/backups/BACKUP_NAME sizeBytes: '1000000000' state: READY
Client libraries
Client libraries don't support getting backup information for a single backup. However, you can list all backups and their information in an instance. For more information, see List backups in an instance.
List backups in an instance
Console
In the Google Cloud console, go to the Spanner Instances page.
Click your instance to view all available backups and their information.
In the navigation pane, click Backup/Restore.
gcloud
To list all the backups in an instance,
use gcloud spanner backups list
.
Before using any of the command data below, make the following replacements:
- INSTANCE_ID: the Spanner instance ID.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud spanner backups list --instance=INSTANCE_ID
Windows (PowerShell)
gcloud spanner backups list --instance=INSTANCE_ID
Windows (cmd.exe)
gcloud spanner backups list --instance=INSTANCE_ID
You should receive a response 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, to filter the list
to only include the backups that are still being created, add
--filter="state:creating"
. For information about filter syntax, see gcloud topic filters
.
For information on filtering backups, see the filter
field in ListBackupsRequest
.
Client libraries
The following code sample lists the backups in a given instance.
You can filter the list of returned backups (for example, filtering by name, version
time, or backup expiration time) by providing a filter expression. For
information on filtering syntax, see the filter
parameter in
List Backups.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Update the backup expiration period
Console
Go to the Spanner Instances page in the Google Cloud console.
Click the instance containing the database to open its Overview page.
Click the database to open its Overview page.
In the navigation pane, click Backup/Restore.
Click the Actions button for your selected backup, then select Update metadata.
Select the new expiration date.
Click Update.
gcloud
To update a backup's expiration period date,
use gcloud spanner backups update-metadata
:
Before using any of the command data below, make the following replacements:
- PROJECT_ID: the project ID.
- BACKUP_ID: the Spanner backup ID.
- INSTANCE_ID: the Spanner instance ID.
- EXPIRATION_DATE: the expiration date time stamp.
- DATABASE_ID: the Spanner database ID.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud spanner backups update-metadata BACKUP_ID \ --instance=INSTANCE_ID \ --expiration-date=EXPIRATION_DATE
Windows (PowerShell)
gcloud spanner backups update-metadata BACKUP_ID ` --instance=INSTANCE_ID ` --expiration-date=EXPIRATION_DATE
Windows (cmd.exe)
gcloud spanner backups update-metadata BACKUP_ID ^ --instance=INSTANCE_ID ^ --expiration-date=EXPIRATION_DATE
You should receive a response similar to the following:
createTime: '2020-02-04T02:05:43.920377Z' database: projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID expireTime: '2020-05-05T00:00:00Z' name: projects/PROJECT_ID/instances/INSTANCE_ID/backups/BACKUP_ID sizeBytes: '1000000000' state: READY
Client libraries
The following code sample retrieves the expiry time of a backup and extends it.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Delete a backup
Console
Go to the Spanner Instances page in the Google Cloud console.
Click the instance containing the database to open its Overview page.
Click the database to open its Overview page.
In the navigation pane, click Backup/Restore.
Click the Actions button for your selected backup, then select Delete.
Type the backup ID.
Click Delete.
gcloud
To delete a backup,
use gcloud spanner backups delete
.
Before using any of the command data below, make the following replacements:
- INSTANCE_ID: the Spanner instance ID.
- BACKUP_NAME: the Spanner backup name.
Execute the following command:
Linux, macOS, or Cloud Shell
gcloud spanner backups delete BACKUP_NAME --instance=INSTANCE_ID
Windows (PowerShell)
gcloud spanner backups delete BACKUP_NAME --instance=INSTANCE_ID
Windows (cmd.exe)
gcloud spanner backups delete BACKUP_NAME --instance=INSTANCE_ID
You should receive a response similar to the following:
You are about to delete backup BACKUP_NAME Do you want to continue (Y/n)? Y Deleted backup BACKUP_NAME.
Client libraries
The following code sample deletes a backup and verifies that it was deleted. Deleting a backup that is still in progress both removes the backup resource and cancels the long-running backup operation.
C++
C#
Go
Java
Node.js