Class: Google::Cloud::Spanner::Project

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/spanner/project.rb

Overview

Project

Projects are top-level containers in Google Cloud Platform. They store information about billing and authorized users, and they contain Cloud Spanner data. Each project has a friendly name and a unique ID.

Google::Cloud::Spanner::Project is the main object for interacting with Cloud Spanner.

Instance and Database objects are created, accessed, and managed by Google::Cloud::Spanner::Project.

A Client obtained from a project can be used to read and/or modify data in a Cloud Spanner database.

See new and Google::Cloud#spanner.

Examples:

Obtaining an instance and a database from a project.

require "google/cloud"

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

Obtaining a client for use with a database.

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  results = tx.execute_query "SELECT * FROM users"

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end
end

Instance Method Summary collapse

Instance Method Details

#batch_client(instance_id, database_id, labels: nil, query_options: nil, directed_read_options: nil) ⇒ ::Google::Cloud::Spanner::BatchClient

Creates a Cloud Spanner batch client. A batch client is used to read data across multiple machines or processes.

The following settings can be provided:

  • :exclude_replicas (Hash) Exclude_replicas indicates what replicas should be excluded from serving requests. Spanner will not route requests to the replicas in this list.
  • :include_replicas (Hash) Include_replicas indicates the order of replicas to process the request. If auto_failover_disabled is set to true and all replicas are exhausted without finding a healthy replica, Spanner will wait for a replica in the list to become available, requests may fail due to DEADLINE_EXCEEDED errors.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

batch_client = spanner.batch_client "my-instance", "my-database"

batch_snapshot = batch_client.batch_snapshot
serialized_snapshot = batch_snapshot.dump

partitions = batch_snapshot.partition_read "users", [:id, :name]

partition = partitions.first
serialized_partition = partition.dump

# In a separate process
new_batch_snapshot = batch_client.load_batch_snapshot \
  serialized_snapshot

new_partition = batch_client.load_partition \
  serialized_partition

results = new_batch_snapshot.execute_partition \
  new_partition

Parameters:

  • instance_id (String) —

    The unique identifier for the instance. Required.

  • database_id (String) —

    The unique identifier for the database. Required.

  • labels (Hash) (defaults to: nil) —

    The labels to be applied to all sessions created by the batch client. 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.). Optional. The default is nil.

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

    A hash of values to specify the custom query options for executing SQL query. Query options are optional. The following settings can be provided:

    • :optimizer_version (String) The version of optimizer to use. Empty to use database default. "latest" to use the latest available optimizer version.
    • :optimizer_statistics_package (String) Statistics package to use. Empty to use the database default.
  • directed_read_options (Hash) (defaults to: nil) —

    Client options used to set the directed_read_options for all ReadRequests and ExecuteSqlRequests that indicates which replicas or regions should be used for non-transactional reads or queries. Will represent Google::Cloud::Spanner::V1::DirectedReadOptions

Returns:



681
682
683
684
685
686
687
 
# File 'lib/google/cloud/spanner/project.rb', line 681

def batch_client instance_id, database_id, labels: nil,
                 query_options: nil, directed_read_options: nil
  # Convert from possible Google::Protobuf::Map
  labels = labels.to_h { |k, v| [String(k), String(v)] } if labels
  BatchClient.new self, instance_id, database_id, session_labels: labels,
                  query_options: query_options, directed_read_options: directed_read_options
end

#client(instance_id, database_id, pool: {}, labels: nil, query_options: nil, database_role: nil, directed_read_options: nil, isolation_level: nil, read_lock_mode: nil) ⇒ ::Google::Cloud::Spanner::Client

Creates a Cloud Spanner client. A client is used to read and/or modify data in a Cloud Spanner database.

The following settings can be provided:

  • :exclude_replicas (Hash) Exclude_replicas indicates what replicas should be excluded from serving requests. Spanner will not route requests to the replicas in this list.
  • :include_replicas (Hash) Include_replicas indicates the order of replicas to process the request. If auto_failover_disabled is set to true and all replicas are exhausted without finding a healthy replica, Spanner will wait for a replica in the list to become available, requests may fail due to DEADLINE_EXCEEDED errors.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.transaction do |tx|
  results = tx.execute_query "SELECT * FROM users"

  results.rows.each do |row|
    puts "User #{row[:id]} is #{row[:name]}"
  end
end

