rb_snowflake_client 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef7c1798270965128711042d7d218668b318356bf6a3fac8efc2144538c5a246
-  data.tar.gz: a04c605cfff4659c18deb58ccdca3d49db8a6d85d98825a496ab6d8641030193
+  metadata.gz: ddf76c34f14ea4b7192e5bd3dbdb18b7d176e66c6327fab97ef8d4352138d964
+  data.tar.gz: 20223663cc72100e28b22a4ea572611d2b2bc8291519d1cde9f2b536c02865f1
 SHA512:
-  metadata.gz: 3633bc26af9b0912735ad82840795ab81c6178c381b11ae7ade7b6fd2272576a7a9d4f65a7cd22a5786ede9f2d153bc7ccb3a5816fe0263e48cb6f5df448297b
-  data.tar.gz: 449e2d7140b58c6d629fd17bf4641b3d698a03d10a1fb6df3444fd3bd5bf6fd6da1f146c59d96dcedd3932ddc1f5b4b086524f427385510435e36dc8de052824
+  metadata.gz: 266de51be70f28c748b703fc55787b0a495404a62226fba151c44dfe00ce31465c3aae5e516ba362cdfa8a22a0d597514d86fd6644f263a046cb275b0a3e3f46
+  data.tar.gz: b0e90b538d9b6557d7de1b58f085570097036df3a9d1ea6be500babb6b56fafb50f21a4d905f1c50e8a274df7ffdd58b6268d65f9dc2220c7e9f70680662479c

data/.github/workflows/ci.yml

@@ -12,9 +12,9 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Set up Ruby
-        uses: ruby/setup-ruby@904f3fef85a9c80a3750cbe7d5159268fd5caa9f
+        uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.0.6'
+          ruby-version: '3.3'
       - name: Install dependencies
         run: bundle install
       - name: Build gem

data/.github/workflows/release-gh-packages.yml

@@ -1,5 +1,6 @@
 name: Release to Github Packages
 on:
+  workflow_dispatch:
   push:
     branches:
       - "master"
@@ -14,9 +15,9 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Set up Ruby
-        uses: ruby/setup-ruby@904f3fef85a9c80a3750cbe7d5159268fd5caa9f
+        uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.0.6'
+          ruby-version: '3.3'
       - name: Install dependencies
         run: bundle install
       - name: Build gem

data/.github/workflows/release-rubygems.yml

@@ -1,5 +1,6 @@
 name: Release to Rubygems
 on:
+  workflow_dispatch:
   push:
     branches:
       - "master"
@@ -11,9 +12,9 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Set up Ruby
-        uses: ruby/setup-ruby@904f3fef85a9c80a3750cbe7d5159268fd5caa9f
+        uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.0.6'
+          ruby-version: '3.3'
       - name: Install dependencies
         run: bundle install
       - name: Publish to RubyGems

