Class: Google::Cloud::Spanner::Instance Deprecated

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

Overview

Deprecated.

Use

Instance

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

Represents a Cloud Spanner instance. Instances are dedicated Cloud Spanner serving and storage resources to be used by Cloud Spanner databases. Instances offer isolation: problems with databases in one instance will not affect other instances. However, within an instance databases can affect each other. For example, if one database in an instance receives a lot of requests and consumes most of the instance resources, fewer resources are available for other databases in that instance, and their performance may suffer.

See Project#instances, Project#instance, and Project#create_instance.

Admin::Instance#instance_admin instead.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

job = spanner.create_instance "my-new-instance",
                              name: "My New Instance",
                              config: "regional-us-central1",
                              nodes: 5,
                              labels: { production: :env }

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

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

Defined Under Namespace

Classes: Config, Job, List

Instance Method Summary collapse

Instance Method Details

#backup(backup_id) ⇒ Google::Cloud::Spanner::Backup?

Retrieves a backup belonging to the instance by identifier.

Examples:

require "google/cloud/spanner"

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

Will return nil if backup does not exist.

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
instance = spanner.instance "my-instance"
backup = instance.backup "non-existing-backup" # nil



692
693
694
695
696
697
698
 
# File 'lib/google/cloud/spanner/instance.rb', line 692

def backup backup_id
  ensure_service!
  grpc = service.get_backup instance_id, backup_id
  Backup.from_grpc grpc, service
rescue Google::Cloud::NotFoundError
  nil
end

#backup_operations(filter: nil, page_size: nil) ⇒ Array<Google::Cloud::Spanner::Backup::Job>

Retrieves the list of database backup operations for the given instance.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"

jobs = instance.backup_operations
jobs.each do |job|
  if job.error?
    p job.error
  else
    p job.backup.backup_id
  end
end

Retrieve all

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"

jobs = instance.backup_operations
jobs.all do |job|
  if job.error?
    p job.error
  else
    p job.backup.backup_id
  end
end

List by page size

require "google/cloud/spanner"

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

jobs = instance.backup_operations page_size: 10
jobs.each do |job|
  if job.error?
    p job.error
  else
    puts job.backup.backup_id
  end
end

Filter and list

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"

filter = "metadata.@type:CreateBackupMetadata"
jobs = instance.backup_operations filter: filter
jobs.each do |job|
  if job.error?
    p job.error
  else
    puts job.backup.backup_id
  end
end



832
833
834
835
836
837
838
 
# File 'lib/google/cloud/spanner/instance.rb', line 832

def backup_operations filter: nil, page_size: nil
  grpc = service.list_backup_operations \
    instance_id,
    filter: filter,
    page_size: page_size
  Backup::Job::List.from_grpc grpc, service
end

#backups(filter: nil, page_size: nil) ⇒ Array<Google::Cloud::Spanner::Backup>

Retrieves backups belonging to the instance.

Examples:

require "google/cloud/spanner"

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

instance.backups.all.each do |backup|
  puts backup.backup_id
end

List backups by page size

require "google/cloud/spanner"

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

instance.backups(page_size: 5).all.each do |backup|
  puts backup.backup_id
end

Filter and list backups

require "google/cloud/spanner"

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

# filter backups by name.
instance.backups(filter: "name:my-backup").all.each do |backup|
  puts backup.backup_id
end

# filter backups by database name.
instance.backups(filter: "database:prod-db").all.each do |backup|
  puts backup.backup_id
end



661
662
663
664
665
666
667
668
 
# File 'lib/google/cloud/spanner/instance.rb', line 661

def backups filter: nil, page_size: nil
  ensure_service!
  grpc = service.list_backups \
    instance_id,
    filter: filter,
    page_size: page_size
  Backup::List.from_grpc grpc, service
end

#config ⇒ Instance::Config

The instance configuration resource.



120
121
122
123
124
125
126
 
# File 'lib/google/cloud/spanner/instance.rb', line 120

def config
  ensure_service!
  config_grpc = service.get_instance_config @grpc.config
  Instance::Config.from_grpc config_grpc
