clickhouse-rb 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a02afdcdcdd890944f581300c9ff98218ec8b7458d7dee112d35d8c0a1ce947b
-  data.tar.gz: d09c320b71796475a012155a2d9b8b8b845e638c947e7e9551f22bd6fcbb1288
+  metadata.gz: b3665b6f44472615341970c7b6169eaa3e54e7df0132ad866d24b8e24cb170df
+  data.tar.gz: b5948f2b40a4e969ed35daf92dfb24f3da23215fa113b86b168c3ab911f20335
 SHA512:
-  metadata.gz: 9882fa7f3d7e3727922536b05523405678806ad3b57be3094bddfa4e6430fb10ae86148b05582a6e648efa662a15cea7f78f8bc6fc2064da0427d15dc4b95787
-  data.tar.gz: 0e4ff78680cdedd9ef3271b84cd4bf1b1550eaf27199644f4b64a30a1fad1bb30429d98f39e270630fc201505d094abf11e09194a4b527ce3e9eac816a3ab8b4
+  metadata.gz: 777e4c17a2d3278fb7a1221ed16f5d4ea01f16eeaac31c5e24ba52f81a2b5dc81613ea379c1e722b9d75f55c3850f6761a1ad5e45265e3be4a2199449777f68c
+  data.tar.gz: af8ac7a565c217142e5234d4d83dc9caf70cf2aca86714985b76155ecf8434076f27b9716794f09090b392033a49a7b14097645bc8b180190d089df4e45616c5

data/CHANGELOG.md