data/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+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.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
+- Added case-insensitive access to Row columns via both symbol and string keys
+- Added numeric column access to Row (e.g., `row[0]`)
+- Support setting organization or ENV["SNOWFLAKE_ORGANIZATION"] to nil or "" in JWT authentication
+- Added default_role parameter and SNOWFLAKE_DEFAULT_ROLE env variable
+
+## [1.3.0] - 2025-01-03
+### Changed
+- Bumped gem dependencies to newer versions
+- Added support for role parameter in Client and query method
+
+## [1.2.0] - 2025-01-03
+### Changed
+- Switched from Oj to JSON gem for parsing
+- Improved performance by utilizing the optimized JSON gem
+
+## [1.1.5] - 2024-12-19
+### Fixed
+- Parse exception detail OR message for better error handling
+
+## [1.1.4] - 2024-11-05
+### Fixed
+- Fixed ENV variable issue
+
+## [1.1.3] - 2024-08-09
+### Added
+- Retry HTTP codes in the 3xx range
+
+## [1.1.2] - 2024-08-06
+### Fixed
+- CI error fixes
+
+## [1.1.1] - 2024-07-12
+### Fixed
+- Added 502 to specific list of retryable HTTP error codes
+- Fixed issue with checking string code presence in an array of integer values
+
+## [1.1.0] - 2024-06-05
+### Added
+- Support for specifying a schema in query method
+- Merged multiple community contributions
+
+## [1.0.6] - 2024-06-05
+### Added
+- Allow specifying schema in query method
+
+## [1.0.5] - 2024-03-20
+### Added
+- Added exponential backoff to retryable calls
+- Improved handling of rate limiting (429 responses)
+
+## [1.0.4] - 2024-01-30
+### Fixed
+- Fixed raise arguments
+- Now properly raising OpenSSL errors to retry them
+
+## [1.0.3] - 2024-01-17
+### Fixed
+- Now upcasing database and warehouse fields in requests
+- Fixed error where lowercase field names would result in "Unable to run command without specifying database/warehouse"
+
+## [1.0.2] - 2024-01-16
+### Fixed
+- Fixed typo in key pair memoization
+
+## [1.0.1] - 2024-01-09
+### Added
+- Added `create_jwt_token` helper method for testing
+- Support for time travel in tests
+
+## [1.0.0] - 2023-12-11
+### Changed
+- First stable release
+- Fixed markdown links in documentation
+
+## [0.3.0] - 2023-12-08
+### Added
+- Support for Snowflake polling responses
+- Handle async query execution
+
+## [0.2.0] - 2023-12-07
+### Added
+- Extracted authentication logic into its own class
+- Improved time handling for various Snowflake date/time types
+- Support for TIME, DATETIME, TIMESTAMP, TIMESTAMP_LTZ, TIMESTAMP_NTZ, TIMESTAMP_TZ
+
+## [0.1.2] - 2023-12-04
+### Added
+- Support for database parameter in requests
+- Added missing dependencies to gemspec
+
+## [0.1.1] - 2023-12-01
+### Added
+- Added `fetch` as an alias for `query` for compatibility with other clients
+
+## [0.1.0] - 2023-11-28
+### Added
+- First minor version release with basic functionality
+- Support for querying Snowflake with the HTTP API
+- Support for streaming results
+
+## [0.0.6] - 2023-11-27
+### Changed
+- Cleaned up key pair authentication
+- Improved documentation with better setup instructions
+
+## [0.0.5] - 2023-11-27
+### Fixed
+- Various bug fixes and improvements
+
+## [0.0.4] - 2023-11-22
+### Changed
+- Fixed type handling for query results
+- All specs now pass
+
+## [0.0.3] - 2023-11-21
+### Changed
+- Renamed to RubySnowflake namespace
+- Initial gem structure

data/Gemfile

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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rb_snowflake_client (1.3.0)
+    rb_snowflake_client (1.5.0)
       bigdecimal (>= 3.0)
       concurrent-ruby (>= 1.2)
       connection_pool (>= 2.4)
@@ -13,42 +13,66 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    base64 (0.2.0)
-    bigdecimal (3.1.9)
+    activesupport (8.0.3)
+      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.4.1)
+    bigdecimal (3.3.1)
     coderay (1.1.3)
-    concurrent-ruby (1.3.4)
-    connection_pool (2.4.1)
-    diff-lcs (1.5.1)
-    dotenv (3.1.7)
-    json (2.9.1)
-    jwt (2.10.1)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.4)
+    diff-lcs (1.6.2)
+    dotenv (3.1.8)
+    drb (2.2.3)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    json (2.15.1)
+    jwt (3.1.2)
       base64
+    logger (1.7.0)
     method_source (1.1.0)
-    parallel (1.26.3)
+    minitest (5.26.0)
+    parallel (1.27.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.2)
+    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.0.4)
 
 PLATFORMS
   arm64-darwin-22
   ruby
 
 DEPENDENCIES
+  activesupport
   bundler
   parallel
   pry

data/README.md

