Module: ClickhouseRuby

Defined in:
lib/clickhouse_ruby.rb,
lib/clickhouse_ruby/types.rb,
lib/clickhouse_ruby/client.rb,
lib/clickhouse_ruby/errors.rb,
lib/clickhouse_ruby/result.rb,
lib/clickhouse_ruby/version.rb,
lib/clickhouse_ruby/types/map.rb,
lib/clickhouse_ruby/connection.rb,
lib/clickhouse_ruby/types/base.rb,
lib/clickhouse_ruby/types/uuid.rb,
lib/clickhouse_ruby/types/array.rb,
lib/clickhouse_ruby/types/float.rb,
lib/clickhouse_ruby/types/tuple.rb,
lib/clickhouse_ruby/types/parser.rb,
lib/clickhouse_ruby/types/string.rb,
lib/clickhouse_ruby/active_record.rb,
lib/clickhouse_ruby/configuration.rb,
lib/clickhouse_ruby/types/boolean.rb,
lib/clickhouse_ruby/types/integer.rb,
lib/clickhouse_ruby/types/nullable.rb,
lib/clickhouse_ruby/types/registry.rb,
lib/clickhouse_ruby/connection_pool.rb,
lib/clickhouse_ruby/types/date_time.rb,
lib/clickhouse_ruby/active_record/railtie.rb,
lib/clickhouse_ruby/types/low_cardinality.rb,
lib/clickhouse_ruby/active_record/arel_visitor.rb,
lib/clickhouse_ruby/active_record/schema_statements.rb,
lib/clickhouse_ruby/active_record/connection_adapter.rb

Overview

ClickhouseRuby - Ruby/ActiveRecord integration for ClickHouse

A robust, reliable ClickHouse client for Ruby that prioritizes:

  • No silent failures (proper error handling)

  • Correct type handling (AST-based parser for complex types)

  • Performance (bulk operations, connection pooling)

  • Security (SSL verification enabled by default)

Examples:

Basic usage

ClickhouseRuby.configure do |config|
  config.host = 'localhost'
  config.port = 8123
  config.database = 'analytics'
end

client = ClickhouseRuby::Client.new
result = client.execute('SELECT * FROM events LIMIT 10')
result.each { |row| puts row['name'] }

Bulk insert

client.insert('events', [
  { id: 1, name: 'click', timestamp: Time.now },
  { id: 2, name: 'view', timestamp: Time.now }
])

Defined Under Namespace

Modules: ActiveRecord, Types Classes: Client, Configuration, ConfigurationError, Connection, ConnectionError, ConnectionNotEstablished, ConnectionPool, ConnectionTimeout, Error, PoolError, PoolExhausted, PoolTimeout, QueryError, QueryTimeout, Result, SSLError, StatementInvalid, SyntaxError, TypeCastError, UnknownColumn, UnknownDatabase, UnknownTable

Constant Summary collapse

ERROR_CODE_MAPPING =

Maps ClickHouse error codes to exception classes See: github.com/ClickHouse/ClickHouse/blob/master/src/Common/ErrorCodes.cpp

{
  60 => UnknownTable,        # UNKNOWN_TABLE
  16 => UnknownColumn,       # NO_SUCH_COLUMN_IN_TABLE
  81 => UnknownDatabase,     # UNKNOWN_DATABASE
  62 => SyntaxError,         # SYNTAX_ERROR
  159 => QueryTimeout,       # TIMEOUT_EXCEEDED
}.freeze
VERSION = 
'0.1.0'

Class Method Summary collapse

Class Method Details

.client ⇒ Client

Creates a new client with the global configuration

Returns:

  • (Client) —

    a new client instance



73
74
75
 
# File 'lib/clickhouse_ruby.rb', line 73

def client
  Client.new(configuration)
end

.configuration ⇒ Configuration

Returns the global configuration instance

Returns:



42
43
44
 
# File 'lib/clickhouse_ruby.rb', line 42

def configuration
  @configuration ||= Configuration.new
end

.configure {|Configuration| ... } ⇒ Configuration

Allows configuration via a block

Examples:

ClickhouseRuby.configure do |config|
  config.host = 'clickhouse.example.com'
  config.port = 8443
  config.ssl = true
end

Yields:

Returns:



57
58
59
60
 
# File 'lib/clickhouse_ruby.rb', line 57

def configure
  yield(configuration)
  configuration
end

.error_class_for_code(code) ⇒ Class

Maps a ClickHouse error code to the appropriate exception class

Parameters:

  • code (Integer) —

    the ClickHouse error code

Returns:

  • (Class) —

    the exception class to use



140
141
142
 
# File 'lib/clickhouse_ruby/errors.rb', line 140

def error_class_for_code(code)
  ERROR_CODE_MAPPING.fetch(code, QueryError)
end

.execute(sql, **options) ⇒ Result

Convenience method to execute a query using global configuration

Parameters:

  • sql (String) —

    the SQL query to execute

  • options (Hash) —

    query options

Returns:

  • (Result) —

    the query result



82
83
84
 
# File 'lib/clickhouse_ruby.rb', line 82

def execute(sql, **options)
  client.execute(sql, **options)
end

.insert(table, rows, **options) ⇒ Result

Convenience method to insert data using global configuration

Parameters:

  • table (String) —

    the table name

  • rows (Array<Hash>) —

    the rows to insert

  • options (Hash) —

    insert options

Returns:

  • (Result) —

    the insert result



92
93
94
 
# File 'lib/clickhouse_ruby.rb', line 92

def insert(table, rows, **options)
  client.insert(table, rows, **options)
end

.reset_configuration! ⇒ Configuration

Resets the configuration to defaults Primarily useful for testing

Returns:



66
67
68
 
# File 'lib/clickhouse_ruby.rb', line 66

def reset_configuration!
  @configuration = Configuration.new
end