doc(go-client): add per config detail config reference page#6004
Draft
doc(go-client): add per config detail config reference page#6004
Conversation
This config reference covers every single config/tweaks a user can make in clickhouse-go client along with 1. What it is? 2. What's the default value? 3. What's the recommended value? 4. What are the ways we can override these configs 5. What are the symptoms if those are configured in-correctly Signed-off-by: Kaviraj <kavirajkanagaraj@gmail.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
4 Skipped Deployments
|
Signed-off-by: Kaviraj <kavirajkanagaraj@gmail.com>
Signed-off-by: Kaviraj <kavirajkanagaraj@gmail.com>
Signed-off-by: Kaviraj <kavirajkanagaraj@gmail.com>
peter-leonov-ch
approved these changes
Apr 10, 2026
Contributor
peter-leonov-ch
left a comment
peter-leonov-ch
left a comment
There was a problem hiding this comment.
My Clause suggests:
- Add a "Version Compatibility" section for version-specific features
- Expand explanation of "per block" timeout behavior for ReadTimeout
- Consider adding a visual diagram for HTTP two-layer pooling
- Add memory calculation examples for buffer sizing
mshustov
reviewed
Apr 13, 2026
| |-------|-----------|----------| | ||
| | **Connection** | `clickhouse.Options` struct or DSN string | All queries on the connection | | ||
| | **Query** | `clickhouse.Context()` with `WithXxx` functions | Single query execution | | ||
| | **Batch** | `PrepareBatch()` option functions | Single batch operation | |
Member
There was a problem hiding this comment.
Should we call out which one takes precedence?
|
|
||
| | Option | Type | Default | DSN param | Description | Best practice | When misconfigured | | ||
| |--------|------|---------|-----------|-------------|---------------|-------------------| | ||
| | `Protocol` | `Protocol` (int) | `Native` | Scheme: `clickhouse://`=Native, `http://`=HTTP | Communication protocol: `Native` (0) for TCP, `HTTP` (1) for HTTP | Use Native for ~30% better performance. Use HTTP for proxy support, firewall traversal (port 80/443), or HTTP-only compression (`gzip`/`br`). See [TCP vs HTTP](/integrations/language-clients/go/configuration#tcp-vs-http). | HTTP scheme with Native port (9000): connection refused. Native blocked by firewall: timeouts. | |
Member
There was a problem hiding this comment.
The current structure works well for AI agents. @Blargian
I’d like to know your recommendations for improving readability for both human and AI agents.
Probably, we should follow the same pattern that Core uses ? https://clickhouse.com/docs/operations/server-configuration-parameters/settings
Member
There was a problem hiding this comment.
From what I've read agents process markdown tables just as well. I find them more readable for humans too, but could just be a personal preference.
| | `Auth.Username` | `string` | `"default"` | `username` or URL user portion | Username for ClickHouse authentication | Never use `default` in production. Create dedicated users with minimal permissions. | Wrong username: `"Code: 516. DB::Exception: Authentication failed"`. Empty string: silently uses `"default"`. | | ||
| | `Auth.Password` | `string` | `""` | `password` or URL password portion | Password for ClickHouse authentication | Use env vars or secret managers in production. URL-encode special characters in DSN. | Wrong password: `"Code: 516. DB::Exception: Authentication failed"`. Special chars not URL-encoded: parsing errors. | | ||
| | `Auth.Database` | `string` | `""` (server default) | `database` or URL path (`/mydb`) | Default database for the connection | Always specify explicitly. Use dedicated databases per application in production. | Non-existent: `"Code: 81. DB::Exception: Database xyz doesn't exist"`. Empty in multi-tenant setup: queries hit wrong database. | | ||
| | `GetJWT` | `func(ctx) (string, error)` | `nil` | — (programmatic only) | Callback returning JWT for ClickHouse Cloud auth. Overridable per query with `WithJWT(token)`. | Implement token caching/refresh -- called per connection/request. | Expired token: auth errors. Blocking callback: timeouts. JWT takes precedence over user/pass. Requires TLS -- without it, falls back to user/pass silently. | |
Member
There was a problem hiding this comment.
For the recently introduced settings, it would be beneficial to include a client version when it was first added
|
|
||
| ### Timeouts {#timeouts} | ||
|
|
||
| | Option | Type | Default | DSN param | Description | Best practice | When misconfigured | |
Member
There was a problem hiding this comment.
❤️ to this when misconfigured section
| | Option | Type | Default | DSN param | Description | Best practice | When misconfigured | | ||
| |--------|------|---------|-----------|-------------|---------------|-------------------| | ||
| | `DialTimeout` | `time.Duration` | `30s` | `dial_timeout` | Max time to establish a new connection. Also controls pool acquisition wait when `MaxOpenConns` is reached. | 5-10s on LAN, 15-30s on WAN/cloud. Never below 1s. | Too short: `"clickhouse: acquire conn timeout"` during congestion. Too long (> 60s): app hangs during outages. | | ||
| | `ReadTimeout` | `time.Duration` | `5m` (300s) | `read_timeout` | Max time to wait for a server response per read call. Applied per block, not entire query. Context deadline takes precedence. | 10-30s for OLTP, 5-30m for OLAP/long queries. | Too short: `"i/o timeout"` or `"read: connection reset by peer"` mid-query; server continues executing. Too long: dead connections not detected. | |
|
|
||
| ### HTTP-specific {#http-specific} | ||
|
|
||
| These options only affect `Protocol: clickhouse.HTTP`. Silently ignored for Native. |
Member
There was a problem hiding this comment.
Should it be wrapped as a warning?
| ```go | ||
| Settings: clickhouse.Settings{ | ||
| "max_execution_time": 60, // important -- errors if unknown | ||
| "my_custom_setting": clickhouse.CustomSetting{Value: "value"}, // custom -- ignored if unknown |
|
|
||
| ## Quick reference tables {#quick-reference-tables} | ||
|
|
||
| ### Connection pool sizing {#pool-sizing} |
Member
There was a problem hiding this comment.
Suggested change
| ### Connection pool sizing {#pool-sizing} | |
| ### Connection pool sizing recommendations {#pool-sizing} |
|
|
||
| **Cause:** Connection pool exhausted -- all `MaxOpenConns` connections are in use and none became available within `DialTimeout`. | ||
|
|
||
| **Fix:** |
Member
There was a problem hiding this comment.
Should one take each step one-by-one or do it all at once?
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
4 participants
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
This config reference covers every single config/tweaks a user can make in clickhouse-go client along with
Checklist