ch_connect 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e4176a0227a2a6a7e94c379e75d37325d7cf51428c01131bb88ca9903a9a62e3
+  data.tar.gz: fa438af73ded93b0f5eae03cd77543414d596ba6fc19e23f2e6bc536bb28be21
+SHA512:
+  metadata.gz: a5718c7457b517d5586e210b597500400bea09145e24a89088ff797b200be4d99522759e7dd1381e3dd79f65bee3c83fbf7a611a7c2abcf39bb3c1f6613a5fbd
+  data.tar.gz: be54de4f246642315f5a815afc2b78498dc30890172cb7318e2cff82a3f801be9f92b86e35c4977f0a30fc3074f1b19a36d7fcfe8f8e80766eaf589833164646

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.4

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## Unreleased
+
+## [0.1.0] - 2026-01-31
+
+- Initial release

data/README.md

@@ -0,0 +1,207 @@
+# ch_connect
+
+> **Note:** This gem was previously published as `clickhouse-rb` and has been renamed to `ch_connect` due to name conflicts.
+
+Fast Ruby client for ClickHouse database using the Native binary format for efficient data transfer.
+
+## Features
+
+- Native binary format parsing (faster than JSON/TSV)
+- Persistent HTTP connections with built-in connection pooling
+- Thread-safe concurrent access
+- Supports all common ClickHouse data types
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ch_connect"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Configuration
+
+```ruby
+require "ch_connect"
+
+ChConnect.configure do |config|
+  config.host = "localhost"
+  config.port = 8123
+  config.database = "default"
+  config.username = "default"
+  config.password = ""
+end
+```
+
+Or configure via URL:
+
+```ruby
+ChConnect.configure do |config|
+  config.url = "http://user:pass@localhost:8123/mydb"
+end
+```
+
+### Single Connection
+
+```ruby
+conn = ChConnect::Connection.new
+response = conn.query("SELECT id, name FROM users WHERE active = true")
+
+response.each do |row|
+  puts "#{row[:id]}: #{row[:name]}"
+end
+```
+
+### Thread-Safe Usage
+
+Connections use httpx's built-in connection pooling, making them safe for concurrent use:
+
+```ruby
+conn = ChConnect::Connection.new
+
+threads = 10.times.map do
+  Thread.new { conn.query("SELECT 1") }
+end
+threads.each(&:join)
+```
+
+Pool settings are configured globally:
+
+```ruby
+ChConnect.configure do |config|
+  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]
+
+# Convert to array of hashes
+response.to_a      # => [{id: 1, name: "Alice", ...}, ...]
+
+# Query summary from ClickHouse (symbol keys)
+response.summary   # => {read_rows: "1", read_bytes: "42", ...}
+```
+
+### Query Parameters
+
+```ruby
+response = conn.query(
+  "SELECT * FROM users WHERE id = {id:UInt64}",
+  params: { param_id: 123 }
+)
+```
+
+## Supported Data Types
+
+| ClickHouse Type | Ruby Type |
+|-----------------|-----------|
+| UInt8/16/32/64 | Integer |
+| UInt128/256 | Integer |
+| Int8/16/32/64 | Integer |
+| Int128/256 | Integer |
+| Float32/64 | Float |
+| Decimal | BigDecimal |
+| Bool | TrueClass/FalseClass |
+| String, FixedString | String |
+| Date, Date32 | Date |
+| DateTime, DateTime64 | Time |
+| UUID | String |
+| IPv4, IPv6 | IPAddr |
+| Enum8, Enum16 | Integer |
+| Array | Array |
+| Tuple | Array |
+| Map | Hash |
+| Nullable | nil or inner type |
+| LowCardinality | inner type |
+
+## Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `scheme` | `"http"` | URL scheme (http/https) |
+| `host` | `"localhost"` | ClickHouse server host |
+| `port` | `8123` | ClickHouse HTTP port |
+| `database` | `"default"` | Database name |
+| `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 |
+
+## Instrumentation
+
+You can instrument queries by providing an instrumenter that responds to `#instrument`:
+
+```ruby
+ChConnect.configure do |config|
+  config.instrumenter = ActiveSupport::Notifications
+end
+
+# 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 ChConnect::QueryError => e
+  puts "Query failed: #{e.message}"
+end
+
+# Unsupported types raise an exception
+begin
+  conn.query("SELECT '{}'::JSON")
+rescue ChConnect::UnsupportedTypeError => e
+  puts "Unsupported type: #{e.message}"
+end
+```
+
+## Development
+
+```bash
+# Run tests (requires ClickHouse)
+CLICKHOUSE_URL=http://default:password@localhost:8123/default bundle exec rspec
+
+# Run linter
+bundle exec standardrb
+```
+
+## License
+
+MIT License

