ClickHouse Go

**Choosing an API:** Pick the ClickHouse API for maximum performance and the full feature set (progress callbacks, columnar inserts, rich type support). Pick `database/sql` when you need to integrate with ORMs or tools that expect a standard Go database interface.

**Choosing a transport:** TCP is faster and is the default. Switch to HTTP when your infrastructure requires it — for example, when connecting through an HTTP load balancer or proxy, or when you need HTTP-specific features like sessions with temporary tables, or additional compression algorithms (`gzip`, `deflate`, `br`).

Both APIs use the native binary encoding regardless of transport, so HTTP carries no serialization overhead.

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Native format TCP transport HTTP transport Bulk write Struct marshaling Compression Progress callbacks|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | ClickHouse API ✅ ✅ ✅ ✅ ✅ ✅ ✅|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | `database/sql` API ✅ ✅ ✅ ✅ ✅  | | | | | | | | | | | | | | | | | | | | | | | |

### Choosing a client[​](#choosing-a-client "Direct link to Choosing a client")

Selecting a client library depends on your usage patterns and need for optimal performance. For insert heavy use cases, where millions of inserts are required per second, we recommend using the low level client [ch-go](https://github.com/ClickHouse/ch-go). This client avoids the associated overhead of pivoting the data from a row-orientated format to columns, as the ClickHouse native format requires. Furthermore, it avoids any reflection or use of the `interface{}` (`any`) type to simplify usage.

For query workloads focused on aggregations or lower throughput insert workloads, the [clickhouse-go](https://github.com/ClickHouse/clickhouse-go) provides a familiar `database/sql` interface and more straightforward row semantics. You can also optionally use HTTP for the transport protocol and take advantage of helper functions to marshal rows to and from structs.

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Native format Native protocol HTTP protocol Row Orientated API Column Orientated API Type flexibility Compression Query Placeholders|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | clickhouse-go ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | ch-go ✅ ✅ ✅ ✅  | | | | | | | | | | | | | | | | | | | | | | | | | | |

## Installation[​](#installation "Direct link to Installation")

v1 of the driver is deprecated and won't reach feature updates or support for new ClickHouse types. You should migrate to v2, which offers superior performance.

To install the 2.x version of the client, add the package to your go.mod file:

`require github.com/ClickHouse/clickhouse-go/v2 main`

Or, clone the repository:

```
git clone --branch v2 https://github.com/clickhouse/clickhouse-go.git $GOPATH/src/github
```

To install another version, modify the path or the branch name accordingly.

```
mkdir my-clickhouse-app && cd my-clickhouse-app

cat > go.mod <<-END
  module my-clickhouse-app

  go 1.21

  require github.com/ClickHouse/clickhouse-go/v2 main
END

cat > main.go <<-END
  package main

  import (
    "fmt"
    "github.com/ClickHouse/clickhouse-go/v2"
  )

  func main() {
   conn, _ := clickhouse.Open(&clickhouse.Options{Addr: []string{"127.0.0.1:9000"}})
    v, _ := conn.ServerVersion()
    fmt.Println(v.String())
  }
END

go mod tidy
go run main.go
```

### Versioning[​](#versioning "Direct link to Versioning")

The client is released independently of ClickHouse. 2.x represents the current major under development. All versions of 2.x should be compatible with each other.

#### ClickHouse compatibility[​](#clickhouse-compatibility "Direct link to ClickHouse compatibility")

The client supports:

- All currently supported versions of ClickHouse as recorded [here](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md). As ClickHouse versions are no longer supported they're also no longer actively tested against client releases.
- All versions of ClickHouse 2 years from the release date of the client. Note only LTS versions are actively tested.

#### Golang compatibility[​](#golang-compatibility "Direct link to Golang compatibility")

|  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Client Version Golang Versions|  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | | => 2.0 <= 2.2 1.17, 1.18|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | >= 2.3, < 2.41 1.18+|  |  |  |  | | --- | --- | --- | --- | | >= 2.41 1.21+|  |  | | --- | --- | | >= 2.43 1.24+ | | | | | | | | | |

## Best practices[​](#best-practices "Direct link to Best practices")

- Utilize the ClickHouse API where possible, especially for primitive types. This avoids significant reflection and indirection.
- If reading large datasets, consider modifying the [`BlockBufferSize`](/docs/integrations/language-clients/go/configuration#connection-settings). This will increase the memory footprint but will mean more blocks can be decoded in parallel during row iteration. The default value of 2 is conservative and minimizes memory overhead. Higher values will mean more blocks in memory. This requires testing since different queries can produce different block sizes. It can therefore be set on a [query level](/docs/integrations/language-clients/go/clickhouse-api#using-context) via the Context.
- Be specific with your types when inserting data. While the client aims to be flexible, e.g., allowing strings to be parsed for UUIDs or IPs, this requires data validation and incurs a cost at insert time.
- Use column-oriented inserts where possible. Again these should be strongly typed, avoiding the need for the client to convert your values.
- Follow ClickHouse [recommendations](/docs/sql-reference/statements/insert-into#performance-considerations) for optimal insert performance.

## Next steps[​](#next-steps "Direct link to Next steps")

- [Configuration](/docs/integrations/language-clients/go/configuration) — connection settings, TLS, authentication, logging, compression
- [ClickHouse API](/docs/integrations/language-clients/go/clickhouse-api) — native Go API for queries and inserts
- [Database/SQL API](/docs/integrations/language-clients/go/database-sql-api) — standard `database/sql` interface
- [Data Types](/docs/integrations/language-clients/go/data-types) — Go type mappings and complex type support

- [Quickstart](#quick-start)
  - [Connection details](#connection-details)- [Initialize a module](#initialize-a-module)- [Copy in some sample code](#copy-in-some-sample-code)- [Run go mod tidy](#run-go-mod-tidy)- [Set your connection details](#set-your-connection-details)- [Run the example](#run-the-example)- [Learn more](#learn-more)- [Overview](#overview)
    - [Four ways to connect](#four-ways-to-connect)- [Choosing a client](#choosing-a-client)- [Installation](#installation)
      - [Versioning](#versioning)- [Best practices](#best-practices)- [Next steps](#next-steps)

Was this page helpful?