{"id":13695630,"url":"https://github.com/vahid-sohrabloo/chconn","last_synced_at":"2026-01-30T01:47:02.512Z","repository":{"id":37511646,"uuid":"244838756","full_name":"vahid-sohrabloo/chconn","owner":"vahid-sohrabloo","description":"Low-level ClickHouse database driver for Golang","archived":false,"fork":false,"pushed_at":"2024-05-21T13:53:27.000Z","size":1275,"stargazers_count":148,"open_issues_count":8,"forks_count":11,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-08-03T18:19:47.618Z","etag":null,"topics":["clickhouse","fast","go","golang","tcp"],"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/vahid-sohrabloo.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2020-03-04T07:48:52.000Z","updated_at":"2024-05-20T07:17:10.000Z","dependencies_parsed_at":"2023-02-15T07:45:32.664Z","dependency_job_id":"9d0b3efc-0280-42ff-960a-59b012f9309f","html_url":"https://github.com/vahid-sohrabloo/chconn","commit_stats":{"total_commits":150,"total_committers":4,"mean_commits":37.5,"dds":"0.17333333333333334","last_synced_commit":"519075190b8387f8fe148b6f2a647d82e7e1fc59"},"previous_names":["vahid-sohrabloo/chpool"],"tags_count":73,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vahid-sohrabloo%2Fchconn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vahid-sohrabloo%2Fchconn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vahid-sohrabloo%2Fchconn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vahid-sohrabloo%2Fchconn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vahid-sohrabloo","download_url":"https://codeload.github.com/vahid-sohrabloo/chconn/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224364341,"owners_count":17299052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","fast","go","golang","tcp"],"created_at":"2024-08-02T18:00:31.361Z","updated_at":"2026-01-08T11:08:17.275Z","avatar_url":"https://github.com/vahid-sohrabloo.png","language":"Go","funding_links":[],"categories":["Language bindings"],"sub_categories":["Golang"],"readme":"[![Go Reference](https://pkg.go.dev/badge/github.com/vahid-sohrabloo/chconn/v2.svg)](https://pkg.go.dev/github.com/vahid-sohrabloo/chconn/v2)\n[![codecov](https://codecov.io/gh/vahid-sohrabloo/chconn/branch/master/graph/badge.svg?token=K3JN6XWFVV)](https://codecov.io/gh/vahid-sohrabloo/chconn)\n[![Go Report Card](https://goreportcard.com/badge/github.com/vahid-sohrabloo/chconn/v2)](https://goreportcard.com/report/github.com/vahid-sohrabloo/chconn/v2)\n[![Actions Status](https://github.com/vahid-sohrabloo/chconn/workflows/CI/badge.svg)](https://github.com/vahid-sohrabloo/chconn/actions)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fvahid-sohrabloo%2Fchconn.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fvahid-sohrabloo%2Fchconn?ref=badge_shield)\n\n# chconn - ClickHouse low level Driver\n\nchconn is a pure generic Go (1.18+) driver for [ClickHouse](https://clickhouse.com/) that use Native protocol\nchconn aims to be low-level, fast, and performant.\n\nFor comparison with other libraries, please see https://github.com/vahid-sohrabloo/go-ch-benchmark and https://github.com/go-faster/ch-bench#benchmarks\n\nIf you have any suggestion or comment, please feel free to open an issue\n\n## Example Usage\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"os\"\n\t\"time\"\n\n\t\"github.com/vahid-sohrabloo/chconn/v2/chpool\"\n\t\"github.com/vahid-sohrabloo/chconn/v2/column\"\n)\n\nfunc main() {\n\tconn, err := chpool.New(os.Getenv(\"DATABASE_URL\"))\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tdefer conn.Close()\n\n\t// to check if the connection is alive\n\terr = conn.Ping(context.Background())\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\terr = conn.Exec(context.Background(), `DROP TABLE IF EXISTS example_table`)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\terr = conn.Exec(context.Background(), `CREATE TABLE  example_table (\n\t\tuint64 UInt64,\n\t\tuint64_nullable Nullable(UInt64)\n\t) Engine=Memory`)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tcol1 := column.New[uint64]()\n\tcol2 := column.New[uint64]().Nullable()\n\trows := 1_000_0000 // Ten million rows - insert in 10 times\n\tnumInsert := 10\n\tcol1.SetWriteBufferSize(rows)\n\tcol2.SetWriteBufferSize(rows)\n\tstartInsert := time.Now()\n\tfor i := 0; i \u003c numInsert; i++ {\n\t\tfor y := 0; y \u003c rows; y++ {\n\t\t\tcol1.Append(uint64(i))\n\t\t\tif i%2 == 0 {\n\t\t\t\tcol2.Append(uint64(i))\n\t\t\t} else {\n\t\t\t\tcol2.AppendNil()\n\t\t\t}\n\t\t}\n\n\t\tctxInsert, cancelInsert := context.WithTimeout(context.Background(), time.Second*30)\n\t\t// insert data\n\t\terr = conn.Insert(ctxInsert, \"INSERT INTO example_table (uint64,uint64_nullable) VALUES\", col1, col2)\n\t\tif err != nil {\n\t\t\tcancelInsert()\n\t\t\tpanic(err)\n\t\t}\n\t\tcancelInsert()\n\t}\n\tfmt.Println(\"inserted 10M rows in \", time.Since(startInsert))\n\n\t// select data\n\tcol1Read := column.New[uint64]()\n\tcol2Read := column.New[uint64]().Nullable()\n\n\tctxSelect, cancelSelect := context.WithTimeout(context.Background(), time.Second*30)\n\tdefer cancelSelect()\n\n\tstartSelect := time.Now()\n\tselectStmt, err := conn.Select(ctxSelect, \"SELECT uint64,uint64_nullable FROM  example_table\", col1Read, col2Read)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\t// make sure the stmt close after select. but it's not necessary\n\tdefer selectStmt.Close()\n\n\tvar col1Data []uint64\n\tvar col2DataNil []bool\n\tvar col2Data []uint64\n\t// read data block by block\n\t// for more information about block, see: https://clickhouse.com/docs/en/development/architecture/#block\n\tfor selectStmt.Next() {\n\t\tcol1Data = col1Data[:0]\n\t\tcol1Data = col1Read.Read(col1Data)\n\n\t\tcol2DataNil = col2DataNil[:0]\n\t\tcol2DataNil = col2Read.ReadNil(col2DataNil)\n\n\t\tcol2Data = col2Data[:0]\n\t\tcol2Data = col2Read.Read(col2Data)\n\t}\n\n\t// check errors\n\tif selectStmt.Err() != nil {\n\t\tpanic(selectStmt.Err())\n\t}\n\tfmt.Println(\"selected 10M rows in \", time.Since(startSelect))\n}\n```\n```\ninserted 10M rows in  1.206666188s\nselected 10M rows in  880.505004ms\n```\n\n\n**For moe information**, please see the [documentation](https://github.com/vahid-sohrabloo/chconn/wiki)\n## Features\n*   Generics (go1.18) for column types\n*   Connection pool with after-connect hook for arbitrary connection setup similar to pgx (thanks @jackc)\n*   Support DSN and Query connection string  (thanks @jackc)\n*   Support All ClickHouse data types\n*   Read and write data in column-oriented (like ClickHouse)\n*   Do not use `interface{}` , `reflect`\n*   Batch select and insert\n*   Full TLS connection control\n*   Read raw binary data\n*   Supports profile and progress \n*   database url connection very like pgx (thanks @jackc)\n*   Code generator for Insert\n*   Support LZ4 and ZSTD compression protocol\n*   Support execution telemetry streaming profiles and progress\n\n## Supported types\n*   UInt8, UInt16, UInt32, UInt64, UInt128, UInt256\n*   Int8, Int16, Int32, Int64, Int128, Int256\n*   Date, Date32, DateTime, DateTime64\n*   Decimal32, Decimal64, Decimal128, Decimal256\n*   IPv4, IPv6\n*   String, FixedString(N)\n*   UUID\n*   Array(T)\n*   Enums\n*   LowCardinality(T)\n*   Map(K, V)\n*   Tuple(T1, T2, ..., Tn)\n*   Nullable(T)\n*   Point, Ring, Polygon, MultiPolygon\n\n\n\n# Benchmarks\nthe source code of this benchmark here\nhttps://github.com/vahid-sohrabloo/go-ch-benchmark\n\n```\nname \\ time/op           chconn              chgo       go-clickhouse         uptrace\nTestSelect100MUint64-16   150ms             154ms \t       8019ms \t       3045ms \t\nTestSelect10MString-16    271ms \t    447ms \t        969ms \t        822ms \t\nTestInsert10M-16          198ms \t    514ms \t        561ms \t        304ms \t\n\nname \\ alloc/op          chconn              chgo       go-clickhouse         uptrace\nTestSelect100MUint64-16   111kB \t    262kB \t    3202443kB \t     800941kB \t\nTestSelect10MString-16   1.63MB \t   1.79MB \t    1626.51MB \t     241.03MB \t\nTestInsert10M-16         26.0MB \t  283.7MB \t     1680.4MB \t      240.2MB \t\n\nname \\ allocs/op         chconn              chgo       go-clickhouse         uptrace\nTestSelect100MUint64-16    35.0 \t   6683.0 \t  200030937.0 \t  100006069.0 \t\nTestSelect10MString-16     49.0 \t   1748.0 \t   30011991.0 \t   20001120.0 \t\nTestInsert10M-16           26.0 \t     80.0 \t        224.0 \t         50.0 \t\n```\n\n## License\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fvahid-sohrabloo%2Fchconn.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fvahid-sohrabloo%2Fchconn?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvahid-sohrabloo%2Fchconn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvahid-sohrabloo%2Fchconn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvahid-sohrabloo%2Fchconn/lists"}