Class: Google::Cloud::Spanner::Database

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/spanner/database.rb,
lib/google/cloud/spanner/database/job.rb,
lib/google/cloud/spanner/database/list.rb

Overview

# Database

Represents a Cloud Spanner database. To use Cloud Spanner’s read and write operations, you must first create a database. A database belongs to a Instance and contains tables and indexes. You may create multiple databases in an Instance.

See Instance#databases, Instance#database, and Instance#create_database.

To read and/or modify data in a Cloud Spanner database, use an instance of Client. See Project#client.

Examples:

require "google/cloud"

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

database = instance.database "my-new-database"

Defined Under Namespace

Classes: Job, List

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(grpc, service) ⇒ Database

Returns a new instance of Database.



59
60
61
62
 
# File 'lib/google/cloud/spanner/database.rb', line 59

def initialize grpc, service
  @grpc = grpc
  @service = service
end

Instance Attribute Details

#service ⇒ Object 



56
57
58
 
# File 'lib/google/cloud/spanner/database.rb', line 56

def service
  @service
end

Class Method Details

.from_grpc(grpc, service) ⇒ Object

Google::Spanner::Admin::Database::V1::Database.



357
358
359
 
# File 'lib/google/cloud/spanner/database.rb', line 357

def self.from_grpc grpc, service
  new grpc, service
end

Instance Method Details

#creating? ⇒ Boolean

The database is still being created. Operations on the database may fail with ‘FAILED_PRECONDITION` in this state.

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/google/cloud/spanner/database.rb', line 109

def creating?
  state == :CREATING
end

#database_id ⇒ String

The unique identifier for the database.

Returns:

  • (String) 


80
81
82
83
 
# File 'lib/google/cloud/spanner/database.rb', line 80

def database_id
  Admin::Database::V1::DatabaseAdminClient
    .match_database_from_database_name @grpc.name
end

#ddl(force: nil) ⇒ Array<String>

Retrieve the Data Definition Language (DDL) statements that define database structures. DDL statements are used to create, update, and delete tables and indexes.

Examples:

statements are memoized to reduce the number of API calls:

require "google/cloud/spanner"

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

statements = database.ddl # API call
statements_2 = database.ddl # No API call

Use ‘force` to retrieve the statements from the service:

require "google/cloud/spanner"

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

statements = database.ddl force: true # API call
statements_2 = database.ddl force: true # API call

Parameters:

  • force (Boolean) (defaults to: nil) —

    Force the latest DDL statements to be retrieved from the Spanner service when ‘true`. Otherwise the DDL statements will be memoized to reduce the number of API calls made to the Spanner service. The default is `false`.

Returns:

  • (Array<String>) —

    The DDL statements.

See Also:



153
154
155
156
157
158
 
# File 'lib/google/cloud/spanner/database.rb', line 153

def ddl force: nil
  return @ddl if @ddl && !force
  ensure_service!
  ddl_grpc = service.get_database_ddl instance_id, database_id
  @ddl = ddl_grpc.statements
end

#drop ⇒ Boolean

Drops (deletes) the Cloud Spanner database.

Examples:

require "google/cloud/spanner"

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

database.drop

Returns:

  • (Boolean) —

    Returns ‘true` if the database was deleted.



220
221
222
223
224
 
# File 'lib/google/cloud/spanner/database.rb', line 220

def drop
  ensure_service!
  service.drop_database instance_id, database_id
  true
end

#instance_id ⇒ String

The unique identifier for the instance.

Returns:

  • (String) 


73
74
75
76
 
# File 'lib/google/cloud/spanner/database.rb', line 73

def instance_id
  Admin::Database::V1::DatabaseAdminClient
    .match_instance_from_database_name @grpc.name
end

#path ⇒ String

