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,
lib/google/cloud/spanner/database/job/list.rb,
lib/google/cloud/spanner/database/backup_info.rb,
lib/google/cloud/spanner/database/restore_info.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: BackupInfo, Job, List, RestoreInfo

Instance Method Summary collapse

Instance Method Details

#backups(page_size: nil) ⇒ Array<Google::Cloud::Spanner::Backup>

Retrieves backups belonging to the database.

Examples:

require "google/cloud/spanner"

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

database.backups.all.each do |backup|
  puts backup.backup_id
end

List backups by page size

require "google/cloud/spanner"

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

database.backups(page_size: 5).all.each do |backup|
  puts backup.backup_id
end

Parameters:

  • page_size (Integer) (defaults to: nil) —

    Optional. Number of backups to be returned in the response. If 0 or less, defaults to the server's maximum allowed page size.

Returns:



486
487
488
489
490
491
492
493
 
# File 'lib/google/cloud/spanner/database.rb', line 486

def backups page_size: nil
  ensure_service!
  grpc = service.list_backups \
    instance_id,
    filter: "database:#{database_id}",
    page_size: page_size
  Backup::List.from_grpc grpc, service
end

#create_backup(backup_id, expire_time, version_time: nil) ⇒ Google::Cloud::Spanner::Backup::Job

Creates a database backup.

Examples:

Create backup with expiration time

require "google/cloud/spanner"

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

backup_id = "my-backup"
expire_time = Time.now + (24 * 60 * 60) # 1 day from now
version_time = Time.now - (24 * 60 * 60) # 1 day ago (optional)

job = database.create_backup backup_id, expire_time, version_time: version_time

job.done? #=> false
job.reload! # API call
job.done? #=> true

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

Parameters:

  • backup_id (String) —

    The unique identifier for the backup. Values are of the form [a-z][a-z0-9_\-]*[a-z0-9] and must be between 2 and 60 characters in length. Required.

  • expire_time (Time) —

    The expiration time of the backup, with microseconds granularity that must be at least 6 hours and at most 366 days from the time the request is received. Required. Once the expire_time has passed, Cloud Spanner will delete the backup and free the resources used by the backup. Required.

  • version_time (Time) (defaults to: nil) —

    Specifies the time to have an externally consistent copy of the database. If no version time is specified, it will be automatically set to the backup create time. The version time can be as far in the past as specified by the database earliest version time. Optional.

Returns:



446
447
448
449
450
451
452
453
454
455
 
# File 'lib/google/cloud/spanner/database.rb', line 446

def create_backup backup_id, expire_time, version_time: nil
  ensure_service!
  grpc = service.create_backup \
    instance_id,
    database_id,
    backup_id,
    expire_time,
    version_time
  Backup::Job.from_grpc grpc, service
end

#creating? ⇒ Boolean

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

Returns:

  • (Boolean) 


120
121
122
 
# File 'lib/google/cloud/spanner/database.rb', line 120

def creating?
  state == :CREATING
end

#database_id ⇒ String

The unique identifier for the database.

Returns:

  • (String) 


84
85
86
 
# File 'lib/google/cloud/spanner/database.rb', line 84

def database_id
  @grpc.name.split("/")[5]
end

#database_operations(filter: nil, page_size: nil) ⇒ Array<Google::Cloud::Spanner::Database::Job>

Retrieves the list of database operations for the given database.

Examples:

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

database = spanner.database "my-instance", "my-database"

jobs = database.database_operations
jobs.each do |job|
  if job.error?
    p job.error
  else
    p job.database.database_id
  end
end

Retrieve all

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

database = spanner.database "my-instance", "my-database"

jobs = database.database_operations
jobs.all do |job|
  if job.error?
    p job.error
  else
    puts job.database.database_id
  end
end

List by page size

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

database = spanner.database "my-instance", "my-database"

jobs = database.database_operations page_size: 10
jobs.each do |job|
  if job.error?
    p job.error
  else
    puts job.database.database_id
  end
end

Filter and list

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

database = spanner.database "my-instance", "my-database"

jobs = database.database_operations filter: "done:true"
jobs.each do |job|
  if job.error?
    p job.error
  else
    puts job.database.database_id
  end
end

Parameters:

  • filter (String) (defaults to: nil) —

    A filter expression that filters what operations are returned in the response.

    The response returns a list of Google::Longrunning::Operation long-running operations whose names are prefixed by a database name within the specified instance. The long-running operation Google::Longrunning::Operation#metadata metadata field type metadata.type_url describes the type of the metadata.

    The filter expression must specify the field name, a comparison operator, and the value that you want to use for filtering. The value must be a string, a number, or a boolean. The comparison operator must be <, >, <=, >=, !=, =, or :. Colon ':' represents a HAS operator which is roughly synonymous with equality. Filter rules are case insensitive.

    The long-running operation fields eligible for filtering are:

    * `name` --> The name of the long-running operation
