ch_connect 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4176a0227a2a6a7e94c379e75d37325d7cf51428c01131bb88ca9903a9a62e3
-  data.tar.gz: fa438af73ded93b0f5eae03cd77543414d596ba6fc19e23f2e6bc536bb28be21
+  metadata.gz: 50be174654df1074c817ad1cf895a206bc165452dda7fc47b4b6209aa622565f
+  data.tar.gz: e0b9467ebc013a701653ff16c277651e0e81fac81d225ea6d9cc5f2d64b5bb57
 SHA512:
-  metadata.gz: a5718c7457b517d5586e210b597500400bea09145e24a89088ff797b200be4d99522759e7dd1381e3dd79f65bee3c83fbf7a611a7c2abcf39bb3c1f6613a5fbd
-  data.tar.gz: be54de4f246642315f5a815afc2b78498dc30890172cb7318e2cff82a3f801be9f92b86e35c4977f0a30fc3074f1b19a36d7fcfe8f8e80766eaf589833164646
+  metadata.gz: 27992acbdb31511f7838201941f09f36587f2786e2df1b0bb000acc308405fd93d494955c202d0c732c2eace0bde0b0c5ffb106887f5ac9321c028e09d832384
+  data.tar.gz: 6e64f8873f628a856e21f199462c9eef435216ef0c8ea72f7f959a744e10115d85b63cf51f0700babd7919a8f8eb514f13557adc54077a14b01d5e49e1c2a753

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## Unreleased
 