rescue Google::Cloud::NotFoundError
  @grpc.config
end

#create_database(database_id, statements: [], encryption_config: nil) ⇒ Database::Job

Creates a database and starts preparing it to begin serving.

See Database::Job.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"
job = instance.create_database "my-new-database"

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

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

Create with encryption config

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"

kms_key_name = "projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>"
job = instance.create_database "my-new-database", encryption_config: { kms_key_name: kms_key_name }

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

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



433
434
435
436
437
438
 
# File 'lib/google/cloud/spanner/instance.rb', line 433

def create_database database_id, statements: [], encryption_config: nil
  grpc = service.create_database instance_id, database_id,
                                 statements: statements,
                                 encryption_config: encryption_config
  Database::Job.from_grpc grpc, service
end

#creating? ⇒ Boolean

The instance is still being created. Resources may not be available yet, and operations such as database creation may not work.



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

def creating?
  state == :CREATING
end

#database(database_id) ⇒ Google::Cloud::Spanner::Database?

Retrieves a database belonging to the instance by identifier.

Examples:

require "google/cloud/spanner"

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

Will return nil if instance does not exist.

require "google/cloud/spanner"

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



362
363
364
365
366
367
368
 
# File 'lib/google/cloud/spanner/instance.rb', line 362

def database database_id
  ensure_service!
  grpc = service.get_database instance_id, database_id
  Database.from_grpc grpc, service
rescue Google::Cloud::NotFoundError
  nil
end

#database_operations(filter: nil, page_size: nil) ⇒ Array<Google::Cloud::Spanner::Database::Job>

Retrieves the list of database operations for the given instance.

Google::Longrunning::Operation long-running operations whose names are prefixed by a database name within the specified instance. The long-running operation Google::Longrunning::Operation#metadata metadata field type metadata.type_url describes the type of the metadata.

The filter expression must specify the field name, a comparison operator, and the value that you want to use for filtering. The value must be a string, a number, or a boolean. The comparison operator must be <, >, <=, >=, !=, =, or :. Colon ':' represents a HAS operator which is roughly synonymous with equality. Filter rules are case insensitive.

The long-running operation fields eligible for filtering are: * name --> The name of the long-running operation * done --> False if the operation is in progress, else true. * metadata.type_url (using filter string metadata.@type) and fields in metadata.value (using filter string metadata.<field_name>, where is a field in metadata.value) are eligible for filtering. * error --> Error associated with the long-running operation. * response.type_url (using filter string response.@type) and fields in response.value (using filter string response.<field_name>, where is a field in response.value)are eligible for filtering.

To filter on multiple expressions, provide each separate
expression within parentheses. By default, each expression
is an AND expression. However, you can include AND, OR, and NOT
expressions explicitly.

Some examples of using filters are:

* `done:true` --> The operation is complete.
* `(metadata.@type:type.googleapis.com/google.spanner.admin.\
  database.v1.RestoreDatabaseMetadata)
  AND (metadata.source_type:BACKUP)
  AND (metadata.backup_info.backup:backup_howl)
  AND (metadata.name:restored_howl)
  AND (metadata.progress.start_time < \"2018-03-28T14:50:00Z\")
  AND (error:*)`
  --> Return RestoreDatabase operations from backups whose name
  contains "backup_howl", where the created database name
  contains the string "restored_howl", the start_time of the
  restore operation is before 2018-03-28T14:50:00Z,
  and the operation returned an error.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"

jobs = instance.database_operations
jobs.each do |job|
  if job.error?
    p job.error
  else
    p job.database.database_id
  end
end

Retrieve all

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"

jobs = instance.database_operations
jobs.all do |job|
  if job.error?
    p job.error
  else
    puts job.database.database_id
  end
end

List by page size

require "google/cloud/spanner"

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

jobs = instance.database_operations page_size: 10
jobs.each do |job|
  if job.error?
    p job.error
  else
    puts job.database.database_id
  end
end

Filter and list

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"

filter = "metadata.@type:CreateDatabaseMetadata"
jobs = instance.database_operations filter: filter
jobs.each do |job|
  if job.error?
    p job.error
  else
    puts job.database.database_id
  end