Parameters:

  • instance_id (String) —

    The unique identifier for the instance. Required.

  • database_id (String) —

    The unique identifier for the database. Required.

  • pool (Hash) (defaults to: {}) —

    Optional. Defaults to {}. Deprecated. @deprecated This parameter is non-functional since the multiplexed SessionCache does not require pool options.

  • labels (Hash) (defaults to: nil) —

    The labels to be applied to all sessions created by the client. 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.). Optional. The default is nil.

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

    A hash of values to specify the custom query options for executing SQL query. Query options are optional. The following settings can be provided:

    • :optimizer_version (String) The version of optimizer to use. Empty to use database default. "latest" to use the latest available optimizer version.
    • :optimizer_statistics_package (String) Statistics package to use. Empty to use the database default.
  • directed_read_options (Hash) (defaults to: nil) —

    Client options used to set the directed_read_options for all ReadRequests and ExecuteSqlRequests that indicates which replicas or regions should be used for non-transactional reads or queries. Will represent Google::Cloud::Spanner::V1::DirectedReadOptions

  • isolation_level (::Symbol, nil) (defaults to: nil) —

    Optional. The isolation level for the transactions. Can be overridden by the isolation level set on the transaction. Can be one of the following:

    • :ISOLATION_LEVEL_UNSPECIFIED : The default unspecified isolation level.
    • :SERIALIZABLE : The serializable isolation level.
    • :REPEATABLE_READ : The repeatable read isolation level.
  • read_lock_mode (::Symbol, nil) (defaults to: nil) —

    Optional. The read lock mode for the transactions. Can be overridden by the read lock mode set on the transaction. Can be one of the following:

    • :READ_LOCK_MODE_UNSPECIFIED : The default unspecified read lock mode.
    • :PESSIMISTIC : The pessimistic lock mode, where depending on the isolation level and/or lock requested, locks are acquired on read.
    • :OPTIMISTIC : The optimistic lock mode, where locks are not acquired on read. Depending on the isolation level and/or lock requested on a read, data may be validated at commit time to be not changed since the transaction started.

Returns:



584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
 
# File 'lib/google/cloud/spanner/project.rb', line 584

def client instance_id, database_id, pool: {}, labels: nil,
           query_options: nil, database_role: nil, directed_read_options: nil,
           isolation_level: nil, read_lock_mode: nil
  # Convert from possible Google::Protobuf::Map
  labels = labels.to_h { |k, v| [String(k), String(v)] } if labels
  # Configs set by environment variables take over client-level configs.
  if query_options.nil?
    query_options = @query_options
  else
    query_options = query_options.merge @query_options unless @query_options.nil?
  end

  _pool = pool # unused. Here only to avoid having to disable Rubocop's Lint/UnusedMethodArgument

  Client.new self, instance_id, database_id,
             session_labels: labels,
             query_options: query_options,
             database_role: database_role,
             directed_read_options: directed_read_options,
             isolation_level: isolation_level,
             read_lock_mode: read_lock_mode
end

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

Deprecated.

Use Admin::Database.database_admin.create_database instead.

Creates a database and starts preparing it to begin serving.

See Database::Job.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

job = spanner.create_database "my-instance",
                              "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

kms_key_name = "projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>"
encryption_config = { kms_key_name: kms_key_name }
job = spanner.create_database "my-instance",
                              "my-new-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

Parameters:

  • instance_id (String) —

    The unique identifier for the instance. Required.

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



493
494
495
496
497
498
499
 
# File 'lib/google/cloud/spanner/project.rb', line 493

def create_database instance_id, 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

#create_instance(instance_id, name: nil, config: nil, nodes: nil, processing_units: nil, labels: nil) ⇒ Instance::Job

Deprecated.

Use Admin::Instance.instance_admin.create_instance instead.

Creates a Cloud Spanner instance and starts preparing it to begin serving.

See Instance::Job.

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

Create instance using processsing units

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

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

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

Parameters:

  • instance_id (String) —

    The unique identifier for the instance, which cannot be changed after the instance is created. Values are of the form [a-z][-a-z0-9]*[a-z0-9] and must be between 6 and 30 characters in length. Required.

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

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

  • config (String, Instance::Config) (defaults to: nil) —

    The name of the instance's configuration. Values can be the instance_config_id, the full path, or an Instance::Config object. Required.

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

    The number of nodes allocated to this instance. Optional. Specify either nodes or processing_units

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

    The number of processing units allocated to this instance. Optional. Specify either nodes or processing_units

  • labels (Hash) (defaults to: nil) —

    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.

Returns:

  • (Instance::Job) —

    The job representing the long-running, asynchronous processing of an instance create operation.

Raises:

  • (ArgumentError) —

    if both processing_units or nodes are specified.



269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/google/cloud/spanner/project.rb', line 269

def create_instance instance_id, name: nil, config: nil, nodes: nil,
                    processing_units: nil, labels: nil
  config = config.path if config.respond_to? :path

  # Convert from possible Google::Protobuf::Map
  labels = labels.to_h { |k, v| [String(k), String(v)] } if labels
  grpc = service.create_instance \
    instance_id, name: name, config: config, nodes: nodes,
                 processing_units: processing_units, labels: labels
  Instance::Job.from_grpc grpc, service
