google-cloud-spanner 2.3.0 → 2.8.0

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

@@ -69,6 +69,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
         #   | `TIMESTAMP` | `Time`, `DateTime` | |
@@ -127,6 +128,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
         #   | `TIMESTAMP` | `Time`, `DateTime` | |
@@ -184,6 +186,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
         #   | `TIMESTAMP` | `Time`, `DateTime` | |
@@ -243,6 +246,7 @@ module Google
         #   | `BOOL`      | `true`/`false` | |
         #   | `INT64`     | `Integer`      | |
         #   | `FLOAT64`   | `Float`        | |
+        #   | `NUMERIC`   | `BigDecimal`   | |
         #   | `STRING`    | `String`       | |
         #   | `DATE`      | `Date`         | |
         #   | `TIMESTAMP` | `Time`, `DateTime` | |

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

@@ -139,9 +139,10 @@ module Google
         #
         def to_a skip_dup_check: nil
           values.map do |value|
-            if value.is_a? Data
+            case value
+            when Data
               value.to_h skip_dup_check: skip_dup_check
-            elsif value.is_a? Array
+            when Array
               value.map do |v|
                 v.is_a?(Data) ? v.to_h(skip_dup_check: skip_dup_check) : v
               end
@@ -169,9 +170,7 @@ module Google
         #   or indexes and corresponding values.
         #
         def to_h skip_dup_check: nil
-          unless skip_dup_check
-            raise DuplicateNameError if fields.duplicate_names?
-          end
+          raise DuplicateNameError if !skip_dup_check && fields.duplicate_names?
 
           Hash[keys.zip to_a(skip_dup_check: skip_dup_check)]
         end

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

@@ -85,6 +85,18 @@ module Google
           @grpc.name.split("/")[5]
         end
 
+        # The version retention period for a database.
+        # @return [String]
+        def version_retention_period
+          @grpc.version_retention_period
+        end
+
+        # The earliest available version time for a database.
+        # @return [Time]
+        def earliest_version_time
+          Convert.timestamp_to_time @grpc.earliest_version_time
+        end
+
         ##
         # The full path for the database resource. Values are of the form
         # `projects/<project_id>/instances/<instance_id>/databases/<database_id>`.
@@ -101,6 +113,38 @@ module Google
           @grpc.state
         end
 
+        ##
+        # Time at which the database creation started.
+        # @return [Time]
+        def create_time
+          Convert.timestamp_to_time @grpc.create_time
+        end
+
+        # An encryption configuration describing the encryption type and key
+        # resources in Cloud KMS.
+        #
+        # @return [Google::Cloud::Spanner::Admin::Database::V1::EncryptionConfig, nil]
+        def encryption_config
+          @grpc.encryption_config
+        end
+
+        # 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.
+        #
+        # @return [Array<Google::Cloud::Spanner::Admin::Database::V1::EncryptionInfo>]
+        def encryption_info
+          @grpc.encryption_info.to_a
+        end
+
         ##
         # The database is still being created. Operations on the database may
         # raise with `FAILED_PRECONDITION` in this state.
@@ -400,6 +444,31 @@ module Google
         #   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.
+        # @param [Time] version_time 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.
+        # @param [Hash] encryption_config An encryption configuration describing
+        #   the encryption type and key resources in Cloud KMS. Optional. The
+        #   following settings can be provided:
+        #
+        #   * `:kms_key_name` (String) The name of KMS key to use which should
+        #     be the full path, e.g., `projects/<project>/locations/<location>\
+        #     /keyRings/<key_ring>/cryptoKeys/<kms_key_name>`
+        #     This field should be set only when encryption type
+        #     `:CUSTOMER_MANAGED_ENCRYPTION`.
+        #   * `:encryption_type` (Symbol) The encryption type of the backup.
+        #     Valid values are:
+        #       1. `:USE_DATABASE_ENCRYPTION` - Use the same encryption configuration as
+        #         the database.
+        #       2. `:GOOGLE_DEFAULT_ENCRYPTION` - Google default encryption.
+        #       3. `:CUSTOMER_MANAGED_ENCRYPTION` - Use customer managed encryption.
+        #         If specified, `:kms_key_name` must contain a valid Cloud KMS key.
+        #
+        # @raise [ArgumentError] if `:CUSTOMER_MANAGED_ENCRYPTION` specified without
+        #   customer managed kms key.
+        #
         # @return [Google::Cloud::Spanner::Backup::Job] The job representing
         #   the long-running, asynchronous processing of a backup create
         #   operation.