@@ -30,11 +30,12 @@ require "rb_snowflake_client"
 client = RubySnowflake::Client.new(
   "https://yourinstance.region.snowflakecomputing.com", # insert your URL here
   File.read("secrets/my_key.pem"),                      # your private key in PEM format (scroll down for instructions)
-  "snowflake-organization",                             # your account name (doesn't match your URL)
+  "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
   "some_warehouse",                                     # The name of your warehouse to use by default
   "some_database",                                      # The name of the database in the context of which the queries will run
+  default_role: "some_role",                            # The name of the role with which the queries will run. A `nil` value uses the primary role of the user.
   max_connections: 12,                                  # Config options can be passed in
   connection_timeout: 45,                               # See below for the full set of options
   query_timeout: 1200,                                  # how long to wait for queries, in seconds
@@ -48,10 +49,12 @@ Available ENV variables (see below in the config section for details)
 - `SNOWFLAKE_PRIVATE_KEY_PATH` or `SNOWFLAKE_PRIVATE_KEY`
   - Use either the key or the path. Key takes precedence if both are provided.
 - `SNOWFLAKE_ORGANIZATION`
+  - Optional, if you leave it off, the library will authenticate with an account name of only SNOWFLAKE_ACCOUNT
 - `SNOWFLAKE_ACCOUNT`
 - `SNOWFLAKE_USER`
 - `SNOWFLAKE_DEFAULT_WAREHOUSE`
 - `SNOWFLAKE_DEFAULT_DATABASE`
+- `SNOWFLAKE_DEFAULT_ROLE`
 - `SNOWFLAKE_JWT_TOKEN_TTL`
 - `SNOWFLAKE_CONNECTION_TIMEOUT`
 - `SNOWFLAKE_MAX_CONNECTIONS`
@@ -69,9 +72,19 @@ result = client.query("SELECT ID, NAME FROM SOMETABLE")
 
 # result is Enumerable
 result.each do |row|
-  puts row[:id]    # row supports access with symbols
-  puts row["name"] # or case insensitive strings
-  puts row.to_h    # and can produce a hash with keys/values
+  # Row implements Enumerable and provides flexible column access:
+  puts row[:id]    # access with symbols (case-insensitive)
+  puts row["name"] # access with strings (case-insensitive)
+  puts row[0]      # access with numeric indices
+
+  # Row has Enumerable methods
+  puts row.keys    # get all column names
+  puts row.values  # get all values
+  puts row.to_h    # convert to Hash with column names as keys
+
+  # Use all Enumerable methods
+  row.each { |column_name, value| puts "#{column_name}: #{value}" }
+  filtered = row.select { |column, value| column.start_with?("i") }
 end
 ```
 
@@ -111,6 +124,22 @@ client.query("SELECT * FROM BIGTABLE", warehouse: "FAST_WH")
 client.query("SELECT * FROM BIGTABLE", schema: "MY_SCHEMA")
 ```
 
+## Specifying role
+
+Queries by default use the primary role assigned to the account. If there are multiple roles you can switch between them on a per query basis.
+
+```ruby
+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`.
@@ -119,16 +148,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`.
@@ -157,7 +215,9 @@ end
 
 1. Does not yet support multiple statements (work around is to wrap in `BEGIN ... END`)
 2. Only supports key pair authentication
-3. Its faster to work directly with the row value and not call to_h if you don't need to
+3. It's faster to work directly with the row value and not call to_h if you don't need to
+4. Rows are Enumerable, providing access to methods like `each`, `map`, `select`, `keys`, and `values`
+5. Row column access is case-insensitive and supports string keys, symbol keys, and numeric indices
 
 # Setting up a user for key pair authentication
 
@@ -205,7 +265,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
-  "snowflake-organization",                             # your account name (doesn't match your URL)
+  "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
   "some_warehouse",                                     # The name of your warehouse to use by default
@@ -213,6 +273,10 @@ client = RubySnowflake::Client.new(
 )
 ```
 
+# Change Log
+
+See [Change Log](CHANGELOG.md)
+
 # Code of conduct
 
 See [Code of Coduct](CODE_OF_CONDUCT.md)

data/lib/ruby_snowflake/client/key_pair_jwt_auth_manager.rb

@@ -30,8 +30,8 @@ module RubySnowflake
           private_key = OpenSSL::PKey.read(@private_key_pem)
 
           payload = {
-            :iss => "#{@organization.upcase}-#{@account.upcase}.#{@user.upcase}.#{public_key_fingerprint}",
-            :sub => "#{@organization.upcase}-#{@account.upcase}.#{@user.upcase}",
+            :iss => "#{account_name}.#{@user.upcase}.#{public_key_fingerprint}",
+            :sub => "#{account_name}.#{@user.upcase}",
             :iat => now,
             :exp => @token_expires_at
           }
@@ -45,6 +45,14 @@ module RubySnowflake
           Time.now.to_i > @token_expires_at
         end
 
+        def account_name
+          if @organization == nil || @organization == ""
+            @account.upcase
+          else
+            "#{@organization.upcase}-#{@account.upcase}"
+          end
+        end
+
         def public_key_fingerprint
           return @public_key_fingerprint unless @public_key_fingerprint.nil?
 

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"
@@ -22,22 +29,12 @@ require_relative "streaming_result"
 
 module RubySnowflake
   class Error < StandardError
-    # This will get pulled through to Sentry, see:
-    # https://github.com/getsentry/sentry-ruby/blob/11ecd254c0d2cae2b327f0348074e849095aa32d/sentry-ruby/lib/sentry/error_event.rb#L31-L33
-    attr_reader :sentry_context
-
     def initialize(details)
-      @sentry_context = details
       @details = details
     end
 
     def message
-      if @details == {}
-        super
-      else
-        @details.to_s
-      end
-
+      @details.to_s
     end
   end
 
@@ -67,6 +64,8 @@ module RubySnowflake
     DEFAULT_HTTP_RETRIES = 2
     # how long to wait to allow a query to complete, in seconds
     DEFAULT_QUERY_TIMEOUT = 600 # 10 minutes
+    # default role to use
+    DEFAULT_ROLE = nil
 
     JSON_PARSE_OPTIONS = { decimal_class: BigDecimal }.freeze
     VALID_RESPONSE_CODES = %w(200 202).freeze
@@ -74,7 +73,7 @@ module RubySnowflake
     POLLING_INTERVAL = 2 # seconds
 
     # can't be set after initialization
-    attr_reader :connection_timeout, :max_connections, :logger, :max_threads_per_query, :thread_scale_factor, :http_retries, :query_timeout
+    attr_reader :connection_timeout, :max_connections, :logger, :max_threads_per_query, :thread_scale_factor, :http_retries, :query_timeout, :default_role
 
     def self.from_env(logger: DEFAULT_LOGGER,
                       log_level: DEFAULT_LOG_LEVEL,
@@ -84,14 +83,15 @@ module RubySnowflake
                       max_threads_per_query: env_option("SNOWFLAKE_MAX_THREADS_PER_QUERY", DEFAULT_MAX_THREADS_PER_QUERY),
                       thread_scale_factor: env_option("SNOWFLAKE_THREAD_SCALE_FACTOR", DEFAULT_THREAD_SCALE_FACTOR),
                       http_retries: env_option("SNOWFLAKE_HTTP_RETRIES", DEFAULT_HTTP_RETRIES),
-                      query_timeout: env_option("SNOWFLAKE_QUERY_TIMEOUT", DEFAULT_QUERY_TIMEOUT))
+                      query_timeout: env_option("SNOWFLAKE_QUERY_TIMEOUT", DEFAULT_QUERY_TIMEOUT),
+                      default_role: env_option("SNOWFLAKE_DEFAULT_ROLE", DEFAULT_ROLE))
       private_key =
         if key = ENV["SNOWFLAKE_PRIVATE_KEY"]
           key
         elsif path = ENV["SNOWFLAKE_PRIVATE_KEY_PATH"]
           File.read(path)
         else
