Add configurable HTTP auth modes for ClickHouse requests (#240)

* Add configurable HTTP auth modes

Keeps the current behavior as default,
sending user and password as URL parameters.

Accept http_auth config with x_clickhouse_headers or basic options
- basic` sends `Authorization: Basic ...` and keeps `database` in URL params.
- x_clickhouse_headers` sends `X-ClickHouse-User`, `X-ClickHouse-Key`, and `X-ClickHouse-Database` headers.

* Add explicit query_params http_auth mode

It documents and validates all supported modes to reduce ambiguity

* Improve local single-spec workflow

Fix console loading and add helper/docs to run single adapter tests consistently

Author: ottony

README.md

@@ -28,6 +28,7 @@ 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
@@ -53,6 +54,28 @@ 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`).
+
 ## Usage in Rails
 
 Add your `database.yml` connection information with postfix `_clickhouse` for you environment:
@@ -343,6 +366,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:

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.

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 "$@"

lib/active_record/connection_adapters/clickhouse/schema_statements.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
+require 'base64'
 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
 
         def with_settings(**settings)
           @block_settings ||= {}
@@ -61,10 +66,7 @@ def execute_to_file(sql, name = nil, format: @response_format, settings: {})
               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)
@@ -303,8 +305,7 @@ def request(statement, settings: {}, except_params: [])
           @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
 
@@ -316,12 +317,41 @@ def log_with_debug(sql, name = nil)
         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?

lib/active_record/connection_adapters/clickhouse_adapter.rb

@@ -32,6 +32,13 @@ def clickhouse_connection(config)
           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
@@ -143,6 +150,7 @@ def initialize(config_or_deprecated_connection, deprecated_logger = nil, depreca
         @connection_config = { user: @config[:username], password: @config[:password], database: @config[:database] }.compact
         @debug = @config[:debug] || false
         @response_format = @config[:format] || DEFAULT_RESPONSE_FORMAT
+        @http_auth = @config[:http_auth]&.to_sym
 
         @prepared_statements = false