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

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

Defined Under Namespace

Classes: Job, List

Instance Method Summary collapse

Instance Method Details

#creating? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def creating?
  state == :CREATING
end

#database_id ⇒ String

The unique identifier for the database.

Returns:

  • (String) 


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

def database_id
  @grpc.name.split("/")[5]
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:



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

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.



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

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

#instance_id ⇒ String

The unique identifier for the instance.

Returns:

  • (String) 


76
77
78
 
# File 'lib/google/cloud/spanner/database.rb', line 76

def instance_id
  @grpc.name.split("/")[3]
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) 


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

def path
  @grpc.name
end

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

Gets the Cloud 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:



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

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
  update_policy policy
end

#project_id ⇒ String

The unique identifier for the project.

Returns:

  • (String) 


70
71
72
 
# File 'lib/google/cloud/spanner/database.rb', line 70

def project_id
  @grpc.name.split("/")[1]
end

#ready? ⇒ Boolean

The database is fully created and ready for use.

Returns:

  • (Boolean) 


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

def ready?
  state == :READY
end

#state ⇒ Symbol

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

Returns:

  • (Symbol) 


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

def state
  @grpc.state
end

#test_permissions(*permissions) ⇒ Array<Strings>

Tests the specified permissions against the Cloud 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:



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

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][a-z0-9_]*. 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:



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

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

#update_policy(new_policy) ⇒ Policy Also known as: policy=

Updates the Cloud 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.update_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:



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

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