activerecord-clickhouse-adapter 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45e5becdc6a5a3195e53c6dd9f8dd13b154dcb8bbe4fb9862f1656fc380a9b96
-  data.tar.gz: c71340ef169715de6fad45ce9e9795b342ac4a4e953e4f6183d2077c43f996e8
+  metadata.gz: 961d1de0d406b53d1244395ce2159a5629a335eda4f74e71b5bcdbf489c3ed01
+  data.tar.gz: e7022e7db80a7520c083c88fd058d98ddb79d0c4d8450628ba954304a104dbaf
 SHA512:
-  metadata.gz: b1db549fd86bc894a8b43df4870d9465a9eec4a9858fd0c9b4866bd4c67aadc587228d0089e135781fb9e9d6c389f6c6c61f88542fdf8d46a3bf958e90b9856f
-  data.tar.gz: 614a15173f4c2ac7aa502ba21aa610f5bf189a754c068a7764c1da503aa52655eb3619c02a1c3455f509ae690ba8d2c3e24c492a4c843fb5256b59bb23ec35a8
+  metadata.gz: 3b8e3c624094591a222e1fc8bdc0f74abf8a8681bc9732c08b1c587b68a57f89273dbd1fb7f551e40d6ac8aa6f890cc98e531a329c4be45fa2b7a0db1efd458f
+  data.tar.gz: 2598a56859fd5b5c1882da961b8d333fe32e8131abea8173c176a0765cb7df49e733b3a037781cae349c0bc24fa191c50b5a2e5eaf55bb7f15dba8b0ee14cf57

data/CHANGELOG.md

