// the find
ClickHouse/clickhouse-go
Golang driver for ClickHouse
The official Go driver for ClickHouse, maintained by ClickHouse Inc. It offers two interfaces: a native columnar API that talks the ClickHouse TCP protocol directly, and a standard database/sql wrapper for teams that need ORM compatibility. If you're writing Go against ClickHouse, this is the driver — not a community option.
The native interface delegates encoding/decoding to ch-go, which means column-oriented wire format without extra allocation layers — the benchmark numbers (368ms native write vs 604ms sql write for the same workload) reflect real protocol efficiency, not microbenchmark tricks. The JSON column handling is unusually honest: it enforces a single serialization mode per batch at append time rather than silently coercing types and producing garbage on the server. Both TCP and HTTP transports are supported with identical APIs, which matters when you're behind ChProxy or a load balancer that can't pass TCP. The test suite hits a real ClickHouse instance rather than mocking the wire protocol, so the integration tests actually catch regressions.
The two-interface design (native vs database/sql) forces a decision at connection time that's hard to reverse — if you start with sql.Open for ORM compatibility and later need batch performance, you're rewriting call sites, not just swapping a config flag. The JSON column mode-locking behavior is correct but will surprise anyone migrating from a schema where string and object rows co-exist in the same INSERT; the error message tells you the type of the rejected row but not which row index, which makes bulk-insert debugging painful. Context cancellation behavior differs between TCP and HTTP transports in ways that aren't fully documented — the README warns that HTTP Flush is a no-op, but the broader cancellation semantics during long streaming queries require reading the source. Go version support policy is inconsistent: 2.29 re-added 1.21 support after 2.19-2.28 dropped it, suggesting the minimum version is driven by downstream pressure rather than a clear policy.