rb_snowflake_client 1.6.2 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14628efb496cd0a61e49675e329f38d075dd5bb201371df522b7a84e31a6beca
-  data.tar.gz: b8b3618986b2d8d5a24d660270ab8860ebb985718375183c8ab73af0a89cd124
+  metadata.gz: 05c5fef52239a7d043627e57e3a205ef07092452b7c7a47779ad21150637ec66
+  data.tar.gz: f98da0cd8848820a984753175fd9c22d60f41d137da780de0d8d08f99fa4632a
 SHA512:
-  metadata.gz: '00485ce43306464ac2d541a1349879d0e0130c4ced1dba7c785a0c1cd78319954e3eea734c6f77e4448d825f3ed42538f6ea042b1224a01d4b644d587cfa805b'
-  data.tar.gz: 90a65fc0820e5783870540d335a1db672f1a01affb5160cf4d88ba5411217a4e45ad896a16b274061f1d892161863958ad2da1c6ae87a373506c7c59692426f4
+  metadata.gz: f577b2fef1a891a37a0a793a53ed4d24d63e665fc5d6e114332f836a4f12a26494f002bf6a589c1b921df253ccac10d81ad122636e8a0d053f16efe4f1c3313d
+  data.tar.gz: 4cb2888d8274a883689b448ba6acf315b683ba2692612b1d3753921f082ee14cd5292216c436a4e7d4f5b3ef3893af3a946333a6abff710f42c2246400736855

data/.github/workflows/arby-review.yml

@@ -10,13 +10,18 @@
 # Nothing PR-controlled reaches the dispatch: only github.repository and the PR number, passed through env.
 # No checkout, no PR code. The token is minted from the Arby Dispatcher app (Actions: write, installed only on
 # the runner repo) and scoped to that one repo, so all it can do is start runs there. The run's own red/green
-# status shows in the runner repo; on this PR the result is Arby's review. Manual "re-request Arby" reviews
-# aren't supported here yet: push a commit to get a new review.
+# status shows in the runner repo; on this PR the result is Arby's review.
+#
+# Requesting a review: someone with write access requests `rinsed-review-bot` as a reviewer (also on drafts,
+# and also on a PR by an author limit-approval-to doesn't cover, such as an outside contributor's fork PR,
+# which is otherwise not reviewed). The dispatch still carries only the repo and PR number; the runner checks
+# the PR itself for a pending request for Arby made by someone with write access. Such a review is
+# comment-only unless limit-approval-to covers the author.
 name: Arby review (public repo)
 
 on:
   pull_request_target:
-    types: [opened, synchronize, reopened, ready_for_review]
+    types: [opened, synchronize, reopened, ready_for_review, review_requested]
 
 # Nothing by default; each job asks for exactly what it needs.
 permissions: {}
@@ -24,8 +29,11 @@ permissions: {}
 jobs:
   dispatch:
     name: Request Arby review
-    # Drafts skip, as in review.yml.
-    if: github.event.pull_request.draft == false
+    # A request aimed at Arby itself (a team request names no requested_reviewer), drafts included; otherwise
+    # non-drafts only, as in review.yml.
+    if: >-
+      (github.event.action == 'review_requested' && github.event.requested_reviewer.login == 'rinsed-review-bot')
+      || (github.event.action != 'review_requested' && github.event.pull_request.draft == false)
     runs-on: ubuntu-latest
     timeout-minutes: 5
     # Only the app token is used, so the job's own token needs nothing.
@@ -59,6 +67,10 @@ jobs:
   dismiss:
     # The required check is keyed on this name; keep it exactly as is.
     name: Dismiss stale Arby approvals
