clickhouse-rb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a02afdcdcdd890944f581300c9ff98218ec8b7458d7dee112d35d8c0a1ce947b
-  data.tar.gz: d09c320b71796475a012155a2d9b8b8b845e638c947e7e9551f22bd6fcbb1288
+  metadata.gz: 1ccbd22754bea20c9ca9fed064ef2b4e7a5cf936b9e6c8c3f819f732adfc25e7
+  data.tar.gz: 9537ffae5678fa0bf7ffbdd7b0cbb505aa66a8471072271765e98e99456a7f9d
 SHA512:
-  metadata.gz: 9882fa7f3d7e3727922536b05523405678806ad3b57be3094bddfa4e6430fb10ae86148b05582a6e648efa662a15cea7f78f8bc6fc2064da0427d15dc4b95787
-  data.tar.gz: 0e4ff78680cdedd9ef3271b84cd4bf1b1550eaf27199644f4b64a30a1fad1bb30429d98f39e270630fc201505d094abf11e09194a4b527ce3e9eac816a3ab8b4
+  metadata.gz: a289ee47e7d21efdf378737f101dca5efb11a0938ff41b0be804a39a2b0e2d6a694a78e57b0037d65a0e9fe136042d32f3d4377f5320bf9f63d0119d7bb51d33
+  data.tar.gz: e836803b9664e2e5548af277978ed7170b8f18e79b767d908f2bbe8005464bc016fb6261bec5fa84d60774c632b6a42578e1d56899a63f90309c49941050750f

data/CHANGELOG.md

@@ -1,4 +1,8 @@
-## [Unreleased]
+## [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

@@ -53,10 +53,8 @@ end
 conn = Clickhouse::Connection.new
 response = conn.query("SELECT * FROM users WHERE id = 1")
 
-if response.success?
-  response.rows.each do |row|
-    puts row.inspect
-  end
+response.rows.each do |row|
+  puts row.inspect
 end
 ```
 
@@ -96,11 +94,6 @@ 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)
-
 # Query summary from ClickHouse
 response.summary   # => {"read_rows" => "1", "read_bytes" => "42", ...}
 ```
@@ -150,14 +143,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"])
 
-      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/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,35 +3,20 @@
 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.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
+  Response = Data.define(:columns, :types, :rows, :summary) do
     # @param columns [Array<String>] column names
     # @param types [Array<String>] 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)
+    def initialize(columns: [], types: [], rows: [], summary: nil)
       super
     end
 
-    # Returns true if the query succeeded.
-    # @return [Boolean]
-    def success? = error.nil?
-
-    # 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 }

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.2.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.2.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