class Google::Cloud::Spanner::Backup

# Backup

A backup is a representation of Cloud Spanner database backup.

See {Google::Cloud::Spanner::Instance#backups}, {Google::Cloud::Spanner::Instance#backup}, and {Google::Cloud::Spanner::Database#create_backup}.

@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

Attributes

service[RW]

@private The gRPC Service object.

Public Class Methods

from_grpc(grpc, service) click to toggle source

@private Creates a new Backup instance from a `Google::Cloud::Spanner::Admin::Database::V1::Backup`.

# File lib/google/cloud/spanner/backup.rb, line 371
def self.from_grpc grpc, service
  new grpc, service
end
new(grpc, service) click to toggle source

@private Creates a new Backup instance.

# File lib/google/cloud/spanner/backup.rb, line 58
def initialize grpc, service
  @grpc = grpc
  @service = service
end

Public Instance Methods

backup_id() click to toggle source

The unique identifier for the backup. @return [String]

# File lib/google/cloud/spanner/backup.rb, line 80
def backup_id
  @grpc.name.split("/")[5]
end
create_time() click to toggle source

Create time is approximately the time when the backup request was received. @return [Time]

# File lib/google/cloud/spanner/backup.rb, line 181
def create_time
  Convert.timestamp_to_time @grpc.create_time
end
creating?() click to toggle source

The backup is still being created. A backup is not yet available for the database restore operation. @return [Boolean]

# File lib/google/cloud/spanner/backup.rb, line 117
def creating?
  state == :CREATING
end
database_id() click to toggle source

Name of the database from which this backup was created. @return [String]

# File lib/google/cloud/spanner/backup.rb, line 87
def database_id
  @grpc.database.split("/")[5]
end
delete() click to toggle source

Permanently deletes the backup.

@return [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
# File lib/google/cloud/spanner/backup.rb, line 236
def delete
  ensure_service!
  service.delete_backup instance_id, backup_id
  true
end
encryption_info() click to toggle source

Encryption information for a given resource. @return [Google::Cloud::Spanner::Admin::Database::V1::EncryptionInfo, nil]

# File lib/google/cloud/spanner/backup.rb, line 93
def encryption_info
  @grpc.encryption_info
end
expire_time() click to toggle source

The expiration time of the backup, with microseconds granularity. @return [Time]

# File lib/google/cloud/spanner/backup.rb, line 131
def expire_time
  Convert.timestamp_to_time @grpc.expire_time
end
expire_time=(time) click to toggle source

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.

@param [Time] time Backup expiration time. @raise [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
# 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() click to toggle source

The unique identifier for the instance. @return [String]

# File lib/google/cloud/spanner/backup.rb, line 73
def instance_id
  @grpc.name.split("/")[3]
end
path() click to toggle source

The full path for the backup. Values are of the form `projects/<project>/instances/<instance>/backups/<backup_id>`. @return [String]

# File lib/google/cloud/spanner/backup.rb, line 101
def path
  @grpc.name
end
project_id() click to toggle source

The unique identifier for the project. @return [String]

# File lib/google/cloud/spanner/backup.rb, line 66
def project_id
  @grpc.name.split("/")[1]
end
ready?() click to toggle source

The backup is created and can be used to restore a database. @return [Boolean]

# File lib/google/cloud/spanner/backup.rb, line 124
def ready?
  state == :READY
end
referencing_databases() click to toggle source

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.

@return [Array<Google::Cloud::Spanner::Database>] Returns list of

referencing database instances.

@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
# 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) click to toggle source

Restores deleted database from the backup.

@param [String] database_id 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.

@param [String] instance_id 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.

@param [Hash] encryption_config 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.

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

@return [Database] Restored database.

@example

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

@example 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

@example 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
# 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() click to toggle source

Size of the backup in bytes. @return [Integer]

# File lib/google/cloud/spanner/backup.rb, line 188
def size_in_bytes
  @grpc.size_bytes
end
state() click to toggle source

The current backup state. Possible values are `:CREATING` and `:READY`. @return [Symbol]

# File lib/google/cloud/spanner/backup.rb, line 109
def state
  @grpc.state
end
version_time() click to toggle source

The timestamp when a consistent copy of the database for the backup was taken. The version time has microseconds granularity. @return [Time]

# File lib/google/cloud/spanner/backup.rb, line 173
def version_time
  Convert.timestamp_to_time @grpc.version_time
end

Protected Instance Methods

ensure_service!() click to toggle source

@private Raise an error unless an active connection to the service is available.

# File lib/google/cloud/spanner/backup.rb, line 380
def ensure_service!
  raise "Must have active connection to service" unless service
end