rb_snowflake_client 1.6.1 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57d979564fce1cdc8fb8b92043e89b631f4f1ca35db2cc2d4601a1739506e89a
-  data.tar.gz: ecfd25eb94ae8e5767e49c7b3b5dd33f02905e09c839ba0bd59be81f629f1390
+  metadata.gz: 05c5fef52239a7d043627e57e3a205ef07092452b7c7a47779ad21150637ec66
+  data.tar.gz: f98da0cd8848820a984753175fd9c22d60f41d137da780de0d8d08f99fa4632a
 SHA512:
-  metadata.gz: 906470b3b67d6a102bbe25bc02e42c2178a4a9fc7a1eb6785398a1bfc45d6e47e9b5dc392aebc4dc35dbd0c6a2263c30c39c3ce522396a6584629f8d8e7ad43e
-  data.tar.gz: d767e9956def03c80dd8eb66d24649c54c987f37dc07870a319a55ac9455821b330e4d5a59e89246282899f40d76222c6a07b90dc6882a5e89ba3c410a6c1f95
+  metadata.gz: f577b2fef1a891a37a0a793a53ed4d24d63e665fc5d6e114332f836a4f12a26494f002bf6a589c1b921df253ccac10d81ad122636e8a0d053f16efe4f1c3313d
+  data.tar.gz: 4cb2888d8274a883689b448ba6acf315b683ba2692612b1d3753921f082ee14cd5292216c436a4e7d4f5b3ef3893af3a946333a6abff710f42c2246400736855

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

@@ -0,0 +1,108 @@
+# For a PUBLIC repo: copy this one file into its .github/workflows/ instead of review.yml,
+# review-manual-request.yml and review-dismiss-stale.yml. A public repo can't use actions or reusable
+# workflows from rinsed-org/review-bot-workflows (an internal repo), so it doesn't run Arby itself. It asks
+# rinsed-org/review-bot-public-runner (internal) to, by dispatching that repo's review workflow with nothing
+# but this repo's name and the PR number. The runner reads this repo's settings (limit-approval-to,
+# blocking-severities, ...) from its own config file and runs the reusable workflow in cross-repo mode, which
+# reviews this PR in public repo mode and posts the review here as Arby. Per-repo setup: add this repo to the
+# runner's config, then add this file. See the bot's README, "Public repositories".
+#
+# 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.
+#
+# 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, review_requested]
+
+# Nothing by default; each job asks for exactly what it needs.
+permissions: {}
+
+jobs:
+  dispatch:
+    name: Request Arby review
+    # 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.
+    permissions: {}
+    steps:
+      - name: Mint a dispatch token
+        id: token
+        uses: actions/create-github-app-token@v3
+        with:
+          client-id: ${{ secrets.ARBY_DISPATCH_CLIENT_ID }}
+          private-key: ${{ secrets.ARBY_DISPATCH_PRIVATE_KEY }}
+          owner: rinsed-org
+          repositories: review-bot-public-runner
+          permission-actions: write
+      - name: Dispatch the review
+        env:
+          GH_TOKEN: ${{ steps.token.outputs.token }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          # The REST endpoint directly, with an explicit ref: `gh workflow run` would first look up the runner
+          # repo's default branch, which needs Contents read, and this token has only Actions: write.
+          gh api --method POST repos/rinsed-org/review-bot-public-runner/actions/workflows/review.yml/dispatches \
+            -f ref=master -f "inputs[repo]=$REPO" -f "inputs[pr]=$PR"
+
+  # A COPY of rinsed-org/review-bot-workflows' dismiss-stale/action.yml, inlined because a public repo can't
+  # use that internal action. The two must change together. Its own job, so it stays a cheap check with no
+  # dependency on Arby, the app or the runner repo: make THIS job ("Dismiss stale Arby approvals") the
+  # required status check, as in review-dismiss-stale.yml. It runs on the job's default token and consumes
+  # nothing PR-controlled beyond the PR number.
+  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
+    timeout-minutes: 5
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Dismiss stale review-bot approvals
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number }}
+          BOT_LOGIN: rinsed-review-bot
+        run: |
+          set -euo pipefail
+          if [ -z "$PR" ]; then
+            echo "::error::No pull request in the event payload — call this from a pull_request_target workflow."
+            exit 1
+          fi
+          # Skip approvals for the PR's current head: the review workflow runs on the same event with no
+          # ordering, so a delayed dismiss job must not kill an approval Arby already gave the new commits. The
+          # head is fetched at execution time (not from the event payload) so a run delayed past a newer push
+          # can't dismiss that newer push's approval either.
+          head_sha=$(gh api "repos/$REPO/pulls/$PR" --jq .head.sha)
+          gh api "repos/$REPO/pulls/$PR/reviews" --paginate \
+            --jq ".[] | select(.user.login == \"$BOT_LOGIN\" and .state == \"APPROVED\"
+                              and .commit_id != \"$head_sha\") | .id" |
+          while read -r review_id; do
+            echo "Dismissing stale approval (review $review_id)"
+            # The API rejects blank (or whitespace-only) messages, so this is as terse as GitHub allows.
+            gh api --method PUT "repos/$REPO/pulls/$PR/reviews/$review_id/dismissals" \
+              --field message="Dismissing stale review" --field event="DISMISS"
+          done

data/CHANGELOG.md

@@ -7,6 +7,30 @@ 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
+  `ArgumentError: wrong number of arguments (given 2, expected 1)` because the parse options were passed
+  as a positional Hash. They're now passed as keywords, which works on `json` 2.x and 3.x. (#191)
+
 ## [1.6.1] - 2026-08-18
 ### Security
 - Bumped `json` to patch a format-string injection CVE (#169)

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
@@ -300,12 +302,12 @@ module RubySnowflake
       end
 
       def retrieve_result_set(query_start_time, query, response, streaming, query_timeout)
-        json_body = JSON.parse(response.body, JSON_PARSE_OPTIONS)
+        json_body = JSON.parse(response.body, **JSON_PARSE_OPTIONS)
         statement_handle = json_body["statementHandle"]
 
         if response.code == POLLING_RESPONSE_CODE
           result_response = poll_for_completion_or_timeout(query_start_time, query, statement_handle, query_timeout)
-          json_body = JSON.parse(result_response.body, JSON_PARSE_OPTIONS)
+          json_body = JSON.parse(result_response.body, **JSON_PARSE_OPTIONS)
         end
 
         num_threads = number_of_threads_to_use(json_body["resultSetMetaData"]["partitionInfo"].size)
@@ -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.1"
+  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.1
+  version: 1.7.0
 platform: ruby
 authors:
 - Rinsed
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-18 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -120,6 +120,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/dependabot.yml"
+- ".github/workflows/arby-review.yml"
 - ".github/workflows/ci.yml"
 - ".github/workflows/release-gh-packages.yml"
 - ".github/workflows/release-rubygems.yml"
@@ -137,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