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) 


106
107
108
 
# File 'lib/google/cloud/spanner/database.rb', line 106

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:



150
151
152
153
154
155
 
# File 'lib/google/cloud/spanner/database.rb', line 150

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.



217
218
219
220
221
 
# File 'lib/google/cloud/spanner/database.rb', line 217

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) 


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

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:



257
258
259
260
261
262
263
264
 
# File 'lib/google/cloud/spanner/database.rb', line 257

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) 


113
114
115
 
# File 'lib/google/cloud/spanner/database.rb', line 113

def ready?
  state == :READY
end

#state ⇒ Symbol

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

Returns:

  • (Symbol) 


98
99
100
 
# File 'lib/google/cloud/spanner/database.rb', line 98

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:



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

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:



196
197
198
199
200
201
202
 
# File 'lib/google/cloud/spanner/database.rb', line 196

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:



295
296
297
298
299
300
 
# File 'lib/google/cloud/spanner/database.rb', line 295

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