clickhouse-rb 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ccbd22754bea20c9ca9fed064ef2b4e7a5cf936b9e6c8c3f819f732adfc25e7
-  data.tar.gz: 9537ffae5678fa0bf7ffbdd7b0cbb505aa66a8471072271765e98e99456a7f9d
+  metadata.gz: 86a862148595c1c9794a3d122e750db7959f5d4478b9dc3f65ee0f00319c55c0
+  data.tar.gz: c346972569d9e190445eceea9c9c7eef9bffa8d0dea95825ed53c1025e52e74a
 SHA512:
-  metadata.gz: a289ee47e7d21efdf378737f101dca5efb11a0938ff41b0be804a39a2b0e2d6a694a78e57b0037d65a0e9fe136042d32f3d4377f5320bf9f63d0119d7bb51d33
-  data.tar.gz: e836803b9664e2e5548af277978ed7170b8f18e79b767d908f2bbe8005464bc016fb6261bec5fa84d60774c632b6a42578e1d56899a63f90309c49941050750f
+  metadata.gz: a31b2bcd62a7157933af6e3e57a28b3314a9b42fd91c8250304f77a2eb8eb74c4df5651f1952ff76e237aa586eae77135e8d84dc24672e42eba9a95c2c42c899
+  data.tar.gz: '09479b26facc3ae8584d584cd1d2982c3aa46f0c43cffa5a0ec91baa93d036647ce5a910224f51f17ed26c157755e8f5eed3fbbf3d0994a849086258d269d866'

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## Unreleased
+
+## [0.4.0] - 2026-01-25
+
+- Replace http.rb with httpx for HTTP client, remove `Pool` class ([#3](https://github.com/kukicola/clickhouse-rb/pull/3))
+
+## [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`)

data/README.md

@@ -5,8 +5,8 @@ Fast Ruby client for ClickHouse database using the Native binary format for effi
 ## Features
 
 - Native binary format parsing (faster than JSON/TSV)
-- Persistent HTTP connections
-- Connection pooling for thread-safe concurrent access
+- Persistent HTTP connections with built-in connection pooling
+- Thread-safe concurrent access
 - Supports all common ClickHouse data types
 
 ## Installation
@@ -51,51 +51,60 @@ 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")
 
-response.rows.each do |row|
-  puts row.inspect
+response.each do |row|
+  puts "#{row[:id]}: #{row[:name]}"
 end
 ```
 
-### Connection Pool
+### Thread-Safe Usage
 
-For multi-threaded applications:
+Connections use httpx's built-in connection pooling, making them safe for concurrent use:
 
 ```ruby
-pool = Clickhouse::Pool.new
+conn = Clickhouse::Connection.new
 
-# Thread-safe queries
 threads = 10.times.map do
-  Thread.new { pool.query("SELECT 1") }
+  Thread.new { conn.query("SELECT 1") }
 end
 threads.each(&:join)
 ```
 
-Pool size and timeout are configured globally:
+Pool settings are configured globally:
 
 ```ruby
 Clickhouse.configure do |config|
-  config.pool_size = 10
+  config.pool_size = 10 
   config.pool_timeout = 5
 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", ...}, ...]
+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
@@ -141,6 +150,8 @@ response = conn.query(
 | `username` | `""` | Authentication username |
 | `password` | `""` | Authentication password |
 | `connection_timeout` | `5` | Connection timeout in seconds |
+| `read_timeout` | `60` | Read timeout in seconds |
+| `write_timeout` | `60` | Write timeout in seconds |
 | `pool_size` | `100` | Connection pool size |
 | `pool_timeout` | `5` | Pool checkout timeout in seconds |
 | `instrumenter` | `NullInstrumenter` | Instrumenter for query instrumentation |

data/lib/clickhouse/body_reader.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Clickhouse
+  # Wrapper for HTTP response body providing position tracking and EOF detection.
+  # @api private
+  class BodyReader
+    # Creates a new body reader.
+    #
+    # @param body [#read, #bytesize, #close] HTTP response body
+    def initialize(body)
+      @body = body
+      @pos = 0
+      @size = body.bytesize
+    end
+
+    # Closes the underlying body.
+    #
+    # @return [void]
+    def close
+      @body.close
+    end
+
+    # Returns true if at end of stream.
+    #
+    # @return [Boolean]
+    def eof?
+      @pos >= @size
+    end
+
+    # Reads exactly n bytes from the body.
+    #
+    # @param n [Integer] number of bytes to read
+    # @return [String] binary string of n bytes
+    def read(n)
+      result = @body.read(n)
+      @pos += n
+      result
+    end
+  end
+end

data/lib/clickhouse/config.rb

@@ -20,6 +20,8 @@ module Clickhouse
       username: "",
       password: "",
       connection_timeout: 5,
+      read_timeout: 60,
+      write_timeout: 60,
       pool_size: 100,
       pool_timeout: 5,
       instrumenter: NullInstrumenter.new
@@ -32,10 +34,12 @@ module Clickhouse
     # @return [String] Username for authentication
     # @return [String] Password for authentication
     # @return [Integer] Connection timeout in seconds
+    # @return [Integer] Read timeout in seconds
+    # @return [Integer] Write timeout in seconds
     # @return [Integer] Connection pool size
     # @return [Integer] Pool checkout timeout in seconds
     # @return [#instrument] Instrumenter for query instrumentation
-    attr_accessor :scheme, :host, :port, :database, :username, :password, :connection_timeout, :pool_size, :pool_timeout, :instrumenter
+    attr_accessor :scheme, :host, :port, :database, :username, :password, :connection_timeout, :read_timeout, :write_timeout, :pool_size, :pool_timeout, :instrumenter
 
     # Creates a new configuration instance.
     #
@@ -46,7 +50,9 @@ module Clickhouse
     # @option params [String] :database database name (default: "default")
     # @option params [String] :username authentication username (default: "")
     # @option params [String] :password authentication password (default: "")
-    # @option params [Integer] :connection_timeout timeout in seconds (default: 5)
+    # @option params [Integer] :connection_timeout connection timeout in seconds (default: 5)
+    # @option params [Integer] :read_timeout read timeout in seconds (default: 60)
+    # @option params [Integer] :write_timeout write timeout in seconds (default: 60)
     # @option params [Integer] :pool_size connection pool size (default: 100)
     # @option params [Integer] :pool_timeout pool checkout timeout (default: 5)
     def initialize(params = {})

data/lib/clickhouse/http_transport.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "http"
+require "httpx"
 require "json"
 
 module Clickhouse
@@ -12,10 +12,19 @@ module Clickhouse
     # @param config [Config] configuration instance
     def initialize(config)
       @config = config
-      @http_client = HTTP.persistent("#{config.scheme}://#{config.host}:#{config.port}")
-        .use(:auto_deflate)
-        .use(:auto_inflate)
-        .timeout(connect: config.connection_timeout)
+      @base_url = "#{config.scheme}://#{config.host}:#{config.port}"
+      @http_client = HTTPX.plugin(:persistent, close_on_fork: true)
+        .with(
+          timeout: {
+            connect_timeout: config.connection_timeout,
+            read_timeout: config.read_timeout,
+            write_timeout: config.write_timeout
+          },
+          pool_options: {
+            max_connections_per_origin: config.pool_size,
+            pool_timeout: config.pool_timeout
+          }
+        )
 
       @default_headers = {
         "Accept-Encoding" => "gzip",
@@ -34,11 +43,13 @@ module Clickhouse
     # @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)
+      response = @http_client.post(@base_url, params: query_params, body: sql, headers: @default_headers)
 
-      summary = JSON.parse(response.headers["X-ClickHouse-Summary"])
+      raise QueryError, response.error.message if response.error
 
-      raise QueryError, response.body.to_s unless response.status.success?
+      summary = JSON.parse(response.headers["x-clickhouse-summary"], symbolize_names: true)
+
+      raise QueryError, response.body.to_s unless response.status == 200
 
       TransportResult.new(body: response.body, summary: summary)
     end

data/lib/clickhouse/native_format_parser.rb

@@ -11,9 +11,9 @@ module Clickhouse
 
     # Creates a new parser.
     #
-    # @param body [#readpartial] response body to parse
+    # @param body [#read] response body to parse
     def initialize(body)
-      @body = body
+      @reader = BodyReader.new(body)
       @columns = []
       @types = []
       @rows = []
@@ -24,11 +24,10 @@ module Clickhouse
     # @return [Response] parsed response with columns, types, and rows
     # @raise [UnsupportedTypeError] if an unsupported data type is encountered
     def parse
-      @reader = BufferedReader.new(@body)
       parse_block until @reader.eof?
       Response.new(columns: @columns, types: @types, rows: @rows)
     ensure
-      @reader.flush
+      @reader.close
     end
 
     private
@@ -46,8 +45,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 +64,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 +81,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 +91,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 +144,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 +168,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 +188,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 +216,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
@@ -216,8 +247,9 @@ module Clickhouse
       result = 0
       shift = 0
       loop do
-        byte = @reader.read_byte
-        return result if byte.nil?
+        byte_str = @reader.read(1)
+        return result if byte_str.nil? || byte_str.empty?
+        byte = byte_str.ord
         result |= (byte & 0x7F) << shift
         break if (byte & 0x80) == 0
         shift += 7
@@ -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/response.rb

@@ -5,20 +5,27 @@ module Clickhouse
   #
   # @example
   #   response = conn.query("SELECT id, name FROM users")
-  #   response.columns   # => ["id", "name"]
+  #   response.columns   # => [:id, :name]
   #   response.rows      # => [[1, "Alice"], [2, "Bob"]]
-  #   response.to_a      # => [{"id" => 1, "name" => "Alice"}, ...]
+  #   response.each { |row| puts row[:name] }
   Response = Data.define(:columns, :types, :rows, :summary) do
-    # @param columns [Array<String>] column names
-    # @param types [Array<String>] column types
+    include Enumerable
+
+    # @param columns [Array<Symbol>] column names
+    # @param types [Array<Symbol>] column types
     # @param rows [Array<Array>] row data
-    # @param summary [Hash, nil] ClickHouse query summary
+    # @param summary [Hash, nil] ClickHouse query summary with symbol keys
     def initialize(columns: [], types: [], rows: [], summary: nil)
       super
     end
 
-    # 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 }
+    # 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?
+
+      rows.each { |row| yield columns.zip(row).to_h }
+    end
   end
 end

data/lib/clickhouse/version.rb

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

data/lib/clickhouse.rb

@@ -6,9 +6,8 @@ require_relative "clickhouse/config"
 require_relative "clickhouse/transport_result"
 require_relative "clickhouse/http_transport"
 require_relative "clickhouse/connection"
-require_relative "clickhouse/pool"
 require_relative "clickhouse/response"
-require_relative "clickhouse/buffered_reader"
+require_relative "clickhouse/body_reader"
 require_relative "clickhouse/native_format_parser"
 
 # Ruby client for ClickHouse database with Native format support.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clickhouse-rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Karol Bąk
@@ -24,33 +24,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.1'
 - !ruby/object:Gem::Dependency
-  name: connection_pool
+  name: httpx
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: http
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '1.0'
 description: Fast Ruby client for ClickHouse database using the Native binary format
   for efficient data transfer
 email:
@@ -65,13 +51,12 @@ files:
 - README.md
 - lib/clickhouse-rb.rb
 - lib/clickhouse.rb
-- lib/clickhouse/buffered_reader.rb
+- lib/clickhouse/body_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
 - lib/clickhouse/version.rb

data/lib/clickhouse/buffered_reader.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-module Clickhouse
-  # Buffered binary reader for streaming IO.
-  # @api private
-  class BufferedReader
-    # Creates a new buffered reader.
-    #
-    # @param io [#readpartial] IO object supporting readpartial
-    def initialize(io)
-      @io = io
-      @buffer = String.new(encoding: Encoding::BINARY)
-      @eof = false
-    end
-
-    # Returns true if at end of stream.
-    #
-    # @return [Boolean]
-    def eof?
-      fill if @buffer.empty?
-      @buffer.empty?
-    end
-
-    # Reads exactly n bytes from the stream.
-    #
-    # @param n [Integer] number of bytes to read
-    # @return [String] binary string of n bytes
-    def read(n)
-      fill until @buffer.bytesize >= n
-      @buffer.slice!(0, n)
-    end
-
-    # Reads a single byte from the stream.
-    #
-    # @return [Integer, nil] byte value (0-255) or nil if at EOF
-    def read_byte
-      fill if @buffer.empty?
-      return if @buffer.empty?
-
-      @buffer.slice!(0, 1).ord
-    end
-
-    # Drains remaining data from the stream.
-    #
-    # @return [void]
-    def flush
-      @buffer.clear
-      nil while @io.readpartial
-    end
-
-    private
-
-    def fill
-      return if @eof
-
-      loop do
-        chunk = @io.readpartial
-        if chunk.nil?
-          @eof = true
-          break
-        elsif !chunk.empty?
-          @buffer << chunk
-          break
-        end
-        # Empty chunk - keep reading (gzip header processing)
-      end
-    end
-  end
-end

data/lib/clickhouse/pool.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-require "connection_pool"
-
-module Clickhouse
-  # Thread-safe connection pool for ClickHouse.
-  #
-  # @example
-  #   pool = Clickhouse::Pool.new
-  #   response = pool.query("SELECT * FROM users")
-  #
-  # @example Concurrent usage
-  #   pool = Clickhouse::Pool.new
-  #   threads = 10.times.map do
-  #     Thread.new { pool.query("SELECT 1") }
-  #   end
-  #   threads.each(&:join)
-  class Pool
-    # Creates a new connection pool.
-    #
-    # @param config [Config] configuration instance (defaults to global config)
-    #   Pool size and timeout are read from config.pool_size and config.pool_timeout
-    def initialize(config = Clickhouse.config)
-      @pool = ConnectionPool.new(size: config.pool_size, timeout: config.pool_timeout) do
-        Connection.new(config)
-      end
-    end
-
-    # Executes a SQL query using a pooled connection.
-    #
-    # @param sql [String] SQL query to execute
-    # @param options [Hash] query options
-    # @option options [Hash] :params query parameters
-    # @return [Response] query response with rows, columns, and metadata
-    def query(sql, options = {})
-      @pool.with { |conn| conn.query(sql, options) }
-    end
-  end
-end