Module: ClickhouseRuby::ActiveRecord

Defined in:
lib/clickhouse_ruby/active_record.rb,
lib/clickhouse_ruby/active_record/railtie.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

Note:

ClickHouse Limitations

  • No transaction support (savepoints, rollback are no-ops)

  • No foreign key constraints

  • DELETE/UPDATE are asynchronous mutations

  • No auto-increment primary keys

ActiveRecord integration for ClickHouse

This module provides full ActiveRecord adapter support for ClickHouse, allowing Rails applications to use ClickHouse as a database backend.

Examples:

Configuration in database.yml

development:
  adapter: clickhouse
  host: localhost
  port: 8123
  database: analytics_development
  username: default
  password: ''

production:
  adapter: clickhouse
  host: <%= ENV['CLICKHOUSE_HOST'] %>
  port: 8443
  database: analytics_production
  ssl: true
  ssl_verify: true
  username: <%= ENV['CLICKHOUSE_USER'] %>
  password: <%= ENV['CLICKHOUSE_PASSWORD'] %>

Model usage

class Event < ApplicationRecord
  self.table_name = 'events'

  # ClickHouse doesn't use auto-increment IDs
  # Generate UUIDs or use application-level ID generation
  before_create :generate_uuid

  private

  def generate_uuid
    self.id ||= SecureRandom.uuid
  end
end

Querying

# Standard ActiveRecord queries work
Event.where(user_id: 123).count
Event.where(created_at: 1.day.ago..).limit(100)
Event.select(:user_id).distinct.pluck(:user_id)

Bulk inserts (recommended for ClickHouse)

Event.insert_all([
  { id: SecureRandom.uuid, name: 'click', user_id: 1 },
  { id: SecureRandom.uuid, name: 'view', user_id: 2 }
])

Mutations (DELETE/UPDATE)

# IMPORTANT: These raise errors on failure (never silently fail)
Event.where(status: 'old').delete_all
Event.where(user_id: 123).update_all(status: 'archived')

Defined Under Namespace

Modules: SchemaStatements Classes: ArelVisitor, ConnectionAdapter, DatabaseTasks, Railtie, SchemaCreation, TableDefinition

Class Method Summary collapse

Class Method Details

.registered? ⇒ Boolean

Check if the adapter is properly registered

Returns:

  • (Boolean) —

    true if the adapter is available



83
84
85
86
87
88
89
 
# File 'lib/clickhouse_ruby/active_record.rb', line 83

def registered?
  defined?(::ActiveRecord::ConnectionAdapters) &&
    ::ActiveRecord::ConnectionAdapters.respond_to?(:resolve) &&
    ::ActiveRecord::ConnectionAdapters.resolve('clickhouse').present?
rescue StandardError
  false
end

.version ⇒ String

Get the adapter version

Returns:

  • (String) —

    the adapter version



94
95
96
 
# File 'lib/clickhouse_ruby/active_record.rb', line 94

def version
  ClickhouseRuby::VERSION
end