class Google::Cloud::Spanner::Instance
# 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 {Google::Cloud::Spanner::Project#instances}, {Google::Cloud::Spanner::Project#instance}, and {Google::Cloud::Spanner::Project#create_instance}.
@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
Attributes
@private The gRPC Service
object.
Public Class Methods
@private Creates a new Instance
instance from a `Google::Cloud::Spanner::Admin::Instance::V1::Instance`.
# File lib/google/cloud/spanner/instance.rb, line 948 def self.from_grpc grpc, service new grpc, service end
@private Creates a new Instance
instance.
# File lib/google/cloud/spanner/instance.rb, line 68 def initialize grpc, service @grpc = grpc @service = service @current_values = grpc.to_h end
Public Instance Methods
Retrieves a backup belonging to the instance by identifier.
@param [String] backup_id The unique identifier for the backup.
@return [Google::Cloud::Spanner::Backup, nil] Returns `nil`
if database does not exist.
@example
require "google/cloud/spanner" spanner = Google::Cloud::Spanner.new instance = spanner.instance "my-instance" backup = instance.backup "my-backup"
@example 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
# File lib/google/cloud/spanner/instance.rb, line 677 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
Retrieves the list of database backup operations for the given instance.
@param filter [String]
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 <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.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.
@param page_size [Integer]
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.
@return [Array<Google::Cloud::Spanner::Backup::Job>] List
representing
the long-running, asynchronous processing of a backup operations. (See {Google::Cloud::Spanner::Backup::Job::List})
@example
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
@example 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
@example 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
@example 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
# File lib/google/cloud/spanner/instance.rb, line 817 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
Retrieves backups belonging to the instance.
@param [String] filter 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
@param [Integer] page_size Optional. Number of backups to be returned
in the response. If 0 or less, defaults to the server's maximum allowed page size.
@return [Array<Google::Cloud::Spanner::Backup>] Enumerable list of
backups. (See {Google::Cloud::Spanner::Backup::List})
@example
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
@example 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
@example 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
# File lib/google/cloud/spanner/instance.rb, line 646 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
The instance configuration resource. @return [Instance::Config]
# File lib/google/cloud/spanner/instance.rb, line 106 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
Creates a database and starts preparing it to begin serving.
See {Database::Job}.
@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 [Array<String>] statements 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.
@param [Hash] encryption_config 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>`
@return [Database::Job] The job representing the long-running,
asynchronous processing of a database create operation.
@example
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
@example 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
# File lib/google/cloud/spanner/instance.rb, line 418 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
The instance is still being created. Resources may not be available yet, and operations such as database creation may not work. @return [Boolean]
# File lib/google/cloud/spanner/instance.rb, line 167 def creating? state == :CREATING end
Retrieves a database belonging to the instance by identifier.
@param [String] database_id The unique identifier for the database.
@return [Google::Cloud::Spanner::Database, nil] Returns `nil`
if database does not exist.
@example
require "google/cloud/spanner" spanner = Google::Cloud::Spanner.new instance = spanner.instance "my-instance" database = instance.database "my-database"
@example 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
# File lib/google/cloud/spanner/instance.rb, line 347 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
Retrieves the list of database operations for the given instance.
@param filter [String]
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 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.
@param page_size [Integer]
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.
@return [Array<Google::Cloud::Spanner::Database::Job>] List
representing the long-running, asynchronous processing of a database operations. (See {Google::Cloud::Spanner::Database::Job::List})
@example
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
@example 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
@example 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
@example 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
# File lib/google/cloud/spanner/instance.rb, line 556 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
Retrieves the list of databases for the given instance.
@param [String] token 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.
@param [Integer] max Maximum number of databases to return.
@return [Array<Google::Cloud::Spanner::Database>] (See
{Google::Cloud::Spanner::Database::List})
@example
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
@example Retrieve all: (See {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
# File lib/google/cloud/spanner/instance.rb, line 319 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
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.
@return [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
# File lib/google/cloud/spanner/instance.rb, line 280 def delete ensure_service! service.delete_instance path true end
The unique identifier for the instance. @return [String]
# File lib/google/cloud/spanner/instance.rb, line 82 def instance_id @grpc.name.split("/")[3] end
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.
@return [Hash{String=>String}] The label keys and values in a hash.
# File lib/google/cloud/spanner/instance.rb, line 195 def labels @grpc.labels end
The descriptive name for this instance as it appears in UIs. Must be unique per project and between 4 and 30 characters in length. @return [String]
# File lib/google/cloud/spanner/instance.rb, line 98 def name @grpc.display_name end
Updates the descriptive name for this instance as it appears in UIs. @param display_name
[String] The descriptive name for this instance.
# File lib/google/cloud/spanner/instance.rb, line 117 def name= display_name @grpc.display_name = display_name end
The number of nodes allocated to this instance. @return [Integer]
# File lib/google/cloud/spanner/instance.rb, line 125 def nodes @grpc.node_count end
Updates the number of nodes allocated to this instance. @param nodes [Integer] The number of nodes allocated to this instance.
# File lib/google/cloud/spanner/instance.rb, line 133 def nodes= nodes @grpc.node_count = nodes end
The full path for the instance resource. Values are of the form `projects/<project_id>/instances/<instance_id>`. @return [String]
# File lib/google/cloud/spanner/instance.rb, line 90 def path @grpc.name end
Gets the [Cloud IAM](cloud.google.com/iam/) access control policy for this instance.
@see cloud.google.com/spanner/reference/rpc/google.iam.v1#google.iam.v1.Policy
google.iam.v1.IAMPolicy
@yield [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.
@yieldparam [Policy] policy the current Cloud
IAM Policy
for this
instance
@return [Policy] The current Cloud
IAM Policy
for this instance.
@example
require "google/cloud/spanner" spanner = Google::Cloud::Spanner.new instance = spanner.instance "my-instance" policy = instance.policy
@example 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
# File lib/google/cloud/spanner/instance.rb, line 859 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
The number of processing units allocated to this instance.
@return [Integer]
# File lib/google/cloud/spanner/instance.rb, line 142 def processing_units @grpc.processing_units end
Updates number of processing units allocated to this instance.
@param units [Integer] The number of processing units allocated
to this instance.
# File lib/google/cloud/spanner/instance.rb, line 151 def processing_units= units @grpc.processing_units = units end
The unique identifier for the project. @return [String]
# File lib/google/cloud/spanner/instance.rb, line 76 def project_id @grpc.name.split("/")[1] end
The instance is fully created and ready to do work such as creating databases. @return [Boolean]
# File lib/google/cloud/spanner/instance.rb, line 175 def ready? state == :READY end
Update changes.
`display_name`, `labels`, `nodes`, `processing_units` can be updated. `processing_units` and `nodes` can be used interchangeably to update.
@return [Instance::Job] The job representing the long-running,
asynchronous processing of an instance update operation.
@raise [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
# File lib/google/cloud/spanner/instance.rb, line 243 def save ensure_service! field_mask = [] @current_values.each do |field, value| field_mask << field unless @grpc[field.to_s] == value end job_grpc = service.update_instance @grpc, field_mask: field_mask @current_values = @grpc.to_h Instance::Job.from_grpc job_grpc, service end
The current instance state. Possible values are `:CREATING` and `:READY`. @return [Symbol]
# File lib/google/cloud/spanner/instance.rb, line 159 def state @grpc.state end
Tests the specified permissions against the [Cloud IAM](cloud.google.com/iam/) access control policy.
@see cloud.google.com/iam/docs/managing-policies Managing
Policies
@param [String, Array<String>] permissions 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
@return [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
# File lib/google/cloud/spanner/instance.rb, line 937 def test_permissions *permissions permissions = Array(permissions).flatten permissions = Array(permissions).flatten ensure_service! grpc = service.test_instance_permissions path, permissions grpc.permissions end
Updates the [Cloud IAM](cloud.google.com/iam/) access control policy for this instance. The policy should be read from {#policy}. See {Google::Cloud::Spanner::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.
@see cloud.google.com/spanner/reference/rpc/google.iam.v1#google.iam.v1.Policy
google.iam.v1.IAMPolicy
@param [Policy] new_policy a new or modified Cloud
IAM Policy
for this
instance
@return [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
# File lib/google/cloud/spanner/instance.rb, line 897 def update_policy new_policy ensure_service! grpc = service.set_instance_policy path, new_policy.to_grpc Policy.from_grpc grpc end
Protected Instance Methods
@private Raise an error unless an active connection to the service is available.
# File lib/google/cloud/spanner/instance.rb, line 957 def ensure_service! raise "Must have active connection to service" unless service end