Connect ClickHouse with Golang

After reading this blog, you will be able to connect to the locally installed ClickHouse, create a new database, and create a table in it.

ClickHouse is a free and open-source column-oriented database management system (DBMS). It was developed by Yandex and was released as an open-source project in 2016. Since then it has gained popularity due to its speed, scalability, and flexibility. It is used by industry-leading companies like Uber, Cloudflare, Comcast, eBay, and Cisco for different use cases.

teamwork, cooperation, brainstorming-3213924.jpg


Start the ClickHouse server locally. Quick start link. With the help of this quick start guide, You can start both the Clickhouse server and the client locally. I am using ClickHouse version 22.10.1

ClickHouse Client is a command-line interface (CLI) that allows users to interact with the ClickHouse Server. ClickHouse Server is the backend component of the system that stores and manages the data. It is responsible for executing queries and returning results to clients.

Go version should be above 1.17

Initialize a module

mkdir clickhouse-golang-example
cd clickhouse-golang-example
go mod init clickhouse-golang-example

How to connect to ClickHouse

ClickHouse has two Go clients. They support different use cases.

  • clickhouse-go – It is a High-level language client. It supports either the Go standard database/sql interface or the native interface. This is useful for query workloads focused on aggregations or lower throughput insert workloads.
  • ch-go –  It is a Low-level client. It is used for insert heavy use cases, where millions of inserts are required per second.

You will use clickhouse-go v2 for this example as v1 is deprecated. To install the 2.x version of the client, add the package to your go.mod file:

require main

Run go mod tidy‚Äč

go mod tidy

Paste the following code in the main.go

	conn, err := clickhouse.Open(&clickhouse.Options{
		Addr: []string{""},
	if err != nil {

This code will help you connect to ClickHouse on the 9000 port and ping the server. If there is no error in connection, it will print the server version.

You can also connect multiple ClickHouse servers (ClickHouse Cluster), by passing comma-separated list of single address hosts with port. This helps in load-balancing and failover

hosts:= []string{"","",""}
conn, err := clickhouse.Open(&clickhouse.Options{
        Addr: []string{""},
if err != nil {

Create the database with Golang

Now we will create a new database ClickHouse

conn.Exec(context.Background(), "CREATE DATABASE IF NOT EXISTS hello")

Similarly, you can create the table in the database.

conn.Exec(context.Background(), `CREATE TABLE hello.example
		id UInt64,
		name String
	ENGINE = MergeTree

You can verify the table creation with the ClickHouse client.

verifying with the ClickHouse client

You can get the complete code here.

Congratulations, you are successfully able to connect to ClickHouse with Golang.

I am planning to use ClickHouse for one of my projects for activity timeline use. If you have any ClickHouse experience, share that in the comment.

For more such content, consider subscribing blogyourcode. Happy Coding!!!


Leave a Reply