ClickHouse client for Go 1.18+
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
, andDateTime64
.Array(T)
including nested arrays.- Enums and
LowCardinality(String)
. Nullable(T)
exceptNullable(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
- Golang ORM for PostgreSQL, MySQL, MSSQL, and SQLite
- Golang PostgreSQL
- Golang HTTP router