+    # Runs on review requests too, though they add no commits. Skipping it there would report a newer,
+    # skipped check, which satisfies the required check even while the dismissal for the latest push failed
+    # or is still running. A request that cancels an in-flight run below is harmless: the new run reads the
+    # current head itself and dismisses everything the cancelled one would have.
     concurrency:
       group: arby-dismiss-stale-${{ github.event.pull_request.number }}
       cancel-in-progress: true

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## [1.7.0] - 2026-10-22
+### Added
+- `query` accepts `parameters:` for Snowflake session parameters such as `QUERY_TAG` (#163, thanks Elayamani K)
+- `*_OUTPUT_FORMAT` parameters raise `ArgumentError`: the client parses Snowflake's default date and time
+  encodings, and returns binary values in its default hex (#197)
+### Changed
+- A failed partition fetch that isn't a pool timeout raises `RubySnowflake::Error` with the original as `cause`,
+  not the `ConnectionStarvedError` the threaded path raised in 1.6.2: code that rescues only
+  `ConnectionStarvedError` (e.g. to retry) should rescue `RubySnowflake::Error` or check `cause` (#197)
+### Fixed
+- Streaming results no longer leak a thread per query (#163, thanks Nate Berkopec)
+- Stopping a stream early doesn't wait for its prefetch to finish (#197)
+- Threaded in-memory results no longer leak their threads (#197)
+- A failed partition fetch always raises; it could yield a `nil` partition before (#197, thanks Justin Léger)
+- A failed fetch or an interrupt cancels the partition fetches that haven't started (#197, thanks Justin Léger)
+- No longer requires `benchmark`, which isn't a default gem from Ruby 4.0, so loading the client doesn't need it
+  in the bundle (#198)
+
 ## [1.6.2] - 2026-10-19
 ### Fixed
 - Compatibility with `json` 3.0, where `JSON.parse` options are keyword-only: every query raised

data/README.md

@@ -160,6 +160,35 @@ client.query(query, bindings: bindings)
 
 For additional information about binding parameters refer to snowflake documentation: https://docs.snowflake.com/en/developer-guide/sql-api/submitting-requests#using-bind-variables-in-a-statement
 
+## Session parameters
+
+You can set Snowflake session parameters on a per-query basis by passing a hash to the `parameters` option. These parameters affect query behavior and can be used to set things like query tags, timezones, and other session-level settings.
+
+```ruby
+client.query(
+  "SELECT * FROM BIGTABLE",
+  parameters: {
+    "QUERY_TAG" => "my_custom_tag",
+    "TIMEZONE" => "America/Los_Angeles"
+  }
+)
+```
+
+The ones that are useful here are:
+
+- `QUERY_TAG`: tags the query, e.g. so you can find it in `QUERY_HISTORY`
+- `TIMEZONE`: sets the session time zone
+- `USE_CACHED_RESULT`: set to `false` to skip Snowflake's result cache
+- `CLIENT_RESULT_CHUNK_SIZE`: the maximum size, in MB, of each chunk of query results
+
+A few others need care:
+
+- The `*_OUTPUT_FORMAT` parameters raise an `ArgumentError`: the client parses Snowflake's default date, time and timestamp encodings, and returns binary values in its default hex.
+- `MULTI_STATEMENT_COUNT` lets you run several statements in one query, but the result is only the parent statement's summary, not each statement's rows.
+- `ROWS_PER_RESULTSET` caps the number of rows returned.
+
+For a full list of available parameters, refer to the Snowflake documentation: https://docs.snowflake.com/en/developer-guide/sql-api/reference
+
 ## Instrumentation
 
 If ActiveSupport is available, this library additionally emits [notification events](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) around queries. You can subscribe to those to track timing, query counts, etc.

data/lib/ruby_snowflake/client/threaded_in_memory_strategy.rb

@@ -9,31 +9,21 @@ module RubySnowflake
         result[0] = statement_json_body["data"]
 
         thread_pool = Concurrent::FixedThreadPool.new(num_threads)
-        partitions
-          .each_with_index.map do |partition, index|
+        futures = []
+        begin
+          partitions.each_index do |index|
             next if index == 0 # already have the first partition
-            [index, Concurrent::Future.execute(executor: thread_pool) { retreive_proc.call(index) }]
+            futures << [index, Concurrent::Future.execute(executor: thread_pool) { retreive_proc.call(index) }]
           end
-          .each do |entry|
-            next if entry.nil? # 0th index
 
-            index, future = entry
-            if future.rejected?
-              if future.reason.is_a? RubySnowflake::Error
-                raise future.reason
-              else
-                raise ConnectionStarvedError.new(
-                        "A partition request timed out. This is usually do to using the client in" \
-                        "multiple threads. The client uses a connection thread pool and if too many" \
-                        "requests are all done in threads at the same time, threads can get starved" \
-                        "of access to connections. The solution for this is to either increase the " \
-                        "max_connections parameter on the client or create a new client instance" \
-                        "with it's own connection pool to snowflake per thread. Rejection reason: #{future.reason.message}"
-                      )
-              end
-            end
-            result[index] = future.value
+          futures.each do |index, future|
+            result[index] = PartitionFuture.value!(future)
           end
+        ensure
+          # On a failure or interrupt, skip the fetches that haven't started
+          futures.each { |_index, future| future.cancel }
+          thread_pool.shutdown # no wait: in-flight fetches finish and return their connections
+        end
         result
       end
     end

data/lib/ruby_snowflake/client.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "base64"
-require "benchmark"
 require "bigdecimal"
 require "concurrent"
 require "connection_pool"
@@ -19,33 +18,17 @@ rescue LoadError
   # This isn't required
 end
 
+require_relative "errors"
 require_relative "client/http_connection_wrapper"
 require_relative "client/key_pair_jwt_auth_manager"
 require_relative "client/single_thread_in_memory_strategy"
 require_relative "client/streaming_result_strategy"
 require_relative "client/threaded_in_memory_strategy"
+require_relative "partition_future"
 require_relative "result"
 require_relative "streaming_result"
 
 module RubySnowflake
-  class Error < StandardError
-    def initialize(details)
-      @details = details
-    end
-
-    def message
-      @details.to_s
-    end
-  end
-
-  class BadResponseError < Error ; end
-  class ConnectionError < Error ; end
-  class ConnectionStarvedError < Error ; end
-  class MissingConfig < Error ; end
-  class RetryableBadResponseError < Error ; end
-  class RequestError < Error ; end
-  class QueryTimeoutError < Error ;  end
-
   class Client
     DEFAULT_LOGGER = Logger.new(STDOUT)
     DEFAULT_LOG_LEVEL = Logger::INFO
@@ -71,6 +54,9 @@ module RubySnowflake
     VALID_RESPONSE_CODES = %w(200 202).freeze
     POLLING_RESPONSE_CODE = "202"
     POLLING_INTERVAL = 2 # seconds
+    # Row parses Snowflake's default date and time encodings and returns binary as its default hex
+    OUTPUT_FORMAT_PARAMETER = /_OUTPUT_FORMAT\z/i
+    private_constant :OUTPUT_FORMAT_PARAMETER
 
     # can't be set after initialization
     attr_reader :connection_timeout, :max_connections, :logger, :max_threads_per_query, :thread_scale_factor, :http_retries, :query_timeout, :default_role
@@ -151,11 +137,12 @@ module RubySnowflake
       @_enable_polling_queries = false
     end
 
-    def query(query, warehouse: nil, streaming: false, database: nil, schema: nil, bindings: nil, role: nil, query_name: nil, query_timeout: nil)
+    def query(query, warehouse: nil, streaming: false, database: nil, schema: nil, bindings: nil, role: nil, query_name: nil, query_timeout: nil, parameters: nil)
       warehouse ||= @default_warehouse
       database ||= @default_database
       role ||= @default_role
       query_timeout ||= @query_timeout
+      validate_parameters!(parameters)
 
       with_instrumentation({ database:, schema:, warehouse:, query_name: }) do
         query_start_time = Time.now.to_i
@@ -170,6 +157,8 @@ module RubySnowflake
             "role" => role,
             "timeout" => query_timeout
           }
+          # Omit rather than send null, which Snowflake doesn't document for parameters
+          request_body["parameters"] = parameters unless parameters.nil?
 
           response = request_with_auth_and_headers(
             connection,
@@ -198,6 +187,18 @@ module RubySnowflake
     private_class_method :env_option
 
     private
+      def validate_parameters!(parameters)
+        return if parameters.nil?
+        raise ArgumentError, "parameters must be a Hash, got #{parameters.class}" unless parameters.is_a?(Hash)
+
+        output_format_key = parameters.keys.find { |key| key.to_s.match?(OUTPUT_FORMAT_PARAMETER) }
+        return if output_format_key.nil?
+
+        raise ArgumentError,
+              "The #{output_format_key} parameter is not supported: this client parses Snowflake's default " \
+              "date, time and timestamp encodings, and returns binary values in its default hex"
+      end
+
       def connection_pool
         @connection_pool ||= ConnectionPool.new(size: @max_connections, timeout: @connection_timeout) do
           HttpConnectionWrapper.new(hostname, port).start
@@ -225,9 +226,10 @@ module RubySnowflake
                             sleep: lambda {|n| 2**n }, # 1, 2, 4, 8, etc
                             on: [RetryableBadResponseError, OpenSSL::SSL::SSLError],
                             log_method: retryable_log_method) do
-          response = nil
-          bm = Benchmark.measure { response = connection.request(request) }
-          logger.debug { "HTTP Request time: #{bm.real}" }
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          response = connection.request(request)
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+          logger.debug { "HTTP Request time: #{elapsed}" }
           raise_on_bad_response(response)
           response
         end
@@ -330,9 +332,10 @@ module RubySnowflake
           )
         end
 
-        partition_json = {}
-        bm = Benchmark.measure { partition_json = JSON.parse(partition_response.body, **JSON_PARSE_OPTIONS) }
-        logger.debug { "JSON parsing took: #{bm.real}" }
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        partition_json = JSON.parse(partition_response.body, **JSON_PARSE_OPTIONS)
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+        logger.debug { "JSON parsing took: #{elapsed}" }
         partition_data = partition_json["data"]
 
         partition_data

data/lib/ruby_snowflake/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RubySnowflake
+  class Error < StandardError
+    def initialize(details)
+      @details = details
+    end
+
+    def message
+      @details.to_s
+    end
+  end
+
+  class BadResponseError < Error ; end
+  class ConnectionError < Error ; end
+  class ConnectionStarvedError < Error ; end
+  class MissingConfig < Error ; end
+  class RetryableBadResponseError < Error ; end
+  class RequestError < Error ; end
+  class QueryTimeoutError < Error ;  end
+end

data/lib/ruby_snowflake/partition_future.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "connection_pool"
+
+require_relative "errors"
+
+module RubySnowflake
+  module PartitionFuture
+    # Waits for a partition fetch. RubySnowflake errors pass through, pool timeouts become
+    # ConnectionStarvedError and anything else a RubySnowflake::Error, with the original as cause.
+    # Only the fetch's own error is mapped, never an interrupt raised in the waiting thread.
+    def self.value!(future)
+      future.wait
+      return future.value unless future.rejected?
+
+      reason = future.reason
+      case reason
+      when RubySnowflake::Error
+        raise reason
+      when ConnectionPool::TimeoutError
+        raise ConnectionStarvedError.new(
+                "A partition request timed out. This is usually due to using the client in " \
+                "multiple threads. The client uses a connection thread pool and if too many " \
+                "requests are all done in threads at the same time, threads can get starved " \
+                "of access to connections. The solution for this is to either increase the " \
+                "max_connections parameter on the client or create a new client instance " \
+                "with its own connection pool to snowflake per thread. Rejection reason: #{reason.message}"
+              ), cause: reason
+      else
+        raise Error.new("Fetching a result partition failed: #{reason.class}: #{reason.message}"), cause: reason
+      end
+    end
+  end
+  private_constant :PartitionFuture
+end

data/lib/ruby_snowflake/streaming_result.rb

@@ -2,6 +2,7 @@
 
 require "concurrent"
 
+require_relative "partition_future"
 require_relative "result"
 
 module RubySnowflake
@@ -16,30 +17,36 @@ module RubySnowflake
 
       thread_pool = Concurrent::FixedThreadPool.new 1
 
-      data.each_with_index do |_partition, index|
-        next_index = [index+1, data.size-1].min
-        if data[next_index].nil? # prefetch
-          data[next_index] = Concurrent::Future.execute(executor: thread_pool) do
-            @retreive_proc.call(next_index)
+      begin
+        data.each_with_index do |_partition, index|
+          next_index = [index+1, data.size-1].min
+          if data[next_index].nil? # prefetch
+            data[next_index] = Concurrent::Future.execute(executor: thread_pool) do
+              @retreive_proc.call(next_index)
+            end
           end
-        end
 
-        if data[index].is_a? Concurrent::Future
-          data[index] = data[index].value # wait for it to finish
-        end
+          if data[index].is_a? Concurrent::Future
+            data[index] = PartitionFuture.value!(data[index]) # wait for it to finish and propagate errors
+          end
 
-        data[index].each do |row|
-          yield wrap_row(row)
-        end
+          data[index].each do |row|
+            yield wrap_row(row)
+          end
 
-        # After iterating over the current partition, clear the data to release memory
-        data[index].clear
+          # After iterating over the current partition, clear the data to release memory
+          data[index].clear
 
-        # Reassign to a symbol so:
-        # - When looking at the list of partitions in `data` it is easier to detect
-        # - Will raise an exception if `data.each` is attempted to be called again
-        # - It won't trigger prefetch detection as `next_index`
-        data[index] = :finished
+          # Reassign to a symbol so:
+          # - When looking at the list of partitions in `data` it is easier to detect
+          # - Will raise an exception if `data.each` is attempted to be called again
+          # - It won't trigger prefetch detection as `next_index`
+          data[index] = :finished
+        end
+      ensure
+        # No wait: an early exit shouldn't block on a prefetch it won't read. The worker finishes
+        # it and exits; killing it could return a connection mid-response.
+        thread_pool.shutdown
       end
     end
 

data/lib/ruby_snowflake/version.rb

@@ -1,3 +1,3 @@
 module RubySnowflake
-  VERSION = "1.6.2"
+  VERSION = "1.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rb_snowflake_client
 version: !ruby/object:Gem::Version
-  version: 1.6.2
+  version: 1.7.0
 platform: ruby
 authors:
 - Rinsed
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -138,6 +138,8 @@ files:
 - lib/ruby_snowflake/client/single_thread_in_memory_strategy.rb
 - lib/ruby_snowflake/client/streaming_result_strategy.rb
 - lib/ruby_snowflake/client/threaded_in_memory_strategy.rb
+- lib/ruby_snowflake/errors.rb
+- lib/ruby_snowflake/partition_future.rb
 - lib/ruby_snowflake/result.rb
 - lib/ruby_snowflake/row.rb
 - lib/ruby_snowflake/streaming_result.rb