clickhouse-go

clickhouse-go is ClickHouse’s official Golang database driver, maintained by the ClickHouse team itself. It exposes two ways to talk to a ClickHouse server: a ClickHouse-specific driver.Conn interface (clickhouse.Open) that speaks the native wire protocol for maximum throughput, and a standard database/sql-compatible interface (clickhouse.OpenDB / sql.Open) for teams that want to reuse existing tooling, ORMs, and connection-pooling conventions.

Both interfaces work over TCP-native and HTTP transports, and the driver leans on ClickHouse’s own low-level ch-go client for column encoding, decoding, and compression. It covers the breadth of ClickHouse’s type system (including newer types like BFloat16, Dynamic, Variant, and geo types), supports bulk batch inserts, async inserts, connection pooling with failover/load balancing, structured logging via log/slog, JWT authentication, and OpenTelemetry-aware query context.

What You Get

• A native driver.Conn interface (clickhouse.Open) using ClickHouse’s binary wire protocol for the fastest column-oriented reads and writes
• A standard database/sql implementation (clickhouse.OpenDB) that works with existing Go database tooling, migration tools, and ORMs expecting the stdlib interface
• Bulk batch insert support (PrepareBatch) and async inserts for high-throughput ingestion workloads
• Connection pooling with configurable open strategies (in-order, round-robin, random) and automatic failover across multiple ClickHouse addresses
• Broad ClickHouse type coverage — Decimal, Map, Array, Tuple, Nested, JSON, geo types, BFloat16, Dynamic, and Variant — with struct scanning/marshaling helpers
• Structured logging via Go’s log/slog, JWT auth, LZ4/ZSTD/Brotli/GZIP compression, and OpenTelemetry-aware query context

Common Use Cases

• Powering analytics dashboards and reporting services that query ClickHouse directly from Go backends
• High-throughput event or log ingestion pipelines that batch-insert rows via the native protocol
• Migrating an existing database/sql-based Go service onto ClickHouse without rewriting its data-access layer
• Building internal tooling or CLIs that need typed access to ClickHouse-specific column types (JSON, geo, Dynamic/Variant)
• Streaming query results or inserts in raw formats (CSV, JSONEachRow, Parquet) over HTTP for interop with external systems

Under The Hood

Architecture

The driver is organized as a small set of layers rather than one monolithic client: the top-level clickhouse package exposes Open/OpenDB entry points that dispatch to one of two transport implementations — a native TCP path (conn.go, conn_pool.go, backed by an internal circular-queue connection pool with lifetime-based eviction) or an HTTP path (conn_http.go) — both implementing a shared internal transport interface so the rest of the driver is protocol-agnostic. Row/column encoding and the ClickHouse wire format live in lib/column and lib/proto, decoupled from connection handling, while lib/driver defines the public driver.Conn/driver.Batch contracts that both the native API and the database/sql adapter (clickhouse_std.go) implement against. This separation means the database/sql surface is a thin wrapper reusing the same dial/connect functions as the native client rather than a parallel implementation, so a change to the wire protocol only needs to happen once.

Tech Stack

Built on Go 1.25 with the toolchain pinned in go.mod. Column encoding, decoding, and compression delegate to ClickHouse’s own low-level ch-go library rather than reimplementing the wire format locally. Compression support spans LZ4, ZSTD, GZIP, Deflate, and Brotli (andybalholm/brotli). Integration tests spin up real ClickHouse instances via testcontainers-go and Docker Compose rather than mocks. Additional dependencies cover OpenTelemetry tracing (go.opentelemetry.io/otel), geo types (paulmach/orb), arbitrary-precision decimals (shopspring/decimal), and UUID generation (google/uuid).

Code Quality

The repository carries an extensive test suite — 259 _test.go files covering unit tests, benchmark tests, and fuzz tests (e.g. conn_http_errors_fuzz_test.go) built on testify assertions, alongside a tests/ directory of integration tests that run against live ClickHouse containers. CI (.github/workflows/) runs separate workflows for head-of-branch tests, ClickHouse Cloud tests, linting, and CodeQL static analysis, plus a docs-sync check that keeps the published documentation in step with the code. Error handling is explicit throughout, using sentinel errors.New values (ErrBatchInvalid, ErrConnectionClosed, etc.) and a typed OpError wrapper rather than bare error strings.

API Design The defining design choice is offering two API surfaces — a ClickHouse-native interface for performance-sensitive code and a database/sql-compatible one for drop-in use with existing Go tooling — built on the same underlying connection and encoding layers so neither is a second-class citizen. On top of that it exposes ClickHouse-specific ergonomics that a generic SQL driver wouldn’t: typed struct scanning/appending, batch-release-connection helpers, named/numeric/positional parameter binding, and direct support for ClickHouse’s more unusual types (Dynamic, Variant, LineString) without falling back to raw bytes.