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

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

Deprecated.

Use

Database

NOTE: From google-cloud-spanner/v2.11.0 onwards, new features for mananging databases will only be available through the google-cloud-spanner-admin-database-v1 client. See the README for further details.

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.

Admin::Database#database_admin instead.

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



612
613
614
615
616
617
618
619
 
# File 'lib/google/cloud/spanner/database.rb', line 612

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, encryption_config: 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

Create backup with encryption config

require "google/cloud/spanner"

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

kms_key_name = "projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>"
encryption_config = {
  kms_key_name: kms_key_name,
  encryption_type: :CUSTOMER_MANAGED_ENCRYPTION
}
job = database.create_backup "my-backup",
                             Time.now + 36000,
                             encryption_config: encryption_config

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

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

Raises:

  • (ArgumentError) —

    if :CUSTOMER_MANAGED_ENCRYPTION specified without customer managed kms key.



563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
 
# File 'lib/google/cloud/spanner/database.rb', line 563

def create_backup backup_id, expire_time,
                  version_time: nil, encryption_config: nil
  ensure_service!

  if encryption_config&.include?(:kms_key_name) &&
     encryption_config[:encryption_type] != :CUSTOMER_MANAGED_ENCRYPTION
    raise Google::Cloud::InvalidArgumentError,
          "kms_key_name only used with CUSTOMER_MANAGED_ENCRYPTION"
  end

  grpc = service.create_backup \
    instance_id,
    database_id,
    backup_id,
    expire_time,
    version_time,
    encryption_config: encryption_config
  Backup::Job.from_grpc grpc, service
end

#create_time ⇒ Time

Time at which the database creation started.



132
133
134
 
# File 'lib/google/cloud/spanner/database.rb', line 132

def create_time
  Convert.timestamp_to_time @grpc.create_time
end

#creating? ⇒ Boolean

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



165
166
167
 
# File 'lib/google/cloud/spanner/database.rb', line 165

def creating?
  state == :CREATING
end

#database_id ⇒ String

The unique identifier for the database.



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

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



457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
 
# File 'lib/google/cloud/spanner/database.rb', line 457

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

See Also:



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

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



313
314
315
316
317
 
# File 'lib/google/cloud/spanner/database.rb', line 313

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.



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

def earliest_version_time
  Convert.timestamp_to_time @grpc.earliest_version_time
end

#encryption_config ⇒ Google::Cloud::Spanner::Admin::Database::V1::EncryptionConfig?

An encryption configuration describing the encryption type and key resources in Cloud KMS.



140
141
142
 
# File 'lib/google/cloud/spanner/database.rb', line 140

def encryption_config
  @grpc.encryption_config
end

#encryption_info ⇒ Array<Google::Cloud::Spanner::Admin::Database::V1::EncryptionInfo>

Encryption information for the database.

For databases that are using customer managed encryption, this field contains the encryption information for the database, such as encryption state and the Cloud KMS key versions that are in use.

For databases that are using Google default or other types of encryption, this field is empty.

This field is propagated lazily from the backend. There might be a delay from when a key version is being used and when it appears in this field.



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

def encryption_info
  @grpc.encryption_info.to_a
end

#instance_id ⇒ String

The unique identifier for the instance.



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

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



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

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

See Also:



663
664
665
666
667
668
669
670
 
# File 'lib/google/cloud/spanner/database.rb', line 663

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.



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

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

#ready? ⇒ Boolean

The database is fully created and ready for use.



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

def ready?
  state == :READY
end

#ready_optimizing? ⇒ Boolean

The database is fully created from backup and optimizing.



179
180
181
 
# File 'lib/google/cloud/spanner/database.rb', line 179

def ready_optimizing?
  state == :READY_OPTIMIZING
end

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

Information about the source used to restore the database.



624
625
626
627
 
# File 'lib/google/cloud/spanner/database.rb', line 624

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.



125
126
127
 
# File 'lib/google/cloud/spanner/database.rb', line 125

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

See Also:



751
752
753
754
755
756
757
758
 
# File 'lib/google/cloud/spanner/database.rb', line 751

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, descriptor_set: 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 =
  "    CREATE TABLE users (\n      id INT64 NOT NULL,\n      username STRING(25) NOT NULL,\n      name STRING(45) NOT NULL,\n      email STRING(128),\n    ) PRIMARY KEY(id)\n  SQL\n\ndatabase.update statements: [add_users_table_sql]\n"

require "google/cloud/spanner"

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

create_proto_bundle_sql =
  "    CREATE PROTO BUNDLE (\n      `examples.User`\n    )\n  SQL\n\ncreate_users_table_sql =\n  <<~SQL\n    CREATE TABLE users (\n      id INT64 NOT NULL,\n      user `examples.User` NOT NULL\n    ) PRIMARY KEY (id)\n  SQL\n\ndatabase.update statements: [create_proto_bundle_sql, create_users_table_sql],\n                descriptor_set: \"/usr/local/user_descriptors.pb\"\n"

See Also:



291
292
293
294
295
296
297
298
 
# File 'lib/google/cloud/spanner/database.rb', line 291

def update statements: [], operation_id: nil, descriptor_set: nil
  ensure_service!
  grpc = service.update_database_ddl instance_id, database_id,
                                     statements: statements,
                                     operation_id: operation_id,
                                     descriptor_set: descriptor_set
  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

See Also:



701
702
703
704
705
706
 
# File 'lib/google/cloud/spanner/database.rb', line 701

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.



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

def version_retention_period
  @grpc.version_retention_period
end