The full path for the database resource. Values are of the form ‘projects/<project_id>/instances/<instance_id>/databases/<database_id>`.

Returns:

  • (String) 


91
92
93
 
# File 'lib/google/cloud/spanner/database.rb', line 91

def path
  @grpc.name
end

#policy {|policy| ... } ⇒ Policy

Gets the [Cloud IAM](cloud.google.com/iam/) access control policy for this database.

Examples:

require "google/cloud/spanner"

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

policy = database.policy

Update the policy by passing a block:

require "google/cloud/spanner"

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

database.policy do |p|
  p.add "roles/owner", "user:[email protected]"
end # 2 API calls

Yields:

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

Yield Parameters:

  • policy (Policy) —

    the current Cloud IAM Policy for this database

Returns:

  • (Policy) —

    The current Cloud IAM Policy for this database.

See Also:



260
261
262
263
264
265
266
267
 
# File 'lib/google/cloud/spanner/database.rb', line 260

def policy
  ensure_service!
  grpc = service.get_database_policy instance_id, database_id
  policy = Policy.from_grpc grpc
  return policy unless block_given?
  yield policy
  self.policy = policy
end

#policy=(new_policy) ⇒ Policy

Updates the [Cloud IAM](cloud.google.com/iam/) access control policy for this database. The policy should be read from #policy. See 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.

Examples:

require "google/cloud/spanner"

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

policy = database.policy # API call

policy.add "roles/owner", "user:[email protected]"

database.policy = policy # API call

Parameters:

  • new_policy (Policy) —

    a new or modified Cloud IAM Policy for this database

Returns:

  • (Policy) —

    The policy returned by the API update operation.

See Also:



298
299
300
301
302
303
 
# File 'lib/google/cloud/spanner/database.rb', line 298

def policy= new_policy
  ensure_service!
  grpc = service.set_database_policy \
    instance_id, database_id, new_policy.to_grpc
  Policy.from_grpc grpc
end

#project_id ⇒ String

The unique identifier for the project.

Returns:

  • (String) 


66
67
68
69
 
# File 'lib/google/cloud/spanner/database.rb', line 66

def project_id
  Admin::Database::V1::DatabaseAdminClient
    .match_project_from_database_name @grpc.name
end

#ready? ⇒ Boolean

The database is fully created and ready for use.

Returns:

  • (Boolean) 


116
117
118
 
# File 'lib/google/cloud/spanner/database.rb', line 116

def ready?
  state == :READY
end

#state ⇒ Symbol

The current database state. Possible values are ‘:CREATING` and `:READY`.

Returns:

  • (Symbol) 


101
102
103
 
# File 'lib/google/cloud/spanner/database.rb', line 101

def state
  @grpc.state
end

#test_permissions(*permissions) ⇒ Array<Strings>

Tests the specified permissions against the [Cloud IAM](cloud.google.com/iam/) access control policy.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new
database = spanner.database "my-instance", "my-database"
perms = database.test_permissions "spanner.databases.get",
                                  "spanner.databases.update"
perms.include? "spanner.databases.get" #=> true
perms.include? "spanner.databases.update" #=> false

Parameters:

  • permissions (String, Array<String>) —

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

    • pubsub.databases.create

    • pubsub.databases.list

    • pubsub.databases.update

    • pubsub.databases.updateDdl

    • pubsub.databases.get

    • pubsub.databases.getDdl

    • pubsub.databases.getIamPolicy

    • pubsub.databases.setIamPolicy

    • pubsub.databases.beginReadOnlyTransaction

    • pubsub.databases.beginOrRollbackReadWriteTransaction

    • pubsub.databases.read

    • pubsub.databases.select

    • pubsub.databases.write

    • pubsub.databases.drop

Returns:

  • (Array<Strings>) —

    The permissions that have access.

See Also:



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

def test_permissions *permissions
  permissions = Array(permissions).flatten
  permissions = Array(permissions).flatten
  ensure_service!
  grpc = service.test_database_permissions \
    instance_id, database_id, permissions
  grpc.permissions
end

#update(statements: [], operation_id: nil) ⇒ Database::Job

Updates the database schema by adding Data Definition Language (DDL) statements to create, update, and delete tables and indexes.

Examples:

require "google/cloud/spanner"

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

add_users_table_sql = %q(
  CREATE TABLE users (
    id INT64 NOT NULL,
    username STRING(25) NOT NULL,
    name STRING(45) NOT NULL,
    email STRING(128),
  ) PRIMARY KEY(id)
)

database.update statements: [add_users_table_sql]

Parameters:

  • statements (Array<String>) (defaults to: []) —

    The DDL statements to be applied to the database.

  • operation_id (String, nil) (defaults to: nil) —

    The operation ID used to perform the update. When ‘nil`, the update request is assigned an automatically-generated operation ID. Specifying an explicit value simplifies determining whether the statements were executed in the event that the update is replayed, or the return value is otherwise lost. This value should be unique within the database, and must be a valid identifier: `[a-z]*`. Will raise AlreadyExistsError if the named operation already exists. Optional.

Returns:

  • (Database::Job) —

    The job representing the long-running, asynchronous processing of a database schema update operation.

See Also:



199
200
201
202
203
204
205
 
# File 'lib/google/cloud/spanner/database.rb', line 199

def update statements: [], operation_id: nil
  ensure_service!
  grpc = service.update_database_ddl instance_id, database_id,
                                     statements: statements,
                                     operation_id: operation_id
  Database::Job.from_grpc grpc, service
end