@@ -410,7 +479,36 @@ module Google
         #   spanner = Google::Cloud::Spanner.new
         #   database = spanner.database "my-instance", "my-database"
         #
-        #   job = database.create_backup "my-backup", Time.now + 36000
+        #   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
+        #
+        # @example 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
@@ -422,13 +520,23 @@ module Google
         #     backup = job.backup
         #   end
         #
-        def create_backup backup_id, expire_time
+        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
+            expire_time,
+            version_time,
+            encryption_config: encryption_config
           Backup::Job.from_grpc grpc, service
         end
 

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

@@ -84,14 +84,23 @@ module Google
           end
 
           ##
-          # The backup contains an externally consistent copy of
-          # `source_database` at the timestamp specified by `create_time`.
-          # received.
+          # The timestamp indicating the creation of the backup.
           # @return [Time]
           def create_time
             Convert.timestamp_to_time @grpc.create_time
           end
 
+          ##
+          # The backup contains an externally consistent copy of
+          # `source_database` at the timestamp specified by
+          # the `version_time` received. If no `version_time` was
+          # given during the creation of the backup, the `version_time`
+          # will be the same as the `create_time`.
+          # @return [Time]
+          def version_time
+            Convert.timestamp_to_time @grpc.version_time
+          end
+
           ##
           # @private Creates a new Database::BackupInfo instance from a
           # `Google::Cloud::Spanner::Admin::Database::V1::BackupInfo`.

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

@@ -130,12 +130,12 @@ module Google
             #     job.database.database_id
             #   end
             #
-            def all
+            def all &block
               return enum_for :all unless block_given?
 
               results = self
               loop do
-                results.each { |r| yield r }
+                results.each(&block)
                 break unless next?
                 grpc.next_page
                 results = self.class.from_grpc grpc, service

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

@@ -71,7 +71,7 @@ module Google
             return nil unless next?
             ensure_service!
             options = { token: token, max: @max }
-            grpc = @service.list_databases @instance_id, options
+            grpc = @service.list_databases @instance_id, **options
             self.class.from_grpc grpc, @service, @max
           end
 
@@ -123,17 +123,17 @@ module Google
           #     puts database.database_id
           #   end
           #
-          def all request_limit: nil
+          def all request_limit: nil, &block
             request_limit = request_limit.to_i if request_limit
             unless block_given?
               return enum_for :all, request_limit: request_limit
             end
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               if request_limit
                 request_limit -= 1
-                break if request_limit < 0
+                break if request_limit.negative?
               end
               break unless results.next?
               results = results.next

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

@@ -57,12 +57,13 @@ module Google
         #   Hash values must contain the type value. If a Hash is used the
         #   fields will be created using the same order as the Hash keys.
         #
-        #   Supported type values incude:
+        #   Supported type values include:
         #
         #   * `:BOOL`
         #   * `:BYTES`
         #   * `:DATE`
         #   * `:FLOAT64`
+        #   * `:NUMERIC`
         #   * `:INT64`
         #   * `:STRING`
         #   * `:TIMESTAMP`
@@ -133,13 +134,14 @@ module Google
         #
         def types
           @grpc_fields.map(&:type).map do |type|
-            if type.code == :ARRAY
+            case type.code
+            when :ARRAY
               if type.array_element_type.code == :STRUCT
                 [Fields.from_grpc(type.array_element_type.struct_type.fields)]
               else
                 [type.array_element_type.code]
               end
-            elsif type.code == :STRUCT
+            when :STRUCT
               Fields.from_grpc type.struct_type.fields
             else
               type.code

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

@@ -68,6 +68,7 @@ module Google
         def initialize grpc, service
           @grpc = grpc
           @service = service
+          @current_values = grpc.to_h
         end
 
         # The unique identifier for the project.
