google-cloud-spanner 1.15.0 → 1.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31f7875bf6e782a6e02f78fc4c56059b6a7a33aad2aea8e5bb8ddb93932749e6
-  data.tar.gz: 2d0babe313899246327cdc92fe537a94e5b2a8d58d2e300913bc79bfac4ced84
+  metadata.gz: f50e50b175e8946175ae34b8eae4e2ad6a9df8c2ab38ab71db0f4a7820b683f5
+  data.tar.gz: 3494e84da57d1d7f98fb96069435106d91a7c84d773e26722073ade94f2b47fe
 SHA512:
-  metadata.gz: 73fd57fd66a11124e0e987f9dedde6bc1435a5ada931fab6eec310ecc219c977c977eef845eeb134f184dd41903a8f60a630573ba455f597ddbbcd768c00a593
-  data.tar.gz: 39c0e508c9f06534fa6ea0ba9ecf91fff841b6d4709ccdfd2cbcafefa879b47a2c96d9678a96de109098962f4a31b462eea1893f2a00d0025a76f1c6fb2cb1b0
+  metadata.gz: bbcf972b4d1548ebfae47f13ac49f5f77472b6ce914172ac56acbb42b46f44c2a047868bee5dc8f1bf0a33bce4d937720be43a6e6bc349d661090c1e6e89fe70
+  data.tar.gz: 796d977752cd8f8cd699237fda28fcf964324e7542feb4ac1b9d9b6a6eeeb07111d4473292e318fb72b6d35ea5d4853b023770625ec225b6067ddbb0eba2102e

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 1.16.0 / 2020-03-20
+
+#### Features
+
+* Added support for backing up and restoring databases  ([#5053](https://www.github.com/googleapis/google-cloud-ruby/issues/5053))
+
 ### 1.15.0 / 2020-03-15
 
 #### Features

data/lib/google/cloud/spanner/admin/database/v1/database_admin_client_config.json

@@ -66,7 +66,7 @@
           "retry_params_name": "default"
         },
         "CreateBackup": {
-          "timeout_millis": 30000,
+          "timeout_millis": 3600000,
           "retry_codes_name": "non_idempotent",
           "retry_params_name": "default"
         },
@@ -76,12 +76,12 @@
           "retry_params_name": "default"
         },
         "UpdateBackup": {
-          "timeout_millis": 30000,
+          "timeout_millis": 3600000,
           "retry_codes_name": "non_idempotent",
           "retry_params_name": "default"
         },
         "DeleteBackup": {
-          "timeout_millis": 30000,
+          "timeout_millis": 3600000,
           "retry_codes_name": "idempotent",
           "retry_params_name": "default"
         },
@@ -91,7 +91,7 @@
           "retry_params_name": "default"
         },
         "RestoreDatabase": {
-          "timeout_millis": 30000,
+          "timeout_millis": 3600000,
           "retry_codes_name": "non_idempotent",
           "retry_params_name": "default"
         },

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