+## [0.2.1] - 2026-02-08
+
+- Added automatic retries on connection errors with configurable `max_retries` (default: 3) ([#6](https://github.com/kukicola/ch_connect/pull/6))
+
+## [0.2.0] - 2026-01-31
+
+- Added benchmark suite comparing against other ClickHouse Ruby gems ([#5](https://github.com/kukicola/ch_connect/pull/5))
+- Optimized BodyReader with chunked buffering for better memory efficiency ([#5](https://github.com/kukicola/ch_connect/pull/5))
+- Optimized NativeFormatParser with transpose-based row building ([#5](https://github.com/kukicola/ch_connect/pull/5))
+
 ## [0.1.0] - 2026-01-31
 
 - Initial release

data/README.md

@@ -8,9 +8,32 @@ Fast Ruby client for ClickHouse database using the Native binary format for effi
 
 - Native binary format parsing (faster than JSON/TSV)
 - Persistent HTTP connections with built-in connection pooling
+- Automatic retries on connection errors
 - Thread-safe concurrent access
 - Supports all common ClickHouse data types
 
+## Benchmarks
+
+Compared against other Ruby ClickHouse gems ([click_house](https://github.com/shlima/click_house), [clickhouse](https://github.com/archan937/clickhouse), [click_house-client](https://gitlab.com/gitlab-org/ruby/gems/clickhouse-client)) on Ruby 3.4.3:
+
+**Speed (iterations/second, higher is better):**
+
+| Scenario | ch_connect | click_house | clickhouse | click_house-client |
+|----------|------------|-------------|------------|--------------------|
+| Small queries (10 rows) | **680 i/s** | 342 i/s (2.0x slower) | 293 i/s (2.3x slower) | 346 i/s (2.0x slower) |
+| Large queries (100K rows) | **3.5 i/s** | 1.1 i/s (3.3x slower) | 0.5 i/s (6.9x slower) | 1.6 i/s (2.2x slower) |
+
+**Memory (large query, lower is better):**
+
+| Gem | Allocated |
+|-----|-----------|
+| ch_connect | **130 MB** |
+| click_house | 205 MB (1.6x more) |
+| clickhouse | 483 MB (3.7x more) |
+| click_house-client | 210 MB (1.6x more) |
+
+See `benchmark/` directory for full benchmark suite and methodology.
+
 ## Installation
 
 Add to your Gemfile:
@@ -156,6 +179,7 @@ response = conn.query(
 | `write_timeout` | `60` | Write timeout in seconds |
 | `pool_size` | `100` | Connection pool size |
 | `pool_timeout` | `5` | Pool checkout timeout in seconds |
+| `max_retries` | `3` | Max retry attempts on connection errors (0 to disable) |
 | `instrumenter` | `NullInstrumenter` | Instrumenter for query instrumentation |
 
 ## Instrumentation

data/lib/ch_connect/body_reader.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
 module ChConnect
-  # Wrapper for HTTP response body providing position tracking and EOF detection.
+  # Wrapper for HTTP response body providing buffered reads.
+  # Reads data in chunks for efficient small reads.
   # @api private
   class BodyReader
+    CHUNK_SIZE = 64 * 1024 # 64KB chunks
+
     # Creates a new body reader.
     #
     # @param body [#read, #bytesize, #close] HTTP response body
     def initialize(body)
       @body = body
-      @pos = 0
       @size = body.bytesize
+      @buffer = "".b
+      @buffer_pos = 0
+      @eof = false
     end
 
     # Closes the underlying body.
@@ -24,7 +29,8 @@ module ChConnect
     #
     # @return [Boolean]
     def eof?
-      @pos >= @size
+      fill_buffer(1) if @buffer_pos >= @buffer.bytesize && !@eof
+      @eof && @buffer_pos >= @buffer.bytesize
     end
 
     # Reads exactly n bytes from the body.
@@ -32,9 +38,42 @@ module ChConnect
     # @param n [Integer] number of bytes to read
     # @return [String] binary string of n bytes
     def read(n)
-      result = @body.read(n)
-      @pos += n
+      fill_buffer(n)
+      result = @buffer.byteslice(@buffer_pos, n)
+      @buffer_pos += n
+      compact_buffer if @buffer_pos > CHUNK_SIZE
       result
     end
+
+    # Reads a single byte as integer, returns nil at EOF.
+    #
+    # @return [Integer, nil] byte value or nil at EOF
+    def getbyte
+      fill_buffer(1)
+      return nil if @buffer_pos >= @buffer.bytesize
+
+      byte = @buffer.getbyte(@buffer_pos)
+      @buffer_pos += 1
+      compact_buffer if @buffer_pos > CHUNK_SIZE
+      byte
+    end
+
+    private
+
+    def fill_buffer(needed)
+      while !@eof && (@buffer.bytesize - @buffer_pos) < needed
+        chunk = @body.read(CHUNK_SIZE)
+        if chunk.nil? || chunk.empty?
+          @eof = true
+        else
+          @buffer << chunk
+        end
+      end
+    end
+
+    def compact_buffer
+      @buffer = @buffer.byteslice(@buffer_pos..-1) || "".b
+      @buffer_pos = 0
+    end
   end
 end

data/lib/ch_connect/config.rb

@@ -24,6 +24,7 @@ module ChConnect
       write_timeout: 60,
       pool_size: 100,
       pool_timeout: 5,
+      max_retries: 3,
       instrumenter: NullInstrumenter.new
     }.freeze
 
@@ -38,8 +39,9 @@ module ChConnect
     # @return [Integer] Write timeout in seconds
     # @return [Integer] Connection pool size
     # @return [Integer] Pool checkout timeout in seconds
+    # @return [Integer] Max retry attempts on connection errors
     # @return [#instrument] Instrumenter for query instrumentation
-    attr_accessor :scheme, :host, :port, :database, :username, :password, :connection_timeout, :read_timeout, :write_timeout, :pool_size, :pool_timeout, :instrumenter
+    attr_accessor :scheme, :host, :port, :database, :username, :password, :connection_timeout, :read_timeout, :write_timeout, :pool_size, :pool_timeout, :max_retries, :instrumenter
 
     # Creates a new configuration instance.
     #
@@ -55,6 +57,7 @@ module ChConnect
     # @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)
+    # @option params [Integer] :max_retries max retry attempts on connection errors (default: 3)
     def initialize(params = {})
       DEFAULTS.merge(params).each do |key, value|
         send("#{key}=", value)

data/lib/ch_connect/http_transport.rb

@@ -14,6 +14,7 @@ module ChConnect
       @config = config
       @base_url = "#{config.scheme}://#{config.host}:#{config.port}"
       @http_client = HTTPX.plugin(:persistent, close_on_fork: true)
+        .plugin(:retries, max_retries: config.max_retries, retry_change_requests: true)
         .with(
           timeout: {
             connect_timeout: config.connection_timeout,

data/lib/ch_connect/native_format_parser.rb

@@ -52,9 +52,7 @@ module ChConnect
         columns_data << read_column(col_type, num_rows)
       end
 
-      num_rows.times do |row_idx|
-        @rows << columns_data.map { |col| col[row_idx] }
-      end
+      @rows.concat(columns_data.transpose) if num_rows > 0
     end
 
     def read_column(type, num_rows)
@@ -247,9 +245,8 @@ module ChConnect
       result = 0
       shift = 0
       loop do
-        byte_str = @reader.read(1)
-        return result if byte_str.nil? || byte_str.empty?
-        byte = byte_str.ord
+        byte = @reader.getbyte
+        return result if byte.nil?
         result |= (byte & 0x7F) << shift
         break if (byte & 0x80) == 0
         shift += 7
@@ -286,7 +283,8 @@ module ChConnect
     def read_nullable_column(inner_type, num_rows)
       nulls = @reader.read(num_rows).bytes
       values = read_column(inner_type, num_rows)
-      values.each_with_index.map { |v, i| (nulls[i] == 1) ? nil : v }
+      num_rows.times { |i| values[i] = nil if nulls[i] == 1 }
+      values
     end
 
     # Array: cumulative offsets (uint64 per row), then all elements
@@ -298,10 +296,10 @@ module ChConnect
 
       elements = read_column(inner_type, total_elements)
 
-      arrays = []
+      arrays = Array.new(num_rows)
       prev_offset = 0
-      offsets.each do |offset|
-        arrays << elements[prev_offset...offset]
+      offsets.each_with_index do |offset, i|
+        arrays[i] = elements.slice(prev_offset, offset - prev_offset)
         prev_offset = offset
       end
       arrays
@@ -317,10 +315,11 @@ module ChConnect
       keys = read_column(key_type, total_pairs)
       values = read_column(value_type, total_pairs)
 
-      maps = []
+      maps = Array.new(num_rows)
       prev_offset = 0
-      offsets.each do |offset|
-        maps << keys[prev_offset...offset].zip(values[prev_offset...offset]).to_h
+      offsets.each_with_index do |offset, i|
+        len = offset - prev_offset
+        maps[i] = keys.slice(prev_offset, len).zip(values.slice(prev_offset, len)).to_h
         prev_offset = offset
       end
       maps

data/lib/ch_connect/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ch_connect
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Karol Bąk