{"id":13412406,"url":"https://github.com/ClickHouse/clickhouse-go","last_synced_at":"2025-03-14T18:31:24.160Z","repository":{"id":37402336,"uuid":"78678862","full_name":"ClickHouse/clickhouse-go","owner":"ClickHouse","description":"Golang driver for ClickHouse","archived":false,"fork":false,"pushed_at":"2025-03-12T02:29:22.000Z","size":4397,"stargazers_count":2992,"open_issues_count":87,"forks_count":577,"subscribers_count":58,"default_branch":"main","last_synced_at":"2025-03-14T14:43:12.906Z","etag":null,"topics":["analytics-database","clickhouse","database","golang","golang-driver","sql"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ClickHouse.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"2017-01-11T20:53:23.000Z","updated_at":"2025-03-14T07:42:30.000Z","dependencies_parsed_at":"2023-10-26T10:35:01.194Z","dependency_job_id":"b5b5b8aa-60c6-4431-b5b5-8c19f4b46fb2","html_url":"https://github.com/ClickHouse/clickhouse-go","commit_stats":{"total_commits":1180,"total_committers":184,"mean_commits":6.413043478260869,"dds":0.7652542372881356,"last_synced_commit":"e73451324119e377f822245eb2b7b821a1f25aff"},"previous_names":["kshvakov/clickhouse","kshvakov/clickhouse-go"],"tags_count":153,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fclickhouse-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClickHouse","download_url":"https://codeload.github.com/ClickHouse/clickhouse-go/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243625121,"owners_count":20321236,"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":["analytics-database","clickhouse","database","golang","golang-driver","sql"],"created_at":"2024-07-30T20:01:24.304Z","updated_at":"2025-03-14T18:31:23.615Z","avatar_url":"https://github.com/ClickHouse.png","language":"Go","readme":"# ClickHouse [![run-tests](https://github.com/ClickHouse/clickhouse-go/actions/workflows/run-tests.yml/badge.svg?branch=v2)](https://github.com/ClickHouse/clickhouse-go/actions/workflows/run-tests.yml) [![Go Reference](https://pkg.go.dev/badge/github.com/ClickHouse/clickhouse-go/v2.svg)](https://pkg.go.dev/github.com/ClickHouse/clickhouse-go/v2)\n\nGolang SQL database client for [ClickHouse](https://clickhouse.com/).\n\n## Key features\n\n* Uses ClickHouse native format for optimal performance. Utilises low level [ch-go](https://github.com/ClickHouse/ch-go) client for encoding/decoding and compression (versions \u003e= 2.3.0).\n* Supports native ClickHouse TCP client-server protocol\n* Compatibility with [`database/sql`](#std-databasesql-interface) ([slower](#benchmark) than [native interface](#native-interface)!)\n* [`database/sql`](#std-databasesql-interface) supports http protocol for transport. (Experimental)\n* Marshal rows into structs ([ScanStruct](examples/clickhouse_api/scan_struct.go), [Select](examples/clickhouse_api/select_struct.go))\n* Unmarshal struct to row ([AppendStruct](benchmark/v2/write-native-struct/main.go))\n* Connection pool\n* Failover and load balancing\n* [Bulk write support](examples/clickhouse_api/batch.go) (for `database/sql` [use](examples/std/batch.go) `begin-\u003eprepare-\u003e(in loop exec)-\u003ecommit`)\n* [PrepareBatch options](#preparebatch-options)\n* [AsyncInsert](benchmark/v2/write-async/main.go) (more details in [Async insert](#async-insert) section)\n* Named and numeric placeholders support\n* LZ4/ZSTD compression support\n* External data\n* [Query parameters](examples/std/query_parameters.go)\n\nSupport for the ClickHouse protocol advanced features using `Context`:\n\n* Query ID\n* Quota Key\n* Settings\n* [Query parameters](examples/clickhouse_api/query_parameters.go)\n* OpenTelemetry\n* Execution events:\n\t* Logs\n\t* Progress\n\t* Profile info\n\t* Profile events\n\n\n## Supported ClickHouse Versions\n\nThe client is tested against the currently [supported versions](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md) of ClickHouse\n\n## Supported Golang Versions\n\n| Client Version | Golang Versions  |\n|----------------|------------------|\n| =\u003e 2.0 \u003c= 2.2  | 1.17, 1.18       |\n| \u003e= 2.3         | 1.18.4+, 1.19    |\n| \u003e= 2.14        | 1.20, 1.21       |\n| \u003e= 2.19        | 1.21, 1.22       |\n| \u003e= 2.28        | 1.22, 1.23       |\n| \u003e= 2.29        | 1.21, 1.22, 1.23 |\n\n## Documentation\n\n[https://clickhouse.com/docs/en/integrations/go](https://clickhouse.com/docs/en/integrations/go)\n\n# `clickhouse` interface (formally `native` interface)\n\n```go\n\tconn, err := clickhouse.Open(\u0026clickhouse.Options{\n\t\tAddr: []string{\"127.0.0.1:9000\"},\n\t\tAuth: clickhouse.Auth{\n\t\t\tDatabase: \"default\",\n\t\t\tUsername: \"default\",\n\t\t\tPassword: \"\",\n\t\t},\n\t\tDialContext: func(ctx context.Context, addr string) (net.Conn, error) {\n\t\t\tdialCount++\n\t\t\tvar d net.Dialer\n\t\t\treturn d.DialContext(ctx, \"tcp\", addr)\n\t\t},\n\t\tDebug: true,\n\t\tDebugf: func(format string, v ...any) {\n\t\t\tfmt.Printf(format+\"\\n\", v...)\n\t\t},\n\t\tSettings: clickhouse.Settings{\n\t\t\t\"max_execution_time\": 60,\n\t\t},\n\t\tCompression: \u0026clickhouse.Compression{\n\t\t\tMethod: clickhouse.CompressionLZ4,\n\t\t},\n\t\tDialTimeout:      time.Second * 30,\n\t\tMaxOpenConns:     5,\n\t\tMaxIdleConns:     5,\n\t\tConnMaxLifetime:  time.Duration(10) * time.Minute,\n\t\tConnOpenStrategy: clickhouse.ConnOpenInOrder,\n\t\tBlockBufferSize: 10,\n\t\tMaxCompressionBuffer: 10240,\n\t\tClientInfo: clickhouse.ClientInfo{ // optional, please see Client info section in the README.md\n\t\t\tProducts: []struct {\n\t\t\t\tName    string\n\t\t\t\tVersion string\n\t\t\t}{\n\t\t\t\t{Name: \"my-app\", Version: \"0.1\"},\n\t\t\t},\n\t\t},\n\t})\n\tif err != nil {\n\t\treturn err\n\t}\n\treturn conn.Ping(context.Background())\n```\n\n# `database/sql` interface\n\n## OpenDB\n\n```go\nconn := clickhouse.OpenDB(\u0026clickhouse.Options{\n\tAddr: []string{\"127.0.0.1:9999\"},\n\tAuth: clickhouse.Auth{\n\t\tDatabase: \"default\",\n\t\tUsername: \"default\",\n\t\tPassword: \"\",\n\t},\n\tTLS: \u0026tls.Config{\n\t\tInsecureSkipVerify: true,\n\t},\n\tSettings: clickhouse.Settings{\n\t\t\"max_execution_time\": 60,\n\t},\n\tDialTimeout: time.Second * 30,\n\tCompression: \u0026clickhouse.Compression{\n\t\tMethod: clickhouse.CompressionLZ4,\n\t},\n\tDebug: true,\n\tBlockBufferSize: 10,\n\tMaxCompressionBuffer: 10240,\n\tClientInfo: clickhouse.ClientInfo{ // optional, please see Client info section in the README.md\n\t\tProducts: []struct {\n\t\t\tName    string\n\t\t\tVersion string\n\t\t}{\n\t\t\t{Name: \"my-app\", Version: \"0.1\"},\n\t\t},\n\t},\n})\nconn.SetMaxIdleConns(5)\nconn.SetMaxOpenConns(10)\nconn.SetConnMaxLifetime(time.Hour)\n```\n\n## DSN\n\n* hosts  - comma-separated list of single address hosts for load-balancing and failover\n* username/password - auth credentials\n* database - select the current default database\n* dial_timeout -  a duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix such as \"300ms\", \"1s\". Valid time units are \"ms\", \"s\", \"m\". (default 30s)\n* connection_open_strategy - random/round_robin/in_order (default in_order).\n    * random      - choose random server from the set\n    * round_robin - choose a round-robin server from the set\n    * in_order    - first live server is chosen in specified order\n* debug - enable debug output (boolean value)\n* compress - compress - specify the compression algorithm - “none” (default), `zstd`, `lz4`, `gzip`, `deflate`, `br`. If set to `true`, `lz4` will be used.\n* compress_level - Level of compression (default is 0). This is algorithm specific:\n  - `gzip` - `-2` (Best Speed) to `9` (Best Compression)\n  - `deflate` - `-2` (Best Speed) to `9` (Best Compression)\n  - `br` - `0` (Best Speed) to `11` (Best Compression)\n  - `zstd`, `lz4` - ignored\n* block_buffer_size - size of block buffer (default 2)\n* read_timeout - a duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix such as \"300ms\", \"1s\". Valid time units are \"ms\", \"s\", \"m\" (default 5m).\n* max_compression_buffer - max size (bytes) of compression buffer during column by column compression (default 10MiB)\n* client_info_product - optional list (comma separated) of product name and version pair separated with `/`. This value will be pass a part of client info. e.g. `client_info_product=my_app/1.0,my_module/0.1` More details in [Client info](#client-info) section.\n* http_proxy - HTTP proxy address\n\nSSL/TLS parameters:\n\n* secure - establish secure connection (default is false)\n* skip_verify - skip certificate verification (default is false)\n\nExample:\n\n```sh\nclickhouse://username:password@host1:9000,host2:9000/database?dial_timeout=200ms\u0026max_execution_time=60\n```\n\n### HTTP Support (Experimental)\n\n**Note**: using HTTP protocol is possible only with `database/sql` interface.\n\nThe native format can be used over the HTTP protocol. This is useful in scenarios where users need to proxy traffic e.g. using [ChProxy](https://www.chproxy.org/) or via load balancers.\n\nThis can be achieved by modifying the DSN to specify the HTTP protocol.\n\n```sh\nhttp://host1:8123,host2:8123/database?dial_timeout=200ms\u0026max_execution_time=60\n```\n\nAlternatively, use `OpenDB` and specify the interface type.\n\n```go\nconn := clickhouse.OpenDB(\u0026clickhouse.Options{\n\tAddr: []string{\"127.0.0.1:8123\"},\n\tAuth: clickhouse.Auth{\n\t\tDatabase: \"default\",\n\t\tUsername: \"default\",\n\t\tPassword: \"\",\n\t},\n\tSettings: clickhouse.Settings{\n\t\t\"max_execution_time\": 60,\n\t},\n\tDialTimeout: 30 * time.Second,\n\tCompression: \u0026clickhouse.Compression{\n\t\tMethod: clickhouse.CompressionLZ4,\n\t},\n\tProtocol:  clickhouse.HTTP,\n})\n```\n\n#### Proxy support\n\nHTTP proxy can be set in the DSN string by specifying the `http_proxy` parameter.\n(make sure to URL encode the proxy address)\n\n```sh\nhttp://host1:8123,host2:8123/database?dial_timeout=200ms\u0026max_execution_time=60\u0026http_proxy=http%3A%2F%2Fproxy%3A8080\n```\n\nIf you are using `clickhouse.OpenDB`, set the `HTTProxy` field in the `clickhouse.Options`.\n\nAn alternative way is to enable proxy by setting the `HTTP_PROXY` (for HTTP) or `HTTPS_PROXY` (for HTTPS) environment variables.\nSee more details in the [Go documentation](https://pkg.go.dev/net/http#ProxyFromEnvironment).\n\n## Compression\n\nZSTD/LZ4 compression is supported over native and http protocols. This is performed column by column at a block level and is only used for inserts. Compression buffer size is set as `MaxCompressionBuffer` option.\n\nIf using `Open` via the std interface and specifying a DSN, compression can be enabled via the `compress` flag. Currently, this is a boolean flag which enables `LZ4` compression.\n\nOther compression methods will be added in future PRs.\n\n## TLS/SSL\n\nAt a low level all client connect methods (DSN/OpenDB/Open) will use the [Go tls package](https://pkg.go.dev/crypto/tls) to establish a secure connection. The client knows to use TLS if the Options struct contains a non-nil tls.Config pointer.\n\nSetting secure in the DSN creates a minimal tls.Config struct with only the InsecureSkipVerify field set (either true or false).  It is equivalent to this code:\n\n```go\nconn := clickhouse.OpenDB(\u0026clickhouse.Options{\n\t...\n    TLS: \u0026tls.Config{\n            InsecureSkipVerify: false\n\t}\n\t...\n    })\n```\nThis minimal tls.Config is normally all that is necessary to connect to the secure native port (normally 9440) on a ClickHouse server. If the ClickHouse server does not have a valid certificate (expired, wrong host name, not signed by a publicly recognized root Certificate Authority), InsecureSkipVerify can be to `true`, but that is strongly discouraged.\n\nIf additional TLS parameters are necessary the application code should set the desired fields in the tls.Config struct. That can include specific cipher suites, forcing a particular TLS version (like 1.2 or 1.3), adding an internal CA certificate chain, adding a client certificate (and private key) if required by the ClickHouse server, and most of the other options that come with a more specialized security setup.\n\n### HTTPS (Experimental)\n\nTo connect using HTTPS either:\n\n- Use `https` in your dsn string e.g.\n\n    ```sh\n    https://host1:8443,host2:8443/database?dial_timeout=200ms\u0026max_execution_time=60\n    ```\n\n- Specify the interface type as `HttpsInterface` e.g.\n\n```go\nconn := clickhouse.OpenDB(\u0026clickhouse.Options{\n\tAddr: []string{\"127.0.0.1:8443\"},\n\tAuth: clickhouse.Auth{\n\t\tDatabase: \"default\",\n\t\tUsername: \"default\",\n\t\tPassword: \"\",\n\t},\n\tProtocol:  clickhouse.HTTP,\n})\n```\n\n## Client info\n\n\nClickhouse-go implements [client info](https://docs.google.com/document/d/1924Dvy79KXIhfqKpi1EBVY3133pIdoMwgCQtZ-uhEKs/edit#heading=h.ah33hoz5xei2) as a part of language client specification. `client_name` for native protocol and HTTP `User-Agent` header values are provided with the exact client info string.\n\nUsers can extend client options with additional product information included in client info. This might be useful for analysis [on a server side](https://clickhouse.com/docs/en/operations/system-tables/query_log/).\n\nOrder is the highest abstraction to the lowest level implementation left to right.\n\nUsage examples for [native API](examples/clickhouse_api/client_info.go) and [database/sql](examples/std/client_info.go)  are provided.\n\n## Async insert\n\n[Asynchronous insert](https://clickhouse.com/docs/en/optimize/asynchronous-inserts#enabling-asynchronous-inserts) is supported via dedicated `AsyncInsert` method. This allows to insert data with a non-blocking call.\nEffectively, it controls a `async_insert` setting for the query. \n\n### Using with batch API\n\nUsing native protocol, asynchronous insert does not support batching. It means, only inline query data is supported. Please see an example [here](examples/std/async.go).\n\nHTTP protocol supports batching. It can be enabled by setting `async_insert` when using standard `Prepare` method.\n\nFor more details please see [asynchronous inserts](https://clickhouse.com/docs/en/optimize/asynchronous-inserts#enabling-asynchronous-inserts) documentation.\n\n## PrepareBatch options\n\nAvailable options:\n- [WithReleaseConnection](examples/clickhouse_api/batch_release_connection.go) - after PrepareBatch connection will be returned to the pool. It can help you make a long-lived batch.\n\n## Benchmark\n\n| [V1 (READ)](benchmark/v1/read/main.go) | [V2 (READ) std](benchmark/v2/read/main.go) | [V2 (READ) clickhouse API](benchmark/v2/read-native/main.go) |\n| -------------------------------------- | ------------------------------------------ |--------------------------------------------------------------|\n| 1.218s                                 | 924.390ms                                  | 675.721ms                                                    |\n\n\n| [V1 (WRITE)](benchmark/v1/write/main.go) | [V2 (WRITE) std](benchmark/v2/write/main.go) | [V2 (WRITE) clickhouse API](benchmark/v2/write-native/main.go) | [V2 (WRITE) by column](benchmark/v2/write-native-columnar/main.go) |\n| ---------------------------------------- | -------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------ |\n| 1.899s                                   | 1.177s                                       | 699.203ms                                              | 661.973ms                                                          |\n\n\n\n## Install\n\n```sh\ngo get -u github.com/ClickHouse/clickhouse-go/v2\n```\n\n## Examples\n\n### native interface\n\n* [batch](examples/clickhouse_api/batch.go)\n* [batch with release connection](examples/clickhouse_api/batch_release_connection.go)\n* [async insert](examples/clickhouse_api/async.go)\n* [batch struct](examples/clickhouse_api/append_struct.go)\n* [columnar](examples/clickhouse_api/columnar_insert.go)\n* [scan struct](examples/clickhouse_api/scan_struct.go)\n* [query parameters](examples/clickhouse_api/query_parameters.go)\n* [bind params](examples/clickhouse_api/bind.go) (deprecated in favour of native query parameters)\n* [client info](examples/clickhouse_api/client_info.go)\n\n### std `database/sql` interface\n\n* [batch](examples/std/batch.go)\n* [async insert](examples/std/async.go)\n* [open db](examples/std/connect.go)\n* [query parameters](examples/std/query_parameters.go)\n* [bind params](examples/std/bind.go) (deprecated in favour of native query parameters)\n* [client info](examples/std/client_info.go)\n\n## Third-party libraries\n\n* [clickhouse-go-rows-utils](https://github.com/EpicStep/clickhouse-go-rows-utils) - utilities that simplify working with rows.\n\n## ClickHouse alternatives - ch-go\n\nVersions of this client \u003e=2.3.x utilise [ch-go](https://github.com/ClickHouse/ch-go) for their low level encoding/decoding. This low lever client provides a high performance columnar interface and should be used in performance critical use cases. This client provides more familar row orientated and `database/sql` semantics at the cost of some performance.\n\nBoth clients are supported by ClickHouse.\n\n## Third-party alternatives\n\n* Database client/clients:\n\t* [mailru/go-clickhouse](https://github.com/mailru/go-clickhouse) (uses the HTTP protocol)\n\t* [uptrace/go-clickhouse](https://github.com/uptrace/go-clickhouse) (uses the native TCP protocol with `database/sql`-like API)\n\t* Drivers with columnar interface:\n\t\t* [vahid-sohrabloo/chconn](https://github.com/vahid-sohrabloo/chconn)\n\n* Insert collectors:\n\t* [KittenHouse](https://github.com/YuriyNasretdinov/kittenhouse)\n\t* [nikepan/clickhouse-bulk](https://github.com/nikepan/clickhouse-bulk)\n","funding_links":[],"categories":["Go","开源类库","Open source library","Database Drivers","Language bindings"],"sub_categories":["数据库","Database","Search and Analytic Databases","Golang"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FClickHouse%2Fclickhouse-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FClickHouse%2Fclickhouse-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FClickHouse%2Fclickhouse-go/lists"}