ConnectionTimeout and CommandTimeout

Connect-phase budget and per-statement query timeout.

Category: connection-string

Syntax

ConnectionTimeout=<seconds>;CommandTimeout=<seconds>

Description

## ConnectionTimeout Wraps the entire connect path: name resolution, the network handshake, authentication, and the first request that establishes the data path. If any of these collectively exceed the budget, the connect fails with `08001 connection timeout` and the diagnostic chain identifies which sub-step ran out of time. The default of 10 seconds is enough for a warm deployment on a healthy network. Cold-start warehouses (where the compute node spins up on demand) routinely need 30 to 60 seconds; bump `ConnectionTimeout=` accordingly. The ODBC API also exposes a per-handle override: `SQLSetConnectAttr(SQL_ATTR_LOGIN_TIMEOUT, <seconds>, 0)` called before `SQLDriverConnect` wins over the connection-string value. BI tools use this attribute to surface a settings UI for the connect timeout. ## CommandTimeout A default for `SQL_ATTR_QUERY_TIMEOUT` on every new statement allocated against this connection. `0` (the default) means "no client-side timeout"; queries run as long as the engine allows. Setting a positive value caps every statement at that many seconds; on expiry the driver cancels the in-flight request and returns `HYT00 Operation timed out`. The application can override per-statement via `SQLSetStmtAttr(stmt, SQL_ATTR_QUERY_TIMEOUT, <seconds>, 0)`. The most-recently-set value wins. ## Aliases | External key | Maps to | |---|---| | `LoginTimeout` | `ConnectionTimeout` | | `Connect Timeout` | `ConnectionTimeout` | | `QueryTimeout` | `CommandTimeout` | ## Tuning recommendations - For interactive BI tooling, leave `CommandTimeout=0` so the user can run long-form analytical queries. - For ETL connections, set `CommandTimeout=` to the SLA on the slowest expected statement plus a safety margin. Cancellation is preferable to a hung pipeline. - For cold-start warehouses, set `ConnectionTimeout=60` or higher. The cost is paid only on the connect, not on subsequent statements.

Parameters

Name	Type	Description
`ConnectionTimeout`		Total budget in seconds for the connect phase: DNS, TCP handshake, TLS, and the auth round-trip. Aliases: `LoginTimeout`. Forwarded to the underlying HTTP client as the connect timeout.
`CommandTimeout`		Default `SQL_ATTR_QUERY_TIMEOUT` for new statements, in seconds. `0` (the default) means no per-statement timeout. The application can override via `SQLSetStmtAttr`.

Examples

# Cold-start warehouses need a longer connect budget
ConnectionTimeout=60

# Cap every statement on this connection at 5 minutes
CommandTimeout=300

# SQL Server vocabulary is also accepted
LoginTimeout=30

Pitfalls

`CommandTimeout=` is a default. Once a BI tool calls `SQLSetStmtAttr(SQL_ATTR_QUERY_TIMEOUT, ...)` it overrides the default for that statement. To force a hard cap, set both the connection-string default and ensure the application does not override it.
A `ConnectionTimeout=0` is interpreted as "no timeout" and can hang indefinitely on a misconfigured `Server=` URL. Prefer a finite default.
The connect timeout does not include retry budget: if the auth provider returns a transient 5xx and the driver retries, each retry has its own budget. The wall-clock connect time can exceed `ConnectionTimeout` slightly for retried connects.