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

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

# Instance

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.

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

instance = spanner.instance "my-new-instance"

Defined Under Namespace

Classes: Config, Job, List

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(grpc, service) ⇒ Instance

Returns a new instance of Instance.



64
65
66
67
 
# File 'lib/google/cloud/spanner/instance.rb', line 64

def initialize grpc, service
  @grpc = grpc
  @service = service
end

Instance Attribute Details

#service ⇒ Object 



61
62
63
 
# File 'lib/google/cloud/spanner/instance.rb', line 61

def service
  @service
end

Class Method Details

.from_grpc(grpc, service) ⇒ Object

Google::Spanner::Admin::Instance::V1::Instance.



451
452
453
 
# File 'lib/google/cloud/spanner/instance.rb', line 451

def self.from_grpc grpc, service
  new grpc, service
end

Instance Method Details

#config ⇒ Instance::Config

The instance configuration resource.

Returns:



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

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: []) ⇒ 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
database = job.database

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]` and must be between 2 and 30 characters in length. Required.

  • statements (Array<String>) (defaults to: []) —

    DDL statements to run inside the newly created database. Statements can create tables, indexes, etc. These statements execute atomically with the creation of the database: if there is an error in any statement, the database is not created. Optional.

Returns:

  • (Database::Job) —

    The job representing the long-running, asynchronous processing of a database create operation.



323
324
325
326
327
 
# File 'lib/google/cloud/spanner/instance.rb', line 323

def create_database database_id, statements: []
  grpc = service.create_database instance_id, database_id,
                                 statements: statements
  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.

Returns:

  • (Boolean) 


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

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

Parameters:

  • database_id (String) —

    The unique identifier for the database.

Returns:



284
285
286
287
288
289
290
 
# File 'lib/google/cloud/spanner/instance.rb', line 284

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

#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 Instance::Config::List::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

Parameters:

  • token (String) (defaults to: nil) —

    The ‘token` value returned by the last call to `databases`; indicates that this is a continuation of a call, and that the system should return the next page of data.

  • max (Integer) (defaults to: nil) —

    Maximum number of databases to return.

Returns:



256
257
258
259
260
 
# File 'lib/google/cloud/spanner/instance.rb', line 256

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

Returns:

  • (Boolean) —

    Returns ‘true` if the instance was deleted.



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

def delete
  ensure_service!
  service.delete_instance path
  true
end

#instance_id ⇒ String

The unique identifier for the instance.

Returns:

  • (String) 


78
79
80
81
 
# File 'lib/google/cloud/spanner/instance.rb', line 78

def instance_id
  Admin::Instance::V1::InstanceAdminClient
    .match_instance_from_instance_name @grpc.name
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])?`.

  • Label values must be between 0 and 63 characters long and must conform to the regular expression ‘([a-z](*[a-z0-9])?)?`.

  • No more than 64 labels can be associated with a given resource.

Returns:

  • (Hash{String=>String}) —

    The label keys and values in a hash.



175
176
177
 
# File 'lib/google/cloud/spanner/instance.rb', line 175

def labels
  @grpc.labels
end

#labels=(labels) ⇒ Object

Updates the Cloud Labels.

Parameters:

  • labels (Hash{String=>String}) —

    The Cloud Labels.



182
183
184
185
186
 
# File 'lib/google/cloud/spanner/instance.rb', line 182

def labels= labels
  @grpc.labels = Google::Protobuf::Map.new(
    :string, :string,
    Hash[labels.map { |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.

Returns:

  • (String) 


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

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.

Parameters:

  • display_name (String) —

    The descriptive name for this instance.



114
115
116
 
# File 'lib/google/cloud/spanner/instance.rb', line 114

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.

Returns:

  • (Integer) 


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

def nodes
  @grpc.node_count
end

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

Updates the number of nodes allocated to this instance.

Parameters:

  • nodes (Integer) —

    The number of nodes allocated to this instance.



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

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

Returns:

  • (String) 


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

def path
  @grpc.name
end

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

Gets the [Cloud IAM](cloud.google.com/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

Returns:

  • (Policy) —

    The current Cloud IAM Policy for this instance.

See Also:



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

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

#policy=(new_policy) ⇒ Policy

Updates the [Cloud IAM](cloud.google.com/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.policy = policy # API call

Parameters:

  • new_policy (Policy) —

    a new or modified Cloud IAM Policy for this instance

Returns:

  • (Policy) —

    The policy returned by the API update operation.

See Also:



401
402
403
404
405
 
# File 'lib/google/cloud/spanner/instance.rb', line 401

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

#project_id ⇒ String

The unique identifier for the project.

Returns:

  • (String) 


71
72
73
74
 
# File 'lib/google/cloud/spanner/instance.rb', line 71

def project_id
  Admin::Instance::V1::InstanceAdminClient
    .match_project_from_instance_name @grpc.name
end

#ready? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def ready?
  state == :READY
end

#save ⇒ Object Also known as: update 



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

def save
  job_grpc = service.update_instance @grpc
  Instance::Job.from_grpc job_grpc, service
end

#state ⇒ Symbol

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

Returns:

  • (Symbol) 


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

def state
  @grpc.state
end

#test_permissions(*permissions) ⇒ Array<Strings>

Tests the specified permissions against the [Cloud IAM](cloud.google.com/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

Parameters:

  • permissions (String, Array<String>) —

    The set of permissions to check access for. Permissions with wildcards (such as ‘*` or `storage.*`) are not allowed.

    The permissions that can be checked on a instance are:

    • pubsub.instances.create

    • pubsub.instances.list

    • pubsub.instances.get

    • pubsub.instances.getIamPolicy

    • pubsub.instances.update

    • pubsub.instances.setIamPolicy

    • pubsub.instances.delete

Returns:

  • (Array<Strings>) —

    The permissions that have access.

See Also:



440
441
442
443
444
445
446
 
# File 'lib/google/cloud/spanner/instance.rb', line 440

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