-          raise MissingConfig.new({}), "Either ENV['SNOWFLAKE_PRIVATE_KEY'] or ENV['SNOWFLAKE_PRIVATE_KEY_PATH'] must be set"
+          raise MissingConfig, "Either ENV['SNOWFLAKE_PRIVATE_KEY'] or ENV['SNOWFLAKE_PRIVATE_KEY_PATH'] must be set"
         end
 
       new(
@@ -102,6 +102,7 @@ module RubySnowflake
         ENV.fetch("SNOWFLAKE_USER"),
         ENV["SNOWFLAKE_DEFAULT_WAREHOUSE"],
         ENV["SNOWFLAKE_DEFAULT_DATABASE"],
+        default_role: ENV.fetch("SNOWFLAKE_DEFAULT_ROLE", nil),
         logger: logger,
         log_level: log_level,
         jwt_token_ttl: jwt_token_ttl,
@@ -116,6 +117,7 @@ module RubySnowflake
 
     def initialize(
       uri, private_key, organization, account, user, default_warehouse, default_database,
+      default_role: nil,
       logger: DEFAULT_LOGGER,
       log_level: DEFAULT_LOG_LEVEL,
       jwt_token_ttl: DEFAULT_JWT_TOKEN_TTL,
@@ -131,6 +133,7 @@ module RubySnowflake
         KeyPairJwtAuthManager.new(organization, account, user, private_key, jwt_token_ttl)
       @default_warehouse = default_warehouse
       @default_database = default_database
+      @default_role = default_role
 
       # set defaults for config settings
       @logger = logger
@@ -147,29 +150,35 @@ module RubySnowflake
       @_enable_polling_queries = false
     end
 
-    def query(query, warehouse: nil, streaming: false, database: nil, schema: nil, bindings: 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
-        }
-
-        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
@@ -228,11 +237,11 @@ module RubySnowflake
 
         # there are a class of errors we want to retry rather than just giving up
         if retryable_http_response_code?(response.code)
-          raise RetryableBadResponseError.new({}),
+          raise RetryableBadResponseError,
                 "Retryable bad response! Got code: #{response.code}, w/ message #{response.body}"
 
         else # not one we should retry
-          raise BadResponseError.new({}),
+          raise BadResponseError,
             "Bad response! Got code: #{response.code}, w/ message #{response.body}"
         end
       end
@@ -253,7 +262,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|
@@ -261,7 +270,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
@@ -289,12 +298,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
 
@@ -331,5 +340,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/row.rb

@@ -5,6 +5,8 @@ require "time"
 
 module RubySnowflake
   class Row
+    include Enumerable
+
     EPOCH_JULIAN_DAY_NUMBER = Date.new(1970,1,1).jd
     TIME_FORMAT = "%s.%N".freeze
 
@@ -16,7 +18,13 @@ module RubySnowflake
 
     # see: https://docs.snowflake.com/en/developer-guide/sql-api/handling-responses#getting-the-data-from-the-results
     def [](column)
-      index = column.is_a?(Numeric) ? Integer(column) : @column_to_index[column]
+      index = if column.is_a?(Numeric)
+                Integer(column)
+              else
+                # Handle column names case-insensitively regardless of string or symbol
+                @column_to_index[column.to_s.downcase]
+              end
+
       return nil if index.nil?
       return nil if @data[index].nil?
 
@@ -49,12 +57,24 @@ module RubySnowflake
       end
     end
 
-    def to_h
-      output = {}
+    def each
+      return to_enum __method__ unless block_given?
+
       @column_to_index.each_pair do |name, index|
-        output[name.downcase] = self[index]
+        yield(name, self[index])
       end
-      output
+
+      self
+    end
+
+    def keys
+      map { |k, _| k }
+    end
+
+    alias columns keys
+
+    def values
+      map { |_, v| v }
     end
 
     def to_s

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.3.0"
+  VERSION = "1.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rb_snowflake_client
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Rinsed
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-03 00:00:00.000000000 Z
+date: 2025-10-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -124,6 +124,7 @@ files:
 - ".github/workflows/release-gh-packages.yml"
 - ".github/workflows/release-rubygems.yml"
 - ".gitignore"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -146,7 +147,7 @@ homepage: https://github.com/rinsed-org/rb-snowflake-client
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -161,8 +162,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Snowflake connector for Ruby
 test_files: []