end



571
572
573
574
575
576
577
 
# File 'lib/google/cloud/spanner/instance.rb', line 571

def database_operations filter: nil, page_size: nil
  grpc = service.list_database_operations \
    instance_id,
    filter: filter,
    page_size: page_size
  Database::Job::List.from_grpc grpc, service
end

#databases(token: nil, max: nil) ⇒ Array<Google::Cloud::Spanner::Database>

Retrieves the list of databases for the given instance.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"
databases = instance.databases
databases.each do |database|
  puts database.database_id
end

Retrieve all: (See Google::Cloud::Spanner::Instance::Config::List#all)

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"
databases = instance.databases
databases.all do |database|
  puts database.database_id
end



334
335
336
337
338
 
# File 'lib/google/cloud/spanner/instance.rb', line 334

def databases token: nil, max: nil
  ensure_service!
  grpc = service.list_databases instance_id, token: token, max: max
  Database::List.from_grpc grpc, service, instance_id, max
end

#delete ⇒ Boolean

Permanently deletes the instance.

Immediately upon completion of the request:

  • Billing ceases for all of the instance's reserved resources.

Soon afterward:

  • The instance and all of its databases immediately and irrevocably disappear from the API. All data in the databases is permanently deleted.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"
instance.delete



295
296
297
298
299
 
# File 'lib/google/cloud/spanner/instance.rb', line 295

def delete
  ensure_service!
  service.delete_instance path
  true
end

#instance_id ⇒ String

The unique identifier for the instance.



96
97
98
 
# File 'lib/google/cloud/spanner/instance.rb', line 96

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

#labels ⇒ Hash{String=>String}

Cloud Labels are a flexible and lightweight mechanism for organizing cloud resources into groups that reflect a customer's organizational needs and deployment strategies. Cloud Labels can be used to filter collections of resources. They can be used to control how resource metrics are aggregated. And they can be used as arguments to policy management rules (e.g. route, firewall, load balancing, etc.).

  • Label keys must be between 1 and 63 characters long and must conform to the following regular expression: [a-z]([-a-z0-9]*[a-z0-9])?.
  • Label values must be between 0 and 63 characters long and must conform to the regular expression ([a-z]([-a-z0-9]*[a-z0-9])?)?.
  • No more than 64 labels can be associated with a given resource.


209
210
211
 
# File 'lib/google/cloud/spanner/instance.rb', line 209

def labels
  @grpc.labels
end

#labels=(labels) ⇒ Object

Updates the Cloud Labels.



216
217
218
219
220
221
 
# File 'lib/google/cloud/spanner/instance.rb', line 216

def labels= labels
  @grpc.labels = Google::Protobuf::Map.new(
    :string, :string,
    labels.to_h { |k, v| [String(k), String(v)] }
  )
end

#name ⇒ String Also known as: display_name

The descriptive name for this instance as it appears in UIs. Must be unique per project and between 4 and 30 characters in length.



112
113
114
 
# File 'lib/google/cloud/spanner/instance.rb', line 112

def name
  @grpc.display_name
end

#name=(display_name) ⇒ Object Also known as: display_name=

Updates the descriptive name for this instance as it appears in UIs.



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

def name= display_name
  @grpc.display_name = display_name
end

#nodes ⇒ Integer Also known as: node_count

The number of nodes allocated to this instance.



139
140
141
 
# File 'lib/google/cloud/spanner/instance.rb', line 139

def nodes
  @grpc.node_count
end

#nodes=(nodes) ⇒ Object Also known as: node_count=

Updates the number of nodes allocated to this instance.



147
148
149
 
# File 'lib/google/cloud/spanner/instance.rb', line 147

def nodes= nodes
  @grpc.node_count = nodes
end

#path ⇒ String

The full path for the instance resource. Values are of the form projects/<project_id>/instances/<instance_id>.



104
105
106
 
# File 'lib/google/cloud/spanner/instance.rb', line 104

def path
  @grpc.name
end

#policy {|policy| ... } ⇒ Policy

Gets the Cloud IAM access control policy for this instance.

Examples:

require "google/cloud/spanner"

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

policy = instance.policy

Update the policy by passing a block:

require "google/cloud/spanner"

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

instance.policy do |p|
  p.add "roles/owner", "user:[email protected]"
end # 2 API calls

Yields:

  • (policy) —

    A block for updating the policy. The latest policy will be read from the Spanner service and passed to the block. After the block completes, the modified policy will be written to the service.

Yield Parameters:

  • policy (Policy) —

    the current Cloud IAM Policy for this instance

See Also:



874
875
876
877
878
879
880
881
 
# File 'lib/google/cloud/spanner/instance.rb', line 874

def policy
  ensure_service!
  grpc = service.get_instance_policy path
  policy = Policy.from_grpc grpc
  return policy unless block_given?
  yield policy
  update_policy policy
end

#processing_units ⇒ Integer

The number of processing units allocated to this instance.



156
157
158
 
# File 'lib/google/cloud/spanner/instance.rb', line 156

def processing_units
  @grpc.processing_units
end

#processing_units=(units) ⇒ Object

Updates number of processing units allocated to this instance.



165
166
167
 
# File 'lib/google/cloud/spanner/instance.rb', line 165

def processing_units= units
  @grpc.processing_units = units
end

#project_id ⇒ String

The unique identifier for the project.



90
91
92
 
# File 'lib/google/cloud/spanner/instance.rb', line 90

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

#ready? ⇒ Boolean

The instance is fully created and ready to do work such as creating databases.



189
190
191
 
# File 'lib/google/cloud/spanner/instance.rb', line 189

def ready?
  state == :READY
end

#save ⇒ Instance::Job Also known as: update

Update changes. display_name, labels, nodes, processing_units can be updated. processing_units and nodes can be used interchangeably to update.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance = spanner.instance "my-instance"
instance.display_name = "prod-instance"
instance.labels = { env: "prod", app: "api" }
instance.nodes = 2
# OR
# instance.processing_units = 500

job = instance.save

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

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

Raises:

  • (ArgumentError) —

    if both processing_units or nodes are specified.



257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/google/cloud/spanner/instance.rb', line 257

def save
  ensure_service!

  field_mask = []
  new_values = @grpc.to_h
  (@current_values.keys + new_values.keys).uniq.each do |field|
    field_mask << field unless new_values[field] == @current_values[field]
  end

  job_grpc = service.update_instance @grpc, field_mask: field_mask
  @current_values = new_values
  Instance::Job.from_grpc job_grpc, service
end

#state ⇒ Symbol

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



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

def state
  @grpc.state
end

#test_permissions(*permissions) ⇒ Array<Strings>

Tests the specified permissions against the Cloud IAM access control policy.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
instance = spanner.instance "my-instance"
perms = instance.test_permissions "spanner.instances.get",
                                  "spanner.instances.update"
perms.include? "spanner.instances.get" #=> true
perms.include? "spanner.instances.update" #=> false

See Also:



952
953
954
955
956
957
958
 
# File 'lib/google/cloud/spanner/instance.rb', line 952

def test_permissions *permissions
  permissions = Array(permissions).flatten
  permissions = Array(permissions).flatten
  ensure_service!
  grpc = service.test_instance_permissions path, permissions
  grpc.permissions
end

#update_policy(new_policy) ⇒ Policy Also known as: policy=

Updates the Cloud IAM access control policy for this instance. The policy should be read from #policy. See Policy for an explanation of the policy etag property and how to modify policies.

You can also update the policy by passing a block to #policy, which will call this method internally after the block completes.

Examples:

require "google/cloud/spanner"

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

policy = instance.policy # API call

policy.add "roles/owner", "user:[email protected]"

instance.update_policy policy # API call

See Also:



912
913
914
915
916
 
# File 'lib/google/cloud/spanner/instance.rb', line 912

def update_policy new_policy
  ensure_service!
  grpc = service.set_instance_policy path, new_policy.to_grpc
  Policy.from_grpc grpc
end