google-cloud-spanner 2.0.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49b3d879f62998284edf63a941432c67a8caebf708f2ef4df883a3f336dbc758
-  data.tar.gz: e6768ee6037df38c765f888f64a4b29cc192b8a30a1bbcf02d01240c3c228621
+  metadata.gz: 9768d839e58d7697a3ec4d57f924c6dd251bf59b1bb531ca2fbcf14da1b6120d
+  data.tar.gz: 2fd33ab3bfddeaed840fd815d057e3ddb81bf3a4b746b88f20dcc72ecca46e44
 SHA512:
-  metadata.gz: 3c456f4ee2482f6b0c488c749f11b508092b9c2a9befe8a4c44c74d6321c3dc1be43a6abd4cfec56c1ca7d2312feb79998383537ebd20bbe6f3d0be10f6cf576
-  data.tar.gz: b31fad2484409183d77bb00e11ba3526fdb9d5ae6817e8a95af51f61e09d7d3635ac7e58c99fbbb4b862b49a3092d59f7e88505aa86cb509ab1d23447ebfb060
+  metadata.gz: ba9f01ea9fc094a4ece357bacddc46cf235704f242eea88393de8ea5b1e5ae56b1f5260ad26e999ad53047d4a4c7f6d855612ea6de139e80ae7d60ec6b305fdf
+  data.tar.gz: fb498abaae70d4b8c56736b8267f87ae3637ddfe6b3aad675ad35c2faa1d4681a3a91be98ce6604454b185557a11aaf5a8294b0e007a849ff08ff19cad3088ae

data/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Release History
 
