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) ⇒ Client

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

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


532
533
534
535
536
 
# File 'lib/google/cloud/spanner/project.rb', line 532

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

#client(instance_id, database_id, pool: {}, labels: nil) ⇒ 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_query "SELECT * FROM users"

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


473
474
475
476
477
478
479
 
# File 'lib/google/cloud/spanner/project.rb', line 473

def client instance_id, database_id, pool: {}, labels: nil
  # Convert from possible Google::Protobuf::Map
  labels = Hash[labels.map { |k, v| [String(k), String(v)] }] if labels
  Client.new self, instance_id, database_id,
             session_labels: labels,
             pool_opts: 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

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


404
405
406
407
408
 
# File 'lib/google/cloud/spanner/project.rb', line 404

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

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


219
220
221
222
223
224
225
226
227
228
 
# File 'lib/google/cloud/spanner/project.rb', line 219

def create_instance instance_id, name: nil, config: nil, nodes: nil,
                    labels: nil
  config = config.path if config.respond_to? :path
  # Convert from possible Google::Protobuf::Map
  labels = Hash[labels.map { |k, v| [String(k), String(v)] }] if labels
  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


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

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#all)

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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


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

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


154
155
156
157
158
159
160
 
# File 'lib/google/cloud/spanner/project.rb', line 154

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


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

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


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

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#all)

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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


128
129
130
131
132
 
# File 'lib/google/cloud/spanner/project.rb', line 128

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 ⇒ Object 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"


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

def project_id
  service.project
end