/go-clickhouse

Golang ClickHouse client

Primary LanguageGoBSD 2-Clause "Simplified" LicenseBSD-2-Clause

ClickHouse client for Go 1.18+

build workflow PkgGoDev Documentation Chat

This ClickHouse client uses native protocol to communicate with ClickHouse server and requires Go 1.18+ in order to use generics. This is not a database/sql driver, but the API is compatible.

Main features are:

  • ClickHouse native protocol support and efficient column-oriented design.
  • API compatible with database/sql.
  • Bun-like query builder.
  • Selecting into scalars, structs, maps, slices of maps/structs/scalars.
  • Date, DateTime, and DateTime64.
  • Array(T) including nested arrays.
  • Enums and LowCardinality(String).
  • Nullable(T) except Nullable(Array(T)).
  • Migrations.
  • OpenTelemetry support.
  • In production at Uptrace

Resources:

Benchmark

Read (best of 3 runs):

Library Timing
This library 655ms
ClickHouse/clickhouse-go 849ms

Write (best of 3 runs):

Library Timing
This library 475ms
ClickHouse/clickhouse-go 881ms

Installation

go get github.com/uptrace/go-clickhouse@latest

Example

A basic example:

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/uptrace/go-clickhouse/ch"
	"github.com/uptrace/go-clickhouse/chdebug"
)

type Model struct {
	ch.CHModel `ch:"partition:toYYYYMM(time)"`

	ID   uint64
	Text string    `ch:",lc"`
	Time time.Time `ch:",pk"`
}

func main() {
	ctx := context.Background()

	db := ch.Connect(ch.WithDatabase("test"))
	db.AddQueryHook(chdebug.NewQueryHook(chdebug.WithVerbose(true)))

	if err := db.Ping(ctx); err != nil {
		panic(err)
	}

	var num int
	if err := db.QueryRowContext(ctx, "SELECT 123").Scan(&num); err != nil {
		panic(err)
	}
	fmt.Println(num)

	if err := db.ResetModel(ctx, (*Model)(nil)); err != nil {
		panic(err)
	}

	src := &Model{ID: 1, Text: "hello", Time: time.Now()}
	if _, err := db.NewInsert().Model(src).Exec(ctx); err != nil {
		panic(err)
	}

	dest := new(Model)
	if err := db.NewSelect().Model(dest).Where("id = ?", src.ID).Limit(1).Scan(ctx); err != nil {
		panic(err)
	}
	fmt.Println(dest)
}

See also