This page describes Spanner backup operations and explains how to back up a database. For more information about backups, see Backups overview.
You can back up databases using the following:
Before you begin
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
You have an instance named
test-instance
and a database namedexample-db
.
-
To get the permissions that you need to create and 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 (
Create 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 back up.
Click the database.
In the navigation pane, click Backup/Restore.
In the Backups tab, click Create backup.
Fill out the form, and click Create.
To check the progress of a backup operation, see Check the operation progress.
gcloud
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, seegcloud topic datetimes
. - The name of the backup 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.
Client libraries
The following code sample creates a backup at a specific version_time
and then waits for it to complete. Once complete, it verifies that the backup is
ready and retrieves some information about it, such as its name, size, and
create time.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
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
To copy a backup to a different instance in the same project,
use gcloud spanner backups copy
:
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 can't 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 can't 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.
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:
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 thefilter
field inListBackupOperationsRequest
.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.
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
Use gcloud spanner operations cancel
to cancel a backup operation.
gcloud spanner operations cancel OPERATION_ID --instance=INSTANCE_NAME \ --database=DATABASE_NAME --backup=BACKUP
Replace the following:
- OPERATION_ID with the operation ID of the backup.
- INSTANCE_NAME with the Spanner instance name.
- DATABASE_NAME with the name of the database.
- BACKUP with the name of the backup.
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
:
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
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
:
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, 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
:
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
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
:
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].
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
PHP
Python
Ruby