Skip to content

docs: clarify DialTimeout and Cloud idle behavior #94

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify DialTimeout and Cloud idle behavior #94

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion integrations/language-clients/go/config-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,9 +101,15 @@ GetJWT: func(ctx context.Context) (string, error) {

| 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. |
| `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, 1-2m if connecting to an idled ClickHouse Cloud service. Never below 1s. | Too short: `"clickhouse: acquire conn timeout"` during congestion, or connection failure before an idled Cloud service finishes waking. 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 short interactive queries; 5-30m for long analytical queries. | Too short: `"i/o timeout"` or `"read: connection reset by peer"` mid-query; server continues executing. Too long: dead connections not detected. |

<Note title="ClickHouse Cloud idle services">
A ClickHouse Cloud service that has been idle is paused, and wakes on the first incoming connection. Wake-up typically takes a few tens of seconds, during which the dial blocks. If `DialTimeout` is lower than the wake time, the first query after an idle period fails with a dial timeout instead of running.

Set `DialTimeout` to `1m`–`2m` for clients that may be the first to reach an idled service. The tradeoff is slower failure detection during a real outage — dials block for the full timeout before erroring — so prefer scoping the higher timeout to the first connect, or use context deadlines on individual queries to cap end-to-end latency.
</Note>

---

### Connection pool {#connection-pool}
Expand Down
2 changes: 1 addition & 1 deletion integrations/language-clients/go/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ When opening a connection, an Options struct can be used to control client behav
| `Auth` | `Auth` | — | Authentication credentials (`Database`, `Username`, `Password`). See [Authentication](#authentication). |
| `TLS` | `*tls.Config` | `nil` | TLS configuration. A non-nil value enables TLS. See [TLS](#using-tls). |
| `DialContext` | `func(ctx, addr) (net.Conn, error)` | — | Custom dial function to control how TCP connections are established. |
| `DialTimeout` | `time.Duration` | `30s` | Maximum time to wait when opening a new connection. |
| `DialTimeout` | `time.Duration` | `30s` | Maximum time to wait when opening a new connection. Raise to `1m`–`2m` when connecting to a ClickHouse Cloud service that may be idle — see [Timeouts](/integrations/language-clients/go/config-reference#timeouts). |
| `MaxOpenConns` | `int` | `MaxIdleConns + 5` | Maximum number of connections open at any time. |
| `MaxIdleConns` | `int` | `5` | Number of idle connections to keep in the pool. |
| `ConnMaxLifetime` | `time.Duration` | `1h` | Maximum lifetime of a pooled connection. See [Connection pooling](#connection-pooling). |
Expand Down