ClickHouse Go Driver: High-Performance Go Client

Connecting Go Applications to ClickHouse

The ClickHouse Go Driver is a Golang SQL database client for ClickHouse, published as github.com/ClickHouse/clickhouse-go/v2. It exposes two ways to connect: a ClickHouse-specific driver.Conn opened with clickhouse.Open, and a database/sql-compatible interface opened with clickhouse.OpenDB. Both work over native TCP or HTTP transport, and versions 2.3.0+ use the lower-level ch-go library for encoding and compression.

Core Capabilities and Advanced Features

• ✓Two connection interfaces in one package: clickhouse.Open returns a ClickHouse-specific driver.Conn for direct column encoding, and clickhouse.OpenDB returns a standard database/sql.DB for existing tooling and ORMs.
• ✓Native TCP and HTTP transport are both supported by either interface, so the same client can run through a proxy such as ChProxy or an HTTP load balancer without switching APIs.
• ✓Struct marshaling in both directions — ScanStruct/Select map query results into structs, and AppendStruct writes a struct back out as a row.
• ✓Connection pooling with configurable MaxOpenConns, MaxIdleConns, and ConnMaxLifetime, plus failover and load balancing across a host list using in_order, round_robin, or random strategies.
• ✓Compression covers LZ4, ZSTD, LZ4HC, GZIP, Deflate, and Brotli, with native block compression and HTTP web compression treated as separate, explicitly configurable layers.
• ✓Async insert through the WithAsync() helper, usable on both the native and database/sql interfaces, replacing the deprecated AsyncInsert() API.
• ✓Structured logging via Go's log/slog package, JWT authentication support, and context-based access to protocol features like query ID, quota key, OpenTelemetry, and execution progress events.

Getting Started with the Driver

Install it with `go get github.com/ClickHouse/clickhouse-go/v2` — that's the only install step the README documents; there's no separate CLI or config file to set up first. Go version support tracks the client's own release: versions 2.0-2.2 need Go 1.17/1.18, 2.3+ need 1.18.4+/1.19, 2.29+ support Go 1.21 through 1.24, and the newest listed range, 2.41+, needs Go 1.24 or 1.25, per the compatibility table in the README. Full documentation lives at clickhouse.com/docs/en/integrations/go.

Connecting and Querying Examples

Opening a native connection means building a clickhouse.Options struct — address, Auth (Database/Username/Password), and optionally Settings, Compression, and timeouts — then calling clickhouse.Open(&options) and conn.Ping(ctx) to confirm it's reachable: ```go conn, err := clickhouse.Open(&clickhouse.Options{ Addr: []string{"127.0.0.1:9000"}, Auth: clickhouse.Auth{ Database: "default", Username: "default", Password: "", }, }) if err != nil { return err } return conn.Ping(context.Background()) ``` For database/sql, clickhouse.OpenDB(&options) returns a *sql.DB you configure the normal way, with SetMaxIdleConns, SetMaxOpenConns, and SetConnMaxLifetime. A DSN string works too — `clickhouse://user:pass@host1:9000,host2:9000/database?dial_timeout=200ms&read_timeout=30s` — and query parameters like compress, secure, and connection_open_strategy map directly to Options fields. Bulk writes go through PrepareBatch on the native interface, or a begin→prepare→exec-in-loop→commit pattern with database/sql.

Choosing Between Native and `database/sql` Interfaces

Frequently Asked Questions

The problem it solves

Every Go application talking to ClickHouse has to pick a wire protocol and an API shape before writing the first query, and getting that choice wrong later costs real throughput or forces a rewrite. The README addresses this head-on with its own "Which interface should I use?" comparison table — a ClickHouse-specific driver.Conn for direct column encoding, or a database/sql-compatible driver for existing tooling — rather than shipping one generic SQL driver and leaving that trade-off for you to discover through a benchmark later.

Best use cases

• •Building a new Go service that writes to or queries ClickHouse and wants the fastest path — the README recommends the native driver.Conn interface with its direct column encoding when in doubt.
• •Adding ClickHouse to a codebase already built on database/sql tooling or an ORM, via clickhouse.OpenDB, without introducing a second driver-specific API.
• •Streaming bulk inserts or exports in the server's own format — QueryFormat/InsertFormat pass raw CSV, JSONEachRow, or Parquet straight through without the driver re-encoding it.
• •Connecting through an HTTP proxy or load balancer such as ChProxy, since the native format can travel over the HTTP transport as well as raw TCP.
• •Running async, non-blocking inserts via WithAsync() in write-heavy pipelines that don't need each insert acknowledged before moving on.

Who should try it — and who should skip

Reach for the ClickHouse Go Driver if you're writing new Go code against ClickHouse and want direct access to native-protocol features — connection pooling, failover, compression choices, and the driver.Conn API — without routing through database/sql. Use the database/sql interface specifically, but keep the same driver, if you're bolting ClickHouse onto an existing database/sql-based codebase or ORM and are willing to trade some throughput for compatibility, per the project's own benchmark comparison. Skip the package entirely if you need a client in a language other than Go.

Related repositories