Method: projects.instances.databases.restore

Create a new database by restoring from a completed backup. The new database must be in the same project and in an instance with the same instance configuration as the instance containing the backup. The returned database long-running operation has a name of the formatprojects/<project>/instances/<instance>/databases/<database>/operations/<operationId>, and can be used to track the progress of the operation, and to cancel it. The metadata field type isRestoreDatabaseMetadata. The response type isDatabase, if successful. Cancelling the returned operation will stop the restore and delete the database. There can be only one database being restored into an instance at a time. Once the restore operation completes, a new restore operation can be initiated, without waiting for the optimize operation associated with the first restore to complete.

HTTP request


POST https://spanner.googleapis.com/v1/{parent=projects/*/instances/*}/databases:restore

The URLs usegRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. The name of the instance in which to create the restored database. This instance must be in the same project and have the same instance configuration as the instance containing the source backup. Values are of the formprojects/<project>/instances/<instance>.

Authorization requires the followingIAM permission on the specified resourceparent:

  • spanner.databases.create

Request body

The request body contains data with the following structure:

JSON representation
{"databaseId":string,"encryptionConfig":{object (RestoreDatabaseEncryptionConfig)},// Union fieldsource can be only one of the following:"backup":string// End of list of possible types for union fieldsource.}
Fields
databaseId

string

Required. The id of the database to create and restore to. This database must not already exist. ThedatabaseId appended toparent forms the full database name of the formprojects/<project>/instances/<instance>/databases/<databaseId>.

encryptionConfig

object (RestoreDatabaseEncryptionConfig)

Optional. An encryption configuration describing the encryption type and key resources in Cloud KMS used to encrypt/decrypt the database to restore to. If this field is not specified, the restored database will use the same encryption configuration as the backup by default, namelyencryptionType =USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION.

Union fieldsource. Required. The source from which to restore.source can be only one of the following:
backup

string

Name of the backup from which to restore. Values are of the formprojects/<project>/instances/<instance>/backups/<backup>.

Authorization requires the followingIAM permission on the specified resourcebackup:

  • spanner.backups.restoreDatabase

Response body

If successful, the response body contains an instance ofOperation.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/spanner.admin
  • https://www.googleapis.com/auth/cloud-platform

For more information, see theAuthentication Overview.

RestoreDatabaseEncryptionConfig

Encryption configuration for the restored database.

JSON representation
{"encryptionType":enum (EncryptionType),"kmsKeyName":string,"kmsKeyNames":[string]}
Fields
encryptionType

enum (EncryptionType)

Required. The encryption type of the restored database.

kmsKeyName

string

Optional. This field is maintained for backwards compatibility. For new callers, we recommend usingkmsKeyNames to specify the KMS key. Only usekmsKeyName if the location of the KMS key matches the database instance's configuration (location) exactly. For example, if the KMS location is inus-central1 ornam3, then the database instance must also be inus-central1 ornam3.

The Cloud KMS key that is used to encrypt and decrypt the restored database. Set this field only whenencryptionType isCUSTOMER_MANAGED_ENCRYPTION. Values are of the formprojects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kmsKeyName>.

kmsKeyNames[]

string

Optional. Specifies the KMS configuration for one or more keys used to encrypt the database. Values have the formprojects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kmsKeyName>.

The keys referenced bykmsKeyNames must fully cover all regions of the database's instance configuration. Some examples:

  • For regional (single-region) instance configurations, specify a regional location KMS key.
  • For multi-region instance configurations of typeGOOGLE_MANAGED, either specify a multi-region location KMS key or multiple regional location KMS keys that cover all regions in the instance configuration.
  • For an instance configuration of typeUSER_MANAGED, specify only regional location KMS keys to cover each region in the instance configuration. Multi-region location KMS keys aren't supported forUSER_MANAGED type instance configurations.

EncryptionType

Encryption types for the database to be restored.

Enums
ENCRYPTION_TYPE_UNSPECIFIEDUnspecified. Do not use.
USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTIONThis is the default option whenencryptionConfig is not specified.
GOOGLE_DEFAULT_ENCRYPTIONUse Google default encryption.
CUSTOMER_MANAGED_ENCRYPTIONUse customer managed encryption. If specified,kmsKeyName must must contain a valid Cloud KMS key.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-12 UTC.