rb_snowflake_client 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c1581fededb6e083bc1f55249d806fca4a63462fafee98f9277986729dd1107
-  data.tar.gz: e810744812f56a65d519d8a30ce96e97d2f1341479ee7aeb2a50766c0f541e90
+  metadata.gz: 8d4e6f5f28c211ce79c5c049125008efdbddca46ecb670f7bc724a10c11eb5ef
+  data.tar.gz: 42378b7321d2ce549b347b5f882d85af33f393a4a34e3032fa22e5bbbaa264e7
 SHA512:
-  metadata.gz: 7cc78b78f3a5a3d056c826107aab889d23705ea76249800a7c098e43e8515db4fc9f85e11a2fae86cced570b1c5aaa869dded60495467bbb2b52241edd466c2e
-  data.tar.gz: 6b57c2a14a03fe96711d86554eb13b86bd5865a1aafa629a30ea02b2c27fc72f743f8942fc0d4d35b590d824cbd110c2ad3efbe6ffc235037c7039213644e97c
+  metadata.gz: 33be4299bb251eb3be2ddef2301ab6e471c1a312d3a35dab3a2067d757125eec473aecf230bd84544992714e4dc7ab23b4a2129c8a460c5654eadb68de5f0109
+  data.tar.gz: 71ed8816683f48ed434fdb44515a3e92d0121d8935cc1e89c41a4accef4431ef5448c2feed0355df66cc04d17a1e88afcc7732a5a56af915d85e8345b84bd49a

data/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+## [1.6.0] - 2026-04-13
+### Added
+- Support for passing a passphrase when using an encrypted private key for JWT authentication (#166)
+### Security
+- Bumped `activesupport` to patch CVEs (#167)
+
+## [1.5.0] - 2025-10-14
+### Added
+- Instrumentation feature added for Active Support users
+- Added `query_timeout` as a per-query parameter, allowing timeout override on individual queries
+### Fixed
+- `query_timeout` now properly sends timeout parameter to Snowflake API for server-side enforcement
+- Streaming mode now releases consumed records, fixing memory leak. Note: if you were iterating over streaming results more than once, this is a breaking change (though that was not its intended usage).
+
 ## [1.4.0] - 2025-05-01
 ### Added
 - Enhanced Row API to implement Enumerable interface

data/Gemfile

@@ -8,6 +8,10 @@ gemspec
 gem "bundler"
 gem "rake"
 
+group :development, :test do
+  gem "activesupport", "~> 8.0.4", ">= 8.0.4.1"
+end
+
 group :development do
   gem "parallel"
   gem "pry"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rb_snowflake_client (1.4.0)
+    rb_snowflake_client (1.6.0)
       bigdecimal (>= 3.0)
       concurrent-ruby (>= 1.2)
       connection_pool (>= 2.4)
@@ -13,42 +13,69 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    base64 (0.2.0)
-    bigdecimal (3.1.9)
+    activesupport (8.0.5)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.3.0)
+    benchmark (0.5.0)
+    bigdecimal (4.1.1)
     coderay (1.1.3)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.3)
-    diff-lcs (1.6.1)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    diff-lcs (1.6.2)
     dotenv (3.1.8)
-    json (2.11.3)
-    jwt (2.10.1)
+    drb (2.2.3)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    json (2.15.1)
+    jwt (3.1.2)
       base64
+    logger (1.7.0)
     method_source (1.1.0)
+    minitest (6.0.3)
+      drb (~> 2.0)
+      prism (~> 1.5)
     parallel (1.27.0)
+    prism (1.9.0)
     pry (0.15.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    rake (13.2.1)
+    rake (13.3.0)
     retryable (3.0.5)
-    rspec (3.13.0)
+    rspec (3.13.1)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.3)
+    rspec-core (3.13.5)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.3)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.2)
+    rspec-mocks (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.2)
+    rspec-support (3.13.6)
+    securerandom (0.4.1)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.1.1)
 
 PLATFORMS
   arm64-darwin-22
   ruby
 
 DEPENDENCIES
