google-cloud-spanner 1.14.0 → 2.0.0

data/lib/google/cloud/spanner/credentials.rb

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 
-require "google/cloud/spanner/v1/credentials"
+require "google/cloud/spanner/v1/spanner/credentials"
 
 module Google
   module Cloud
@@ -37,7 +37,7 @@ module Google
       #
       #   spanner.project_id #=> "my-project"
       #
-      class Credentials < Google::Cloud::Spanner::V1::Credentials
+      class Credentials < Google::Cloud::Spanner::V1::Spanner::Credentials
       end
     end
   end

data/lib/google/cloud/spanner/data.rb

@@ -216,9 +216,9 @@ module Google
         ##
         # @private
         def to_grpc_type
-          Google::Spanner::V1::Type.new(
+          V1::Type.new(
             code: :STRUCT,
-            struct_type: Google::Spanner::V1::StructType.new(
+            struct_type: V1::StructType.new(
               fields: @grpc_fields
             )
           )

data/lib/google/cloud/spanner/database.rb

@@ -15,6 +15,8 @@
 
 require "google/cloud/spanner/database/job"
 require "google/cloud/spanner/database/list"
+require "google/cloud/spanner/database/restore_info"
+require "google/cloud/spanner/backup"
 require "google/cloud/spanner/policy"
 
 module Google
@@ -114,6 +116,13 @@ module Google
           state == :READY
         end
 
+        ##
+        # The database is fully created from backup and optimizing.
+        # @return [Boolean]
+        def ready_optimizing?
+          state == :READY_OPTIMIZING
+        end
+
         ##
         # Retrieve the Data Definition Language (DDL) statements that define
         # database structures. DDL statements are used to create, update,
@@ -220,6 +229,255 @@ module Google
           true
         end
 
+        # @private
+        DATBASE_OPERATION_METADAT_FILTER_TEMPLATE = [
+          "(metadata.@type:CreateDatabaseMetadata AND " \
+          "metadata.database:%<database_id>s)",
+          "(metadata.@type:RestoreDatabaseMetadata AND "\
+          "metadata.name:%<database_id>s)",
+          "(metadata.@type:UpdateDatabaseDdl AND "\
+          "metadata.database:%<database_id>s)"
+        ].join(" OR ")
+
+        ##
+        # Retrieves the list of database operations for the given database.
+        #
+        # @param filter [String]
+        #   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.
+        # @param page_size [Integer]
+        #   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.
+        #
+        # @return [Array<Google::Cloud::Spanner::Database::Job>] List
+        #   representing the long-running, asynchronous processing
+        #   of a database operations.
+        #   (See {Google::Cloud::Spanner::Database::Job::List})
+        #
+        # @example
+        #   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
+        #
+        # @example 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
+        #
+        # @example 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
+        #
+        # @example 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
+        #
+        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
+
+        ##
+        # Creates a database backup.
+        #
+        # @param [String] backup_id 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.
+        # @param [Time] expire_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.
+        # @return [Google::Cloud::Spanner::Backup::Job] The job representing
+        #   the long-running, asynchronous processing of a backup create
+        #   operation.
+        #
+        # @example Create backup with expiration time
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   database = spanner.database "my-instance", "my-database"
+        #
+        #   job = database.create_backup "my-backup", Time.now + 36000
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     backup = job.backup
+        #   end
+        #
+        def create_backup backup_id, expire_time
+          ensure_service!
+          grpc = service.create_backup \
+            instance_id,
+            database_id,
+            backup_id,
+            expire_time
+          Backup::Job.from_grpc grpc, service
+        end
+
+        ##
+        # Retrieves backups belonging to the database.
+        #
+        # @param [Integer] page_size Optional. Number of backups to be returned
+        #   in the response. If 0 or less, defaults to the server's maximum
+        #   allowed page size.
+        # @return [Array<Google::Cloud::Spanner::Backup>] Enumerable list of
+        #   backups. (See {Google::Cloud::Spanner::Backup::List})
+        #
+        # @example
+        #   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
+        #
+        # @example 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
+        #
+        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
+
+        # Information about the source used to restore the database.
+        #
+        # @return [Google::Cloud::Spanner::Database::RestoreInfo, nil]
+        def restore_info
+          return nil unless @grpc.restore_info
+          RestoreInfo.from_grpc @grpc.restore_info
+        end
+
         ##
         # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
         # policy for this database.
@@ -313,20 +571,22 @@ module Google
         #
         #   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
+        #  * 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
         #
         # @return [Array<Strings>] The permissions that have access.
         #
@@ -351,7 +611,7 @@ module Google
 
         ##
         # @private Creates a new Database instance from a
-        # Google::Spanner::Admin::Database::V1::Database.
+        # `Google::Cloud::Spanner::Admin::Database::V1::Database`.
         def self.from_grpc grpc, service
           new grpc, service
         end

data/lib/google/cloud/spanner/database/backup_info.rb

@@ -0,0 +1,105 @@
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Spanner
+      class Database
+        class BackupInfo
+          ##
+          # @private Creates a new Database::BackupInfo instance.
+          def initialize grpc
+            @grpc = grpc
+          end
+
+          ##
+          # The unique identifier for the project.
+          # @return [String]
+          def project_id
+            @grpc.backup.split("/")[1]
+          end
+
+          ##
+          # The unique identifier for the instance.
+          # @return [String]
+          def instance_id
+            @grpc.backup.split("/")[3]
+          end
+
+          ##
+          # The unique identifier for the backup.
+          # @return [String]
+          def backup_id
+            @grpc.backup.split("/")[5]
+          end
+
+          ##
+          # The full path for the backup. Values are of the form
+          # `projects/<project>/instances/<instance>/backups/<backup_id>`.
+          # @return [String]
+          def path
+            @grpc.backup
+          end
+
+          ##
+          # Name of the database the backup was created from.
+          # @return [String]
+          def source_database_id
+            @grpc.source_database.split("/")[5]
+          end
+
+          ##
+          # The unique identifier for the source database project.
+          # @return [String]
+          def source_database_project_id
+            @grpc.backup.split("/")[1]
+          end
+
+          ##
+          # The unique identifier for the source database instance.
+          # @return [String]
+          def source_database_instance_id
+            @grpc.backup.split("/")[3]
+          end
+
+          ##
+          # The full path for the source database the backup was created from.
+          # Values are of the form
+          # `projects/<project>/instances/<instance>/database/<database_id>`.
+          # @return [String]
+          def source_database_path
+            @grpc.source_database
+          end
+
+          ##
+          # The backup contains an externally consistent copy of
+          # `source_database` at the timestamp specified by `create_time`.
+          # received.
+          # @return [Time]
+          def create_time
+            Convert.timestamp_to_time @grpc.create_time
+          end
+
+          ##
+          # @private Creates a new Database::BackupInfo instance from a
+          # `Google::Cloud::Spanner::Admin::Database::V1::BackupInfo`.
+          def self.from_grpc grpc
+            new grpc
+          end
+        end
+      end
+    end
+  end
+end