Cloud Spanner API - Class Google::Cloud::Spanner::Instance (v2.23.0)

Reference documentation and code samples for the Cloud Spanner API class Google::Cloud::Spanner::Instance.

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.

Inherits

  • Object

Example

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

Methods

#backup

def backup(backup_id) -> Google::Cloud::Spanner::Backup, nil

Retrieves a backup belonging to the instance by identifier.

Parameter
  • backup_id (String) — The unique identifier for the backup.
Returns
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

#backup_operations

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

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

Parameters
  • filter (String) (defaults to: nil) —

    A filter expression that filters what operations are returned in the response.

    The response returns a list of Google::Longrunning::Operation long-running operations whose names are prefixed by a backup 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 of an operation, 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
    • 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

    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.database:prod --> The database the backup was taken from has a name containing the string "prod".
    • (metadata.@type:type.googleapis.com/google.spanner.admin.\ database.v1.CreateBackupMetadata) AND (metadata.name:howl) AND (metadata.progress.start_time < \"2018-03-28T14:50:00Z\") AND (error:*) --> Return CreateBackup operations where the created backup name contains the string "howl", the progress.start_time of the backup operation is before 2018-03-28T14:50:00Z, and the operation returned an error.
  • page_size (Integer) (defaults to: nil) — The maximum number of resources contained in the underlying API response. If page streaming is performed per-resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.
Returns
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

#backups

def backups(filter: nil, page_size: nil) -> Array<Google::Cloud::Spanner::Backup>

Retrieves backups belonging to the instance.

Parameters
  • filter (String) (defaults to: nil) —

    Optional. A filter expression that filters backups listed in the response. The 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 fields eligible for filtering are:

    • name
    • database
    • state
    • create_time(and values are of the format YYYY-MM-DDTHH:MM:SSZ)
    • expire_time(and values are of the format YYYY-MM-DDTHH:MM:SSZ)
    • size_bytes

    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:

    • name:Howl --> The backup's name contains the string "howl".
    • database:prod --> The database's name contains the string "prod".
    • state:CREATING --> The backup is pending creation.
    • state:READY --> The backup is fully created and ready for use.
    • (name:howl) AND (create_time < \"2018-03-28T14:50:00Z\") --> The backup name contains the string "howl" and create_time of the backup is before 2018-03-28T14:50:00Z.
    • expire_time < \"2018-03-28T14:50:00Z\" --> The backup expire_time is before 2018-03-28T14:50:00Z.
    • size_bytes > 10000000000 --> The backup's size is greater than 10GB
  • page_size (Integer) (defaults to: nil) — Optional. Number of backups to be returned in the response. If 0 or less, defaults to the server's maximum allowed page size.
Returns
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

#config

def config() -> Instance::Config

The instance configuration resource.

Returns

#create_database

def create_database(database_id, statements: [], encryption_config: nil) -> Database::Job

Creates a database and starts preparing it to begin serving.

See Database::Job.

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.
  • 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.
  • encryption_config (Hash) (defaults to: nil) —

    An encryption configuration describing the encryption type and key resources in Cloud KMS. 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>
Returns
  • (Database::Job) — The job representing the long-running, asynchronous processing of a database create operation.
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

#creating?

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

#database

def database(database_id) -> Google::Cloud::Spanner::Database, nil

Retrieves a database belonging to the instance by identifier.

Parameter
  • database_id (String) — The unique identifier for the database.
Returns
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

#database_operations

def 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 <field_name> 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 <field_name> 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.
Parameters
  • filter (String) (defaults to: nil) — A filter expression that filters what operations are returned in the response.

    The response returns a list of

  • page_size (Integer) (defaults to: nil) — The maximum number of resources contained in the underlying API response. If page streaming is performed per-resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.
Returns
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

#databases

def databases(token: nil, max: nil) -> Array<Google::Cloud::Spanner::Database>

Retrieves the list of databases for the given instance.

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

#delete

def 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.
Returns
  • (Boolean) — Returns true if the instance was deleted.
Example 
require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

#display_name

def display_name() -> String
Alias Of: #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)

#display_name=

def display_name=(display_name)
Alias Of: #name=

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

Parameter
  • display_name (String) — The descriptive name for this instance.

#instance_id

def instance_id() -> String

The unique identifier for the instance.

Returns
  • (String)

#labels

def 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?.
  • Label values must be between 0 and 63 characters long and must conform to the regular expression (a-z?)?.
  • No more than 64 labels can be associated with a given resource.
Returns
  • (Hash{String=>String}) — The label keys and values in a hash.

#labels=

def labels=(labels)

Updates the Cloud Labels.

Parameter
  • labels (Hash{String=>String}) — The Cloud Labels.

#name

def name() -> String
Aliases

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)

#name=

def name=(display_name)
Aliases

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

Parameter
  • display_name (String) — The descriptive name for this instance.

#node_count

def node_count() -> Integer
Alias Of: #nodes

The number of nodes allocated to this instance.

Returns
  • (Integer)

#node_count=

def node_count=(nodes)
Alias Of: #nodes=

Updates the number of nodes allocated to this instance.

Parameter
  • nodes (Integer) — The number of nodes allocated to this instance.

#nodes

def nodes() -> Integer
Aliases

The number of nodes allocated to this instance.

Returns
  • (Integer)

#nodes=

def nodes=(nodes)
Aliases

Updates the number of nodes allocated to this instance.

Parameter
  • nodes (Integer) — The number of nodes allocated to this instance.

#path

def path() -> String

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

Returns
  • (String)

#policy

def policy() { |policy| ... } -> Policy

Gets the Cloud IAM access control policy for this instance.

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 Parameter
  • policy (Policy) — the current Cloud IAM Policy for this instance
Returns
  • (Policy) — The current Cloud IAM 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:owner@example.com"
end # 2 API calls

#policy=

def policy=(new_policy) -> Policy
Alias Of: #update_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.

Parameter
  • new_policy (Policy) — a new or modified Cloud IAM Policy for this instance
Returns
  • (Policy) — The policy returned by the API update operation.
Example 
require "google/cloud/spanner"

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

policy = instance.policy # API call

policy.add "roles/owner", "user:owner@example.com"

instance.update_policy policy # API call

#processing_units

def processing_units() -> Integer

The number of processing units allocated to this instance.

Returns
  • (Integer)

#processing_units=

def processing_units=(units)

Updates number of processing units allocated to this instance.

Parameter
  • units (Integer) — The number of processing units allocated to this instance.

#project_id

def project_id() -> String

The unique identifier for the project.

Returns
  • (String)

#ready?

def ready?() -> Boolean

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

Returns
  • (Boolean)

#save

def save() -> Instance::Job
Aliases

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

Returns
  • (Instance::Job) — The job representing the long-running, asynchronous processing of an instance update operation.
Raises
  • (ArgumentError) — if both processing_units or nodes are specified.
Example 
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

#state

def state() -> Symbol

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

Returns
  • (Symbol)

#test_permissions

def test_permissions(*permissions) -> Array<Strings>

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

Parameter
  • 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.
Example 
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

#update

def update() -> Instance::Job
Alias Of: #save

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

Returns
  • (Instance::Job) — The job representing the long-running, asynchronous processing of an instance update operation.
Raises
  • (ArgumentError) — if both processing_units or nodes are specified.
Example 
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

#update_policy

def update_policy(new_policy) -> Policy
Aliases

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.

Parameter
  • new_policy (Policy) — a new or modified Cloud IAM Policy for this instance
Returns
  • (Policy) — The policy returned by the API update operation.
Example 
require "google/cloud/spanner"

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

policy = instance.policy # API call

policy.add "roles/owner", "user:owner@example.com"

instance.update_policy policy # API call