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

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

Backup

A backup is a representation of Cloud Spanner database backup.

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

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) 


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

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) 


181
182
183
 
# File 'lib/google/cloud/spanner/backup.rb', line 181

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) 


117
118
119
 
# File 'lib/google/cloud/spanner/backup.rb', line 117

def creating?
  state == :CREATING
end

#database_id ⇒ String

Name of the database from which this backup was created.

Returns:

  • (String) 


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

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.



236
237
238
239
240
 
# File 'lib/google/cloud/spanner/backup.rb', line 236

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) 


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

def encryption_info
  @grpc.encryption_info
end

#expire_time ⇒ Time

The expiration time of the backup, with microseconds granularity.

Returns:

  • (Time) 


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

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.



157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/google/cloud/spanner/backup.rb', line 157

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) 


73
74
75
 
# File 'lib/google/cloud/spanner/backup.rb', line 73

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) 


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

def path
  @grpc.name
end

#project_id ⇒ String

The unique identifier for the project.

Returns:

  • (String) 


66
67
68
 
# File 'lib/google/cloud/spanner/backup.rb', line 66

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

#ready? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

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:



212
213
214
215
216
217
218
219
220
 
# File 'lib/google/cloud/spanner/backup.rb', line 212

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:



347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
 
# File 'lib/google/cloud/spanner/backup.rb', line 347

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) 


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

def size_in_bytes
  @grpc.size_bytes
end

#state ⇒ Symbol

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

Returns:

  • (Symbol) 


109
110
111
 
# File 'lib/google/cloud/spanner/backup.rb', line 109

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) 


173
174
175
 
# File 'lib/google/cloud/spanner/backup.rb', line 173

def version_time
  Convert.timestamp_to_time @grpc.version_time
end