{"id":26121520,"url":"https://github.com/mkbeh/xclick","last_synced_at":"2026-06-15T11:31:49.787Z","repository":{"id":281370740,"uuid":"895571796","full_name":"mkbeh/xclick","owner":"mkbeh","description":"library provides an API for working with ClickHouse, using clickhouse-go and integration with OpenTelemetry for tracing and metrics","archived":false,"fork":false,"pushed_at":"2025-11-19T19:34:47.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-19T21:13:29.759Z","etag":null,"topics":["clickhouse","clickhouse-client","clickhouse-go","client","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkbeh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-28T13:09:01.000Z","updated_at":"2025-11-19T19:34:20.000Z","dependencies_parsed_at":"2025-08-06T12:11:06.555Z","dependency_job_id":"18704dd5-a4c7-466d-908a-9bc1a57304ee","html_url":"https://github.com/mkbeh/xclick","commit_stats":null,"previous_names":["mkbeh/xclick"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/mkbeh/xclick","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkbeh%2Fxclick","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkbeh%2Fxclick/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkbeh%2Fxclick/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkbeh%2Fxclick/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkbeh","download_url":"https://codeload.github.com/mkbeh/xclick/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkbeh%2Fxclick/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34358714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clickhouse","clickhouse-client","clickhouse-go","client","go","golang"],"created_at":"2025-03-10T14:23:36.213Z","updated_at":"2026-06-15T11:31:49.782Z","avatar_url":"https://github.com/mkbeh.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xclick\n\n![Go Version](https://img.shields.io/badge/go-1.26+-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n\nGo client for ClickHouse with migrations, query builder, and observability.\n\nBuilt on top of [clickhouse-go](https://github.com/ClickHouse/clickhouse-go).\n\n## Features\n\n- **Query builder** — [squirrel](https://github.com/Masterminds/squirrel) with `$`-placeholder support out of the box\n- **Migrations** — via [golang-migrate](https://github.com/golang-migrate/migrate) using `embed.FS`\n- **Observability** — connection pool metrics exposed via Prometheus\n\n## Installation\n\n```bash\ngo get github.com/mkbeh/xclick\n```\n\n## Quick start\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n)\n\nfunc main() {\n\tcfg := \u0026clickhouse.Config{\n\t\tHosts:    \"127.0.0.1:9000\",\n\t\tUser:     \"user\",\n\t\tPassword: \"password\",\n\t\tDB:       \"mydb\",\n\t}\n\n\tpool, err := clickhouse.NewPool(\n\t\tclickhouse.WithConfig(cfg),\n\t\tclickhouse.WithClientID(\"my-service\"),\n\t)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer pool.Close()\n\n\tvar result string\n\tif err := pool.QueryRow(context.Background(), \"SELECT 'hello world'\").Scan(\u0026result); err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tfmt.Println(result)\n}\n\n```\n\nMore examples in [examples/](https://github.com/mkbeh/xclick/tree/main/examples).\n\n## Migrations\n\nCreate an `embed.go` file in your migrations directory:\n\n```go\npackage migrations\n\nimport \"embed\"\n\n//go:embed *.sql\nvar FS embed.FS\n```\n\nPass `FS` via `WithMigrations`:\n\n```go\npool, err := clickhouse.NewPool(\n    clickhouse.WithConfig(cfg),\n    clickhouse.WithMigrations(migrations.FS),\n)\n```\n\nMigrations are applied automatically on pool startup when `MigrateEnabled: true` is set in the config.\n\n### Additional migration connection args\n\nSet via `CLICKHOUSE_MIGRATE_ARGS` or the `MigrateArgs` config field:\n\n```\nx-multi-statement=true\nx-cluster-name=distributed_cluster\nx-migrations-table-engine=ReplicatedMergeTree\n```\n\n## Configuration\n\nAll parameters can be set via environment variables or directly in the `Config` struct.\n\n| ENV | Required | Default | Description |\n|-----|:--------:|:-------:|-------------|\n| `CLICKHOUSE_HOSTS` | ✓ | — | Comma-separated list of hosts: `host1:9000,host2:9000` |\n| `CLICKHOUSE_USER` | ✓ | — | Username |\n| `CLICKHOUSE_PASSWORD` | ✓ | — | Password |\n| `CLICKHOUSE_DB` | ✓ | — | Database name |\n| `CLICKHOUSE_SHARD_ID` | | `0` | Shard identifier |\n| `CLICKHOUSE_MAX_OPEN_CONNS` | | `32` | Max open connections |\n| `CLICKHOUSE_MAX_IDLE_CONNS` | | `8` | Max idle connections |\n| `CLICKHOUSE_CONN_MAX_LIFETIME` | | `1h` | Max connection lifetime |\n| `CLICKHOUSE_DIAL_TIMEOUT` | | `10s` | Connection dial timeout |\n| `CLICKHOUSE_READ_TIMEOUT` | | `10s` | Read timeout |\n| `CLICKHOUSE_CONN_OPEN_STRATEGY` | | `in_order` | Strategy: `in_order`, `round_robin`, `random` |\n| `CLICKHOUSE_BLOCK_BUFFER_SIZE` | | `2` | Block buffer size |\n| `CLICKHOUSE_MAX_COMPRESSION_BUFFER` | | `10 MiB` | Max compression buffer size |\n| `CLICKHOUSE_HTTP_HEADERS` | | — | Additional HTTP headers |\n| `CLICKHOUSE_HTTP_URL_PATH` | | — | Additional URL path for HTTP requests |\n| `CLICKHOUSE_DEBUG` | | `false` | Enable debug logging |\n| `CLICKHOUSE_FREE_BUFFER_ON_CONN_RELEASE` | | `false` | Free memory buffer after each query |\n| `CLICKHOUSE_INSECURE_SKIP_VERIFY` | | `false` | Skip TLS certificate verification |\n| `CLICKHOUSE_MIGRATE_ENABLED` | | `false` | Run migrations on startup |\n| `CLICKHOUSE_MIGRATE_ARGS` | | — | Extra connection string args for migrations |\n\n## Client options\n\n```go\nclickhouse.WithConfig(cfg)           // connection config\nclickhouse.WithClientID(\"name\")      // client identifier, used in metrics labels\nclickhouse.WithMigrations(fs)        // embed.FS containing SQL migration files\nclickhouse.WithLogger(logger)        // custom slog.Logger\nclickhouse.WithTLS(tlsCfg)           // TLS configuration\nclickhouse.WithCompression(c)        // compression settings\nclickhouse.WithHTTPProxy(proxyURL)   // HTTP proxy\nclickhouse.WithMetricsNamespace(ns)  // Prometheus metrics namespace\n```\n\n## License\n\n[MIT](LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkbeh%2Fxclick","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkbeh%2Fxclick","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkbeh%2Fxclick/lists"}