+  activesupport (~> 8.0.4, >= 8.0.4.1)
   bundler
   parallel
   pry
@@ -57,4 +84,4 @@ DEPENDENCIES
   rspec
 
 BUNDLED WITH
-   2.5.10
+  4.0.3

data/README.md

@@ -48,6 +48,8 @@ Available ENV variables (see below in the config section for details)
 - `SNOWFLAKE_URI`
 - `SNOWFLAKE_PRIVATE_KEY_PATH` or `SNOWFLAKE_PRIVATE_KEY`
   - Use either the key or the path. Key takes precedence if both are provided.
+- `SNOWFLAKE_PRIVATE_KEY_PASSPHRASE`
+  - Optional, if you are using an encrypted private key
 - `SNOWFLAKE_ORGANIZATION`
   - Optional, if you leave it off, the library will authenticate with an account name of only SNOWFLAKE_ACCOUNT
 - `SNOWFLAKE_ACCOUNT`
@@ -132,6 +134,14 @@ Queries by default use the primary role assigned to the account. If there are mu
 client.query("SELECT * FROM BIGTABLE", role: "MY_ROLE")
 ```
 
+## Query timeout
+
+You can override the query timeout on a per-query basis. The timeout is specified in seconds and will be enforced by both Snowflake server-side and the client-side polling mechanism.
+
+```ruby
+client.query("SELECT * FROM BIGTABLE", query_timeout: 30)
+```
+
 ## Binding parameters
 
 Say we have `BIGTABLE` with a `data` column of a type `VARIANT`.
@@ -140,16 +150,45 @@ Say we have `BIGTABLE` with a `data` column of a type `VARIANT`.
 json_string = '{"valid": "json"}'
 query = "insert into BIGTABLE(data) select parse_json(?)"
 bindings = {
-  "1": {
-    "type": "TEXT",
-    "value": json_string
-  }
-}
+      "1" => {
+        "type" => "TEXT",
+        "value" => "Other Event"
+      }
+    }
 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
 
+## 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.
+
+* `rb_snowflake_client.snowflake_query.finish`: published at query end
+
+Events receive a payload with the following properties:
+* `database`: snowflake database
+* `schema`: snowflake schema
+* `warehouse`: snowflake warehouse
+* `query_id`: random UUID for the query
+* `query_name`: argument passed to query/fetch
+* `exception`: present if the query raised an error, see [Notifications documentation](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html#module-ActiveSupport::Notifications-label-Subscribers) for details
+* `exception_object`: present if the query raised an error, see [Notifications documentation](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html#module-ActiveSupport::Notifications-label-Subscribers) for details
+
+An example integration with [Datadog](https://www.rubydoc.info/gems/datadog) might look like this:
+
+```ruby
+ActiveSupport::Notifications.subscribe("rb_snowflake_client.snowflake_query.finish") do |name, start, finish, id, payload|
+  span = Datadog::Tracing.trace(payload[:query_name] || "snowflake_query",
+    resource: "snowflake",
+    start_time: start,
+    tags: payload,
+    type: Datadog::Tracing::Metadata::Ext::AppTypes::TYPE_DB)
+  
+  span.finish(finish)
+end
+```
+
 # Configuration Options
 
 The client supports the following configuration options, each with their own getter/setter except connection pool options which must be set at construction. Additionally, all except logger can be configured with environment variables (see above, but the pattern is like: "SNOWFLAKE_HTTP_RETRIES". Configuration options can only be set on initialization through `new` or `from_env`.
@@ -228,6 +267,7 @@ or alternatively, use the client to verify:
 client = RubySnowflake::Client.new(
   "https://yourinstance.region.snowflakecomputing.com", # insert your URL here
   File.read("secrets/my_key.pem"),                      # path to your private key
+  "private-key-passphrase",                             # your private key passphrase, if it has one (defaults to nil)
   "snowflake-organization",                             # your account name (doesn't match your URL), using nil may be required depending on your snowflake account
   "snowflake-account",                                  # typically your subdomain
   "snowflake-user",                                     # Your snowflake user

data/lib/ruby_snowflake/client/key_pair_jwt_auth_manager.rb

@@ -8,12 +8,13 @@ module RubySnowflake
   class Client
     class KeyPairJwtAuthManager
       # requires text of a PEM formatted RSA private key
-      def initialize(organization, account, user, private_key, jwt_token_ttl)
+      def initialize(organization, account, user, private_key, jwt_token_ttl, private_key_passphrase = nil)
         @organization = organization
         @account = account
         @user = user
         @private_key_pem = private_key
         @jwt_token_ttl = jwt_token_ttl
+        @private_key_passphrase = private_key_passphrase
 
         # start with an expired value to force creation
         @token_expires_at = Time.now.to_i - 1
@@ -26,8 +27,7 @@ module RubySnowflake
         @token_semaphore.acquire do
           now = Time.now.to_i
           @token_expires_at = now + @jwt_token_ttl
-
-          private_key = OpenSSL::PKey.read(@private_key_pem)
+          private_key = OpenSSL::PKey.read(@private_key_pem, @private_key_passphrase)
 
           payload = {
             :iss => "#{account_name}.#{@user.upcase}.#{public_key_fingerprint}",
@@ -56,7 +56,7 @@ module RubySnowflake
         def public_key_fingerprint
           return @public_key_fingerprint unless @public_key_fingerprint.nil?
 
-          public_key_der = OpenSSL::PKey::RSA.new(@private_key_pem).public_key.to_der
+          public_key_der = OpenSSL::PKey::RSA.new(@private_key_pem, @private_key_passphrase).public_key.to_der
           digest = OpenSSL::Digest::SHA256.new.digest(public_key_der)
           fingerprint = Base64.strict_encode64(digest)
 

data/lib/ruby_snowflake/client.rb

@@ -12,6 +12,13 @@ require "retryable"
 require "securerandom"
 require "uri"
 
+begin
+  require "active_support"
+  require "active_support/notifications"
+rescue LoadError
+  # This isn't required
+end
+
 require_relative "client/http_connection_wrapper"
 require_relative "client/key_pair_jwt_auth_manager"
 require_relative "client/single_thread_in_memory_strategy"
@@ -90,6 +97,7 @@ module RubySnowflake
       new(
         ENV.fetch("SNOWFLAKE_URI"),
         private_key,
+        ENV["SNOWFLAKE_PRIVATE_KEY_PASSPHRASE"],
         ENV.fetch("SNOWFLAKE_ORGANIZATION"),
         ENV.fetch("SNOWFLAKE_ACCOUNT"),
         ENV.fetch("SNOWFLAKE_USER"),
@@ -109,7 +117,7 @@ module RubySnowflake
     end
 
     def initialize(
-      uri, private_key, organization, account, user, default_warehouse, default_database,
+      uri, private_key, private_key_passphrase = nil, organization, account, user, default_warehouse, default_database,
       default_role: nil,
       logger: DEFAULT_LOGGER,
       log_level: DEFAULT_LOG_LEVEL,
@@ -123,7 +131,7 @@ module RubySnowflake
     )
       @base_uri = uri
       @key_pair_jwt_auth_manager =
-        KeyPairJwtAuthManager.new(organization, account, user, private_key, jwt_token_ttl)
+        KeyPairJwtAuthManager.new(organization, account, user, private_key, jwt_token_ttl, private_key_passphrase)
       @default_warehouse = default_warehouse
       @default_database = default_database
       @default_role = default_role
@@ -143,31 +151,35 @@ module RubySnowflake
       @_enable_polling_queries = false
     end
 
-    def query(query, warehouse: nil, streaming: false, database: nil, schema: nil, bindings: nil, role: nil)
+    def query(query, warehouse: nil, streaming: false, database: nil, schema: nil, bindings: nil, role: nil, query_name: nil, query_timeout: nil)
       warehouse ||= @default_warehouse
       database ||= @default_database
       role ||= @default_role
+      query_timeout ||= @query_timeout
 
-      query_start_time = Time.now.to_i
-      response = nil
-      connection_pool.with do |connection|
-        request_body = {
-          "warehouse" => warehouse&.upcase,
-          "schema" => schema&.upcase,
-          "database" =>  database&.upcase,
-          "statement" => query,
-          "bindings" => bindings,
-          "role" => role
-        }
-
-        response = request_with_auth_and_headers(
-          connection,
-          Net::HTTP::Post,
-          "/api/v2/statements?requestId=#{SecureRandom.uuid}&async=#{@_enable_polling_queries}",
-          request_body.to_json
-        )
+      with_instrumentation({ database:, schema:, warehouse:, query_name: }) do
+        query_start_time = Time.now.to_i
+        response = nil
+        connection_pool.with do |connection|
+          request_body = {
+            "warehouse" => warehouse&.upcase,
+            "schema" => schema&.upcase,
+            "database" =>  database&.upcase,
+            "statement" => query,
+            "bindings" => bindings,
+            "role" => role,
+            "timeout" => query_timeout
+          }
+
+          response = request_with_auth_and_headers(
+            connection,
+            Net::HTTP::Post,
+            "/api/v2/statements?requestId=#{SecureRandom.uuid}&async=#{@_enable_polling_queries}",
+            request_body.to_json
+          )
+        end
+        retrieve_result_set(query_start_time, query, response, streaming, query_timeout)
       end
-      retrieve_result_set(query_start_time, query, response, streaming)
     end
 
     alias fetch query
@@ -251,7 +263,7 @@ module RubySnowflake
         end
       end
 
-      def poll_for_completion_or_timeout(query_start_time, query, statement_handle)
+      def poll_for_completion_or_timeout(query_start_time, query, statement_handle, query_timeout)
         first_data_json_body = nil
 
         connection_pool.with do |connection|
@@ -259,7 +271,7 @@ module RubySnowflake
             sleep POLLING_INTERVAL
 
             elapsed_time = Time.now.to_i - query_start_time
-            if elapsed_time > @query_timeout
+            if elapsed_time > query_timeout
               cancelled = attempt_to_cancel_and_silence_errors(connection, statement_handle)
               raise QueryTimeoutError.new("Query timed out. Query cancelled? #{cancelled}; Duration: #{elapsed_time}; Query: '#{query}'")
             end
@@ -287,12 +299,12 @@ module RubySnowflake
         false
       end
 
-      def retrieve_result_set(query_start_time, query, response, streaming)
+      def retrieve_result_set(query_start_time, query, response, streaming, query_timeout)
         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)
+          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)
         end
 
@@ -329,5 +341,15 @@ module RubySnowflake
       def number_of_threads_to_use(partition_count)
         [[1, (partition_count / @thread_scale_factor.to_f).ceil].max, @max_threads_per_query].min
       end
+
+      def with_instrumentation(tags, &block)
+        return block.call unless defined?(::ActiveSupport) && ::ActiveSupport
+
+        ::ActiveSupport::Notifications.instrument(
+            "rb_snowflake_client.snowflake_query.finish",
+            tags.merge(query_id: SecureRandom.uuid)) do
+          block.call
+        end
+      end
   end
 end

data/lib/ruby_snowflake/streaming_result.rb

@@ -27,9 +27,19 @@ module RubySnowflake
         if data[index].is_a? Concurrent::Future
           data[index] = data[index].value # wait for it to finish
         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
+
+        # 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
     end
 

data/lib/ruby_snowflake/version.rb

@@ -1,3 +1,3 @@
 module RubySnowflake
-  VERSION = "1.4.0"
+  VERSION = "1.6.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rb_snowflake_client
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Rinsed
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-01 00:00:00.000000000 Z
+date: 2026-04-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal