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 "SELECT * FROM users"

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(service) ⇒ Project

Returns a new instance of Project.



75
76
77
 
# File 'lib/google/cloud/spanner/project.rb', line 75

def initialize service
  @service = service
end

Instance Attribute Details

#service ⇒ Object 



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

def service
  @service
end

Class Method Details

.default_project ⇒ Object 



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

def self.default_project
  ENV["SPANNER_PROJECT"] ||
    ENV["GOOGLE_CLOUD_PROJECT"] ||
    ENV["GCLOUD_PROJECT"] ||
    Google::Cloud.env.project_id
end

Instance Method Details

#client(instance_id, database_id, pool: {}) ⇒ Client

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

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

db.transaction do |tx|
  results = tx.execute "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: {}) —

    Settings to control how and when sessions are managed by the client. The following settings can be provided:

    • ‘:min` (Integer) Minimum number of sessions that the client will maintain at any point in time. The default is 10.

    • ‘:max` (Integer) Maximum number of sessions that the client will have at any point in time. The default is 100.

    • ‘:keepalive` (Numeric) The amount of time a session can be idle before an attempt is made to prevent the idle sessions from being closed by the Cloud Spanner service. The default is 1800 (30 minutes).

    • ‘:write_ratio` (Float) The ratio of sessions with pre-allocated transactions to those without. Pre-allocating transactions improves the performance of writes made by the client. The higher the value, the more transactions are pre-allocated. The value must be >= 0 and <= 1. The default is 0.3.

    • ‘:fail` (true/false) When `true` the client raises a SessionLimitError when the client has allocated the `max` number of sessions. When `false` the client blocks until a session becomes available. The default is `true`.

    • ‘:threads` (Integer) The number of threads in the thread pool. The default is twice the number of available CPUs.

Returns:

  • (Client) —

    The newly created client.



455
456
457
458
 
# File 'lib/google/cloud/spanner/project.rb', line 455

def client instance_id, database_id, pool: {}
  Client.new self, instance_id, database_id,
             valid_session_pool_options(pool)
end

#create_database(instance_id, 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

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

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

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



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

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

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

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
instance = job.instance

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

  • 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])?`.

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

  • (Instance::Job) —

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



223
224
225
226
227
228
229
230
 
# File 'lib/google/cloud/spanner/project.rb', line 223

def create_instance instance_id, name: nil, config: nil, nodes: nil,
                    labels: nil
  config = config.path if config.respond_to? :path
  grpc = service.create_instance \
    instance_id, name: name, config: config, nodes: nodes,
                 labels: labels
  Instance::Job.from_grpc grpc, service
end

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

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:



360
361
362
363
364
365
366
 
# File 'lib/google/cloud/spanner/project.rb', line 360

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>

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



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

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?

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:



163
164
165
166
167
168
169
 
# File 'lib/google/cloud/spanner/project.rb', line 163

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?

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:



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

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>

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



264
265
266
267
268
 
# File 'lib/google/cloud/spanner/project.rb', line 264

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>

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



137
138
139
140
141
 
# File 'lib/google/cloud/spanner/project.rb', line 137

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 ⇒ Object Also known as: project_id

The identifier for the Cloud Spanner project.

Examples:

require "google/cloud"

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

spanner.project #=> "my-project-id"


92
93
94
 
# File 'lib/google/cloud/spanner/project.rb', line 92

def project
  service.project
end