end

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

Deprecated.

Use Admin::Database.database_admin.get_database instead.

Retrieves a database by unique identifier.

Examples:

require "google/cloud/spanner"

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

Will return nil if instance does not exist.

require "google/cloud/spanner"

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

Parameters:

  • instance_id (String) —

    The unique identifier for the instance.

  • database_id (String) —

    The unique identifier for the database.

Returns:



417
418
419
420
421
422
423
 
# File 'lib/google/cloud/spanner/project.rb', line 417

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

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

Deprecated.

Use Admin::Database.database_admin.list_databases instead.

Retrieves the list of databases for the project.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

Retrieve all: (See Instance::Config::List#all)

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

Parameters:

  • instance_id (String) —

    The unique identifier for the instance.

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



388
389
390
391
392
 
# File 'lib/google/cloud/spanner/project.rb', line 388

def databases instance_id, 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

#instance(instance_id) ⇒ Google::Cloud::Spanner::Instance?

Deprecated.

Use Admin::Instance.instance_admin.get_instance instead.

Retrieves a Cloud Spanner instance by unique identifier.

Examples:

require "google/cloud/spanner"

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

Will return nil if instance does not exist.

require "google/cloud/spanner"

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

Parameters:

  • instance_id (String) —

    The unique identifier for the instance.

Returns:



177
178
179
180
181
182
183
 
# File 'lib/google/cloud/spanner/project.rb', line 177

def instance instance_id
  ensure_service!
  grpc = service.get_instance instance_id
  Instance.from_grpc grpc, service
rescue Google::Cloud::NotFoundError
  nil
end

#instance_config(instance_config_id) ⇒ Google::Cloud::Spanner::Instance::Config?

Deprecated.

Use Admin::Instance.instance_admin.get_instance_config instead.

Retrieves an instance configuration by unique identifier.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
config = spanner.instance_config "regional-us-central1"

Will return nil if instance config does not exist.

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
config = spanner.instance_config "non-existing" # nil

Parameters:

  • instance_config_id (String) —

    The instance configuration identifier. Values can be the instance_config_id, or the full path.

Returns:



346
347
348
349
350
351
352
 
# File 'lib/google/cloud/spanner/project.rb', line 346

def instance_config instance_config_id
  ensure_service!
  grpc = service.get_instance_config instance_config_id
  Instance::Config.from_grpc grpc
rescue Google::Cloud::NotFoundError
  nil
end

#instance_configs(token: nil, max: nil) ⇒ Array<Google::Cloud::Spanner::Instance::Config>

Deprecated.

Use Admin::Instance.instance_admin.list_instance_configs instead.

Retrieves the list of instance configurations for the project.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance_configs = spanner.instance_configs
instance_configs.each do |config|
  puts config.instance_config_id
end

Retrieve all: (See Instance::Config::List#all)

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instance_configs = spanner.instance_configs
instance_configs.all do |config|
  puts config.instance_config_id
end

Parameters:

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

    The token value returned by the last call to instance_configs; 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 instance configs to return.

Returns:



315
316
317
318
319
 
# File 'lib/google/cloud/spanner/project.rb', line 315

def instance_configs token: nil, max: nil
  ensure_service!
  grpc = service.list_instance_configs token: token, max: max
  Instance::Config::List.from_grpc grpc, service, max
end

#instances(token: nil, max: nil) ⇒ Array<Google::Cloud::Spanner::Instance>

Deprecated.

Use Admin::Instance.instance_admin.list_instances instead.

Retrieves the list of Cloud Spanner instances for the project.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instances = spanner.instances
instances.each do |instance|
  puts instance.instance_id
end

Retrieve all: (See Instance::Config::List#all)

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

instances = spanner.instances
instances.all do |instance|
  puts instance.instance_id
end

Parameters:

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

    The token value returned by the last call to instances; 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 instances to return.

Returns:



149
150
151
152
153
 
# File 'lib/google/cloud/spanner/project.rb', line 149

def instances token: nil, max: nil
  ensure_service!
  grpc = service.list_instances token: token, max: max
  Instance::List.from_grpc grpc, service, max
end

#project_id ⇒ ::String Also known as: project

The identifier for the Cloud Spanner project.

Examples:

require "google/cloud"

spanner = Google::Cloud::Spanner.new(
  project_id: "my-project",
  credentials: "/path/to/keyfile.json"
)

spanner.project_id #=> "my-project"

Returns:

  • (::String) 


102
103
104
 
# File 'lib/google/cloud/spanner/project.rb', line 102

def project_id
  service.project
end

#universe_domain ⇒ String

The universe domain the client is connected to

Returns:

  • (String) 


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

def universe_domain
  service.universe_domain
end