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



615
616
617
618
619
620
621
 
# File 'lib/google/cloud/spanner/project.rb', line 615

def batch_client instance_id, database_id, labels: nil,
                 query_options: 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,
                  query_options: query_options
end

#client(instance_id, database_id, pool: {}, labels: nil, query_options: 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



539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
 
# File 'lib/google/cloud/spanner/project.rb', line 539

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

#create_database(instance_id, database_id, statements: [], encryption_config: nil) ⇒ 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

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



459
460
461
462
463
464
465
 
# File 'lib/google/cloud/spanner/project.rb', line 459

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

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

Raises:

  • (ArgumentError) —

    if both processing_units or nodes are specified.



245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/google/cloud/spanner/project.rb', line 245

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 = Hash[labels.map { |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?

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



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

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



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

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



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

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



318
319
320
321
322
323
324
 
# File 'lib/google/cloud/spanner/project.rb', line 318

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



289
290
291
292
293
 
# File 'lib/google/cloud/spanner/project.rb', line 289

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



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

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"



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

def project_id
  service.project
end