Class: Google::Cloud::Spanner::Backup Deprecated

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/spanner/backup.rb,
lib/google/cloud/spanner/backup/job.rb,
lib/google/cloud/spanner/backup/list.rb,
lib/google/cloud/spanner/backup/job/list.rb,
lib/google/cloud/spanner/backup/restore/job.rb

Overview

Deprecated.

Use

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.

Examples:

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

Defined Under Namespace

Classes: Job, List, Restore

Instance Method Summary collapse

Instance Method Details

#backup_id ⇒ String

The unique identifier for the backup.

Returns:

  • (String) 


94
95
96
 
# File 'lib/google/cloud/spanner/backup.rb', line 94

def backup_id
  @grpc.name.split("/")[5]
end

#create_time ⇒ Time

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

Returns:

  • (Time) 


195
196
197
 
# File 'lib/google/cloud/spanner/backup.rb', line 195

def create_time
  Convert.timestamp_to_time @grpc.create_time
end

#creating? ⇒ Boolean

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

Returns:

  • (Boolean) 


131
132
133
 
# File 'lib/google/cloud/spanner/backup.rb', line 131

def creating?
  state == :CREATING
end

#database_id ⇒ String

Name of the database from which this backup was created.

Returns:

  • (String) 


101
102
103
 
# File 'lib/google/cloud/spanner/backup.rb', line 101

def database_id
  @grpc.database.split("/")[5]
end

#delete ⇒ Boolean

Permanently deletes the backup.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

Returns:

  • (Boolean) —

    Returns true if the backup was deleted.



250
251
252
253
254
 
# File 'lib/google/cloud/spanner/backup.rb', line 250

def delete
  ensure_service!
  service.delete_backup instance_id, backup_id
  true
end

#encryption_info ⇒ Google::Cloud::Spanner::Admin::Database::V1::EncryptionInfo?

Encryption information for a given resource.

Returns:

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


107
108
109
 
# File 'lib/google/cloud/spanner/backup.rb', line 107

def encryption_info
  @grpc.encryption_info
end

#expire_time ⇒ Time

The expiration time of the backup, with microseconds granularity.

Returns:

  • (Time) 


145
146
147
 
# File 'lib/google/cloud/spanner/backup.rb', line 145

def expire_time
  Convert.timestamp_to_time @grpc.expire_time
end

#expire_time=(time) ⇒ Object

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.

Examples:

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

Parameters:

  • time (Time) —

    Backup expiration time.

Raises:

  • (Google::Cloud::Error) —

    if expire time is in past or update call is aborted.



171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/google/cloud/spanner/backup.rb', line 171

def expire_time= time
  ensure_service!

  expire_time_was = @grpc.expire_time
  @grpc.expire_time = Convert.time_to_timestamp time
  update_mask = Google::Protobuf::FieldMask.new paths: ["expire_time"]
  @grpc = service.update_backup @grpc, update_mask
rescue Google::Cloud::Error => e
  @grpc.expire_time = expire_time_was
  raise e
end

#instance_id ⇒ String

The unique identifier for the instance.

Returns:

  • (String) 


87
88
89
 
# File 'lib/google/cloud/spanner/backup.rb', line 87

def instance_id
  @grpc.name.split("/")[3]
end

#path ⇒ String

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

Returns:

  • (String) 


115
116
117
 
# File 'lib/google/cloud/spanner/backup.rb', line 115

def path
  @grpc.name
end

#project_id ⇒ String

The unique identifier for the project.

Returns:

  • (String) 


80
81
82
 
# File 'lib/google/cloud/spanner/backup.rb', line 80

def project_id
  @grpc.name.split("/")[1]
end

#ready? ⇒ Boolean

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

Returns:

  • (Boolean) 


138
139
140
 
# File 'lib/google/cloud/spanner/backup.rb', line 138

def ready?
  state == :READY
end

#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.

Examples:

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

Returns:



226
227
228
229
230
231
232
233
234
 
# File 'lib/google/cloud/spanner/backup.rb', line 226

def referencing_databases
  ensure_service!

  @grpc.referencing_databases.map do |referencing_database|
    segments = referencing_database.split "/"
    database_grpc = service.get_database segments[3], segments[5]
    Database.from_grpc database_grpc, service
  end
end

#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.

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

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:



361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
 
# File 'lib/google/cloud/spanner/backup.rb', line 361

def restore database_id, instance_id: nil, encryption_config: nil
  ensure_service!

  instance_id ||= self.instance_id

  if encryption_config&.include?(:kms_key_name) &&
     encryption_config[:encryption_type] != :CUSTOMER_MANAGED_ENCRYPTION
    raise Google::Cloud::InvalidArgumentError,
          "kms_key_name only used with CUSTOMER_MANAGED_ENCRYPTION"
  end

  grpc = service.restore_database \
    self.instance_id,
    backup_id,
    instance_id,
    database_id,
    encryption_config: encryption_config
  Restore::Job.from_grpc grpc, service
end

#size_in_bytes ⇒ Integer

Size of the backup in bytes.

Returns:

  • (Integer) 


202
203
204
 
# File 'lib/google/cloud/spanner/backup.rb', line 202

def size_in_bytes
  @grpc.size_bytes
end

#state ⇒ Symbol

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

Returns:

  • (Symbol) 


123
124
125
 
# File 'lib/google/cloud/spanner/backup.rb', line 123

def state
  @grpc.state
end

#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) 


187
188
189
 
# File 'lib/google/cloud/spanner/backup.rb', line 187

def version_time
  Convert.timestamp_to_time @grpc.version_time
end