@@ -1,4 +1,102 @@
-# 0.1.0 (unreleased)
+# 0.2.1 (2026-07-24)
+
+Fixed:
+
+- Fixed comment hoisting corrupting `INSERT ... VALUES` when a string value contains an
+  unclosed `/*` (e.g. a request path of `/*`). The trailing-comment scan is now
+  string-literal aware, so a `/*` inside a value is never taken for the start of a trailing
+  sqlcommenter tag. Previously such a value mangled the statement and the server rejected the
+  whole batch with a `SYNTAX_ERROR`, dropping every row in it
+
+# 0.2.0 (2026-07-23)
+
+Breaking-ish (schema diff noise, not data changes):
+
+- Updated `t.datetime` to default to precision 6 (microseconds, Rails' convention) —
+  previously an unqualified datetime rendered `DateTime64(3)`. Existing consumer
+  schemas diff as `DateTime64(3)` → `DateTime64(6)`; declare `precision: 3` to keep
+  the old shape
+- Fixed decimal DDL bounds: `precision:` without `scale:` now means scale 0 (the old
+  `Decimal(N, 10)` shape was invalid for N < 10), and `scale:` without `precision:`
+  raises the same `ArgumentError` as Rails' bundled adapters
+
+Added:
+
+- Added a runnable OLAP-on-Rails example (`examples/olap_on_rails.rb`): fact table,
+  streaming ingestion, dictionary lookups, the aggregate-state pipeline, mutable
+  dimensions via ReplacingMergeTree + `final`, partitions, and instrumentation —
+  guarded by a live spec so it cannot drift
+- Added `:binary`/`:blob` column types, mapped to `String` (ClickHouse strings are
+  arbitrary byte sequences)
+- Added `payload[:affected_rows]` to `sql.active_record` notifications, populated
+  from the server summary's written rows on every query and on `insert_stream`
+- Added case-insensitive `matches`/`does_not_match` rendering via ClickHouse's
+  native `ILIKE` (LIKE is case-sensitive here, unlike MySQL); a custom ESCAPE
+  character raises `NotImplementedError` because ClickHouse has no ESCAPE clause
+- Added a no-op `FOR UPDATE` visitor (reads are isolated snapshots of parts; no row
+  locks exist), so shared `Model.lock`/`with_lock` code runs instead of dying —
+  optimistic locking via `lock_version` works end-to-end
+- Added multi-replica support: `hosts:` lists interchangeable endpoints ("host" or
+  "host:port"); connections round-robin their starting endpoint, fail over on
+  connect-phase errors only (a request that never reached a server cannot double a
+  write — mid-flight failures still raise), and skip endpoints that refused within
+  `failover_cooldown:` seconds (default 30)
+- Added `read_only: true` connection option: stamps `readonly=2` on every request so
+  the server itself refuses writes; the refusal (code 164) raises
+  `ActiveRecord::ReadOnlyError` — the same class Rails' `while_preventing_writes`
+  uses — including for server-configured readonly users
+- Added `ClickHouse::AccessDenied` (< `ActiveRecord::StatementInvalid`) for the
+  server's grant refusals (code 497)
+- Added `Errno::ENETUNREACH` to the failover connect-error list (connect-phase by
+  nature, added on review — not reproducible in the test container)
+- Added primary-key reporting for tables whose sorting key is a single integer or
+  UUID column: Rails now auto-detects the model's primary key on id-keyed tables
+  (`find`/`update`/`destroy` and client-generated ids work without
+  `self.primary_key`); composite, expression, and non-id sorting keys still report
+  none — ClickHouse PRIMARY KEY is an index prefix, not a uniqueness guarantee —
+  and schema dumps keep the explicit `id: false` + `order:` shape
+- Added Rails-style `create_table id: :bigint/:uuid` (and bare `id: :primary_key`,
+  a plain Int64): the pk column doubles as the sorting key so no `order:` is
+  needed, and ids are generated client-side — no autoincrement exists
+
+Fixed:
+
+- Fixed `lookup_cast_type` to resolve ClickHouse type names through the adapter's own
+  parser: the abstract TYPE_MAP degraded `Nullable(...)`, `UUID`, `Bool`, and `Map`
+  to bare `Type::Value` and even matched `Tuple(String, Int64)` as Integer; results
+  are frozen so lookups stay Ractor-shareable
+- Fixed `create_table` with a composite `primary_key:` array to render a quoted
+  `PRIMARY KEY (a, b)` tuple; a PRIMARY KEY clause alone now satisfies the
+  sorting-key requirement (the server infers ORDER BY from it)
+- Fixed `disconnect!` to close the raw HTTP connection while still holding the
+  adapter lock (the postgresql adapter's pattern) — closing after release let a
+  concurrently queued query start its read on a dying socket
+- Fixed SQL containing invalid UTF-8 bytes to reach the server instead of raising
+  `ArgumentError` client-side (ClickHouse strings are byte sequences; the server
+  accepts raw bytes in literals and backtick identifiers)
+- Fixed datetime DDL bounds: precision past 9 (nanoseconds, ClickHouse's maximum) now
+  raises `ArgumentError` at migration time instead of a server error, and an explicit
+  `precision: nil` maps to the second-precision base `DateTime` (a bare `t.datetime`
+  still gets Rails' default microseconds)
+- Fixed schema dumps of datetime precision to follow Rails conventions: the default 6
+  is omitted and a precision-less `DateTime` dumps as `precision: nil`
+- Fixed attribute-less creates: Rails' `INSERT INTO t DEFAULT VALUES` is not ClickHouse
+  syntax; the adapter now emits `FORMAT JSONEachRow {}` (one row, all table defaults)
+- Updated datetime and date columns to expose `ActiveRecord::Type::DateTime`/`::Date`
+  (not the ActiveModel types): they respect `ActiveRecord.default_timezone`, and
+  Rails' time-zone-aware attribute machinery type-checks for them
+
+Internal:
+
+- Grew the Rails compatibility harness from ~2,200 to ~4,500 vendored upstream Active
+  Record tests (scoping, autosave, migrations, nested attributes, serialized
+  attributes, enums, dirty tracking, timestamps, batches, query cache, delegated
+  types, instrumentation, and two dozen more suites), each skip documented with the
+  dialect truth behind it
+- Isolated the harness subprocess in a pid-suffixed ClickHouse database so concurrent
+  runs cannot collide
+
+# 0.1.0 (2026-07-15)
 
 First release. Highlights:
 

data/README.md

@@ -8,6 +8,7 @@ A fully featured Active Record adapter for [ClickHouse](https://clickhouse.com)
 - OLAP query surface: `FINAL`, `PREWHERE`, `SAMPLE`, `LIMIT BY`, time bucketing, approximate aggregates
 - Real instrumentation: rows read, bytes read, and server elapsed time on every query
 - Fast wire: RowBinary reads and chunked streaming inserts
+- Multi-replica failover and server-enforced read-only connections
 
 Tested against a live ClickHouse server only — no mocked responses, ever.
 
@@ -25,6 +26,10 @@ Requires Active Record 8.1+, Ruby 3.2+, and ClickHouse 25.8+ (each LTS from 25.8
 
 ## Getting Started
 
+For a runnable end-to-end tour — fact table, streaming ingestion, dictionary
+lookups, the aggregate-state pipeline, partitions — see
+[`examples/olap_on_rails.rb`](examples/olap_on_rails.rb).
+
 Add a ClickHouse database to `config/database.yml`:
 
 ```yaml
@@ -76,6 +81,16 @@ end
 
 Columns are non-nullable by default, matching ClickHouse. Use `null: true` for `Nullable(...)`.
 
+`t.datetime` defaults to precision 6 (microseconds, Rails' convention); pass `precision: nil` for the second-precision base `DateTime`. `t.binary`/`t.blob` map to `String` — ClickHouse strings are arbitrary byte sequences.
+
+Rails-style id tables also work — `id: :bigint` (plain Int64, no autoincrement) or `id: :uuid` creates the pk column as its own sorting key, ids arrive client-generated, and models auto-detect the primary key:
+
+```ruby
+create_table :accounts, id: :bigint do |t|
+  t.string :name, default: ""
+end
+```
+
 The full alter surface works on existing tables — `rename_column`, `change_column`, `change_column_null` (with the Rails backfill default), `change_column_default`, `change_column_comment`, `change_table_comment`, and `add_index`/`remove_index` for data-skipping indexes. `create_join_table` defaults its sorting key to the two reference columns.
 
 ClickHouse-specific column options:
@@ -242,6 +257,8 @@ ActiveSupport::Notifications.subscribe("sql.active_record") do |event|
 end
 ```
 
+The standard `payload[:affected_rows]` reports the server's written rows on inserts.
+
 `explain` supports ClickHouse variants:
 
 ```ruby
@@ -260,6 +277,11 @@ clickhouse:
   database: analytics_production
   username: rails
   password: secret
+  hosts:                   # interchangeable replicas ("host" or "host:port");
+    - ch-1.internal        # connections round-robin start positions and fail over
+    - ch-2.internal:8124   # to the next host on connect-phase errors
+  failover_cooldown: 30    # seconds new connections skip an endpoint that refused
+  read_only: true          # server-enforced reads only (readonly=2 on every request)
   ssl: true                # HTTPS to the server
   ssl_verify: false        # escape hatch for self-signed certificates (default: verify)
   connect_timeout: 5
@@ -275,9 +297,30 @@ clickhouse:
 ## Semantics Worth Knowing
 
 - **No transactions.** ClickHouse has none; `transaction` blocks run their contents without BEGIN/COMMIT and cannot roll back.
-- **Primary keys are client-generated.** Tables with a single-column integer or UUID sorting key get time-ordered ids (Snowflake-style / UUIDv7) assigned before INSERT.
+- **Primary keys are client-generated and auto-detected.** Tables with a single-column integer or UUID sorting key report it as the Active Record primary key — models auto-detect it, and ids are assigned client-side before INSERT (Snowflake-style / UUIDv7). Composite, expression, and other sorting keys report none (ClickHouse PRIMARY KEY is an index prefix, not a uniqueness guarantee); declare `self.primary_key` explicitly when such a key is unique by design, e.g. a ReplacingMergeTree slug.
 - **Mutation counts are best-effort.** `update_all`/`delete_all` return a pre-mutation `SELECT count()` — ClickHouse reports no affected-row counts.
 - **Eventual merges.** `ReplacingMergeTree` deduplicates at merge time; read with `.final` when you need collapsed rows.
+- **Failover never replays a request.** With `hosts:`, only connect-phase failures (refused, unreachable, open timeout) move to the next replica — those cannot have executed anything. A mid-flight failure (read timeout, reset) raises, because the statement may already have run.
+- **Read-only is server-enforced.** `read_only: true` stamps `readonly=2` on every request; the server's refusal (code 164) raises `ActiveRecord::ReadOnlyError` — the same class Rails' `while_preventing_writes` uses — including for server-configured readonly users. Grant refusals (code 497) raise `ClickHouse::AccessDenied`.
+- **`matches` renders `ILIKE`.** ClickHouse `LIKE` is case-sensitive (unlike MySQL), so Arel's case-insensitive `matches`/`does_not_match` use native `ILIKE`.
+- **No row locks.** Reads are isolated snapshots of parts, so `FOR UPDATE` renders as nothing and shared `lock`/`with_lock` code runs instead of dying. Optimistic locking via `lock_version` works end-to-end.
+
+## Migrating from clickhouse-activerecord
+
+This gem registers the same `"clickhouse"` adapter name as [clickhouse-activerecord](https://github.com/PNixx/clickhouse-activerecord) and accepts its `database.yml` shape — swap the gem and the config carries over. The two gems cannot be loaded at once.
+
+Schema-version bookkeeping does not carry over. The incumbent records applied versions in a `(version, active, ver)` ReplacingMergeTree with `active = 0` tombstones; this adapter uses Rails' plain `schema_migrations` table and does not read that shape, so a sink migrated by the incumbent reports zero applied versions.
+
+Never re-run migrations over a live sink to fix that — replaying DDL over final-state tables can corrupt data (enum narrowing, for one). Adopt the version state once instead:
+
+```ruby
+versions = connection.select_values("SELECT version FROM schema_migrations FINAL WHERE active = 1")
+connection.execute("RENAME TABLE schema_migrations TO schema_migrations_legacy")
+pool.schema_migration.create_table
+versions.each { |v| pool.schema_migration.create_version(v) }
+```
+
+Pending migrations run normally afterwards. To roll back the adoption, drop the new `schema_migrations` table and rename the legacy one back.
 
 ## Development
 
@@ -297,7 +340,7 @@ RAILS_SOURCE=edge bundle install
 RAILS_SOURCE=edge bundle exec rspec
 ```
 
-The suite includes a Rails compatibility harness that runs vendored upstream Active Record test suites (~1,600 tests) against the adapter. See `spec/rails_compat/`.
+The suite includes a Rails compatibility harness that runs vendored upstream Active Record test suites (~5,600 tests — 5,558 runs, 447 skips, each skip documenting the dialect truth behind it) against the adapter. See `spec/rails_compat/`.
 
 ## History
 

data/lib/active_record/connection_adapters/clickhouse/database_statements.rb

@@ -139,6 +139,13 @@ module ActiveRecord
           HIGH_PRECISION_CURRENT_TIMESTAMP
         end
 
+        # Rails renders an attribute-less create as "INSERT INTO t DEFAULT VALUES",
+        # which ClickHouse doesn't parse. An empty JSONEachRow row is the equivalent:
+        # one row, every column at its table default (probed live, PLAN.md §2).
+        def empty_insert_statement_value(_primary_key = nil)
+          "FORMAT JSONEachRow {}"
+        end
+
         # Rails nests a SavepointTransaction inside any dirty transaction (e.g. the
         # retry in create_or_find_by) even though supports_savepoints? is false. Like
         # begin/commit/rollback (PLAN.md §5 decision 4), the savepoint verbs are honest
@@ -254,6 +261,7 @@ module ActiveRecord
             with_raw_connection do |raw_connection|
               result = raw_connection.execute_stream(sql, lines)
               verified!
+              notification_payload[:affected_rows] = result.written_rows
               notification_payload[:clickhouse] = result.stats
               result.written_rows
             end
@@ -287,20 +295,45 @@ module ActiveRecord
           end
         end
 
-        TRAILING_COMMENTS = %r{(?:\s*/\*(?:[^*]|\*(?!/))*\*/)+\s*\z}
+        COMMENT = %r{/\*(?:[^*]|\*(?!/))*\*/}m
         INSERT_STATEMENT = /\A\s*INSERT\b/i
-        private_constant :TRAILING_COMMENTS, :INSERT_STATEMENT
-
-        # ClickHouse reads everything after VALUES with the Values input format, which
-        # rejects trailing comments (probed 2026-07-13), so sqlcommenter tags appended
-        # by Rails' QueryLogs are hoisted to the front of INSERT statements.
-        def hoist_trailing_comments(sql)
+        # Data outside strings/comments: any non-space run, but a `/` only when it doesn't open a comment.
+        DATA_RUN = %r{(?:[^\s'`/]|/(?!\*))+}
+        private_constant :COMMENT, :INSERT_STATEMENT, :DATA_RUN
+
+        # ClickHouse reads everything after VALUES with the Values input format, which rejects
+        # trailing comments (probed 2026-07-13), so sqlcommenter tags Rails' QueryLogs appends
+        # are hoisted to the front of INSERTs. Scans string-aware — a /* inside a value (a request
+        # path like "/*") is opaque and never taken for a comment, so the VALUES list stays intact.
+        def hoist_trailing_comments(sql) # rubocop:disable Metrics/MethodLength
+          # ClickHouse strings are byte sequences; SQL carrying invalid UTF-8 must reach the server
+          # rather than die in the scan, so it drops to binary (the patterns are pure ASCII).
+          sql = sql.b unless sql.valid_encoding?
           return sql unless INSERT_STATEMENT.match?(sql)
 
-          comments = sql[TRAILING_COMMENTS]
-          return sql unless comments
+          scanner = StringScanner.new(sql)
+          data_end = 0
+          trailing = []
+          until scanner.eos?
+            next if scanner.skip(/\s+/)
+
+            if (comment = scanner.scan(COMMENT))
+              trailing << comment
+            else
+              consume_data_token(scanner)
+              trailing.clear
+              data_end = scanner.pos
+            end
+          end
+          return sql if trailing.empty?
+
+          "#{trailing.join(" ")} #{sql[0...data_end]}"
+        end
 
-          "#{comments.strip} #{sql[0...-comments.length]}"
+        # One opaque data token: a string literal or backtick identifier (skipped whole, so a /*
+        # inside never reads as a comment), an ordinary data run, or a lone char that starts none.
+        def consume_data_token(scanner)
+          scanner.scan(STRING_LITERAL) || scanner.scan(BACKTICK_IDENTIFIER) || scanner.scan(DATA_RUN) || scanner.getch
         end
 
         # Rails main (8.2) funnels execution through a QueryIntent object; released
@@ -322,6 +355,7 @@ module ActiveRecord
           result = raw_connection.execute(sql, params: params)
           verified!
           if notification_payload
+            notification_payload[:affected_rows] = result.written_rows
             notification_payload[:row_count] = result.rows.size
             notification_payload[:clickhouse] = result.stats
           end

data/lib/active_record/connection_adapters/clickhouse/error_translation.rb

@@ -8,6 +8,7 @@ module ActiveRecord
       class MemoryLimitExceeded < ActiveRecord::StatementInvalid; end
       class QueryTimeout < ActiveRecord::StatementInvalid; end
       class AuthenticationError < ActiveRecord::StatementInvalid; end
+      class AccessDenied < ActiveRecord::StatementInvalid; end
 
       module ErrorTranslation
         EXCEPTION_CLASS_BY_CODE = {
@@ -16,6 +17,7 @@ module ActiveRecord
           241 => MemoryLimitExceeded,
           159 => QueryTimeout,
           160 => QueryTimeout,
+          497 => AccessDenied,
           516 => AuthenticationError
         }.freeze
 
@@ -23,9 +25,16 @@ module ActiveRecord
         # input_format_null_as_default = 0) is a Rails not-null violation.
         NULL_INSERT_MESSAGE = /Cannot insert NULL value into a column of type/
 
+        # READONLY: the server refusing a write for a readonly user or a
+        # read_only: true connection — same refusal Rails models client-side
+        # with while_preventing_writes, so it raises Rails' class for it.
+        READONLY_CODE = 164
+
         private
 
         def translate_exception(exception, message:, sql:, binds:)
+          return ActiveRecord::ReadOnlyError.new(message) if readonly_refusal?(exception)
+
           server_error = server_exception_class(exception)
           return server_error.new(message, sql: sql, binds: binds) if server_error
 
@@ -37,6 +46,10 @@ module ActiveRecord
           end
         end
 
+        def readonly_refusal?(exception)
+          exception.is_a?(HTTPConnection::ExecutionError) && exception.code == READONLY_CODE
+        end
+
         def server_exception_class(exception)
           return nil unless exception.is_a?(HTTPConnection::ExecutionError)
 

data/lib/active_record/connection_adapters/clickhouse/gem_version.rb

@@ -3,7 +3,7 @@
 module ActiveRecord
   module ConnectionAdapters
     module ClickHouse
-      VERSION = "0.1.0"
+      VERSION = "0.2.1"
     end
   end
 end

data/lib/active_record/connection_adapters/clickhouse/http_connection.rb

@@ -20,6 +20,50 @@ module ActiveRecord
         BINARY_FORMAT = "RowBinaryWithNamesAndTypes"
         JSON_FORMAT = "JSONCompactEachRowWithNamesAndTypes"
 
+        # Failures raised before the request reaches a server: retrying them on
+        # another replica can never double a write. Anything mid-flight (read
+        # timeout, reset) raises instead — the statement may have executed.
+        # ENETUNREACH added blind (approved 2026-07-22): connect-phase by nature,
+        # but not reproducible in the test container.
+        CONNECT_ERRORS = [
+          Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, SocketError, Net::OpenTimeout
+        ].freeze
+
+        # Process-wide replica ledger: rotates the starting endpoint across
+        # connections and remembers connect failures so fresh connections skip
+        # an endpoint that refused within the (per-config) cooldown window.
+        @start_counter = 0
+        @connect_failure_times = {}
+        @ledger_lock = Mutex.new
+
+        class << self
+          def claim_start_index(endpoints, cooldown)
+            @ledger_lock.synchronize do
+              start = @start_counter % endpoints.size
+              @start_counter += 1
+              healthy_offset = endpoints.size.times.find do |offset|
+                !recently_failed?(endpoints[(start + offset) % endpoints.size], cooldown)
+              end
+              (start + (healthy_offset || 0)) % endpoints.size
+            end
+          end
+
+          def record_connect_failure(endpoint)
+            @ledger_lock.synchronize do
+              @connect_failure_times[endpoint] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            end
+          end
+
+          private
+
+          def recently_failed?(endpoint, cooldown)
+            failed_at = @connect_failure_times[format_endpoint(endpoint)]
+            failed_at && Process.clock_gettime(Process::CLOCK_MONOTONIC) - failed_at < cooldown
+          end
+
+          def format_endpoint(endpoint) = endpoint.join(":")
+        end
+
         class ExecutionError < StandardError
           attr_reader :code
 
@@ -57,7 +101,13 @@ module ActiveRecord
         def initialize(config)
           @config = config
           @select_format = config[:select_format].to_s == "json" ? JSON_FORMAT : BINARY_FORMAT
-          @http = build_http
+          @endpoints = build_endpoints
+          @endpoint_index = self.class.claim_start_index(@endpoints, failover_cooldown)
+          @http = nil
+        end
+
+        def current_endpoint
+          @endpoints[@endpoint_index].join(":")
         end
 
         # Adapts an enumerator of encoded lines to the partial-read IO contract
@@ -99,7 +149,7 @@ module ActiveRecord
           request = post_request(query_params({}, JSON_FORMAT).merge(query: sql))
           request["Transfer-Encoding"] = "chunked"
           request.body_stream = ChunkedBody.new(lines)
-          parse(raise_unless_success(@http.request(request)), JSON_FORMAT)
+          parse(raise_unless_success(send_request(request)), JSON_FORMAT)
         end
 
         # Scopes extra server settings to the requests made inside the block — the
@@ -120,15 +170,58 @@ module ActiveRecord
         end
 
         def close
-          @http.finish if @http.started?
+          @http.finish if @http&.started?
         rescue IOError
           nil
         end
 
         private
 
+        def http
+          @http ||= build_http
+        end
+
+        # Walks the endpoint list on connect-phase failures, at most one attempt
+        # per endpoint. A single-host config raises immediately, as before.
+        def send_request(request)
+          attempts = 0
+          begin
+            http.request(request)
+          rescue *CONNECT_ERRORS
+            attempts += 1
+            raise if attempts >= @endpoints.size
+
+            rotate_endpoint
+            retry
+          end
+        end
+
+        def rotate_endpoint
+          self.class.record_connect_failure(current_endpoint)
+          close
+          @http = nil
+          @endpoint_index = (@endpoint_index + 1) % @endpoints.size
+        end
+
+        # hosts: lists interchangeable replicas as "host" or "host:port" strings
+        # (the port: key is the default); host:/port: alone stay a single endpoint.
+        def build_endpoints
+          hosts = Array(@config[:hosts])
+          return [[@config[:host], @config[:port]]] if hosts.empty?
+
+          hosts.map do |entry|
+            host, port = entry.to_s.split(":", 2)
+            [host, port ? Integer(port) : @config[:port] || 8123]
+          end
+        end
+
+        def failover_cooldown
+          @config.fetch(:failover_cooldown, 30)
+        end
+
         def build_http
-          http = Net::HTTP.new(@config[:host], @config[:port])
+          host, port = @endpoints[@endpoint_index]
+          http = Net::HTTP.new(host, port)
           configure_tls(http)
           http.open_timeout = @config[:connect_timeout] if @config[:connect_timeout]
           http.read_timeout = @config[:read_timeout] if @config[:read_timeout]
@@ -146,7 +239,7 @@ module ActiveRecord
         def perform(sql, params, format)
           request = post_request(query_params(params, format))
           request.body = sql
-          raise_unless_success(@http.request(request))
+          raise_unless_success(send_request(request))
         end
 
         def post_request(params)
@@ -193,7 +286,10 @@ module ActiveRecord
             input_format_null_as_default: 0,
             # Server gzips responses ~3.6x smaller; Net::HTTP decompresses transparently
             # (it sends Accept-Encoding: gzip by default). Probed 2026-07-12, PLAN.md §2.
-            enable_http_compression: @config.fetch(:compression, true) ? 1 : 0
+            enable_http_compression: @config.fetch(:compression, true) ? 1 : 0,
+            # readonly=2 (not 1): strict readonly refuses the settings above with
+            # code 164 before any query runs — probed live 2026-07-19.
+            readonly: @config[:read_only] ? 2 : nil
           )
         end
 

data/lib/active_record/connection_adapters/clickhouse/schema_definitions.rb

@@ -4,7 +4,7 @@ module ActiveRecord
   module ConnectionAdapters
     module ClickHouse
       class TableDefinition < ConnectionAdapters::TableDefinition
-        attr_reader :engine, :order, :partition, :ttl, :table_settings, :primary_key_clause, :sample
+        attr_reader :engine, :partition, :ttl, :table_settings, :primary_key_clause, :sample
 
         def initialize(conn, name, engine: "MergeTree", order: nil, partition: nil, ttl: nil,
                        settings: nil, primary_key_clause: nil, sample: nil, **)
@@ -17,6 +17,12 @@ module ActiveRecord
           @sample = sample
           super(conn, name, **)
         end
+
+        # A Rails-style id: table carries its own obvious sorting key — the pk
+        # column — so create_table works without an explicit order: (decision #64).
+        def order
+          @order || columns.find { |column| column.options[:primary_key] }&.name&.to_s
+        end
       end
 
       # Carries the ClickHouse-only column metadata the dumper needs: compression codec
@@ -117,7 +123,8 @@ module ActiveRecord
         end
 
         def add_table_options!(create_sql, o)
-          if o.engine.include?("MergeTree") && o.order.nil?
+          # PRIMARY KEY alone is enough: the server infers ORDER BY from it (probed live).
+          if o.engine.include?("MergeTree") && o.order.nil? && o.primary_key_clause.nil?
             raise ArgumentError, "#{o.engine} tables require order: (the sorting key); use order: \"tuple()\" for none"
           end
 

data/lib/active_record/connection_adapters/clickhouse/schema_dumper.rb

@@ -54,8 +54,10 @@ module ActiveRecord
 
         # Projections dump right after their table as add_projection calls, parsed back
         # out of the stored query text (SELECT ... [GROUP BY ...] [ORDER BY ...]).
+        # Primary-key reporting is suppressed so every table dumps as id: false +
+        # explicit columns + order: — an implied id column would lose UInt64 on reload.
         def table(table, stream)
-          super
+          @connection.with_suppressed_primary_key_reporting { super }
           projections(table).each do |row|
             stream.puts("  #{projection_statement(table, row)}")
             stream.puts
@@ -143,12 +145,6 @@ module ActiveRecord
           spec
         end
 
-        # Rails omits precision 6 as the datetime default, but this adapter's default is
-        # DateTime64(3) — always dump the real precision.
-        def schema_precision(column)
-          column.precision&.inspect
-        end
-
         WRAPPER_TYPES = { /\ALowCardinality\((.*)\)\z/m => :low_cardinality, /\ANullable\((.*)\)\z/m => :null }.freeze
         private_constant :WRAPPER_TYPES
 

data/lib/active_record/connection_adapters/clickhouse/schema_statements.rb

@@ -14,7 +14,9 @@ module ActiveRecord
           # With id: false Rails' own primary_key: kwarg is inert, so the DSL reuses the
           # ClickHouse clause name; renamed here because super would swallow it. With an
           # explicit id column the Rails meaning (pk column name) wins untouched.
-          options[:primary_key_clause] = options.delete(:primary_key) if id == false && options.key?(:primary_key)
+          if id == false && options.key?(:primary_key)
+            options[:primary_key_clause] = primary_key_clause(options.delete(:primary_key))
+          end
           super
         end
 
@@ -271,10 +273,27 @@ module ActiveRecord
           data_sources.include?(name.to_s)
         end
 
-        # ClickHouse PRIMARY KEY is an index prefix, not a uniqueness guarantee, so no
-        # column is safe to expose as an Active Record primary key.
-        def primary_keys(_table_name)
-          []
+        # ClickHouse PRIMARY KEY is an index prefix, not a uniqueness guarantee. The
+        # one shape safe to report as Active Record identity is a sorting key that is
+        # exactly one id-typed column — the same class of keys the adapter generates
+        # client-side (decision #64), so Rails auto-detects the pk on id-keyed tables.
+        # Composite, expression, and non-id sorting keys report none; models may still
+        # declare self.primary_key explicitly (decision #13).
+        def primary_keys(table_name)
+          return [] if @suppress_primary_key_reporting
+
+          column, = generatable_primary_key(table_name)
+          column ? [column] : []
+        end
+
+        # The schema dumper opts out: with a reported pk Rails' dumper would imply the
+        # id column (degrading UInt64 to Int64 on reload) instead of dumping the
+        # id: false + explicit-columns + order: shape this adapter round-trips.
+        def with_suppressed_primary_key_reporting
+          @suppress_primary_key_reporting = true
+          yield
+        ensure
+          @suppress_primary_key_reporting = false
         end
 
         def indexes(table_name)
@@ -310,14 +329,17 @@ module ActiveRecord
         def type_to_sql(type, limit: nil, precision: nil, scale: nil, **)
           case type.to_s
           when "integer" then integer_to_sql(limit)
-          when "bigint" then "Int64"
-          when "string", "text" then "String"
+          # No autoincrement; a Rails-style pk is a plain Int64 filled client-side.
+          when "bigint", "primary_key" then "Int64"
+          # binary/blob included: ClickHouse String is an arbitrary byte sequence.
+          when "string", "text", "binary", "blob" then "String"
           when "float" then "Float64"
-          when "decimal", "numeric" then "Decimal(#{precision || 38}, #{scale || 10})"
-          # Rails' shared tests pass mysql-style parenthesized precision ("datetime(6)");
-          # the naked default matches Rails' microsecond convention, not CH's ms.
+          when "decimal", "numeric" then decimal_to_sql(precision, scale)
+          # Rails' shared tests pass mysql-style parenthesized precision ("datetime(6)").
+          # A nil precision here was explicit — Rails injects 6 for a bare t.datetime —
+          # so it means the second-precision base type, like MySQL's plain datetime.
           when /\A(?:datetime|timestamp)(?:\((\d+)\))?\z/
-            "DateTime64(#{Regexp.last_match(1) || precision || 6}, 'UTC')"
+            datetime_to_sql(Regexp.last_match(1) || precision)
           when "date" then "Date32"
           when "boolean" then "Bool"
           when "uuid" then "UUID"
@@ -416,6 +438,9 @@ module ActiveRecord
         end
 
         def changed_column_sql_type(type, options)
+          # Mirror new_column_definition: a datetime change without a precision key gets
+          # Rails' default microseconds; an explicit precision: nil stays plain DateTime.
+          options = { precision: 6, **options } if %i[datetime timestamp].include?(type.to_s.to_sym)
           sql_type = type_to_sql(type, **options.slice(:limit, :precision, :scale))
           sql_type = "Nullable(#{sql_type})" if options[:null]
           sql_type = "LowCardinality(#{sql_type})" if options[:low_cardinality]
@@ -599,6 +624,15 @@ module ActiveRecord
           settings.presence
         end
 
+        # Rails' composite-key convention passes primary_key: as an array of column
+        # names; ClickHouse takes them as a PRIMARY KEY tuple (and infers ORDER BY
+        # from it, probed live). A string is a raw clause and passes untouched.
+        def primary_key_clause(value)
+          return value unless value.is_a?(Array)
+
+          "(#{value.map { |column| quote_column_name(column) }.join(", ")})"
+        end
+
         def internal_table_options(table_name, options)
           case table_name.to_s
           when ActiveRecord::Base.schema_migrations_table_name
@@ -613,6 +647,34 @@ module ActiveRecord
           end
         end
 
+        # DateTime64 tops out at nanoseconds; the server rejects scale 10+ with
+        # ARGUMENT_OUT_OF_BOUND (code 69, probed live). Raise Rails' own wording at
+        # DDL-build time instead, matching the bundled adapters' 0..6 checks.
+        def datetime_to_sql(precision)
+          return "DateTime('UTC')" if precision.nil?
+
+          unless (0..9).cover?(precision.to_i)
+            raise ArgumentError, "No timestamp type has precision of #{precision}. " \
+                                 "The allowed range of precision is from 0 to 9"
+          end
+
+          "DateTime64(#{precision}, 'UTC')"
+        end
+
+        # Bare precision means scale 0 (SQL convention; Decimal(2, 10) is
+        # ARGUMENT_OUT_OF_BOUND — scale may not exceed precision). Bare scale is the
+        # same ArgumentError Rails' other adapters raise. No bounds at all keeps the
+        # wide Decimal(38, 10) default.
+        def decimal_to_sql(precision, scale)
+          if precision
+            "Decimal(#{precision}, #{scale || 0})"
+          elsif scale
+            raise ArgumentError, "Error adding decimal column: precision cannot be empty if scale is specified"
+          else
+            "Decimal(38, 10)"
+          end
+        end
+
         def integer_to_sql(limit)
           case limit
           when nil, 3, 4 then "Int32"

data/lib/active_record/connection_adapters/clickhouse/types.rb

@@ -27,9 +27,12 @@ module ActiveRecord
           when "Decimal", "Decimal32", "Decimal64", "Decimal128", "Decimal256"
             precision, scale = node.args.grep(Integer)
             ActiveModel::Type::Decimal.new(precision: precision, scale: scale)
-          when "Date", "Date32" then ActiveModel::Type::Date.new
-          when "DateTime" then ActiveModel::Type::DateTime.new
-          when "DateTime64" then ActiveModel::Type::DateTime.new(precision: node.args.first)
+          # The Active Record (not ActiveModel) temporal types: they respect
+          # ActiveRecord.default_timezone, and Rails' time-zone-aware attribute
+          # machinery type-checks for them.
+          when "Date", "Date32" then ActiveRecord::Type::Date.new
+          when "DateTime" then ActiveRecord::Type::DateTime.new
+          when "DateTime64" then ActiveRecord::Type::DateTime.new(precision: node.args.first)
           when "Bool" then ActiveModel::Type::Boolean.new
           when "String", "FixedString", "Enum8", "Enum16", "UUID", "IPv4", "IPv6" then ActiveModel::Type::String.new
           when "JSON" then ActiveRecord::Type::Json.new

data/lib/active_record/connection_adapters/clickhouse_adapter.rb

@@ -31,8 +31,8 @@ module ActiveRecord
       end
 
       CONNECTION_PARAMETER_KEYS = %i[
-        host port username password database ssl ssl_verify select_format
-        connect_timeout read_timeout write_timeout
+        host port hosts username password database ssl ssl_verify select_format
+        connect_timeout read_timeout write_timeout read_only failover_cooldown
         mutations_sync compression join_use_nulls async_insert wait_for_async_insert
       ].freeze
 
@@ -55,10 +55,15 @@ module ActiveRecord
         cluster ? " ON CLUSTER #{quote_table_name(cluster)}" : ""
       end
 
+      # Closing inside @lock keeps a queued query (which holds the lock for its whole
+      # HTTP round-trip) from starting on a socket that dies mid-read — the postgresql
+      # adapter's own disconnect! pattern.
       def disconnect!
-        super
-        @raw_connection&.close
-        @raw_connection = nil
+        @lock.synchronize do
+          super
+          @raw_connection&.close
+          @raw_connection = nil
+        end
       end
 
       def supports_explain? = true
@@ -78,6 +83,9 @@ module ActiveRecord
       def build_insert_sql(insert) = "INSERT #{insert.into} #{insert.values_list}" # :nodoc:
 
       NATIVE_DATABASE_TYPES = {
+        # No autoincrement exists; ids are generated client-side (decision #19),
+        # so a Rails-style pk is just a plain Int64 column.
+        primary_key: { name: "Int64" },
         string: { name: "String" },
         text: { name: "String" },
         integer: { name: "Int32", limit: 4 },
@@ -93,10 +101,23 @@ module ActiveRecord
 
       def native_database_types = NATIVE_DATABASE_TYPES
 
+      # Rails' class-level valid_type? reads this off the class.
+      def self.native_database_types = NATIVE_DATABASE_TYPES
+
       # Column types the dumper can't map to AR symbols (Array, Map, Tuple, ...) are
       # dumped verbatim, so every introspected type is valid by construction.
       def valid_type?(_type) = true
 
+      # The abstract TYPE_MAP pattern-matches generic SQL names: ClickHouse-only
+      # shapes (Nullable(...), UUID, Bool, Map, ...) degrade to unfrozen
+      # Type::Value there, and Tuple(String, Int64) even false-matches Integer.
+      # Frozen so lookups stay Ractor-shareable like Rails' own type maps.
+      def lookup_cast_type(sql_type) # :nodoc:
+        ClickHouse::Types.active_record_cast_type(sql_type).freeze
+      rescue ClickHouse::TypeParser::Error
+        super
+      end
+
       def create_schema_dumper(options) # :nodoc:
         ClickHouse::SchemaDumper.create(self, options)
       end

data/lib/arel/visitors/clickhouse.rb

@@ -64,6 +64,29 @@ module Arel
 
       private
 
+      # Arel's matches/does_not_match default to case-insensitive; ClickHouse LIKE is
+      # case-sensitive but ships native ILIKE (probed live), so this renders exactly
+      # like the postgresql visitor. ClickHouse has no ESCAPE clause — backslash is
+      # the fixed escape character — so a custom escape refuses loudly.
+      def visit_Arel_Nodes_Matches(o, collector)
+        raise NotImplementedError, "ClickHouse LIKE has no ESCAPE clause" if o.escape
+
+        infix_value o, collector, o.case_sensitive ? " LIKE " : " ILIKE "
+      end
+
+      def visit_Arel_Nodes_DoesNotMatch(o, collector)
+        raise NotImplementedError, "ClickHouse LIKE has no ESCAPE clause" if o.escape
+
+        infix_value o, collector, o.case_sensitive ? " NOT LIKE " : " NOT ILIKE "
+      end
+
+      # No row locks in ClickHouse (reads are isolated snapshots of parts); FOR UPDATE
+      # drops silently so shared Model.lock / with_lock code keeps working — the same
+      # contract as the sqlite3 adapter's visitor.
+      def visit_Arel_Nodes_Lock(_o, collector)
+        collector
+      end
+
       # ClickHouse's mutation machinery (lightweight DELETE, ALTER UPDATE) resolves WHERE
       # against an internal projection where table-qualified column names raise
       # UNKNOWN_IDENTIFIER (code 47), and it requires an explicit WHERE clause — so
@@ -83,7 +106,8 @@ module Arel
           collector = visit o.relation, collector
           collector << " UPDATE "
           collector = inject_join o.values, collector, ", "
-          collect_update_wheres(o, collector)
+          collector = collect_update_wheres(o, collector)
+          maybe_visit o.comment, collector
         end
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-clickhouse-adapter
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Ikraam Ghoor
@@ -76,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.3
 specification_version: 4
 summary: ClickHouse database adapter for Active Record
 test_files: []