@@ -0,0 +1,315 @@
+# 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.
+
+
+require "google/cloud/spanner/backup/job"
+require "google/cloud/spanner/backup/list"
+require "google/cloud/spanner/backup/restore/job"
+
+module Google
+  module Cloud
+    module Spanner
+      ##
+      # # Backup
+      #
+      # A backup is a representation of Cloud Spanner database backup.
+      #
+      # See {Google::Cloud::Spanner::Instance#backups},
+      # {Google::Cloud::Spanner::Instance#backup}, and
+      # {Google::Cloud::Spanner::Database#create_backup}.
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   spanner = Google::Cloud::Spanner.new
+      #   database = spanner.database "my-instance", "my-database"
+      #
+      #   expire_time = Time.now + 36000
+      #   job = database.create_backup "my-backup", expire_time
+      #
+      #   job.done? #=> false
+      #   job.reload! # API call
+      #   job.done? #=> true
+      #
+      #   if job.error?
+      #     status = job.error
+      #   else
+      #     backup = job.backup
+      #   end
+      #
+      class Backup
+        ##
+        # @private The gRPC Service object.
+        attr_accessor :service
+
+        ##
+        # @private Creates a new Backup instance.
+        def initialize grpc, service
+          @grpc = grpc
+          @service = service
+        end
+
+        ##
+        # The unique identifier for the project.
+        # @return [String]
+        def project_id
+          @grpc.name.split("/")[1]
+        end
+
+        ##
+        # The unique identifier for the instance.
+        # @return [String]
+        def instance_id
+          @grpc.name.split("/")[3]
+        end
+
+        ##
+        # The unique identifier for the backup.
+        # @return [String]
+        def backup_id
+          @grpc.name.split("/")[5]
+        end
+
+        ##
+        # Name of the database from which this backup was created.
+        # @return [String]
+        def database_id
+          @grpc.database.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.name
+        end
+
+        ##
+        # The current backup state. Possible values are `:CREATING` and
+        # `:READY`.
+        # @return [Symbol]
+        def state
+          @grpc.state
+        end
+
+        ##
+        # The backup is still being created. A backup is not yet available
+        # for the database restore operation.
+        # @return [Boolean]
+        def creating?
+          state == :CREATING
+        end
+
+        ##
+        # The backup is created and can be used to restore a database.
+        # @return [Boolean]
+        def ready?
+          state == :READY
+        end
+
+        ##
+        # The expiration time of the backup, with microseconds granularity.
+        # @return [Time]
+        def expire_time
+          Convert.timestamp_to_time @grpc.expire_time
+        end
+
+        ##
+        # Update backup expiration time.
+        #
+        # Set 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. Once the `expire_time` has passed, Cloud Spanner
+        # will delete the backup and free the resources used by the backup.
+        #
+        # @param [Time] time Backup expiration time.
+        # @raise [Google::Cloud::Error] if expire time is in past or update
+        #   call is aborted.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   backup = instance.backup "my-backup"
+        #   backup.expire_time = Time.now + 36000
+        #   puts backup.expire_time
+        #
+        def expire_time= time
+          ensure_service!
+
+          expire_time_was = @grpc.expire_time
+          @grpc.expire_time = Convert.time_to_timestamp time
+          update_mask = Google::Protobuf::FieldMask.new paths: ["expire_time"]
+          @grpc = service.update_backup @grpc, update_mask
+        rescue Google::Cloud::Error => error
+          @grpc.expire_time = expire_time_was
+          raise error
+        end
+
+        ##
+        # Create time is approximately the time when the backup request was
+        # received.
+        # @return [Time]
+        def create_time
+          Convert.timestamp_to_time @grpc.create_time
+        end
+
+        ##
+        # Size of the backup in bytes.
+        # @return [Integer]
+        def size_in_bytes
+          @grpc.size_bytes
+        end
+
+        ##
+        # The instances of the restored databases that reference the backup.
+        # Referencing databases may exist in different instances.
+        # The existence of any referencing database prevents the backup from
+        # being deleted. When a restored database from the backup enters the
+        # `READY` state, the reference to the backup is removed.
+        #
+        # @return [Array<Google::Cloud::Spanner::Database>] Returns list of
+        #   referencing database instances.
+        #
+        # @example
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   backup = instance.backup "my-backup"
+        #
+        #   backup.referencing_databases.each do |database|
+        #     puts database.database_id
+        #   end
+        #
+        def referencing_databases
+          ensure_service!
+
+          @grpc.referencing_databases.map do |referencing_database|
+            segments = referencing_database.split "/"
+            database_grpc = service.get_database segments[3], segments[5]
+            Database.from_grpc database_grpc, service
+          end
+        end
+
+        ##
+        # Permanently deletes the backup.
+        #
+        # @return [Boolean] Returns `true` if the backup was deleted.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   backup = instance.backup "my-backup"
+        #   backup.delete # true
+        #
+        def delete
+          ensure_service!
+          service.delete_backup instance_id, backup_id
+          true
+        end
+
+        ##
+        # Restores deleted database from the backup.
+        #
+        # @param [String] database_id The unique identifier for the database,
+        #   which cannot be changed after the database is created. Values are of
+        #   the form `[a-z][a-z0-9_\-]*[a-z0-9]` and must be between 2 and 30
+        #   characters in length. Required.
+        # @param [String] instance_id The name of the instance in which to
+        #   create the restored database. This instance must be in the same
+        #   project and have the same instance configuration as the instance
+        #   containing the source backup. Optional. Default value is same as a
+        #   backup instance.
+        # @return [Database] Restored database.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   backup = instance.backup "my-backup"
+        #   job = backup.restore "my-restored-database"
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     database = job.database
+        #   end
+        #
+        # @example Restore database in provided instance id
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   backup = instance.backup "my-backup"
+        #   job = backup.restore(
+        #     "my-restored-database",
+        #     instance_id: "other-instance"
+        #   )
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     database = job.database
+        #   end
+        #
+        def restore database_id, instance_id: nil
+          ensure_service!
+
+          instance_id ||= self.instance_id
+
+          grpc = service.restore_database \
+            self.instance_id,
+            backup_id,
+            instance_id,
+            database_id
+          Restore::Job.from_grpc grpc, service
+        end
+
+        ##
+        # @private
+        # Creates a new Backup instance from a
+        # {Google::Spanner::Admin::Database::V1::Backup}.
+        def self.from_grpc grpc, service
+          new grpc, service
+        end
+
+        protected
+
+        ##
+        # @private Raise an error unless an active connection to the service is
+        # available.
+        def ensure_service!
+          raise "Must have active connection to service" unless service
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,274 @@
+# 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.
+
+
+require "google/cloud/spanner/status"
+require "google/cloud/spanner/backup/job/list"
+
+module Google
+  module Cloud
+    module Spanner
+      class Backup
+        ##
+        # # Job
+        #
+        # A resource representing the long-running, asynchronous processing of
+        # backup creation. The job can be refreshed to retrieve the backup
+        # object once the operation has been completed.
+        #
+        # See {Google::Cloud::Spanner::Database#create_backup}
+        #
+        # @see https://cloud.google.com/spanner/reference/rpc/google.longrunning#google.longrunning.Operation
+        #   Long-running Operation
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   database = spanner.database "my-instance", "my-database"
+        #   expire_time = Time.now + 36000
+        #   job = database.create_backup "my-backup", expire_time: expire_time
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     backup = job.backup
+        #   end
+        #
+        class Job
+          ##
+          # @private The Google::Gax::Operation gRPC object.
+          attr_accessor :grpc
+
+          ##
+          # @private The gRPC Service object.
+          attr_accessor :service
+
+          ##
+          # @private Creates a new Backup::Job instance.
+          def initialize
+            @grpc = nil
+            @service = nil
+          end
+
+          ##
+          # The backup is the object of the operation.
+          #
+          # @return [Backup, nil] The backup, or
+          #   `nil` if the operation is not complete.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.done? #=> false
+          #   job.reload!
+          #   job.done? #=> true
+          #   backup = job.backup
+          #
+          def backup
+            return nil unless done?
+            return nil unless @grpc.grpc_op.result == :response
+            Backup.from_grpc @grpc.results, service
+          end
+
+          ##
+          # Checks if the processing of the backup operation is complete.
+          #
+          # @return [boolean] `true` when complete, `false` otherwise.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.done? #=> false
+          #
+          def done?
+            @grpc.done?
+          end
+
+          ##
+          # Checks if the processing of the backup operation has errored.
+          #
+          # @return [boolean] `true` when errored, `false` otherwise.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.error? #=> false
+          #
+          def error?
+            @grpc.error?
+          end
+
+          ##
+          # The status if the operation associated with this job produced an
+          # error.
+          #
+          # @return [Google::Cloud::Spanner::Status, nil] A status object with
+          #   the status code and message, or `nil` if no error occurred.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.error? # true
+          #
+          #   error = job.error
+          #
+          def error
+            return nil unless error?
+            Google::Cloud::Spanner::Status.from_grpc @grpc.error
+          end
+
+          ##
+          # Reloads the job with current data from the long-running,
+          # asynchronous processing of a backup operation.
+          #
+          # @return [Google::Cloud::Spanner::Backup::Job] The same job
+          #   instance.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.done? #=> false
+          #   job.reload! # API call
+          #   job.done? #=> true
+          #
+          def reload!
+            @grpc.reload!
+            self
+          end
+          alias refresh! reload!
+
+          ##
+          # Reloads the job until the operation is complete. The delay between
+          # reloads will incrementally increase.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.done? #=> false
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          def wait_until_done!
+            @grpc.wait_until_done!
+          end
+
+          ##
+          # Cancel the backup job.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.done? #=> false
+          #   job.cancel
+          #
+          def cancel
+            @grpc.cancel
+          end
+
+          ##
+          # The operation progress in percentage.
+          #
+          # @return [Integer]
+          def progress_percent
+            @grpc.metadata.progress.progress_percent
+          end
+
+          ##
+          # The operation start time.
+          #
+          # @return [Time, nil]
+          def start_time
+            return nil unless @grpc.metadata.progress.start_time
+            Convert.timestamp_to_time @grpc.metadata.progress.start_time
+          end
+
+          ##
+          # The operation end time.
+          #
+          # @return [Time, nil]
+          def end_time
+            return nil unless @grpc.metadata.progress.end_time
+            Convert.timestamp_to_time @grpc.metadata.progress.end_time
+          end
+
+          ##
+          # The operation canceled time.
+          #
+          # @return [Time, nil]
+          def cancel_time
+            return nil unless @grpc.metadata.cancel_time
+            Convert.timestamp_to_time @grpc.metadata.cancel_time
+          end
+
+          ##
+          # @private New Backup::Job from a Google::Gax::Operation object.
+          def self.from_grpc grpc, service
+            new.tap do |job|
+              job.instance_variable_set :@grpc, grpc
+              job.instance_variable_set :@service, service
+            end
+          end
+        end
+      end
+    end
+  end
+end