Cloud Spanner API - Class Google::Cloud::Spanner::Backup (v2.24.0)

Reference documentation and code samples for the Cloud Spanner API class Google::Cloud::Spanner::Backup.

Backup

NOTE: From google-cloud-spanner/v2.11.0 onwards, new features for mananging backups will only be available through the google-cloud-spanner-admin-database-v1 client. See the README for further details.

A backup is a representation of Cloud Spanner database backup.

See Instance#backups, Instance#backup, and Database#create_backup.

Admin::Database#database_admin instead.

Inherits

  • Object

Example

require "google/cloud"

spanner = Google::Cloud::Spanner.new
database = spanner.database "my-instance", "my-database"

expire_time = Time.now + 36000
job = database.create_backup "my-backup", expire_time

job.done? #=> false
job.reload! # API call
job.done? #=> true

if job.error?
  status = job.error
else
  backup = job.backup
end

Methods

#backup_id

def backup_id() -> String

The unique identifier for the backup.

Returns
  • (String)

#create_time

def create_time() -> Time

Create time is approximately the time when the backup request was received.

Returns
  • (Time)

#creating?

def creating?() -> Boolean

The backup is still being created. A backup is not yet available for the database restore operation.

Returns
  • (Boolean)

#database_id

def database_id() -> String

Name of the database from which this backup was created.

Returns
  • (String)

#delete

def delete() -> Boolean

Permanently deletes the backup.

Returns
  • (Boolean) — Returns true if the backup was deleted.
Example 
require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"
backup = instance.backup "my-backup"
backup.delete # true

#encryption_info

def encryption_info() -> Google::Cloud::Spanner::Admin::Database::V1::EncryptionInfo, nil

Encryption information for a given resource.

Returns
  • (Google::Cloud::Spanner::Admin::Database::V1::EncryptionInfo, nil)

#expire_time

def expire_time() -> Time

The expiration time of the backup, with microseconds granularity.

Returns
  • (Time)

#expire_time=

def expire_time=(time)

Update backup expiration time.

Set expiration time of the backup, with microseconds granularity that must be at least 6 hours and at most 366 days from the time the request is received. Once the expire_time has passed, Cloud Spanner will delete the backup and free the resources used by the backup.

Parameter
  • time (Time) — Backup expiration time.
Raises
  • (Google::Cloud::Error) — if expire time is in past or update call is aborted.
Example 
require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"
backup = instance.backup "my-backup"
backup.expire_time = Time.now + 36000
puts backup.expire_time

#instance_id

def instance_id() -> String

The unique identifier for the instance.

Returns
  • (String)

#path

def path() -> String

The full path for the backup. Values are of the form projects/<project>/instances/<instance>/backups/<backup_id>.

Returns
  • (String)

#project_id

def project_id() -> String

The unique identifier for the project.

Returns
  • (String)

#ready?

def ready?() -> Boolean

The backup is created and can be used to restore a database.

Returns
  • (Boolean)

#referencing_databases

def referencing_databases() -> Array<Google::Cloud::Spanner::Database>

The instances of the restored databases that reference the backup. Referencing databases may exist in different instances. The existence of any referencing database prevents the backup from being deleted. When a restored database from the backup enters the READY state, the reference to the backup is removed.

Returns
Example 
spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"
backup = instance.backup "my-backup"

backup.referencing_databases.each do |database|
  puts database.database_id
end

#restore

def restore(database_id, instance_id: nil, encryption_config: nil) -> Database

Restores deleted database from the backup.

@raise [ArgumentError] if :CUSTOMER_MANAGED_ENCRYPTION specified without customer managed kms key.

Parameters
  • database_id (String) — The unique identifier for the database, which cannot be changed after the database is created. Values are of the form [a-z][a-z0-9_\-]*[a-z0-9] and must be between 2 and 30 characters in length. Required.
  • instance_id (String) (defaults to: nil) — 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. Optional. Default value is same as a backup instance.
  • encryption_config (Hash) (defaults to: nil) —

    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. Optional. The following settings can be provided:

    • :kms_key_name (String) The name of KMS key to use which should be the full path, e.g., projects/<project>/locations/<location>\ /keyRings/<key_ring>/cryptoKeys/<kms_key_name> This field should be set only when encryption type :CUSTOMER_MANAGED_ENCRYPTION.
    • :encryption_type (Symbol) The encryption type of the backup. Valid values are:
      1. :USE_CONFIG_DEFAULT_OR_BACKUP_ENCRYPTION - This is the default option when config is not specified.
      2. :GOOGLE_DEFAULT_ENCRYPTION - Google default encryption.
      3. :CUSTOMER_MANAGED_ENCRYPTION - Use customer managed encryption. If specified, :kms_key_name must contain a valid Cloud KMS key.
Returns
  • (Database) — Restored database.
Examples 
require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"
backup = instance.backup "my-backup"
job = backup.restore "my-restored-database"

job.done? #=> false
job.reload! # API call
job.done? #=> true

if job.error?
  status = job.error
else
  database = job.database
end

Restore database in provided instance id

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"
backup = instance.backup "my-backup"
job = backup.restore(
  "my-restored-database",
  instance_id: "other-instance"
)

job.done? #=> false
job.reload! # API call
job.done? #=> true

if job.error?
  status = job.error
else
  database = job.database
end

Restore database with encryption config

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"
backup = instance.backup "my-backup"
kms_key_name = "projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>"
encryption_config = {
  kms_key_name: kms_key_name,
  encryption_type: :CUSTOMER_MANAGED_ENCRYPTION
}
job = backup.restore(
  "my-restored-database",
  encryption_config: encryption_config
)

job.done? #=> false
job.reload! # API call
job.done? #=> true

if job.error?
  status = job.error
else
  database = job.database
end

#size_in_bytes

def size_in_bytes() -> Integer

Size of the backup in bytes.

Returns
  • (Integer)

#state

def state() -> Symbol

The current backup state. Possible values are :CREATING and :READY.

Returns
  • (Symbol)

#version_time

def version_time() -> Time

The timestamp when a consistent copy of the database for the backup was taken. The version time has microseconds granularity.

Returns
  • (Time)