clickhouse-activerecord 1.6.6 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df65d8d2275baa9381d84f764c7fd8761c473e84483c10f7bca49b3b6162764f
-  data.tar.gz: b90292432beebf3f4b511d7cbd62f0b41eed56b86350ec6766b89f93ec3d414f
+  metadata.gz: f10ee5755575ea64229e6242e4fc081565fa5c4455581d5eca6fa47f2a047ee9
+  data.tar.gz: '07713045794d44203e419e4935c3abbff43c6f1cf9b5e6ad660b6f7e1f12510b'
 SHA512:
-  metadata.gz: b94e4126d5e196dcd05fcce0799e4967517c4b62024e5f109d86ad5034268dc822c038233b6a0b33aca2be3cb9842480160ae24136c8293a18ad3b4de18ab670
-  data.tar.gz: 13229feeb4ba07c3676668fb76cff54fd6a18bb424e3ad6b4d29ccf794813548a76d1a90db43941fec233417393c9e556ce49e9cf5cda48dad4658640b8fe762
+  metadata.gz: 71d4af6e68d41395dfb924cb5f6dcf202a6d965a8ac49e55757586a544567cea8f60a094da4bdff7aefd438df216d85afb36518526159c750265794e66e4546b
+  data.tar.gz: 351ffc5dfd5acae7db007e28a88d5d2833d80b5dcaa9e35ba8b4a2612720bed9beda848a1d5e09559e79737f58055ea7236623af7b9436ee6f1346a2c9fd2e4e

data/.github/workflows/testing.yml

@@ -22,23 +22,23 @@ jobs:
       max-parallel: 1
       matrix:
         version:
-          - ruby: 2.7
-            rails: 7.1.3
           - ruby: 3.2
-            rails: 7.1.3
-          - ruby: 3.2
-            rails: 7.2.1
+            rails: 7.2.3
           - ruby: 3.2
             rails: 8.0.1
           - ruby: 3.2
             rails: 8.1
-        clickhouse: [ '24.6', '24.9', '25.10' ]
+          - ruby: 4.0
+            rails: 7.2.3
+          - ruby: 4.0
+            rails: 8.1
+        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.4.1
+        uses: hoverkraft-tech/compose-action@v2.5.0
         env:
           CLICKHOUSE_VERSION: ${{ matrix.clickhouse }}
         with:
@@ -71,23 +71,21 @@ jobs:
       max-parallel: 1
       matrix:
         version:
-          - ruby: 2.7
-            rails: 7.1.3
-          - ruby: 3.2
-            rails: 7.1.3
           - ruby: 3.2
             rails: 7.2.1
           - ruby: 3.2
             rails: 8.0.1
           - ruby: 3.2
             rails: 8.1
+          - ruby: 4.0
+            rails: 8.1
         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.4.1
+        uses: hoverkraft-tech/compose-action@v2.5.0
         env:
           CLICKHOUSE_VERSION: ${{ matrix.clickhouse }}
         with:

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+### 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
+
 ### Version 1.6.6 (Feb 16, 2026)
 
 * Fix error: EOFError (end of file reached)

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/clickhouse-activerecord.gemspec

@@ -28,5 +28,4 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.4'
-  spec.add_development_dependency 'pry', '~> 0.12'
 end

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)
@@ -78,23 +84,39 @@ module ActiveRecord
         def exec_insert(sql, name = nil, _binds = [], _pk = nil, _sequence_name = nil, returning: nil)
           new_sql = sql.sub(/ (DEFAULT )?VALUES/, " VALUES")
           with_response_format(nil) { execute(new_sql, name) }
-          true
+          nil
         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?