data/lib/ch_connect/body_reader.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ChConnect
+  # 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/ch_connect/config.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module ChConnect
+  # Configuration for ClickHouse connection.
+  #
+  # @example
+  #   config = ChConnect::Config.new(host: "db.example.com", port: 9000)
+  #
+  # @example Using URL
+  #   config = ChConnect::Config.new
+  #   config.url = "http://user:pass@localhost:8123/mydb"
+  class Config
+    DEFAULTS = {
+      scheme: "http",
+      host: "localhost",
+      port: 8123,
+      database: "default",
+      username: "",
+      password: "",
+      connection_timeout: 5,
+      read_timeout: 60,
+      write_timeout: 60,
+      pool_size: 100,
+      pool_timeout: 5,
+      instrumenter: NullInstrumenter.new
+    }.freeze
+
+    # @return [String] URL scheme (http or https)
+    # @return [String] ClickHouse server hostname
+    # @return [Integer] ClickHouse server port
+    # @return [String] Database name
+    # @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, :read_timeout, :write_timeout, :pool_size, :pool_timeout, :instrumenter
+
+    # Creates a new configuration instance.
+    #
+    # @param params [Hash] configuration options
+    # @option params [String] :scheme URL scheme (default: "http")
+    # @option params [String] :host server hostname (default: "localhost")
+    # @option params [Integer] :port server port (default: 8123)
+    # @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 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 = {})
+      DEFAULTS.merge(params).each do |key, value|
+        send("#{key}=", value)
+      end
+    end
+
+    # Sets configuration from a URL string.
+    #
+    # @param url [String] ClickHouse connection URL
+    # @return [void]
+    def url=(url)
+      uri = URI(url)
+      @scheme = uri.scheme
+      @host = uri.host
+      @port = uri.port
+      @database = uri.path.delete_prefix("/")
+      @username = uri.user
+      @password = uri.password
+    end
+  end
+end

data/lib/ch_connect/connection.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module ChConnect
+  # A single connection to ClickHouse server.
+  #
+  # @example
+  #   conn = ChConnect::Connection.new
+  #   response = conn.query("SELECT * FROM users WHERE id = 1")
+  class Connection
+    # @return [Config] the configuration used by this connection
+    attr_reader :config
+
+    # Creates a new connection.
+    #
+    # @param config [Config] configuration instance (defaults to global config)
+    def initialize(config = ChConnect.config)
+      @config = config
+      @transport = HttpTransport.new(config)
+    end
+
+    # Executes a SQL query and returns the response.
+    #
+    # @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
+    # @raise [QueryError] if the query fails
+    def query(sql, options = {})
+      @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/ch_connect/http_transport.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "httpx"
+require "json"
+
+module ChConnect
+  # HTTP transport layer for ClickHouse communication.
+  # @api private
+  class HttpTransport
+    # Creates a new HTTP transport.
+    #
+    # @param config [Config] configuration instance
+    def initialize(config)
+      @config = config
+      @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",
+        "X-ClickHouse-User" => config.username,
+        "X-ClickHouse-Key" => config.password,
+        "X-ClickHouse-Format" => "Native"
+      }
+    end
+
+    # Executes a SQL query via HTTP.
+    #
+    # @param sql [String] SQL query to execute
+    # @param options [Hash] query options
+    # @option options [Hash] :params query parameters
+    # @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(@base_url, params: query_params, body: sql, headers: @default_headers)
+
+      raise QueryError, response.error.message if response.error
+
+      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
+  end
+end

data/lib/ch_connect/native_format_parser.rb

