Restore from a backup

You can restore a backup of a Spanner database into a new database. The restored database will have all the data and schema from the original database at the version_time of the backup, including all database options that are set with the ALTER DATABASE SET OPTIONS command. It won't have any IAM permissions (except for those inherited from the instance containing the restored database), and you must apply appropriate IAM permissions after the restore completes. It won't include the internal data of any change streams. When you restore from a backup, the restored backup resides in the same instance, region, and project as its source backup. If you need to restore from the backup in a different region or project for compliance or business continuity reasons, you can copy the backup to an instance in a separate region or project, then restore from the copied backup.

You can use restore from a backup in the following ways:

For an overview of backup and restore, see About backup and restore.

How restore from a backup works

When you restore a Spanner database, you must specify a source backup and a new target database. You cannot restore to an existing database. The newly restored database must be in the same project as the backup and be in an instance with the same instance configuration as the backup. For example, if a backup is in an instance configured us-west3, it can be restored to any instance in the project that is also configured us-west3. The compute capacity of the instances does not need to be the same.

The restore process is designed for high-availability. The database can be restored provided that the majority quorum of the regions and zones in the instance is available.

To restore a CMEK-enabled backup, both the key and key version must be available to Spanner. The restored database, by default, uses the same encryption configurations as the backup. You can override this behavior by specifying a different encryption configuration when restoring the database. For more information, see restore from a CMEK-enabled backup.

Restore a backup to a different region or project

If you need to restore the backup to a different region or project, first, copy the backup to the chosen region or project. Copied backups are restorable as soon as the copy finishes. You can restore the backup either in the destination instance or in any instance that has the same instance configuration as the destination instance. Before restoring, make sure that the destination instance has enough nodes or processing units provisioned to support the database size according to the 4TB per node storage limit (e.g. You need at least 2 nodes to restore a 8TB backup). If you have copied the backup to a different project, and if you want to restore it there, make sure that your destination project has enough node quotas required for the restore. Restoring a copied backup works the same way as a normal restore.

Restoration states

A restored database transitions through three states, tracked by two long-running operations.

  • CREATING: Spanner begins restoring by creating a new database and mounting files from the backup. During this initial CREATING state, the restored database is not yet ready for use. This state typically completes within one hour. Once the CREATING state is complete, your database is ready to use.

    To track the progress of this state, you can query the long-running restore operation that Spanner makes available during this process. It returns a RestoreDatabaseMetadata object.

    Note the following caveats regarding the CREATING state:

    • If you are restoring to a different instance, the restore operation belongs to the instance containing the restored database, not the instance containing the backup.
    • Spanner won't allow you to delete the backup while it is being restored. You can delete it after the restore completes and the database enters the READY state.
    • An instance can have at most ten databases in the CREATING state due to restoration from backups. You won't be able to restore another backup to the instance until one of the ten restored databases transitions to the READY_OPTIMIZING or READY state.

  • READY_OPTIMIZING: After Spanner mounts the backup, it starts to copy the backup's data into the new database while optimizing its stored size. Your database is ready for use during this process. This phase of the restore usually takes a few hours to complete for databases less than 100TB in size.

    While you can use your database as usual during READY_OPTIMIZING, the following caveats apply:

    • Read latencies might be slightly higher than usual.
    • Storage metrics display the size of the new database, not the backup. Therefore, with the data transfer still in progress, Spanner storage metrics might show results that don't reflect the total size of all your data.
    • As with the CREATING state, Spanner won't allow you to delete the mounted backup.

    Spanner makes another long-running restore operation available during this state, this time returning a OptimizeRestoredDatabaseMetadata metadata object.

  • READY: Once the copy-and-optimize operation completes, the database transitions to the READY state. The database is fully restored, and no longer references or requires the backup.

Access control (IAM)

The role spanner.restoreAdmin gives you permission to restore from a backup. For more information, see Access control with IAM.

Pricing

There is no charge for restoring from a backup.

What's next