clickhouse-rb 0.1.0

checksums.yaml

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

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] - 2025-12-28
+
+- Initial release

data/README.md

@@ -0,0 +1,183 @@
+# clickhouse-rb
+
+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
+- Connection pooling for thread-safe concurrent access
+- Supports all common ClickHouse data types
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "clickhouse-rb"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Configuration
+
+```ruby
+require "clickhouse"
+
+Clickhouse.configure do |config|
+  config.host = "localhost"
+  config.port = 8123
+  config.database = "default"
+  config.username = "default"
+  config.password = ""
+end
+```
+
+Or configure via URL:
+
+```ruby
+Clickhouse.configure do |config|
+  config.url = "http://user:pass@localhost:8123/mydb"
+end
+```
+
+### Single Connection
+
+```ruby
+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
+end
+```
+
+### Connection Pool
+
+For multi-threaded applications:
+
+```ruby
+pool = Clickhouse::Pool.new
+
+# Thread-safe queries
+threads = 10.times.map do
+  Thread.new { pool.query("SELECT 1") }
+end
+threads.each(&:join)
+```
+
+Pool size and timeout are configured globally:
+
+```ruby
+Clickhouse.configure do |config|
+  config.pool_size = 10
+  config.pool_timeout = 5
+end
+```
+
+### Working with Results
+
+```ruby
+response = conn.query("SELECT id, name, created_at FROM users")
+
+# 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", ...}, ...]
+
+# 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", ...}
+```
+
+### 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 |
+| `pool_size` | `100` | Connection pool size |
+| `pool_timeout` | `5` | Pool checkout timeout in seconds |
+
+## Error Handling
+
+```ruby
+response = conn.query("INVALID SQL")
+
+if response.failure?
+  puts "Query failed: #{response.error}"
+end
+
+# Unsupported types raise an exception
+begin
+  conn.query("SELECT '{}'::JSON")
+rescue Clickhouse::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/clickhouse/buffered_reader.rb

@@ -0,0 +1,69 @@
+# 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/config.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Clickhouse
+  # Configuration for ClickHouse connection.
+  #
+  # @example
+  #   config = Clickhouse::Config.new(host: "db.example.com", port: 9000)
+  #
+  # @example Using URL
+  #   config = Clickhouse::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,
+      pool_size: 100,
+      pool_timeout: 5
+    }.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] Connection pool size
+    # @return [Integer] Pool checkout timeout in seconds
+    attr_accessor :scheme, :host, :port, :database, :username, :password, :connection_timeout, :pool_size, :pool_timeout
+
+    # 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 timeout in seconds (default: 5)
+    # @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/clickhouse/connection.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Clickhouse
+  # A single connection to ClickHouse server.
+  #
+  # @example
+  #   conn = Clickhouse::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 = Clickhouse.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
+    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)
+    end
+  end
+end

data/lib/clickhouse/http_transport.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "http"
+require "json"
+
+module Clickhouse
+  # 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
+      @http_client = HTTP.persistent("#{config.scheme}://#{config.host}:#{config.port}")
+        .use(:auto_deflate)
+        .use(:auto_inflate)
+        .timeout(connect: config.connection_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 or error
+    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
+    end
+  end
+end

data/lib/clickhouse/native_format_parser.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "ipaddr"
+
+module Clickhouse
+  # Parser for ClickHouse Native binary format.
+  # @api private
+  class NativeFormatParser
+    DATE_EPOCH = Date.new(1970, 1, 1)
+
+    # Creates a new parser.
+    #
+    # @param body [#readpartial] response body to parse
+    def initialize(body)
+      @body = 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
+      @reader = BufferedReader.new(@body)
+      parse_block until @reader.eof?
+      Response.new(columns: @columns, types: @types, rows: @rows)
+    ensure
+      @reader.flush
+    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
+          @types << col_type
+        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 Array.new(num_rows) { read_uint128 }
+      when "UInt256" then Array.new(num_rows) { read_uint256 }
+      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 }
+
+      # 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 Array.new(num_rows) { read_string }
+      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 Array.new(num_rows) { read_uuid }
+
+      # IP addresses
+      when "IPv4" then Array.new(num_rows) { read_ipv4 }
+      when "IPv6" then Array.new(num_rows) { read_ipv6 }
+
+      # 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_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_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_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_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 = @reader.read_byte
+        return result if byte.nil?
+        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_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
+      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/clickhouse/pool.rb

@@ -0,0 +1,39 @@
+# 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

data/lib/clickhouse/response.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Clickhouse
+  # Immutable response object containing query results.
+  #
+  # @example Successful response
+  #   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
+    # @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)
+      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 }
+  end
+end

data/lib/clickhouse/transport_result.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+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
+  # @!attribute [r] summary
+  #   @return [Hash] ClickHouse query summary
+  TransportResult = Data.define(:success, :body, :error, :summary)
+end

data/lib/clickhouse/version.rb

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

data/lib/clickhouse.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "clickhouse/version"
+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/native_format_parser"
+
+# Ruby client for ClickHouse database with Native format support.
+#
+# @example Basic usage
+#   Clickhouse.configure do |config|
+#     config.host = "localhost"
+#     config.port = 8123
+#   end
+#
+#   conn = Clickhouse::Connection.new
+#   response = conn.query("SELECT 1")
+#
+# @example Using connection pool
+#   pool = Clickhouse::Pool.new
+#   response = pool.query("SELECT * FROM users")
+module Clickhouse
+  # Base error class for all Clickhouse errors
+  class Error < StandardError; 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,98 @@
+--- !ruby/object:Gem::Specification
+name: clickhouse-rb
+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: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.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'
+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/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/pool.rb
+- lib/clickhouse/response.rb
+- lib/clickhouse/transport_result.rb
+- lib/clickhouse/version.rb
+homepage: https://github.com/kukicola/clickhouse-rb
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://github.com/kukicola/clickhouse-rb/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: []