Add support to configure connection options - #71
Merged
Conversation
Collaborator
|
Your test fix is merged so this just needs a rebase. |
koletzilla
force-pushed
the
clickhouse-connection-options
branch
from
August 31, 2026 09:41
f27a45b to
621893a
Compare
koletzilla
marked this pull request as ready for review
August 31, 2026 10:19
Contributor
Author
|
Rebase done! |
abonander
approved these changes
Aug 31, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Before this change, the driver only accepted a fixed list of options. There was no way to set
general ClickHouse settings like
mutations_sync,alter_syncorinsert_quorum, whichclients often need to pin for correctness.
This PR adds two ways to pass any ClickHouse setting:
1. A passthrough option key:
It can be set on
ClickhouseDatabase,ClickhouseConnectionandClickhouseStatement. Thevalue propagates to objects created lower in the hierarchy, and lower levels can override it —
the same model as
clickhouse.client.product_info. Values can be read back withget_option_string().2. Query parameters in the connection URI:
Every URI query parameter (except the existing
protocolpseudo-parameter) is treated as asetting, exactly as if it were set with the option key above. Previously these parameters were
silently dropped. This helps ADBC consumers that can only pass a URI string.
Internally both map directly to the
clickhouse-rsclient:Client::set_setting(name, value).The client then sends the setting as a URL query parameter on every request, which is the native
way to carry "connection settings" over the ClickHouse HTTP interface (there is no server-side
connection state).
Usage example
Decisions taken
SetOption(key, value)string pairs; there is no"pass a map" call. Encoding the setting name in a namespaced key is the standard ADBC pattern
for open-ended option families (e.g. Flight SQL's
adbc.flight.sql.rpc.call_header.<name>).settings travel anyway (text query parameters). Int/double support can be added later without
breaking anything.
ClickhouseDatabaseholds no client, so its settings arestored and replayed when a connection is created, before the per-connection options are
applied, which is what makes lower levels win.
setting", in whichever order they are set. A
protocolparameter on anhttp(s)://URL isnow rejected with
InvalidArguments(it is only meaningful forclickhouse://rewriting;before, it was silently carried and dropped).
clickhouse-rsdropped them at request time, so they never worked). Now they are folded intothe settings map instead;
test_set_uriexpectations were updated.NotFound; an empty setting name(
"clickhouse.setting.") is rejected withInvalidArguments.clickhouse.client.*options is allowed.clickhouse.setting.session_idwrites the same client state as
clickhouse.client.session_id; last write wins. Note thatquery_idis regenerated for every new statement, so setting it higher up has no effect.This is documented on
SETTING_PREFIX.ClickhouseConnection::get_option_string()is now implemented (it was blanketNotImplemented). This also fixes an existing gap: theSESSION_IDdocs promised read-backthat was never implemented.
strip_prefixearly return instead of a match guard, becauseif-let match guards are not stable on the pinned Rust 1.91.0 toolchain.
Note for #67 (default database)
?database=xin the URI now folds like any other parameter and works through the HTTPinterface's
databasequery parameter. If a dedicated default-database feature (#67) landslater, it should take ownership of the
databaseparameter sPossible future changes
clickhouse.client.*options through the same internal path. They already share the same underlying client state; the per-key match arms could become a small alias table. Kept out of this PR to stay minimal.