@@ -1,4 +1,14 @@
-## [Unreleased]
+## Unreleased
+
+## [0.3.0] - 2025-12-31
+
+- Make responses more user-friendly ([#1](https://github.com/kukicola/clickhouse-rb/pull/1))
+
+## [0.2.0] - 2025-12-28
+
+- Added instrumentation support with configurable `instrumenter` (defaults to `NullInstrumenter`)
+- Query errors now raise `Clickhouse::QueryError` instead of returning a failed response
+- Removed `Response#success?`, `Response#failure?`, and `Response#error` methods
 
 ## [0.1.0] - 2025-12-28
 

data/README.md

@@ -51,12 +51,10 @@ end
 
 ```ruby
 conn = Clickhouse::Connection.new
-response = conn.query("SELECT * FROM users WHERE id = 1")
+response = conn.query("SELECT id, name FROM users WHERE active = true")
 
-if response.success?
-  response.rows.each do |row|
-    puts row.inspect
-  end
+response.each do |row|
+  puts "#{row[:id]}: #{row[:name]}"
 end
 ```
 
@@ -85,24 +83,29 @@ end
 
 ### Working with Results
 
+Response objects implement `Enumerable`, allowing direct iteration:
+
 ```ruby
 response = conn.query("SELECT id, name, created_at FROM users")
 
+# Iterate over rows as hashes with symbol keys
+response.each { |row| puts row[:name] }
+
+# Use any Enumerable method
+response.map { |row| row[:id] }
+response.select { |row| row[:id] > 10 }
+response.first   # => {id: 1, name: "Alice", created_at: 2024-01-01 00:00:00 UTC}
+
 # Access raw rows (arrays)
 response.rows      # => [[1, "Alice", 2024-01-01 00:00:00 UTC], ...]
-response.columns   # => ["id", "name", "created_at"]
-response.types     # => ["UInt64", "String", "DateTime"]
+response.columns   # => [:id, :name, :created_at]
+response.types     # => [:UInt64, :String, :DateTime]
 
 # Convert to array of hashes
-response.to_a      # => [{"id" => 1, "name" => "Alice", ...}, ...]
-
-# Check for errors
-response.success?  # => true
-response.failure?  # => false
-response.error     # => nil (or error message string)
+response.to_a      # => [{id: 1, name: "Alice", ...}, ...]
 
-# Query summary from ClickHouse
-response.summary   # => {"read_rows" => "1", "read_bytes" => "42", ...}
+# Query summary from ClickHouse (symbol keys)
+response.summary   # => {read_rows: "1", read_bytes: "42", ...}
 ```
 
 ### Query Parameters
@@ -150,14 +153,32 @@ response = conn.query(
 | `connection_timeout` | `5` | Connection timeout in seconds |
 | `pool_size` | `100` | Connection pool size |
 | `pool_timeout` | `5` | Pool checkout timeout in seconds |
+| `instrumenter` | `NullInstrumenter` | Instrumenter for query instrumentation |
 
-## Error Handling
+## Instrumentation
+
+You can instrument queries by providing an instrumenter that responds to `#instrument`:
 
 ```ruby
-response = conn.query("INVALID SQL")
+Clickhouse.configure do |config|
+  config.instrumenter = ActiveSupport::Notifications
+end
 
-if response.failure?
-  puts "Query failed: #{response.error}"
+# Subscribe to events
+ActiveSupport::Notifications.subscribe("query.clickhouse") do |name, start, finish, id, payload|
+  puts "Query: #{payload[:sql]} took #{finish - start}s"
+end
+```
+
+The instrumenter receives event name `"query.clickhouse"` and payload `{sql: "..."}`.
+
+## Error Handling
+
+```ruby
+begin
+  conn.query("INVALID SQL")
+rescue Clickhouse::QueryError => e
+  puts "Query failed: #{e.message}"
 end
 
 # Unsupported types raise an exception

data/lib/clickhouse/config.rb

@@ -21,7 +21,8 @@ module Clickhouse
       password: "",
       connection_timeout: 5,
       pool_size: 100,
-      pool_timeout: 5
+      pool_timeout: 5,
+      instrumenter: NullInstrumenter.new
     }.freeze
 
     # @return [String] URL scheme (http or https)
@@ -33,7 +34,8 @@ module Clickhouse
     # @return [Integer] Connection timeout in seconds
     # @return [Integer] Connection pool size
     # @return [Integer] Pool checkout timeout in seconds
-    attr_accessor :scheme, :host, :port, :database, :username, :password, :connection_timeout, :pool_size, :pool_timeout
+    # @return [#instrument] Instrumenter for query instrumentation
+    attr_accessor :scheme, :host, :port, :database, :username, :password, :connection_timeout, :pool_size, :pool_timeout, :instrumenter
 
     # Creates a new configuration instance.
     #

data/lib/clickhouse/connection.rb

@@ -24,11 +24,12 @@ module Clickhouse
     # @param options [Hash] query options
     # @option options [Hash] :params query parameters
     # @return [Response] query response with rows, columns, and metadata
+    # @raise [QueryError] if the query fails
     def query(sql, options = {})
-      result = @transport.execute(sql, options)
-      return Response.new(error: result.error, summary: result.summary) unless result.success
-
-      NativeFormatParser.new(result.body).parse.with(summary: result.summary)
+      @config.instrumenter.instrument("query.clickhouse", {sql: sql}) do
+        result = @transport.execute(sql, options)
+        NativeFormatParser.new(result.body).parse.with(summary: result.summary)
+      end
     end
   end
 end

data/lib/clickhouse/http_transport.rb

@@ -30,18 +30,17 @@ module Clickhouse
     # @param sql [String] SQL query to execute
     # @param options [Hash] query options
     # @option options [Hash] :params query parameters
-    # @return [TransportResult] result containing body or error
+    # @return [TransportResult] result containing body and summary
+    # @raise [QueryError] if the query fails
     def execute(sql, options = {})
       query_params = {database: @config.database}.merge(options[:params] || {})
       response = @http_client.post("/", params: query_params, body: sql, headers: @default_headers)
 
-      summary = JSON.parse(response.headers["X-ClickHouse-Summary"])
+      summary = JSON.parse(response.headers["X-ClickHouse-Summary"], symbolize_names: true)
 
-      if response.status.success?
-        TransportResult.new(success: true, body: response.body, error: nil, summary: summary)
-      else
-        TransportResult.new(success: false, body: nil, error: response.body.to_s, summary: summary)
-      end
+      raise QueryError, response.body.to_s unless response.status.success?
+
+      TransportResult.new(body: response.body, summary: summary)
     end
   end
 end

data/lib/clickhouse/native_format_parser.rb

@@ -46,8 +46,8 @@ module Clickhouse
         col_type = read_string
 
         if @columns.length < num_columns
-          @columns << col_name
-          @types << col_type
+          @columns << col_name.to_sym
+          @types << col_type.to_sym
         end
 
         columns_data << read_column(col_type, num_rows)
@@ -65,14 +65,14 @@ module Clickhouse
       when "UInt16" then read_uint16_column(num_rows)
       when "UInt32" then read_uint32_column(num_rows)
       when "UInt64" then read_uint64_column(num_rows)
-      when "UInt128" then Array.new(num_rows) { read_uint128 }
-      when "UInt256" then Array.new(num_rows) { read_uint256 }
+      when "UInt128" then read_uint128_column(num_rows)
+      when "UInt256" then read_uint256_column(num_rows)
       when "Int8" then read_int8_column(num_rows)
       when "Int16" then read_int16_column(num_rows)
       when "Int32" then read_int32_column(num_rows)
       when "Int64" then read_int64_column(num_rows)
-      when "Int128" then Array.new(num_rows) { read_int128 }
-      when "Int256" then Array.new(num_rows) { read_int256 }
+      when "Int128" then read_int128_column(num_rows)
+      when "Int256" then read_int256_column(num_rows)
 
       # Floats
       when "Float32" then read_float32_column(num_rows)
@@ -82,7 +82,7 @@ module Clickhouse
       when "Bool" then read_bool_column(num_rows)
 
       # Strings
-      when "String" then Array.new(num_rows) { read_string }
+      when "String" then read_string_column(num_rows)
       when /^FixedString\((\d+)\)$/ then read_fixed_string_column($1.to_i, num_rows)
 
       # Dates and Times
@@ -92,11 +92,11 @@ module Clickhouse
       when /^DateTime64\((\d+)(?:,.*)?\)$/ then read_datetime64_column($1.to_i, num_rows)
 
       # UUID
-      when "UUID" then Array.new(num_rows) { read_uuid }
+      when "UUID" then read_uuid_column(num_rows)
 
       # IP addresses
-      when "IPv4" then Array.new(num_rows) { read_ipv4 }
-      when "IPv6" then Array.new(num_rows) { read_ipv6 }
+      when "IPv4" then read_ipv4_column(num_rows)
+      when "IPv6" then read_ipv6_column(num_rows)
 
       # Decimals - ClickHouse always returns Decimal(precision, scale)
       when /^Decimal\((\d+),\s*(\d+)\)$/ then read_decimal_column($1.to_i, $2.to_i, num_rows)
@@ -145,6 +145,14 @@ module Clickhouse
       @reader.read(num_rows * 8).unpack("Q<*")
     end
 
+    def read_uint128_column(num_rows)
+      Array.new(num_rows) { read_le_bytes(16) }
+    end
+
+    def read_uint256_column(num_rows)
+      Array.new(num_rows) { read_le_bytes(32) }
+    end
+
     def read_int8_column(num_rows)
       @reader.read(num_rows).unpack("c*")
     end
@@ -161,6 +169,14 @@ module Clickhouse
       @reader.read(num_rows * 8).unpack("q<*")
     end
 
+    def read_int128_column(num_rows)
+      Array.new(num_rows) { read_signed_le_bytes(16) }
+    end
+
+    def read_int256_column(num_rows)
+      Array.new(num_rows) { read_signed_le_bytes(32) }
+    end
+
     def read_float32_column(num_rows)
       @reader.read(num_rows * 4).unpack("e*")
     end
@@ -173,6 +189,10 @@ module Clickhouse
       @reader.read(num_rows).bytes.map { |b| b == 1 }
     end
 
+    def read_string_column(num_rows)
+      Array.new(num_rows) { read_string }
+    end
+
     def read_fixed_string_column(length, num_rows)
       Array.new(num_rows) { @reader.read(length).force_encoding(Encoding::UTF_8) }
     end
@@ -197,6 +217,18 @@ module Clickhouse
       end
     end
 
+    def read_uuid_column(num_rows)
+      Array.new(num_rows) { read_uuid }
+    end
+
+    def read_ipv4_column(num_rows)
+      Array.new(num_rows) { read_ipv4 }
+    end
+
+    def read_ipv6_column(num_rows)
+      Array.new(num_rows) { read_ipv6 }
+    end
+
     def read_decimal_column(precision, scale, num_rows)
       divisor = 10**scale
       if precision <= 9
@@ -230,10 +262,6 @@ module Clickhouse
     end
 
     def read_uint64 = @reader.read(8).unpack1("Q<")
-    def read_uint128 = read_le_bytes(16)
-    def read_uint256 = read_le_bytes(32)
-    def read_int128 = read_signed_le_bytes(16)
-    def read_int256 = read_signed_le_bytes(32)
 
     def read_uuid
       first_half = @reader.read(8).bytes.reverse

data/lib/clickhouse/null_instrumenter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Clickhouse
+  # Null instrumenter that does nothing.
+  # This is the default instrumenter used when no custom instrumenter is configured.
+  class NullInstrumenter
+    # Executes block without any instrumentation.
+    #
+    # @param _name [String] event name (ignored)
+    # @param _payload [Hash] event payload (ignored)
+    # @yield block to execute
+    # @return [Object] result of the block
+    def instrument(_name, _payload = {})
+      yield
+    end
+  end
+end

data/lib/clickhouse/response.rb

@@ -3,37 +3,29 @@
 module Clickhouse
   # Immutable response object containing query results.
   #
-  # @example Successful response
+  # @example
   #   response = conn.query("SELECT id, name FROM users")
-  #   response.success?  # => true
-  #   response.columns   # => ["id", "name"]
+  #   response.columns   # => [:id, :name]
   #   response.rows      # => [[1, "Alice"], [2, "Bob"]]
-  #   response.to_a      # => [{"id" => 1, "name" => "Alice"}, ...]
-  #
-  # @example Failed response
-  #   response = conn.query("INVALID SQL")
-  #   response.failure?  # => true
-  #   response.error     # => "Syntax error..."
-  Response = Data.define(:columns, :types, :rows, :error, :summary) do
-    # @param columns [Array<String>] column names
-    # @param types [Array<String>] column types
+  #   response.each { |row| puts row[:name] }
+  Response = Data.define(:columns, :types, :rows, :summary) do
+    include Enumerable
+
+    # @param columns [Array<Symbol>] column names
+    # @param types [Array<Symbol>] column types
     # @param rows [Array<Array>] row data
-    # @param error [String, nil] error message if query failed
-    # @param summary [Hash, nil] ClickHouse query summary
-    def initialize(columns: [], types: [], rows: [], error: nil, summary: nil)
+    # @param summary [Hash, nil] ClickHouse query summary with symbol keys
+    def initialize(columns: [], types: [], rows: [], summary: nil)
       super
     end
 
-    # Returns true if the query succeeded.
-    # @return [Boolean]
-    def success? = error.nil?
+    # Iterates over rows as hashes with symbol keys.
+    # @yield [Hash] each row as a hash
+    # @return [Enumerator] if no block given
+    def each
+      return to_enum(:each) unless block_given?
 
-    # Returns true if the query failed.
-    # @return [Boolean]
-    def failure? = !success?
-
-    # Converts rows to an array of hashes.
-    # @return [Array<Hash>] rows as hashes with column names as keys
-    def to_a = rows.map { |row| columns.zip(row).to_h }
+      rows.each { |row| yield columns.zip(row).to_h }
+    end
   end
 end

data/lib/clickhouse/transport_result.rb

@@ -4,13 +4,9 @@ module Clickhouse
   # Immutable result from transport layer.
   # @api private
   #
-  # @!attribute [r] success
-  #   @return [Boolean] true if request succeeded
   # @!attribute [r] body
-  #   @return [HTTP::Response::Body, nil] response body for successful requests
-  # @!attribute [r] error
-  #   @return [String, nil] error message for failed requests
+  #   @return [HTTP::Response::Body] response body
   # @!attribute [r] summary
   #   @return [Hash] ClickHouse query summary
-  TransportResult = Data.define(:success, :body, :error, :summary)
+  TransportResult = Data.define(:body, :summary)
 end

data/lib/clickhouse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clickhouse
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/clickhouse-rb.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "clickhouse"

data/lib/clickhouse.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "clickhouse/version"
+require_relative "clickhouse/null_instrumenter"
 require_relative "clickhouse/config"
 require_relative "clickhouse/transport_result"
 require_relative "clickhouse/http_transport"
@@ -28,6 +29,9 @@ module Clickhouse
   # Base error class for all Clickhouse errors
   class Error < StandardError; end
 
+  # Raised when a query fails (syntax error, unknown table, etc.)
+  class QueryError < Error; end
+
   # Raised when encountering an unsupported ClickHouse data type
   class UnsupportedTypeError < Error; end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clickhouse-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Karol Bąk
@@ -63,12 +63,14 @@ files:
 - ".standard.yml"
 - CHANGELOG.md
 - README.md
+- lib/clickhouse-rb.rb
 - lib/clickhouse.rb
 - lib/clickhouse/buffered_reader.rb
 - lib/clickhouse/config.rb
 - lib/clickhouse/connection.rb
 - lib/clickhouse/http_transport.rb
 - lib/clickhouse/native_format_parser.rb
+- lib/clickhouse/null_instrumenter.rb
 - lib/clickhouse/pool.rb
 - lib/clickhouse/response.rb
 - lib/clickhouse/transport_result.rb