* `done` --> False if the operation is in progress, else true.
* `metadata.type_url` (using filter string `metadata.@type`) and
fields in `metadata.value` (using filter string
`metadata.<field_name>`, where <field_name> is a field in
metadata.value) are eligible for filtering.
* `error` --> Error associated with the long-running operation.
* `response.type_url` (using filter string `response.@type`) and
fields in `response.value` (using filter string
`response.<field_name>`, where <field_name> is a field in
response.value)are eligible for filtering.

To filter on multiple expressions, provide each separate
expression within parentheses. By default, each expression
is an AND expression. However, you can include AND, OR, and NOT
expressions explicitly.

    Some examples of using filters are:

    * `done:true` --> The operation is complete.
* `(metadata.@type:type.googleapis.com/google.spanner.admin.\
database.v1.RestoreDatabaseMetadata)
AND (metadata.source_type:BACKUP)
AND (metadata.backup_info.backup:backup_howl)
AND (metadata.name:restored_howl)
AND (metadata.progress.start_time < \"2018-03-28T14:50:00Z\")
AND (error:*)`
--> Return RestoreDatabase operations from backups whose name
contains "backup_howl", where the created database name
contains the string "restored_howl", the start_time of the
restore operation is before 2018-03-28T14:50:00Z,
and the operation returned an error.
  • page_size (Integer) (defaults to: nil) —

    The maximum number of resources contained in the underlying API response. If page streaming is performed per-resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.

Returns:



385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
 
# File 'lib/google/cloud/spanner/database.rb', line 385

def database_operations filter: nil, page_size: nil
  database_filter = format(
    DATBASE_OPERATION_METADAT_FILTER_TEMPLATE,
    database_id: database_id
  )

  if filter
    database_filter = format(
      "(%<filter>s) AND (%<database_filter>s)",
      filter: filter, database_filter: database_filter
    )
  end

  grpc = service.list_database_operations instance_id,
                                          filter: database_filter,
                                          page_size: page_size
  Database::Job::List.from_grpc grpc, service
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:



171
172
173
174
175
176
 
# File 'lib/google/cloud/spanner/database.rb', line 171

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.



238
239
240
241
242
 
# File 'lib/google/cloud/spanner/database.rb', line 238

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

#earliest_version_time ⇒ Time

The earliest available version time for a database.

Returns:

  • (Time) 


96
97
98
 
# File 'lib/google/cloud/spanner/database.rb', line 96

def earliest_version_time
  Convert.timestamp_to_time @grpc.earliest_version_time
end

#instance_id ⇒ String

The unique identifier for the instance.

Returns:

  • (String) 


78
79
80
 
# File 'lib/google/cloud/spanner/database.rb', line 78

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) 


104
105
106
 
# File 'lib/google/cloud/spanner/database.rb', line 104

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:



537
538
539
540
541
542
543
544
 
# File 'lib/google/cloud/spanner/database.rb', line 537

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) 


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

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

#ready? ⇒ Boolean

The database is fully created and ready for use.

Returns:

  • (Boolean) 


127
128
129
 
# File 'lib/google/cloud/spanner/database.rb', line 127

def ready?
  state == :READY
end

#ready_optimizing? ⇒ Boolean

The database is fully created from backup and optimizing.

Returns:

  • (Boolean) 


134
135
136
 
# File 'lib/google/cloud/spanner/database.rb', line 134

def ready_optimizing?
  state == :READY_OPTIMIZING
end

#restore_info ⇒ Google::Cloud::Spanner::Database::RestoreInfo?

Information about the source used to restore the database.

Returns:



498
499
500
501
 
# File 'lib/google/cloud/spanner/database.rb', line 498

def restore_info
  return nil unless @grpc.restore_info
  RestoreInfo.from_grpc @grpc.restore_info
end

#state ⇒ Symbol

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

Returns:

  • (Symbol) 


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

def state
  @grpc.state
end

#test_permissions(*permissions) ⇒ Array<Strings>

Tests the specified permissions against the Cloud IAM access control policy.

  • spanner.databases.beginPartitionedDmlTransaction
  • spanner.databases.create
  • spanner.databases.createBackup
  • spanner.databases.list
  • spanner.databases.update
  • spanner.databases.updateDdl
  • spanner.databases.get
  • spanner.databases.getDdl
  • spanner.databases.getIamPolicy
  • spanner.databases.setIamPolicy
  • spanner.databases.beginReadOnlyTransaction
  • spanner.databases.beginOrRollbackReadWriteTransaction
  • spanner.databases.read
  • spanner.databases.select
  • spanner.databases.write
  • spanner.databases.drop

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:

Returns:

  • (Array<Strings>) —

    The permissions that have access.

See Also:



625
626
627
628
629
630
631
632
 
# File 'lib/google/cloud/spanner/database.rb', line 625

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:



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

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:



575
576
577
578
579
580
 
# File 'lib/google/cloud/spanner/database.rb', line 575

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

#version_retention_period ⇒ String

The version retention period for a database.

Returns:

  • (String) 


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

def version_retention_period
  @grpc.version_retention_period
end