@@ -134,6 +135,23 @@ module Google
         end
         alias node_count= nodes=
 
+        ##
+        # The number of processing units allocated to this instance.
+        #
+        # @return [Integer]
+        def processing_units
+          @grpc.processing_units
+        end
+
+        ##
+        # Updates number of processing units allocated to this instance.
+        #
+        # @param units [Integer] The number of processing units allocated
+        #   to this instance.
+        def processing_units= units
+          @grpc.processing_units = units
+        end
+
         ##
         # The current instance state. Possible values are `:CREATING` and
         # `:READY`.
@@ -188,8 +206,50 @@ module Google
           )
         end
 
+        ##
+        # Update changes.
+        #  `display_name`, `labels`, `nodes`, `processing_units` can be
+        #  updated. `processing_units` and `nodes` can be used interchangeably
+        #  to update.
+        #
+        # @return [Instance::Job] The job representing the long-running,
+        #   asynchronous processing of an instance update operation.
+        # @raise [ArgumentError] if both processing_units or nodes are specified.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #   instance.display_name = "prod-instance"
+        #   instance.labels = { env: "prod", app: "api" }
+        #   instance.nodes = 2
+        #   # OR
+        #   # instance.processing_units = 500
+        #
+        #   job = instance.save
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     instance = job.instance
+        #   end
+        #
         def save
-          job_grpc = service.update_instance @grpc
+          ensure_service!
+
+          field_mask = []
+          @current_values.each do |field, value|
+            field_mask << field unless @grpc[field.to_s] == value
+          end
+
+          job_grpc = service.update_instance @grpc, field_mask: field_mask
+          @current_values = @grpc.to_h
           Instance::Job.from_grpc job_grpc, service
         end
         alias update save
@@ -306,6 +366,13 @@ module Google
         #   These statements execute atomically with the creation of the
         #   database: if there is an error in any statement, the database is not
         #   created. Optional.
+        # @param [Hash] encryption_config An encryption configuration describing
+        #   the encryption type and key resources in Cloud KMS. Optional. The
+        #   following settings can be provided:
+        #
+        #   * `:kms_key_name` (String) The name of KMS key to use which should
+        #     be the full path, e.g., `projects/<project>/locations/<location>\
+        #     /keyRings/<key_ring>/cryptoKeys/<kms_key_name>`
         #
         # @return [Database::Job] The job representing the long-running,
         #   asynchronous processing of a database create operation.
@@ -328,9 +395,30 @@ module Google
         #     database = job.database
         #   end
         #
-        def create_database database_id, statements: []
+        # @example Create with encryption config
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance = spanner.instance "my-instance"
+        #
+        #   kms_key_name = "projects/<project>/locations/<location>/keyRings/<key_ring>/cryptoKeys/<kms_key_name>"
+        #   job = instance.create_database "my-new-database", encryption_config: { kms_key_name: kms_key_name }
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     database = job.database
+        #   end
+        #
+        def create_database database_id, statements: [], encryption_config: nil
           grpc = service.create_database instance_id, database_id,
-                                         statements: statements
+                                         statements: statements,
+                                         encryption_config: encryption_config
           Database::Job.from_grpc grpc, service
         end
 

data/lib/google/cloud/spanner/instance/config/list.rb

@@ -73,7 +73,7 @@ module Google
               return nil unless next?
               ensure_service!
               options = { token: token, max: @max }
-              grpc = @service.list_instance_configs options
+              grpc = @service.list_instance_configs(**options)
               self.class.from_grpc grpc, @service, @max
             end
 
@@ -123,17 +123,17 @@ module Google
             #     puts config.instance_config_id
             #   end
             #
-            def all request_limit: nil
+            def all request_limit: nil, &block
               request_limit = request_limit.to_i if request_limit
               unless block_given?
                 return enum_for :all, request_limit: request_limit
               end
               results = self
               loop do
-                results.each { |r| yield r }
+                results.each(&block)
                 if request_limit
                   request_limit -= 1
-                  break if request_limit < 0
+                  break if request_limit.negative?
                 end
                 break unless results.next?
                 results = results.next