Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/uptrace/go-clickhouse
Golang ClickHouse client
https://github.com/uptrace/go-clickhouse
clickhouse database go golang
Last synced: 30 days ago
JSON representation
Golang ClickHouse client
- Host: GitHub
- URL: https://github.com/uptrace/go-clickhouse
- Owner: uptrace
- License: bsd-2-clause
- Created: 2022-01-23T07:35:31.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-02-29T16:28:34.000Z (10 months ago)
- Last Synced: 2024-08-03T18:19:46.390Z (4 months ago)
- Topics: clickhouse, database, go, golang
- Language: Go
- Homepage: https://clickhouse.uptrace.dev
- Size: 823 KB
- Stars: 248
- Watchers: 6
- Forks: 26
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-clickhouse - uptrace/go-clickhouse - Golang ClickHouse client providing a native protocol interface and an API compatible with database/sql. (Language bindings / Golang)
README
# ClickHouse client for Go 1.18+
[](https://github.com/uptrace/go-clickhouse/actions)
[](https://pkg.go.dev/github.com/go-clickhouse/ch)
[](https://clickhouse.uptrace.dev/)
[](https://discord.gg/rWtp5Aj)
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](https://github.com/uptrace/bun/)-like query builder.
- [Selecting](https://clickhouse.uptrace.dev/guide/clickhouse-select.html) 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](https://clickhouse.uptrace.dev/guide/clickhouse-migrations.html).
- [OpenTelemetry](https://clickhouse.uptrace.dev/guide/clickhouse-monitoring-performance.html)
support.
- In production at [Uptrace](https://github.com/uptrace/uptrace)
Resources:
- [**Get started**](https://clickhouse.uptrace.dev/guide/getting-started.html)
- [Examples](https://github.com/uptrace/go-clickhouse/tree/master/example)
- [Discussions](https://github.com/uptrace/go-clickhouse/discussions)
- [Chat](https://discord.gg/rWtp5Aj)
- [Reference](https://pkg.go.dev/github.com/uptrace/go-clickhouse/ch)
- [Example app](https://github.com/uptrace/uptrace)
## Benchmark
**Read** (best of 3 runs):
| Library | Timing |
| ------------------------------------------------------------------------------------------------------------------ | ------ |
| [This library](example/benchmark/read-native/main.go) | 655ms |
| [ClickHouse/clickhouse-go](https://github.com/ClickHouse/clickhouse-go/blob/main/benchmark/v2/read-native/main.go) | 849ms |
**Write** (best of 3 runs):
| Library | Timing |
| ---------------------------------------------------------------------------------------------------------------------------- | ------ |
| [This library](example/benchmark/write-native-columnar/main.go) | 475ms |
| [ClickHouse/clickhouse-go](https://github.com/ClickHouse/clickhouse-go/blob/main/benchmark/v2/write-native-columnar/main.go) | 881ms |
## Installation
```shell
go get github.com/uptrace/go-clickhouse@latest
```
## Example
A [basic](example/basic) example:
```go
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](https://github.com/uptrace/bun) for PostgreSQL, MySQL, MSSQL, and SQLite
- [Golang PostgreSQL](https://bun.uptrace.dev/postgres/)
- [Golang HTTP router](https://github.com/uptrace/bunrouter)