+### 2.5.0 / 2021-03-10
+
+#### Features
+
+* Drop support for Ruby 2.4 and add support for Ruby 3.0
+
+### 2.4.0 / 2021-02-18
+
+#### Features
+
+* Point In Time Recovery (PITR) ([#8169](https://www.github.com/googleapis/google-cloud-ruby/issues/8169))
+  * feat(spanner): support pitr-lite
+  * feature(spanner): adds test for throttled
+  * feat(spanner): adds version time to backup
+  * test(spanner): adds unit test for create backup
+  * feat(spanner): exposes version time in backup
+  * chore: fixes rubocop violations
+  * fix: addresses PR comments
+  * test: adds integration tests for pitr backup
+
+### 2.3.0 / 2021-02-09
+
+#### Features
+
+* CommitStats in CommitResponse ([#8058](https://www.github.com/googleapis/google-cloud-ruby/issues/8058))
+* optionalize `credentials` when using cloud spanner emulator host ([#8416](https://www.github.com/googleapis/google-cloud-ruby/issues/8416))
+  * Optionalize `credentials` when using Cloud Spanner Emulator
+  * Remove unnecessary credentials stub for emulator_host in Google::Cloud::Spanner.new
+  * Add test of explicit project_id in Google::Cloud::Spanner.new
+  * Update document for `emulator_host` without credentials
+  * Tidy code according to rubocop settings
+
+### 2.2.0 / 2020-09-15
+
+#### Features
+
+* quota_project can be set via library configuration
+* Support numeric type.
+
+#### Bug Fixes
+
+* retry or resume eos and rst_stream errors
+
+### 2.1.0 / 2020-08-05
+
+#### Features
+
+* Support custom setting of timeout and retry
+
 ### 2.0.0 / 2020-07-23
 
 This is a major update that removes the "low-level" client interface code, and

data/CONTRIBUTING.md

@@ -24,7 +24,7 @@ be able to accept your pull requests.
 In order to use the google-cloud-spanner console and run the project's tests,
 there is a small amount of setup:
 
-1. Install Ruby. google-cloud-spanner requires Ruby 2.4+. You may choose to
+1. Install Ruby. google-cloud-spanner requires Ruby 2.5+. You may choose to
    manage your Ruby and gem installations with [RVM](https://rvm.io/),
    [rbenv](https://github.com/rbenv/rbenv), or
    [chruby](https://github.com/postmodern/chruby).
@@ -45,7 +45,7 @@ there is a small amount of setup:
 
    ```sh
    $ cd google-cloud-spanner/
-   $ bundle exec rake bundleupdate
+   $ bundle install
    ```
 
 ## Console

data/LOGGING.md

@@ -3,7 +3,7 @@
 To enable logging for this library, set the logger for the underlying
 [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
 that you set may be a Ruby stdlib
-[`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as
+[`Logger`](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html) as
 shown below, or a
 [`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
 that will write logs to [Stackdriver

data/lib/google-cloud-spanner.rb

@@ -174,6 +174,7 @@ Google::Cloud.configure.add_config! :spanner do |config|
                     allow_nil: true
   config.add_alias! :keyfile, :credentials
   config.add_field! :scope, default_scopes, match: [String, Array]
+  config.add_field! :quota_project, nil, match: String
   config.add_field! :timeout, nil, match: Integer
   config.add_field! :endpoint, "spanner.googleapis.com", match: String
   config.add_field! :emulator_host, default_emulator, match: String, allow_nil: true

data/lib/google/cloud/spanner.rb

@@ -49,6 +49,8 @@ module Google
       # @param [String, Hash, Google::Auth::Credentials] credentials The path to
       #   the keyfile as a String, the contents of the keyfile as a Hash, or a
       #   Google::Auth::Credentials object. (See {Spanner::Credentials})
+      #   If `emulator_host` is present, this becomes optional and the value is
+      #   internally overriden with `:this_channel_is_insecure`.
       # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
       #   the set of resources and operations that the connection can access.
       #   See [Using OAuth 2.0 to Access Google
@@ -60,7 +62,7 @@ module Google
       #   * `https://www.googleapis.com/auth/spanner.data`
       # @param [Integer] timeout Default timeout to use in requests. Optional.
       # @param [String] endpoint Override of the endpoint host name. Optional.
-      #   If the param is nil, uses the default endpoint.
+      #   If the param is nil, uses `emulator_host` or the default endpoint.
       # @param [String] project Alias for the `project_id` argument. Deprecated.
       # @param [String] keyfile Alias for the `credentials` argument.
       #   Deprecated.
@@ -91,19 +93,19 @@ module Google
       def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
                    endpoint: nil, project: nil, keyfile: nil,
                    emulator_host: nil, lib_name: nil, lib_version: nil
-        project_id    ||= (project || default_project_id)
+        project_id    ||= project || default_project_id
         scope         ||= configure.scope
         timeout       ||= configure.timeout
-        endpoint      ||= configure.endpoint
-        credentials   ||= (keyfile || default_credentials(scope: scope))
         emulator_host ||= configure.emulator_host
+        endpoint      ||= emulator_host || configure.endpoint
+        credentials   ||= keyfile
         lib_name      ||= configure.lib_name
         lib_version   ||= configure.lib_version
 
         if emulator_host
           credentials = :this_channel_is_insecure
-          endpoint = emulator_host
         else
+          credentials ||= default_credentials scope: scope
           unless credentials.is_a? Google::Auth::Credentials
             credentials = Spanner::Credentials.new credentials, scope: scope
           end

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

@@ -155,9 +155,17 @@ module Google
           @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
+        rescue Google::Cloud::Error => e
           @grpc.expire_time = expire_time_was
-          raise error
+          raise e
+        end
+
+        ##
+        # The timestamp when a consistent copy of the database for the backup was
+        # taken. The version time has microseconds granularity.
+        # @return [Time]
+        def version_time
+          Convert.timestamp_to_time @grpc.version_time
         end
 
         ##

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

@@ -39,7 +39,7 @@ module Google
         #
         #   database = spanner.database "my-instance", "my-database"
         #   expire_time = Time.now + 36000
-        #   job = database.create_backup "my-backup", expire_time: expire_time
+        #   job = database.create_backup "my-backup", expire_time
         #
         #   job.done? #=> false
         #   job.reload! # API call
@@ -80,7 +80,7 @@ module Google
           #
           #   database = spanner.database "my-instance", "my-database"
           #   expire_time = Time.now + 36000
-          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #   job = database.create_backup "my-backup", expire_time
           #
           #   job.done? #=> false
           #   job.reload!
@@ -105,7 +105,7 @@ module Google
           #
           #   database = spanner.database "my-instance", "my-database"
           #   expire_time = Time.now + 36000
-          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #   job = database.create_backup "my-backup", expire_time
           #
           #   job.done? #=> false
           #
@@ -125,7 +125,7 @@ module Google
           #
           #   database = spanner.database "my-instance", "my-database"
           #   expire_time = Time.now + 36000
-          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #   job = database.create_backup "my-backup", expire_time
           #
           #   job.error? #=> false
           #
@@ -147,7 +147,7 @@ module Google
           #
           #   database = spanner.database "my-instance", "my-database"
           #   expire_time = Time.now + 36000
-          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #   job = database.create_backup "my-backup", expire_time
           #
           #   job.error? # true
           #
@@ -172,7 +172,7 @@ module Google
           #
           #   database = spanner.database "my-instance", "my-database"
           #   expire_time = Time.now + 36000
-          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #   job = database.create_backup "my-backup", expire_time
           #
           #   job.done? #=> false
           #   job.reload! # API call
@@ -195,7 +195,7 @@ module Google
           #
           #   database = spanner.database "my-instance", "my-database"
           #   expire_time = Time.now + 36000
-          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #   job = database.create_backup "my-backup", expire_time
           #
           #   job.done? #=> false
           #   job.wait_until_done!
@@ -215,7 +215,7 @@ module Google
           #
           #   database = spanner.database "my-instance", "my-database"
           #   expire_time = Time.now + 36000
-          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #   job = database.create_backup "my-backup", expire_time
           #
           #   job.done? #=> false
           #   job.cancel

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

@@ -130,12 +130,12 @@ module Google
             #     job.backup.backup_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/backup/list.rb

@@ -128,12 +128,12 @@ module Google
           #     backup.backup_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/batch_snapshot.rb

@@ -173,6 +173,19 @@ module Google
         #   * `:optimizer_version` (String) The version of optimizer to use.
         #     Empty to use database default. "latest" to use the latest
         #     available optimizer version.
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @return [Array<Google::Cloud::Spanner::Partition>] The partitions
         #   created by the query partition.
@@ -196,7 +209,7 @@ module Google
         #
         def partition_query sql, params: nil, types: nil,
                             partition_size_bytes: nil, max_partitions: nil,
-                            query_options: nil
+                            query_options: nil, call_options: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
@@ -204,7 +217,8 @@ module Google
           results = session.partition_query \
             sql, tx_selector, params: params, types: types,
                               partition_size_bytes: partition_size_bytes,
-                              max_partitions: max_partitions
+                              max_partitions: max_partitions,
+                              call_options: call_options
           results.partitions.map do |grpc|
             # Convert partition protos to execute sql request protos
             execute_sql_grpc = V1::ExecuteSqlRequest.new(
@@ -248,6 +262,19 @@ module Google
         #   partitions to return. For example, this may be set to the number of
         #   workers available. This is only a hint and may provide different
         #   results based on the request.
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @return [Array<Google::Cloud::Spanner::Partition>] The partitions
         #   created by the read partition.
@@ -268,7 +295,8 @@ module Google
         #   batch_snapshot.close
         #
         def partition_read table, columns, keys: nil, index: nil,
-                           partition_size_bytes: nil, max_partitions: nil
+                           partition_size_bytes: nil, max_partitions: nil,
+                           call_options: nil
           ensure_session!
 
           columns = Array(columns).map(&:to_s)
@@ -278,7 +306,8 @@ module Google
             table, columns, tx_selector,
             keys: keys, index: index,
             partition_size_bytes: partition_size_bytes,
-            max_partitions: max_partitions
+            max_partitions: max_partitions,
+            call_options: call_options
 
           results.partitions.map do |grpc|
             # Convert partition protos to read request protos
@@ -304,6 +333,19 @@ module Google
         #
         # @param [Google::Cloud::Spanner::Partition] partition The partition to
         #   be executed.
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @example
         #   require "google/cloud/spanner"
@@ -320,7 +362,7 @@ module Google
         #
         #   batch_snapshot.close
         #
-        def execute_partition partition
+        def execute_partition partition, call_options: nil
           ensure_session!
 
           partition = Partition.load partition unless partition.is_a? Partition
@@ -329,10 +371,11 @@ module Google
           # TODO: raise if session.path != partition.session
           # TODO: raise if grpc.transaction != partition.transaction
 
+          opts = { call_options: call_options }
           if partition.execute?
-            execute_partition_query partition
+            execute_partition_query partition, **opts
           elsif partition.read?
-            execute_partition_read partition
+            execute_partition_read partition, **opts
           end
         end
 
@@ -430,6 +473,19 @@ module Google
         #   * `:optimizer_version` (String) The version of optimizer to use.
         #     Empty to use database default. "latest" to use the latest
         #     available optimizer version.
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the query
         #   execution.
@@ -549,14 +605,40 @@ module Google
         #     puts "User #{row[:id]} is #{row[:name]}"
         #   end
         #
-        def execute_query sql, params: nil, types: nil, query_options: nil
+        # @example Query using custom timeout and retry policy:
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #   batch_client = spanner.batch_client "my-instance", "my-database"
+        #   batch_snapshot = batch_client.batch_snapshot
+        #
+        #   timeout = 30.0
+        #   retry_policy = {
+        #     initial_delay: 0.25,
+        #     max_delay:     32.0,
+        #     multiplier:    1.3,
+        #     retry_codes:   ["UNAVAILABLE"]
+        #   }
+        #   call_options = { timeout: timeout, retry_policy: retry_policy }
+        #
+        #   results = batch_snapshot.execute_query \
+        #      "SELECT * FROM users",
+        #      call_options: call_options
+        #
+        #   results.rows.each do |row|
+        #     puts "User #{row[:id]} is #{row[:name]}"
+        #   end
+        #
+        def execute_query sql, params: nil, types: nil, query_options: nil,
+                          call_options: nil
           ensure_session!
 
           params, types = Convert.to_input_params_and_types params, types
 
           session.execute_query sql, params: params, types: types,
                                 transaction: tx_selector,
-                                query_options: query_options
+                                query_options: query_options,
+                                call_options: call_options
         end
         alias execute execute_query
         alias query execute_query
@@ -578,6 +660,19 @@ module Google
         #   Optional.
         # @param [Integer] limit If greater than zero, no more than this number
         #   of rows will be returned. The default is no limit.
+        # @param [Hash] call_options A hash of values to specify the custom
+        #   call options, e.g., timeout, retries, etc. Call options are
+        #   optional. The following settings can be provided:
+        #
+        #   * `:timeout` (Numeric) A numeric value of custom timeout in seconds
+        #     that overrides the default setting.
+        #   * `:retry_policy` (Hash) A hash of values that overrides the default
+        #     setting of retry policy with the following keys:
+        #     * `:initial_delay` (`Numeric`) - The initial delay in seconds.
+        #     * `:max_delay` (`Numeric`) - The max delay in seconds.
+        #     * `:multiplier` (`Numeric`) - The incremental backoff multiplier.
+        #     * `:retry_codes` (`Array<String>`) - The error codes that should
+        #       trigger a retry.
         #
         # @return [Google::Cloud::Spanner::Results] The results of the read
         #   operation.
@@ -595,14 +690,16 @@ module Google
         #     puts "User #{row[:id]} is #{row[:name]}"
         #   end
         #
-        def read table, columns, keys: nil, index: nil, limit: nil
+        def read table, columns, keys: nil, index: nil, limit: nil,
+                 call_options: nil
           ensure_session!
 
           columns = Array(columns).map(&:to_s)
           keys = Convert.to_key_set keys
 
           session.read table, columns, keys: keys, index: index, limit: limit,
-                                       transaction: tx_selector
+                                       transaction: tx_selector,
+                                       call_options: call_options
         end
 
         ##
@@ -690,7 +787,7 @@ module Google
           raise "Must have active connection to service" unless session
         end
 
-        def execute_partition_query partition
+        def execute_partition_query partition, call_options: nil
           query_options = partition.execute.query_options
           query_options = query_options.to_h unless query_options.nil?
           session.execute_query \
@@ -699,16 +796,18 @@ module Google
             types: partition.execute.param_types.to_h,
             transaction: partition.execute.transaction,
             partition_token: partition.execute.partition_token,
-            query_options: query_options
+            query_options: query_options,
+            call_options: call_options
         end
 
-        def execute_partition_read partition
+        def execute_partition_read partition, call_options: nil
           session.read partition.read.table,
                        partition.read.columns.to_a,
                        keys: partition.read.key_set,
                        index: partition.read.index,
                        transaction: partition.read.transaction,
-                       partition_token: partition.read.partition_token
+                       partition_token: partition.read.partition_token,
+                       call_options: call_options
         end
       end
     end