@@ -0,0 +1,406 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "ipaddr"
+
+module ChConnect
+  # Parser for ClickHouse Native binary format.
+  # @api private
+  class NativeFormatParser
+    DATE_EPOCH = Date.new(1970, 1, 1)
+
+    # Creates a new parser.
+    #
+    # @param body [#read] response body to parse
+    def initialize(body)
+      @reader = BodyReader.new(body)
+      @columns = []
+      @types = []
+      @rows = []
+    end
+
+    # Parses the response body and returns a Response.
+    #
+    # @return [Response] parsed response with columns, types, and rows
+    # @raise [UnsupportedTypeError] if an unsupported data type is encountered
+    def parse
+      parse_block until @reader.eof?
+      Response.new(columns: @columns, types: @types, rows: @rows)
+    ensure
+      @reader.close
+    end
+
+    private
+
+    def parse_block
+      num_columns = read_varint
+      num_rows = read_varint
+
+      return if num_columns == 0 && num_rows == 0
+
+      columns_data = []
+
+      num_columns.times do
+        col_name = read_string
+        col_type = read_string
+
+        if @columns.length < num_columns
+          @columns << col_name.to_sym
+          @types << col_type.to_sym
+        end
+
+        columns_data << read_column(col_type, num_rows)
+      end
+
+      num_rows.times do |row_idx|
+        @rows << columns_data.map { |col| col[row_idx] }
+      end
+    end
+
+    def read_column(type, num_rows)
+      case type
+      # Integers
+      when "UInt8" then read_uint8_column(num_rows)
+      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 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 read_int128_column(num_rows)
+      when "Int256" then read_int256_column(num_rows)
+
+      # Floats
+      when "Float32" then read_float32_column(num_rows)
+      when "Float64" then read_float64_column(num_rows)
+
+      # Boolean
+      when "Bool" then read_bool_column(num_rows)
+
+      # Strings
+      when "String" then read_string_column(num_rows)
+      when /^FixedString\((\d+)\)$/ then read_fixed_string_column($1.to_i, num_rows)
+
+      # Dates and Times
+      when "Date" then read_date_column(num_rows)
+      when "Date32" then read_date32_column(num_rows)
+      when "DateTime", /^DateTime\(.+\)$/ then read_datetime_column(num_rows)
+      when /^DateTime64\((\d+)(?:,.*)?\)$/ then read_datetime64_column($1.to_i, num_rows)
+
+      # UUID
+      when "UUID" then read_uuid_column(num_rows)
+
+      # IP addresses
+      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)
+
+      # Enums (stored as signed integers)
+      when /^Enum8\(.+\)$/ then read_int8_column(num_rows)
+      when /^Enum16\(.+\)$/ then read_int16_column(num_rows)
+
+      # Nullable
+      when /^Nullable\((.+)\)$/ then read_nullable_column($1, num_rows)
+
+      # LowCardinality
+      when /^LowCardinality\((.+)\)$/ then read_low_cardinality_column($1, num_rows)
+
+      # Arrays
+      when /^Array\((.+)\)$/ then read_array_column($1, num_rows)
+
+      # Tuples
+      when /^Tuple\((.*)\)$/ then read_tuple_column(parse_tuple_types($1), num_rows)
+
+      # Maps
+      when /^Map\((.+)\)$/
+        types = parse_tuple_types($1)
+        read_map_column(types[0], types[1], num_rows)
+
+      else
+        raise UnsupportedTypeError, "Unsupported column type: #{type}"
+      end
+    end
+
+    # --- Bulk Column Readers ---
+
+    def read_uint8_column(num_rows)
+      @reader.read(num_rows).bytes
+    end
+
+    def read_uint16_column(num_rows)
+      @reader.read(num_rows * 2).unpack("v*")
+    end
+
+    def read_uint32_column(num_rows)
+      @reader.read(num_rows * 4).unpack("V*")
+    end
+
+    def read_uint64_column(num_rows)
+      @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
+
+    def read_int16_column(num_rows)
+      @reader.read(num_rows * 2).unpack("s<*")
+    end
+
+    def read_int32_column(num_rows)
+      @reader.read(num_rows * 4).unpack("l<*")
+    end
+
+    def read_int64_column(num_rows)
+      @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
+
+    def read_float64_column(num_rows)
+      @reader.read(num_rows * 8).unpack("E*")
+    end
+
+    def read_bool_column(num_rows)
+      @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
+
+    def read_date_column(num_rows)
+      @reader.read(num_rows * 2).unpack("v*").map { |days| DATE_EPOCH + days }
+    end
+
+    def read_date32_column(num_rows)
+      @reader.read(num_rows * 4).unpack("l<*").map { |days| DATE_EPOCH + days }
+    end
+
+    def read_datetime_column(num_rows)
+      @reader.read(num_rows * 4).unpack("V*").map { |ts| Time.at(ts).utc }
+    end
+
+    def read_datetime64_column(precision, num_rows)
+      scale = 10**(9 - precision)
+      @reader.read(num_rows * 8).unpack("q<*").map do |ticks|
+        nsec = ticks * scale
+        Time.at(nsec / 1_000_000_000, nsec % 1_000_000_000, :nanosecond).utc
+      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
+        @reader.read(num_rows * 4).unpack("l<*").map { |v| BigDecimal(v) / divisor }
+      elsif precision <= 18
+        @reader.read(num_rows * 8).unpack("q<*").map { |v| BigDecimal(v) / divisor }
+      elsif precision <= 38
+        Array.new(num_rows) { BigDecimal(read_signed_le_bytes(16)) / divisor }
+      else
+        Array.new(num_rows) { BigDecimal(read_signed_le_bytes(32)) / divisor }
+      end
+    end
+
+    # --- Single Value Readers ---
+
+    def read_varint
+      result = 0
+      shift = 0
+      loop do
+        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
+      end
+      result
+    end
+
+    def read_string
+      @reader.read(read_varint).force_encoding(Encoding::UTF_8)
+    end
+
+    def read_uint64 = @reader.read(8).unpack1("Q<")
+
+    def read_uuid
+      first_half = @reader.read(8).bytes.reverse
+      second_half = @reader.read(8).bytes.reverse
+      hex = (first_half + second_half).pack("C*").unpack1("H*")
+      "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+    end
+
+    def read_ipv4
+      bytes = @reader.read(4).unpack("C4").reverse
+      IPAddr.new(bytes.join("."))
+    end
+
+    def read_ipv6
+      bytes = @reader.read(16)
+      IPAddr.new(bytes.unpack1("H*").scan(/.{4}/).join(":"), Socket::AF_INET6)
+    end
+
+    # --- Container Type Readers ---
+
+    # Nullable: nulls mask (uint8 per row, 1=null), then all values
+    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 }
+    end
+
+    # Array: cumulative offsets (uint64 per row), then all elements
+    def read_array_column(inner_type, num_rows)
+      offsets = read_uint64_column(num_rows)
+      total_elements = offsets.last || 0
+
+      return Array.new(num_rows) { [] } if total_elements == 0
+
+      elements = read_column(inner_type, total_elements)
+
+      arrays = []
+      prev_offset = 0
+      offsets.each do |offset|
+        arrays << elements[prev_offset...offset]
+        prev_offset = offset
+      end
+      arrays
+    end
+
+    # Map: cumulative offsets (uint64 per row), then all keys, then all values
+    def read_map_column(key_type, value_type, num_rows)
+      offsets = read_uint64_column(num_rows)
+      total_pairs = offsets.last || 0
+
+      return Array.new(num_rows) { {} } if total_pairs == 0
+
+      keys = read_column(key_type, total_pairs)
+      values = read_column(value_type, total_pairs)
+
+      maps = []
+      prev_offset = 0
+      offsets.each do |offset|
+        maps << keys[prev_offset...offset].zip(values[prev_offset...offset]).to_h
+        prev_offset = offset
+      end
+      maps
+    end
+
+    # Tuple: all values of element 0, then element 1, etc. (column-major)
+    # Empty tuples send 1 byte per row.
+    def read_tuple_column(element_types, num_rows)
+      if element_types.empty?
+        @reader.read(num_rows)
+        return Array.new(num_rows) { [] }
+      end
+
+      element_columns = element_types.map { |type| read_column(type, num_rows) }
+
+      Array.new(num_rows) { |i| element_columns.map { |col| col[i] } }
+    end
+
+    # LowCardinality: version, meta, dictionary, keys
+    def read_low_cardinality_column(inner_type, num_rows)
+      _version = read_uint64
+      meta = read_uint64
+      key_type = meta & 0xFF
+
+      dict_size = read_uint64
+      dictionary = read_column(inner_type, dict_size)
+
+      _num_keys = read_uint64
+      keys = case key_type
+      when 0 then read_uint8_column(num_rows)
+      when 1 then read_uint16_column(num_rows)
+      when 2 then read_uint32_column(num_rows)
+      else read_uint64_column(num_rows)
+      end
+
+      keys.map { |k| dictionary[k] }
+    end
+
+    # --- Helpers ---
+
+    def read_le_bytes(num_bytes)
+      bytes = @reader.read(num_bytes).bytes
+      result = 0
+      bytes.each_with_index { |b, i| result |= b << (8 * i) }
+      result
+    end
+
+    def read_signed_le_bytes(num_bytes)
+      value = read_le_bytes(num_bytes)
+      max_positive = 1 << (num_bytes * 8 - 1)
+      (value >= max_positive) ? value - (1 << (num_bytes * 8)) : value
+    end
+
+    def parse_tuple_types(types_str)
+      types = []
+      depth = 0
+      current = +""
+
+      types_str.each_char do |c|
+        case c
+        when "("
+          depth += 1
+          current << c
+        when ")"
+          depth -= 1
+          current << c
+        when ","
+          if depth == 0
+            types << current.strip
+            current = +""
+          else
+            current << c
+          end
+        else
+          current << c
+        end
+      end
+
+      types << current.strip unless current.empty?
+      types
+    end
+  end
+end

