ClickhouseRuby

A lightweight Ruby client for ClickHouse with optional ActiveRecord integration.

Why ClickhouseRuby?

SSL verification enabled by default - Secure by default
Never silently fails - All errors properly raised (fixes clickhouse-activerecord #230)
Zero runtime dependencies - Uses only Ruby stdlib
AST-based type parser - Handles complex nested types correctly
Thread-safe connection pooling - Built-in pool with health checks
ClickHouse-specific extensions - PREWHERE, FINAL, SAMPLE, SETTINGS

Installation

# Gemfile
gem 'clickhouse-ruby'

bundle install

Quick Start

require 'clickhouse_ruby'

# Configure
ClickhouseRuby.configure do |config|
  config.host = 'localhost'
  config.port = 8123
  config.database = 'default'
end

# Query
client = ClickhouseRuby.client
result = client.execute('SELECT 1 + 1 AS result')
puts result.first['result'] # => 2

# Insert
client.insert('events', [
  { date: '2024-01-01', event_type: 'click', count: 100 },
  { date: '2024-01-02', event_type: 'view', count: 250 }
])

Features

Core (v0.1.0)

Simple HTTP client with connection pooling
Full type system (Nullable, Array, Map, Tuple)
Comprehensive error handling
SSL/TLS support
Optional ActiveRecord integration

Enhanced (v0.2.0)

Enum & Decimal types
PREWHERE, FINAL, SAMPLE query extensions
HTTP compression, result streaming
Automatic retries with backoff

Production (v0.3.0)

Observability & instrumentation
Migration generators
Health checks
Performance benchmarking

Configuration

ClickhouseRuby.configure do |config|
  config.host = 'localhost'
  config.port = 8123
  config.database = 'default'
  config.username = 'default'
  config.password = ''
  config.ssl = false
  config.pool_size = 5
  config.read_timeout = 60
end

Or via environment variables:

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_DATABASE=default

See Configuration Reference for all options.

Usage

Queries

result = client.execute('SELECT * FROM events LIMIT 10')
result.each { |row| puts row['event_type'] }
result.columns  # => ['id', 'event_type', 'count']
result.types    # => ['UInt64', 'String', 'UInt32']

DDL

client.command(<<~SQL)
  CREATE TABLE events (
    date Date,
    event_type String,
    count UInt32
  ) ENGINE = MergeTree()
  ORDER BY date
SQL

Large Results

# Stream row by row (constant memory)
client.stream_execute('SELECT * FROM huge_table') do |row|
  process_row(row)
end

# Batch processing
client.each_batch('SELECT * FROM huge_table', batch_size: 1000) do |batch|
  process_batch(batch)
end

See Querying Guide for more.

ActiveRecord Integration

require 'clickhouse_ruby/active_record'

ClickhouseRuby::ActiveRecord.establish_connection(
  host: 'localhost',
  database: 'analytics'
)

class Event < ClickhouseRuby::ActiveRecord::Base
  self.table_name = 'events'
end

# Query
Event.where(date: Date.today).count

# ClickHouse-specific extensions
Event.prewhere(date: Date.today).where(status: 'active')  # PREWHERE
User.final.where(id: 123)                                  # FINAL
Event.sample(0.1).count                                    # SAMPLE
Event.settings(max_threads: 4).all                         # SETTINGS

See ActiveRecord Guide for complete documentation.

Error Handling

begin
  client.execute('SELECT * FROM nonexistent_table')
rescue ClickhouseRuby::UnknownTable => e
  puts "Table not found: #{e.message}"
  puts "Error code: #{e.code}"
rescue ClickhouseRuby::ConnectionError => e
  puts "Connection failed: #{e.message}"
end

See Error Reference for all error classes.

Type Support

ClickHouse Type	Ruby Type
Int8-Int64, UInt8-UInt64	Integer
Float32, Float64	Float
String	String
Date, DateTime	Date, Time
Nullable(T)	T or nil
Array(T)	Array
Map(K, V)	Hash
Enum8, Enum16	String
Decimal(P,S)	BigDecimal

See Types Reference for complete mapping.

Documentation

Section	Description
Getting Started	Installation and tutorials
Guides	How-to guides for specific tasks
Reference	Configuration and API reference
Concepts	Architecture and design
Examples	Real-world patterns

Requirements

Ruby >= 2.6.0
ClickHouse >= 20.x (tested with 24.x)

Development

# Start ClickHouse
docker-compose up -d

# Run tests
bundle exec rake spec

# Run linter
bundle exec rake rubocop

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE.