clickhouse-activerecord 1.6.7 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48ec3fe01120adc07f02f2f8c8ff989d8866f8ce054efff32e63940e13dbc29c
-  data.tar.gz: 28f2c0189a4ef073849ea84bae2bb900bdd6c2e59014730e6a683714209f1b88
+  metadata.gz: f10ee5755575ea64229e6242e4fc081565fa5c4455581d5eca6fa47f2a047ee9
+  data.tar.gz: '07713045794d44203e419e4935c3abbff43c6f1cf9b5e6ad660b6f7e1f12510b'
 SHA512:
-  metadata.gz: 940ae4fc464c3bd1526a1c9694ed7ce21496e76dfea85127ad3c37a3cc2aa09661b67e4ad3ec9f640c009ac032106f5c99d70afdcb03c7d0ecc7b6511a1d2523
-  data.tar.gz: c98f507ba8e99e0096251eeff287f18259e2568b62fb60f8cc10385943c18b4877bae0b518c2ba4389af04a965885c4a04b171e033fd15ac38b3e6742d828c07
+  metadata.gz: 71d4af6e68d41395dfb924cb5f6dcf202a6d965a8ac49e55757586a544567cea8f60a094da4bdff7aefd438df216d85afb36518526159c750265794e66e4546b
+  data.tar.gz: 351ffc5dfd5acae7db007e28a88d5d2833d80b5dcaa9e35ba8b4a2612720bed9beda848a1d5e09559e79737f58055ea7236623af7b9436ee6f1346a2c9fd2e4e

data/.github/workflows/testing.yml

@@ -32,10 +32,10 @@ jobs:
             rails: 7.2.3
           - ruby: 4.0
             rails: 8.1
-        clickhouse: [ '24.6', '24.9', '25.10' ]
+        clickhouse: [ '24.9', '25.10' ]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Start ClickHouse ${{ matrix.clickhouse }}
         uses: hoverkraft-tech/compose-action@v2.5.0
@@ -82,7 +82,7 @@ jobs:
         clickhouse: [ '24.9', '25.10' ]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Start ClickHouse Cluster ${{ matrix.clickhouse }}
         uses: hoverkraft-tech/compose-action@v2.5.0

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+### Version 1.7.0 (Sep 29, 2026)
+
+* Fix structure dump table sort
+* Add configurable HTTP auth modes for ClickHouse requests in #240
+* Parse column `DEFAULT` kinds in #246
+* Honor unsigned: false on integer columns without a limit in #253
+* Fix `@response_format` thread race in `with_response_format` in #251
+* Implement URL-based configuration in #249
+* Rails 8 compatibility fixes in #245
+* Update specs in #244
+* Add Float and Bool subtype support for Map OID in #237
+* Fix TimeZoneConverter crash for Map OID attributes in #238
+* Fix Map OID deserialize crash for already-parsed Date/DateTime values in #239
+* Fix multi-column indexes in schema dumper in #234
+* Use `lease_connection` instead of `connection` for Rails 7.2+ in #262
+* Harden HTTP connection: open_timeout, TLS verification, retry, query limits in #266
+* Detect Array columns via Column#array in #260
+* Round-trip Float64 columns through the schema dumper in #269
+* Add support for FINAL when joining tables in #261
+* Clear the query cache when a raw statement writes in #271
+* Treat DEFAULT NULL as a nil column default in #272
+
 ### Version 1.6.7 (Mar 5, 2026)
 
 * Fix insert with default values in Ruby 4.0 and Rails 8.1

data/README.md

@@ -28,14 +28,47 @@ default: &default
   port: 8123
   username: username
   password: password
+  http_auth: query_params # optional, supports query_params, basic, x_clickhouse_headers
   ssl: true # optional for using ssl connection
   debug: true # use for showing in to log technical information
-  migrations_paths: db/clickhouse # optional, default: db/migrate_clickhouse
+  migrations_paths: db/clickhouse # optional
   cluster_name: 'cluster_name' # optional for creating tables in cluster 
   replica_name: '{replica}' # replica macros name, optional for creating replicated tables
   read_timeout: 300 # change network timeouts, by default 60 seconds
   write_timeout: 300
   keep_alive_timeout: 300
+  open_timeout: 5 # timeout for establishing the TCP connection itself, optional (Net::HTTP's default applies if unset)
+  insecure: false # optional, skip TLS certificate verification (default: true, matching prior behavior - set to false to verify)
+  sslca: /path/to/ca.pem # optional, custom CA bundle for TLS verification
+  max_execution_time: 25 # optional, server-side query time limit in seconds, sent as a ClickHouse session setting
+  cancel_http_readonly_queries_on_client_close: true # optional, tell the server to abort a SELECT once the client disconnects
+```
+
+### URL-based configuration
+
+You can configure the adapter with a single `url` key instead of individual fields:
+
+```yml
+default: &default
+  adapter: clickhouse
+  url: clickhouse://username:password@localhost:8123/database
+```
+
+Optional settings can be passed as query parameters:
+
+```
+clickhouse://username:password@localhost:8123/database?ssl=true&http_auth=basic&read_timeout=300&write_timeout=300&keep_alive_timeout=300&open_timeout=5&debug=false&cluster_name=my_cluster
+```
+
+Supported query parameters: `ssl` (true/false), `debug` (true/false), `insecure` (true/false), `http_auth` (query_params/basic/x_clickhouse_headers), `open_timeout`, `read_timeout`, `write_timeout`, `keep_alive_timeout`, `max_execution_time` (integers), `cancel_http_readonly_queries_on_client_close` (true/false), `cluster_name`, `sslca`.
+
+If both a `url` and explicit keys are provided, the explicit keys take precedence:
+
+```yml
+default: &default
+  adapter: clickhouse
+  url: clickhouse://username:password@localhost:8123/database
+  host: production.db.internal  # overrides the host from the URL
 ```
 
 Alternatively if you wish to pass a custom `Net::HTTP` transport (or any other
@@ -53,6 +86,55 @@ class ActionView < ActiveRecord::Base
 end
 ```
 
+### HTTP authentication mode
+
+By default, the adapter sends `user` and `password` as URL parameters.
+You can set `http_auth` explicitly (or omit it and keep the same default behavior):
+
+```yml
+clickhouse:
+  adapter: clickhouse
+  host: localhost
+  port: 8123
+  database: my_db
+  username: app_user
+  password: secret
+  http_auth: x_clickhouse_headers # or basic / query_params
+```
+
+- Use YAML string values: `http_auth: query_params`, `http_auth: basic`, or `http_auth: x_clickhouse_headers`.
+- Both strings and Ruby symbols are accepted internally.
+- `http_auth: x_clickhouse_headers` sends `X-ClickHouse-User`, `X-ClickHouse-Key`, and `X-ClickHouse-Database` headers.
+- `http_auth: basic` sends `Authorization: Basic ...` and keeps `database` in URL params.
+- `http_auth: query_params` sends `user`, `password`, and `database` in URL params (same as omitting `http_auth`).
+
+### Connection hardening
+
+- **TLS verification is now configurable.** Every connection has always been made with
+  `verify_mode: OpenSSL::SSL::VERIFY_NONE`, so an SSL connection to ClickHouse never actually
+  checked the server's certificate. That remains the default (`insecure: true`) to avoid
+  breaking existing setups; set `insecure: false` to turn verification on, optionally with
+  `sslca` pointing at your CA bundle.
+- **`open_timeout`** bounds how long establishing the underlying TCP connection is allowed to
+  take. It's optional and unset by default (`Net::HTTP`'s own default applies), unlike
+  `read_timeout`/`write_timeout` which only apply once a connection exists - a network path that
+  never completes the TCP handshake (a dead route, a security group silently dropping packets)
+  previously had no bound here at all.
+- **Read queries (`SELECT`) are retried once** on a fresh connection when the failure happens
+  before the server responds at all (`Net::OpenTimeout`, `EOFError`, `ECONNRESET`, `IOError`) -
+  the kind of failure a stale pooled connection produces. Writes are never retried, and
+  `Net::ReadTimeout` (the server received the query and hasn't answered yet) is deliberately
+  **not** retried on any query - re-sending a query that's already loading the server doesn't
+  help. If the retry also fails, `ActiveRecord::ConnectionFailed` is raised.
+- **Timeouts and cancellations now raise distinct, Rails-standard error classes** instead of a
+  generic `ActiveRecord::ActiveRecordError`, so callers can `rescue` them the same way they
+  would for any other adapter:
+  - `ActiveRecord::StatementTimeout` - the server killed the query server-side, via
+    `max_execution_time` or `cancel_http_readonly_queries_on_client_close`.
+  - `ActiveRecord::AdapterTimeout` - the client gave up waiting for a response
+    (`Net::ReadTimeout`); the query may still be running server-side.
+  - `ActiveRecord::ConnectionFailed` - the connection-retry above was exhausted.
+
 ## Usage in Rails
 
 Add your `database.yml` connection information with postfix `_clickhouse` for you environment:
@@ -197,6 +279,13 @@ User.joins(:actions).using(:group_id)
 # Clickhouse User Load (10.3ms)  SELECT users.* FROM users INNER JOIN actions USING group_id
 #=> #<ActiveRecord::Relation [#<User *** >]>
 
+# `final` only applies the FINAL modifier to the primary FROM table. Use
+# `joins_final` to also apply FINAL to a joined table (the join is added for
+# you, like `joins`). Pass association names; joins are matched by table name.
+User.final.joins_final(:actions)
+# Clickhouse User Load (10.3ms)  SELECT users.* FROM users FINAL INNER JOIN actions FINAL ON actions.user_id = users.id
+#=> #<ActiveRecord::Relation [#<User *** >]>
+
 User.window('x', order: 'date', partition: 'name', rows: 'UNBOUNDED PRECEDING').select('sum(value) OVER x')
 # SELECT sum(value) OVER x FROM users WINDOW x AS (PARTITION BY name ORDER BY date ROWS UNBOUNDED PRECEDING)
 #=> #<ActiveRecord::Relation [#<User *** >]>
@@ -343,6 +432,38 @@ Donations to this project are going directly to [PNixx](https://github.com/PNixx
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+### Run locally
+
+1. Start ClickHouse (single node):
+
+```bash
+docker compose -f .docker/docker-compose.yml up -d
+```
+
+2. Run single-node specs:
+
+```bash
+bin/test-single
+```
+
+If your local workflow expects `bin/single_test`, use the same command format as `bin/test-single`:
+
+```bash
+CLICKHOUSE_PORT=18123 CLICKHOUSE_DATABASE=default bundle exec rspec spec/single --format progress
+```
+
+3. Start ClickHouse cluster:
+
+```bash
+docker compose -f .docker/docker-compose.cluster.yml up -d
+```
+
+4. Run cluster specs:
+
+```bash
+CLICKHOUSE_PORT=28123 CLICKHOUSE_DATABASE=default CLICKHOUSE_CLUSTER=test_cluster bundle exec rspec spec/cluster --format progress
+```
+
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 Testing github actions:

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "clickhouse/activerecord"
+require "clickhouse-activerecord"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

data/bin/test-single

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+export CLICKHOUSE_PORT="${CLICKHOUSE_PORT:-18123}"
+export CLICKHOUSE_DATABASE="${CLICKHOUSE_DATABASE:-default}"
+
+exec bundle exec rspec spec/single --format progress "$@"

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

@@ -1,13 +1,33 @@
 module ActiveRecord
   module ConnectionAdapters
     module Clickhouse
-      class Column < ActiveRecord::ConnectionAdapters::Column
+      DescribedColumn =
+        Data.define(:name, :sql_type, :default_type, :default_expression, :comment, :codec) do
+          def ephemeral?
+            default_type.to_s.downcase == 'ephemeral'
+          end
+        end
 
-        attr_reader :codec
+      class Column < ActiveRecord::ConnectionAdapters::Column
+        attr_reader :codec, :default_kind
 
-        def initialize(*, codec: nil, **)
+        def initialize(*, codec: nil, default_kind: nil, **)
           super
           @codec = codec
+          @default_kind = ActiveSupport::StringInquirer.new(default_kind.to_s.downcase.presence || 'none')
+        end
+
+        def virtual?
+          default_kind.materialized? || default_kind.alias?
+        end
+
+        # Whether the column holds a ClickHouse `Array(...)` type.
+        #
+        # ActiveRecord core never calls this, but tooling such as annotaterb
+        # detects array columns via `column.respond_to?(:array) && column.array`,
+        # so the base adapter's missing `array` reader left them undetected.
+        def array
+          sql_type.start_with?('Array(')
         end
 
         private

data/lib/active_record/connection_adapters/clickhouse/oid/json.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module ConnectionAdapters
+    module Clickhouse
+      module OID # :nodoc:
+        class Json < Type::Json # :nodoc:
+
+          def deserialize(value)
+            if value.is_a?(::String)
+              ::JSON.parse(value)
+            else
+              super
+            end
+          rescue ::JSON::ParserError => e
+            ActiveSupport.error_reporter.report(e, source: "application.active_record")
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/clickhouse/oid/map.rb

@@ -11,6 +11,10 @@ module ActiveRecord
             when /U?Int(\d+)/
               @subtype = :integer
               @limit = bits_to_limit(Regexp.last_match(1)&.to_i)
+            when /Float/
+              @subtype = :float
+            when /Bool/
+              @subtype = :boolean
             when /DateTime/
               @subtype = :datetime
             when /Date/
@@ -31,9 +35,14 @@ module ActiveRecord
               value.map { |item| deserialize(item) }
             else
               return value if value.nil?
+              return value if already_deserialized?(value)
               case @subtype
                 when :integer
                   value.to_i
+                when :float
+                  value.to_f
+                when :boolean
+                  ActiveRecord::Type::Boolean.new.cast(value)
                 when :datetime
                   ::DateTime.parse(value)
                 when :date
@@ -51,6 +60,8 @@ module ActiveRecord
               value.map { |item| serialize(item) }
             else
               return value if value.nil?
+              return value.to_f if @subtype == :float
+              return ActiveRecord::Type::Boolean.new.cast(value) if @subtype == :boolean
               case @subtype
                 when :integer
                   value.to_i
@@ -68,6 +79,11 @@ module ActiveRecord
 
           private
 
+          def already_deserialized?(value)
+            (@subtype == :date && value.is_a?(::Date)) ||
+              (@subtype == :datetime && (value.is_a?(::DateTime) || value.is_a?(::Time)))
+          end
+
           def bits_to_limit(bits)
             case bits
             when 8   then 1

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

@@ -1,11 +1,20 @@
 # frozen_string_literal: true
 
+require 'base64'
+require 'net/http'
 require 'clickhouse-activerecord/version'
 
 module ActiveRecord
   module ConnectionAdapters
     module Clickhouse
       module SchemaStatements
+        HTTP_AUTH_QUERY_PARAMS = :query_params
+        HTTP_AUTH_BASIC = :basic
+        HTTP_AUTH_X_HEADERS = :x_clickhouse_headers
+        HTTP_AUTH_TYPES = [HTTP_AUTH_QUERY_PARAMS, HTTP_AUTH_BASIC, HTTP_AUTH_X_HEADERS].freeze
+
+        # Connection-level failures worth a single retry on a fresh connection.
+        RETRYABLE_CONNECTION_ERRORS = [Net::OpenTimeout, EOFError, Errno::ECONNRESET, IOError].freeze
 
         def with_settings(**settings)
           @block_settings ||= {}
@@ -32,14 +41,14 @@ module ActiveRecord
         #   end
         #   # sends and executes "SELECT * FROM table"
         def with_response_format(format)
-          prev_format = @response_format
-          @response_format = format
+          stack = response_format_stack
+          stack.push(format)
           yield
         ensure
-          @response_format = prev_format
+          stack.pop
         end
 
-        def execute(sql, name = nil, format: @response_format, settings: {})
+        def execute(sql, name = nil, format: response_format, settings: {})
           with_response_format(format) do
             log(sql, [adapter_name, name].compact.join(' ')) do
               raw_execute(sql, settings: settings)
@@ -55,16 +64,13 @@ module ActiveRecord
 
         # Execute an SQL query and save the result to a file in stream mode
         # @return [Tempfile]
-        def execute_to_file(sql, name = nil, format: @response_format, settings: {})
+        def execute_to_file(sql, name = nil, format: response_format, settings: {})
           with_response_format(format) do
             log(sql, [adapter_name, 'Stream', name].compact.join(' ')) do
-              statement = Statement.new(sql, format: @response_format)
+              statement = Statement.new(sql, format: response_format)
               result = nil
               @lock.synchronize do
-                req = Net::HTTP::Post.new("/?#{settings_params(settings)}", {
-                  'Content-Type' => 'application/x-www-form-urlencoded',
-                  'User-Agent' => ClickhouseAdapter::USER_AGENT,
-                })
+                req = Net::HTTP::Post.new("/?#{settings_params(settings)}", build_request_headers)
                 @connection.start unless @connection.started?
                 @connection.request(req, statement.formatted_sql) do |response|
                   result = statement.streaming_response(response)
@@ -82,19 +88,35 @@ module ActiveRecord
         end
 
         def internal_exec_query(sql, name = nil, binds = [], prepare: false, async: false, allow_retry: false)
-          result = execute(sql, name)
-          columns = result['meta'].map { |m| m['name'] }
-          types = {}
-          result['meta'].each_with_index do |m, i|
-            # need use column name and index after commit in 7.2:
-            # https://github.com/rails/rails/commit/24dbf7637b1d5cd6eb3d7100b8d0f6872c3fee3c
-            types[m['name']] = types[i] = type_map.lookup(m['type'])
+          connection_retries = 0
+          begin
+            result = execute(sql, name)
+            columns = result['meta'].map { |m| m['name'] }
+            types = {}
+            result['meta'].each_with_index do |m, i|
+              # need use column name and index after commit in 7.2:
+              # https://github.com/rails/rails/commit/24dbf7637b1d5cd6eb3d7100b8d0f6872c3fee3c
+              types[m['name']] = types[i] = type_map.lookup(m['type'])
+            end
+            ActiveRecord::Result.new(columns, result['data'], types)
+          rescue ActiveRecord::ActiveRecordError => e
+            raise e
+          rescue Net::ReadTimeout => e
+            raise ActiveRecord::AdapterTimeout, "Response: #{e.message}"
+          rescue *RETRYABLE_CONNECTION_ERRORS => e
+            raise ActiveRecord::ConnectionFailed, "Response: #{e.message}" if connection_retries.positive?
+
+            connection_retries += 1
+            logger&.warn("[clickhouse-activerecord] retrying read query after connection failure (#{e.class}: #{e.message})")
+            begin
+              reconnect
+            rescue StandardError
+              nil
+            end
+            retry
+          rescue StandardError => e
+            raise ActiveRecord::ActiveRecordError, "Response: #{e.message}"
           end
-          ActiveRecord::Result.new(columns, result['data'], types)
-        rescue ActiveRecord::ActiveRecordError => e
-          raise e
-        rescue StandardError => e
-          raise ActiveRecord::ActiveRecordError, "Response: #{e.message}"
         end
 
         def exec_insert_all(sql, name)
@@ -111,7 +133,7 @@ module ActiveRecord
         # @link https://clickhouse.com/docs/en/sql-reference/statements/delete
         def exec_delete(sql, name = nil, _binds = [])
           log(sql, "#{adapter_name} #{name}") do
-            statement = Statement.new(sql, format: @response_format)
+            statement = Statement.new(sql, format: response_format)
             res = request(statement)
             begin
               data = JSON.parse(res.header['x-clickhouse-summary'])
@@ -239,11 +261,23 @@ module ActiveRecord
           result = do_system_execute("DESCRIBE TABLE `#{table_name}`", table_name)
           data = result['data']
 
-          return data unless data.empty?
+          raise ActiveRecord::StatementInvalid, "Could not find table '#{table_name}'" if data.empty?
+
+          data.map do |row|
+            Clickhouse::DescribedColumn.new(
+              name: row[0],
+              sql_type: row[1],
+              default_type: row[2],
+              default_expression: row[3],
+              comment: row[4],
+              codec: row[5],
+            )
+          end
+        end
 
-          raise ActiveRecord::StatementInvalid, "Could not find table '#{table_name}'"
+        def column_definitions(table_name)
+          table_structure(table_name).reject(&:ephemeral?)
         end
-        alias column_definitions table_structure
 
         private
 
@@ -256,22 +290,22 @@ module ActiveRecord
         end
 
         def new_column_from_field(table_name, field, _definitions)
-          column_name, sql_type, default_type, default_expression = field
-          type_metadata = fetch_type_metadata(sql_type)
-          default_value = extract_value_from_default(default_expression, default_type)
-          default_function = extract_default_function(default_expression)
-          cast_type = lookup_cast_type(sql_type)
+          type_metadata = fetch_type_metadata(field.sql_type)
+          default_value = extract_value_from_default(field.default_expression, field.default_type)
+          default_function = extract_default_function(field.default_expression)
+          cast_type = lookup_cast_type(field.sql_type)
           default_value = cast_type.cast(default_value)
 
-          args = [column_name]
+          args = [field.name]
           args << cast_type if ::ActiveRecord::version >= Gem::Version.new('8.1')
-          args += [default_value, type_metadata, field[1].include?('Nullable'), default_function]
+          args += [default_value, type_metadata, field.sql_type.include?('Nullable'), default_function]
 
-          Clickhouse::Column.new(*args, codec: field[5].presence)
+          Clickhouse::Column.new(*args, codec: field.codec.presence, default_kind: field.default_type)
         end
 
         def extract_value_from_default(default_expression, default_type)
           return nil if default_type != 'DEFAULT' || default_expression.blank?
+          return nil if default_expression == 'NULL'
           return nil if has_default_function?(default_expression)
 
           # Convert string
@@ -289,7 +323,7 @@ module ActiveRecord
         end
 
         def raw_execute(sql, settings: {}, except_params: [])
-          statement = Statement.new(sql, format: @response_format)
+          statement = Statement.new(sql, format: response_format)
           response = request(statement, settings: settings, except_params: except_params)
           statement.processed_response(response)
         end
@@ -303,8 +337,7 @@ module ActiveRecord
           @lock.synchronize do
             @connection.post("/?#{settings_params(settings, except: except_params)}",
                              statement.formatted_sql,
-                             'Content-Type' => 'application/x-www-form-urlencoded',
-                             'User-Agent' => ClickhouseAdapter::USER_AGENT)
+                             build_request_headers(include_database: !except_params.include?(:database)))
           end
         end
 
@@ -313,15 +346,57 @@ module ActiveRecord
           log(sql, "#{name} (system)") { yield }
         end
 
+        # The response format that should be applied to the next request.
+        # Reads the per-thread override pushed by `with_response_format`, falling
+        # back to the adapter-level default when no override is in scope.
+        def response_format
+          stack = response_format_stack
+          stack.empty? ? @default_response_format : stack.last
+        end
+
+        def response_format_stack
+          key = (@response_format_stack_key ||= :"clickhouse_response_format_stack_#{object_id}")
+          Thread.current[key] ||= []
+        end
+
         def settings_params(settings = {}, except: [])
           request_params = @connection_config || {}
           block_settings = @block_settings || {}
+
+          case @http_auth
+          when HTTP_AUTH_BASIC
+            request_params = request_params.except(:user, :password)
+          when HTTP_AUTH_X_HEADERS
+            request_params = request_params.except(:user, :password, :database)
+          end
+
           request_params.merge(block_settings)
                         .merge(settings)
                         .except(*except)
                         .to_param
         end
 
+        def build_request_headers(include_database: true)
+          request_headers = {
+            'Content-Type' => 'application/x-www-form-urlencoded',
+            'User-Agent' => ClickhouseAdapter::USER_AGENT
+          }
+
+          case @http_auth
+          when HTTP_AUTH_BASIC
+            if @config[:username] && @config[:password]
+              credentials = Base64.strict_encode64("#{@config[:username]}:#{@config[:password]}")
+              request_headers['Authorization'] = "Basic #{credentials}"
+            end
+          when HTTP_AUTH_X_HEADERS
+            request_headers['X-ClickHouse-User'] = @config[:username].to_s if @config[:username]
+            request_headers['X-ClickHouse-Key'] = @config[:password].to_s if @config[:password]
+            request_headers['X-ClickHouse-Database'] = @config[:database].to_s if include_database && @config[:database]
+          end
+
+          request_headers
+        end
+
         # Returns a hash of table names to their engine types
         def table_engines(table_names = nil)
           table_names_sql = if table_names.present?

data/lib/active_record/connection_adapters/clickhouse/statement/response_processor.rb

@@ -54,7 +54,7 @@ module ActiveRecord
 
           # @return [String, Hash, Array]
           def process_successful_response
-            raise_generic!(@sql) if @body.include?('DB::Exception') && @body.match?(DB_EXCEPTION_REGEXP)
+            raise_database_error!(@sql) if @body.include?('DB::Exception') && @body.match?(DB_EXCEPTION_REGEXP)
 
             format_body_response
           end
@@ -103,14 +103,17 @@ module ActiveRecord
             JSON.parse(payload, decimal_class: BigDecimal)
           end
 
-          def raise_database_error!
+          def raise_database_error!(sql = nil)
             case @body
             when /DB::Exception:.*\(UNKNOWN_DATABASE\)/
               raise ActiveRecord::NoDatabaseError
             when /DB::Exception:.*\(DATABASE_ALREADY_EXISTS\)/
               raise ActiveRecord::DatabaseAlreadyExists
+            when /DB::Exception:.*\(TIMEOUT_EXCEEDED\)/
+              # server-side cancellation, vs. ActiveRecord::AdapterTimeout (client gave up)
+              raise ActiveRecord::StatementTimeout, "Response code: #{@raw_response.code}:\n#{@body}#{"\nQuery: #{sql}" if sql}"
             else
-              raise_generic!
+              raise_generic!(sql)
             end
           end
 

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

@@ -41,7 +41,7 @@ module ActiveRecord
           unsigned = options[:unsigned]
           unsigned = true if unsigned.nil?
 
-          kind = :uint32 # default
+          kind = unsigned ? :uint32 : :int32 # default
 
           if options[:limit]
             if unsigned
@@ -63,6 +63,12 @@ module ActiveRecord
           args.each { |name| column(name, kind, **options.except(:limit, :unsigned)) }
         end
 
+        def float(*args, **options)
+          kind = options[:limit] == 8 ? :float64 : :float
+
+          args.each { |name| column(name, kind, **options.except(:limit)) }
+        end
+
         def datetime(*args, **options)
           kind = :datetime
 

data/lib/active_record/connection_adapters/clickhouse_adapter.rb

@@ -2,6 +2,7 @@
 
 require 'arel/visitors/clickhouse'
 require 'arel/nodes/final'
+require 'arel/nodes/final_table'
 require 'arel/nodes/grouping_sets'
 require 'arel/nodes/settings'
 require 'arel/nodes/using'
@@ -11,6 +12,7 @@ require 'active_record/connection_adapters/clickhouse/oid/date'
 require 'active_record/connection_adapters/clickhouse/oid/date_time'
 require 'active_record/connection_adapters/clickhouse/oid/big_integer'
 require 'active_record/connection_adapters/clickhouse/oid/map'
+require 'active_record/connection_adapters/clickhouse/oid/json'
 require 'active_record/connection_adapters/clickhouse/oid/uuid'
 require 'active_record/connection_adapters/clickhouse/column'
 require 'active_record/connection_adapters/clickhouse/quoting'
@@ -20,6 +22,7 @@ require 'active_record/connection_adapters/clickhouse/statement'
 require 'active_record/connection_adapters/clickhouse/table_definition'
 require 'net/http'
 require 'openssl'
+require 'uri'
 
 module ActiveRecord
   class Base
@@ -28,10 +31,22 @@ module ActiveRecord
       def clickhouse_connection(config)
         config = config.symbolize_keys
 
+        if config[:url]
+          url_config = ConnectionAdapters::ClickhouseAdapter.parse_clickhouse_url(config.delete(:url))
+          config = url_config.merge(config)
+        end
+
         unless config.key?(:database)
           raise ArgumentError, 'No database specified. Missing argument: database.'
         end
 
+        if config[:http_auth]
+          unless ConnectionAdapters::Clickhouse::SchemaStatements::HTTP_AUTH_TYPES.include?(config[:http_auth]&.to_sym)
+            raise ArgumentError, "Unknown :http_auth mode #{config[:http_auth].inspect}. " \
+              + "Use one of #{ConnectionAdapters::Clickhouse::SchemaStatements::HTTP_AUTH_TYPES}."
+          end
+        end
+
         ConnectionAdapters::ClickhouseAdapter.new(config)
       end
     end
@@ -52,6 +67,8 @@ module ActiveRecord
   module ModelSchema
     module ClassMethods
       delegate :final, :final!,
+               :joins_final, :joins_final!,
+               :left_joins_final, :left_joins_final!,
                :group_by_grouping_sets, :group_by_grouping_sets!,
                :settings, :settings!,
                :window, :window!,
@@ -90,6 +107,7 @@ module ActiveRecord
         integer: { name: 'UInt32' },
         big_integer: { name: 'UInt64' },
         float: { name: 'Float32' },
+        float64: { name: 'Float64' },
         decimal: { name: 'Decimal' },
         datetime: { name: 'DateTime' },
         datetime64: { name: 'DateTime64' },
@@ -119,8 +137,16 @@ module ActiveRecord
 
       include Clickhouse::SchemaStatements
 
+      # our `execute` shadows the wrapper `QueryCache` installs on `AbstractAdapter`
+      ActiveRecord::ConnectionAdapters::QueryCache.dirties_query_cache(self, :execute)
+
       # Initializes and connects a Clickhouse adapter.
       def initialize(config_or_deprecated_connection, deprecated_logger = nil, deprecated_connection_options = nil, deprecated_config = nil)
+        if config_or_deprecated_connection.is_a?(Hash) && config_or_deprecated_connection[:url]
+          config_or_deprecated_connection = config_or_deprecated_connection.dup
+          url_config = self.class.parse_clickhouse_url(config_or_deprecated_connection.delete(:url))
+          config_or_deprecated_connection = url_config.merge(config_or_deprecated_connection)
+        end
         super
         if @config[:connection]
           connection = {
@@ -132,7 +158,9 @@ module ActiveRecord
             host: @config[:host] || 'localhost',
             port: port,
             ssl: @config[:ssl].present? ? @config[:ssl] : port == 443,
+            insecure: @config.fetch(:insecure, true),
             sslca: @config[:sslca],
+            open_timeout: @config[:open_timeout],
             read_timeout: @config[:read_timeout],
             write_timeout: @config[:write_timeout],
             keep_alive_timeout: @config[:keep_alive_timeout]
@@ -140,9 +168,16 @@ module ActiveRecord
         end
         @connection_parameters = connection
 
-        @connection_config = { user: @config[:username], password: @config[:password], database: @config[:database] }.compact
+        @connection_config = {
+          user: @config[:username],
+          password: @config[:password],
+          database: @config[:database],
+          max_execution_time: @config[:max_execution_time],
+          cancel_http_readonly_queries_on_client_close: @config[:cancel_http_readonly_queries_on_client_close],
+        }.compact
         @debug = @config[:debug] || false
-        @response_format = @config[:format] || DEFAULT_RESPONSE_FORMAT
+        @default_response_format = @config[:format] || DEFAULT_RESPONSE_FORMAT
+        @http_auth = @config[:http_auth]&.to_sym
 
         @prepared_statements = false
 
@@ -185,11 +220,55 @@ module ActiveRecord
         !native_database_types[type].nil?
       end
 
+      # Rails appends the limit to the native type name (e.g. "Float32(8)"), which is not valid in ClickHouse.
+      # Resolve the float width by limit here so that add_column / change_column behave like TableDefinition#float.
+      def type_to_sql(type, limit: nil, precision: nil, scale: nil, **)
+        return native_database_types[limit == 8 ? :float64 : :float][:name] if type.to_s == 'float'
+
+        super
+      end
+
       def supports_indexes_in_create?
         true
       end
 
       class << self
+        def parse_clickhouse_url(url)
+          uri = URI.parse(url)
+          config = {}
+
+          config[:host]     = uri.host                                    if uri.host
+          config[:port]     = uri.port                                    if uri.port
+          config[:username] = URI.decode_www_form_component(uri.user)     if uri.user
+          config[:password] = URI.decode_www_form_component(uri.password) if uri.password
+
+          if uri.path && uri.path.length > 1
+            config[:database] = uri.path.delete_prefix('/')
+          end
+
+          if uri.query
+            URI.decode_www_form(uri.query).each do |key, value|
+              case key
+              when 'ssl'                then config[:ssl]                = (value == 'true')
+              when 'debug'              then config[:debug]              = (value == 'true')
+              when 'insecure'           then config[:insecure]           = (value == 'true')
+              when 'open_timeout'       then config[:open_timeout]       = value.to_i
+              when 'read_timeout'       then config[:read_timeout]       = value.to_i
+              when 'write_timeout'      then config[:write_timeout]      = value.to_i
+              when 'keep_alive_timeout' then config[:keep_alive_timeout] = value.to_i
+              when 'http_auth'          then config[:http_auth]          = value
+              when 'cluster_name'       then config[:cluster_name]       = value
+              when 'sslca'              then config[:sslca]              = value
+              when 'max_execution_time' then config[:max_execution_time] = value.to_i
+              when 'cancel_http_readonly_queries_on_client_close'
+                config[:cancel_http_readonly_queries_on_client_close] = (value == 'true')
+              end
+            end
+          end
+
+          config
+        end
+
         def extract_limit(sql_type) # :nodoc:
           case sql_type
             when /(Nullable)?\(?String\)?/
@@ -204,6 +283,10 @@ module ActiveRecord
               8
             when /(Nullable)?\(?U?Int128\)?/
               16
+            when /(Nullable)?\(?Float32\)?/
+              nil
+            when /(Nullable)?\(?Float64\)?/
+              8
             else
               super
           end
@@ -254,7 +337,7 @@ module ActiveRecord
             Clickhouse::OID::Map.new(sql_type)
           end
 
-          m.register_type %r(JSON)i, ActiveRecord::Type::Json.new
+          m.register_type(%r(JSON)) { Clickhouse::OID::Json.new }
         end
       end
 
@@ -304,7 +387,7 @@ module ActiveRecord
         end
 
         pk = table_structure(table_name).first
-        return ['id'] if pk.present? && pk[0] == 'id'
+        return ['id'] if pk.present? && pk.name == 'id'
         []
       end
 
@@ -426,9 +509,9 @@ module ActiveRecord
       end
 
       def change_column_null(table_name, column_name, null, default = nil)
-        structure = table_structure(table_name).select{|v| v[0] == column_name.to_s}.first
+        structure = table_structure(table_name).find { |col| col.name == column_name.to_s }
         raise "Column #{column_name} not found in table #{table_name}" if structure.nil?
-        change_column table_name, column_name, structure[1].gsub(/(Nullable\()?(.*?)\)?/, '\2'), {null: null, default: default}.compact
+        change_column table_name, column_name, structure.sql_type.gsub(/(Nullable\()?(.*?)\)?/, '\2'), {null: null, default: default}.compact
       end
 
       def change_column_default(table_name, column_name, default)
@@ -539,8 +622,13 @@ module ActiveRecord
 
       protected
 
-      def last_inserted_id(result)
-        result
+      def last_inserted_id(_result)
+        # Rails 7.1 persistence.rb:1258:
+        # _write_attribute(column, value)  # wrote true directly — ugly but no crash
+
+        # Rails 8.0 persistence.rb:933:
+        # _write_attribute(column, type_for_attribute(column).deserialize(value))  # now deserializes first
+        nil
       end
 
       def change_column_for_alter(table_name, column_name, type, **options)
@@ -552,9 +640,15 @@ module ActiveRecord
       private
 
       def connect
-        @connection = @connection_parameters[:connection] || Net::HTTP.start(@connection_parameters[:host], @connection_parameters[:port], use_ssl: @connection_parameters[:ssl], verify_mode: OpenSSL::SSL::VERIFY_NONE)
-
-        @connection.ca_file = @connection_parameters[:ca_file] if @connection_parameters[:ca_file]
+        @connection = @connection_parameters[:connection] || Net::HTTP.start(
+          @connection_parameters[:host],
+          @connection_parameters[:port],
+          use_ssl: @connection_parameters[:ssl],
+          verify_mode: @connection_parameters[:insecure] ? OpenSSL::SSL::VERIFY_NONE : OpenSSL::SSL::VERIFY_PEER,
+          **{ open_timeout: @connection_parameters[:open_timeout] }.compact
+        )
+
+        @connection.ca_file = @connection_parameters[:sslca] if @connection_parameters[:sslca]
         @connection.read_timeout = @connection_parameters[:read_timeout] if @connection_parameters[:read_timeout]
         @connection.write_timeout = @connection_parameters[:write_timeout] if @connection_parameters[:write_timeout]
 

data/lib/arel/nodes/final_table.rb

@@ -0,0 +1,10 @@
+module Arel # :nodoc: all
+  module Nodes
+    # Wraps the table source of a JOIN so the ClickHouse visitor renders
+    # `<table> FINAL ON ...` for that join. Built by
+    # ActiveRecord::Relation#joins_final, which marks the matching join
+    # sources after Arel has been constructed.
+    class FinalTable < Arel::Nodes::Unary
+    end
+  end
+end

data/lib/arel/visitors/clickhouse.rb

@@ -10,8 +10,7 @@ module Arel
       end
 
       def aggregate(name, o, collector)
-        # replacing function name for materialized view
-        if o.expressions.first && o.expressions.first != '*' && !o.expressions.first.is_a?(String) && o.expressions.first.relation&.is_view
+        if o.expressions.first && o.expressions.first != '*' && !o.expressions.first.is_a?(String) && o.expressions.first.respond_to?(:relation) && o.expressions.first.relation&.is_view
           super("#{name.downcase}Merge", o, collector)
         else
           super
@@ -89,6 +88,16 @@ module Arel
         collector
       end
 
+      # Renders the FINAL modifier for a single JOIN source, e.g.
+      # `INNER JOIN espm_binaries FINAL ON ...`. The join visitors inherited
+      # from ToSql all emit their table via `visit o.left`, so wrapping that
+      # table in a FinalTable node is enough to add FINAL to any join type.
+      def visit_Arel_Nodes_FinalTable(o, collector)
+        collector = visit o.expr, collector
+        collector << ' FINAL'
+        collector
+      end
+
       def visit_Arel_Nodes_GroupingSets(o, collector)
         collector << 'GROUPING SETS '
         grouping_array_or_grouping_element(o.expr, collector)
@@ -100,7 +109,7 @@ module Arel
         collector << "SETTINGS "
         o.expr.each_with_index do |(key, value), i|
           collector << ", " if i > 0
-          collector << key.to_s.gsub(/\W+/, "")
+          collector << sanitize_as_setting_name(key).to_s
           collector << " = "
           collector << sanitize_as_setting_value(value)
         end
@@ -146,7 +155,7 @@ module Arel
 
       def sanitize_as_setting_name(value)
         return value if Arel::Nodes::SqlLiteral === value
-        @connection.sanitize_as_setting_name(value)
+        value.to_s.gsub(/\W+/, "")
       end
 
       private

data/lib/clickhouse-activerecord/schema_dumper.rb

@@ -99,7 +99,7 @@ module ClickhouseActiverecord
             end
           end
 
-          indexes = sql.scan(/INDEX \S+ \S+ TYPE .*? GRANULARITY \d+/)
+          indexes = sql.scan(/INDEX \S+ .+? TYPE .*? GRANULARITY \d+/)
           if indexes.any?
             tbl.puts ''
             indexes.flatten.map!(&:strip).each do |index|
@@ -154,22 +154,17 @@ module ClickhouseActiverecord
       end
     end
 
-    def schema_limit(column)
-      return nil if column.type == :float
-      super
-    end
-
     def schema_unsigned(column)
       return nil unless column.type == :integer && !simple
       (column.sql_type =~ /(Nullable)?\(?UInt\d+\)?/).nil? ? false : nil
     end
 
     def schema_array(column)
-      (column.sql_type =~ /Array\(/).nil? ? nil : true
+      column.array ? true : nil
     end
 
     def schema_map(column)
-      if column.sql_type =~ /Map\(([^,]+),\s*(Array)\)/
+      if column.sql_type =~ /Map\([^,]+,\s*Array\(/
         return :array
       end
 

data/lib/clickhouse-activerecord/tasks.rb

@@ -34,28 +34,32 @@ module ClickhouseActiverecord
       create
     end
 
-    def structure_dump(*args)
+    def structure_dump(path, *)
       establish_master_connection
 
+      # get all functions
+      functions = connection.execute("SELECT create_query FROM system.functions WHERE origin = 'SQLUserDefined' ORDER BY name")['data']
+                            .flatten
+                            .map { |function| function.gsub('\\n', "\n") }
+
       # get all tables
-      tables = connection.execute("SHOW TABLES FROM #{@configuration.database} WHERE name NOT LIKE '.inner_id.%'")['data'].flatten.map do |table|
-        connection.show_create_table(table, single_line: false).gsub("#{@configuration.database}.", '')
-      end.compact
+      table_defs = connection.execute("SHOW TABLES FROM #{@configuration.database} WHERE name NOT LIKE '.inner_id.%'")['data']
+                             .flatten
+                             .map { |name| connection.show_create_table(name, single_line: false).gsub("#{@configuration.database}.", '') }
 
-      # sort view to last
-      tables.sort_by! {|table| table.match(/^CREATE\s+(MATERIALIZED\s+)?VIEW/) ? 1 : 0}
+      # separate views from tables
+      views, tables = table_defs.partition { |sql| sql.match(/^CREATE\s+(MATERIALIZED\s+)?VIEW/) }
 
-      # get all functions
-      functions = connection.execute("SELECT create_query FROM system.functions WHERE origin = 'SQLUserDefined' ORDER BY name")['data'].flatten
+      # separate materialized from regular views
+      mat_views, views = views.partition { |sql| sql.match(/^CREATE\s+MATERIALIZED\s+VIEW/) }
 
-      # put to file
-      File.open(args.first, 'w:utf-8') do |file|
-        functions.each do |function|
-          file.puts function.gsub('\\n', "\n") + ";\n\n"
-        end
+      # sort: UDFs -> tables -> materialized views -> views
+      ordered_definitions = functions.sort + tables.sort + mat_views.sort + views.sort
 
-        tables.each do |table|
-          file.puts table + ";\n\n"
+      # puts to file
+      File.open(path, 'w:utf-8') do |file|
+        ordered_definitions.each do |sql|
+          file.puts "#{sql};\n\n"
         end
       end
     end

data/lib/clickhouse-activerecord/version.rb

@@ -1,3 +1,3 @@
 module ClickhouseActiverecord
-  VERSION = '1.6.7'
+  VERSION = '1.7.0'
 end

data/lib/clickhouse-activerecord.rb

@@ -30,5 +30,15 @@ module ClickhouseActiverecord
     Arel::Nodes::SelectStatement.prepend(CoreExtensions::Arel::Nodes::SelectStatement)
     Arel::SelectManager.prepend(CoreExtensions::Arel::SelectManager)
     Arel::Table.prepend(CoreExtensions::Arel::Table)
+
+    # Prevent TimeZoneConverter wrapping for Map OID with DateTime subtype.
+    # Map(String, DateTime) would crash with "Hash values are not supported"
+    # when TimeZoneConverter tries to convert Hash values.
+    ActiveRecord::AttributeMethods::TimeZoneConversion::ClassMethods.prepend(Module.new do
+      def create_time_zone_conversion_attribute?(name, cast_type)
+        return false if cast_type.is_a?(ActiveRecord::ConnectionAdapters::Clickhouse::OID::Map)
+        super
+      end
+    end)
   end
 end

data/lib/core_extensions/active_record/relation.rb

@@ -3,11 +3,12 @@ module CoreExtensions
     module Relation
 
       def self.prepended(base)
-        base::VALID_UNSCOPING_VALUES << :final << :settings
+        base::VALID_UNSCOPING_VALUES << :final << :settings << :joins_final
       end
 
       def reverse_order!
-        return super unless connection.is_a?(::ActiveRecord::ConnectionAdapters::ClickhouseAdapter)
+        conn = respond_to?(:lease_connection) ? lease_connection : connection
+        return super unless conn.is_a?(::ActiveRecord::ConnectionAdapters::ClickhouseAdapter)
 
         orders = order_values.uniq.reject(&:blank?)
         return super unless orders.empty? && !primary_key
@@ -90,6 +91,79 @@ module CoreExtensions
         @values.fetch(:final, nil)
       end
 
+      # Apply the FINAL modifier to one or more joined tables. Unlike #final,
+      # which only adds FINAL to the query's primary FROM table, #joins_final
+      # adds the join(s) and renders FINAL on the joined table so ClickHouse
+      # merges those rows before joining.
+      # For example:
+      #
+      #   AppControlEvent.final.joins_final(:espm_binary)
+      #   # SELECT ... FROM espm_app_control_events FINAL
+      #   #   INNER JOIN espm_binaries FINAL ON ...
+      #
+      # Each argument is an association name and is added as a join (like
+      # #joins); FINAL is then rendered on the joined table. Joins are matched
+      # by table name, so if the same table is joined more than once every join
+      # of that table receives FINAL. An
+      # <tt>ActiveRecord::ActiveRecordError</tt> will be raised if the database
+      # is not ClickHouse.
+      #
+      # @param [Array] args
+      def joins_final(*args)
+        spawn.joins_final!(*args)
+      end
+
+      # @param [Array] args
+      def joins_final!(*args)
+        check_command!('FINAL')
+        joins!(*args)
+        self.joins_final_values |= args
+        self
+      end
+
+      # Like #joins_final, but adds the join(s) as LEFT OUTER JOINs (via
+      # #left_outer_joins) and renders FINAL on the joined table. Use this when
+      # the joined rows must be preserved even with no match (e.g. an optional
+      # catalog lookup) while still merging the joined table with FINAL.
+      # For example:
+      #
+      #   AppControlEvent.left_joins_final(:espm_binary)
+      #   # SELECT ... FROM espm_app_control_events
+      #   #   LEFT OUTER JOIN espm_binaries FINAL ON ...
+      #
+      # Each argument is an association name and is added as a left outer join
+      # (like #left_outer_joins); FINAL is then rendered on the joined table.
+      # Joins are matched by table name, so if the same table is joined more
+      # than once every join of that table receives FINAL. An
+      # <tt>ActiveRecord::ActiveRecordError</tt> will be raised if the database
+      # is not ClickHouse.
+      #
+      # @param [Array] args
+      def left_joins_final(*args)
+        spawn.left_joins_final!(*args)
+      end
+
+      # @param [Array] args
+      def left_joins_final!(*args)
+        check_command!('FINAL')
+        left_outer_joins!(*args)
+        self.joins_final_values |= args
+        self
+      end
+
+      def joins_final_values
+        @values.fetch(:joins_final, ::ActiveRecord::QueryMethods::FROZEN_EMPTY_ARRAY)
+      end
+
+      def joins_final_values=(value)
+        if ::ActiveRecord::version >= Gem::Version.new('7.2')
+          assert_modifiable!
+        else
+          assert_mutability!
+        end
+        @values[:joins_final] = value
+      end
+
       # GROUPING SETS allows you to specify multiple groupings in the GROUP BY clause.
       # Whereas GROUP BY CUBE generates all possible groupings, GROUP BY GROUPING SETS generates only the specified groupings.
       # For example:
@@ -175,6 +249,50 @@ module CoreExtensions
         raise ::ActiveRecord::ActiveRecordError, cmd + ' is a ClickHouse specific query clause' unless connection.is_a?(::ActiveRecord::ConnectionAdapters::ClickhouseAdapter)
       end
 
+      # Wrap the left (table) side of every join source that matches a
+      # requested #joins_final argument in an Arel::Nodes::FinalTable so the
+      # ClickHouse visitor renders FINAL on that join. Called before
+      # +arel.final!+ so the join source is still the plain JoinSource (and not
+      # yet wrapped in the FROM-level Final node).
+      def mark_final_joins!(arel)
+        names = final_join_table_names
+        return if names.empty?
+
+        arel.join_sources.each do |join|
+          next unless join.respond_to?(:left) && join.respond_to?(:left=)
+
+          left = join.left
+          next if left.is_a?(::Arel::Nodes::FinalTable)
+          next unless final_join_match?(left, names)
+
+          join.left = ::Arel::Nodes::FinalTable.new(left)
+        end
+      end
+
+      # Resolve the #joins_final arguments to the set of table names that
+      # should carry FINAL. Association names are mapped to their table;
+      # anything else is treated as a literal table name.
+      def final_join_table_names
+        joins_final_values.flatten.filter_map do |arg|
+          case arg
+          when Symbol, String
+            reflection = klass.reflect_on_association(arg.to_sym)
+            reflection ? reflection.table_name : arg.to_s
+          end
+        end.to_set
+      end
+
+      # Does the join's table source match one of the requested FINAL names?
+      # Handles both Arel::Table (name) and Arel::Nodes::TableAlias (alias name
+      # plus the underlying relation's name).
+      def final_join_match?(left, names)
+        candidates = []
+        candidates << left.name if left.respond_to?(:name)
+        candidates << left.table_alias if left.respond_to?(:table_alias) && left.table_alias
+        candidates << left.relation.name if left.respond_to?(:relation) && left.relation.respond_to?(:name)
+        candidates.any? { |c| names.include?(c.to_s) }
+      end
+
       def build_arel(connection_or_aliases = nil, aliases = nil)
         requirement = Gem::Requirement.new('>= 7.2', '< 8.1')
 
@@ -184,6 +302,7 @@ module CoreExtensions
           arel = super(connection_or_aliases)
         end
 
+        mark_final_joins!(arel) if joins_final_values.present?
         arel.final! if final_value
         arel.limit_by(*@values[:limit_by]) if @values[:limit_by].present?
         arel.settings(settings_values) unless settings_values.empty?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: clickhouse-activerecord
 version: !ruby/object:Gem::Version
-  version: 1.6.7
+  version: 1.7.0
 platform: ruby
 authors:
 - Sergey Odintsov
@@ -96,12 +96,14 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- bin/test-single
 - clickhouse-activerecord.gemspec
 - lib/active_record/connection_adapters/clickhouse/column.rb
 - lib/active_record/connection_adapters/clickhouse/oid/array.rb
 - lib/active_record/connection_adapters/clickhouse/oid/big_integer.rb
 - lib/active_record/connection_adapters/clickhouse/oid/date.rb
 - lib/active_record/connection_adapters/clickhouse/oid/date_time.rb
+- lib/active_record/connection_adapters/clickhouse/oid/json.rb
 - lib/active_record/connection_adapters/clickhouse/oid/map.rb
 - lib/active_record/connection_adapters/clickhouse/oid/uuid.rb
 - lib/active_record/connection_adapters/clickhouse/quoting.rb
@@ -113,6 +115,7 @@ files:
 - lib/active_record/connection_adapters/clickhouse/table_definition.rb
 - lib/active_record/connection_adapters/clickhouse_adapter.rb
 - lib/arel/nodes/final.rb
+- lib/arel/nodes/final_table.rb
 - lib/arel/nodes/grouping_sets.rb
 - lib/arel/nodes/limit_by.rb
 - lib/arel/nodes/settings.rb
@@ -153,7 +156,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.9
 specification_version: 4
 summary: ClickHouse ActiveRecord
 test_files: []