data/lib/ch_connect/null_instrumenter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ChConnect
+  # 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/ch_connect/response.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ChConnect
+  # Immutable response object containing query results.
+  #
+  # @example
+  #   response = conn.query("SELECT id, name FROM users")
+  #   response.columns   # => [:id, :name]
+  #   response.rows      # => [[1, "Alice"], [2, "Bob"]]
+  #   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 summary [Hash, nil] ClickHouse query summary with symbol keys
+    def initialize(columns: [], types: [], rows: [], summary: nil)
+      super
+    end
+
+    # 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/ch_connect/transport_result.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ChConnect
+  # Immutable result from transport layer.
+  # @api private
+  #
+  # @!attribute [r] body
+  #   @return [HTTP::Response::Body] response body
+  # @!attribute [r] summary
+  #   @return [Hash] ClickHouse query summary
+  TransportResult = Data.define(:body, :summary)
+end

data/lib/ch_connect/version.rb

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

data/lib/ch_connect.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "ch_connect/version"
+require_relative "ch_connect/null_instrumenter"
+require_relative "ch_connect/config"
+require_relative "ch_connect/transport_result"
+require_relative "ch_connect/http_transport"
+require_relative "ch_connect/connection"
+require_relative "ch_connect/response"
+require_relative "ch_connect/body_reader"
+require_relative "ch_connect/native_format_parser"
+
+# Ruby client for ClickHouse database with Native format support.
+#
+# @example Basic usage
+#   ChConnect.configure do |config|
+#     config.host = "localhost"
+#     config.port = 8123
+#   end
+#
+#   conn = ChConnect::Connection.new
+#   response = conn.query("SELECT 1")
+#
+# @example Using connection pool
+#   pool = ChConnect::Pool.new
+#   response = pool.query("SELECT * FROM users")
+module ChConnect
+  # Base error class for all ChConnect 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
+
+  # Returns the global configuration instance.
+  #
+  # @return [Config] the configuration instance
+  def self.config
+    @config ||= Config.new
+  end
+
+  # Yields the global configuration for modification.
+  #
+  # @yield [Config] the configuration instance
+  # @return [void]
+  def self.configure
+    yield(config) if block_given?
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: ch_connect
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Karol Bąk
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: httpx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Fast Ruby client for ClickHouse database using the Native binary format
+  for efficient data transfer
+email:
+- kukicola@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- CHANGELOG.md
+- README.md
+- lib/ch_connect.rb
+- lib/ch_connect/body_reader.rb
+- lib/ch_connect/config.rb
+- lib/ch_connect/connection.rb
+- lib/ch_connect/http_transport.rb
+- lib/ch_connect/native_format_parser.rb
+- lib/ch_connect/null_instrumenter.rb
+- lib/ch_connect/response.rb
+- lib/ch_connect/transport_result.rb
+- lib/ch_connect/version.rb
+homepage: https://github.com/kukicola/ch_connect
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://github.com/kukicola/ch_connect/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Ruby client for ClickHouse with Native format support
+test_files: []