{"id":20102457,"url":"https://github.com/clickhouse/metabase-clickhouse-driver","last_synced_at":"2025-04-08T06:31:12.651Z","repository":{"id":37819591,"uuid":"175096978","full_name":"ClickHouse/metabase-clickhouse-driver","owner":"ClickHouse","description":"ClickHouse database driver for the Metabase business intelligence front-end","archived":false,"fork":false,"pushed_at":"2025-03-19T19:25:58.000Z","size":600,"stargazers_count":507,"open_issues_count":35,"forks_count":96,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-02T02:55:36.867Z","etag":null,"topics":["analytics","bi-tools","business-intelligence","clickhouse","metabase"],"latest_commit_sha":null,"homepage":"","language":"Clojure","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":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-11T23:01:26.000Z","updated_at":"2025-03-31T11:51:41.000Z","dependencies_parsed_at":"2023-12-20T19:23:56.142Z","dependency_job_id":"cf162302-9a33-47d8-bd95-0ad88cb36698","html_url":"https://github.com/ClickHouse/metabase-clickhouse-driver","commit_stats":null,"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fmetabase-clickhouse-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fmetabase-clickhouse-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fmetabase-clickhouse-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClickHouse%2Fmetabase-clickhouse-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClickHouse","download_url":"https://codeload.github.com/ClickHouse/metabase-clickhouse-driver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247791459,"owners_count":20996757,"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","bi-tools","business-intelligence","clickhouse","metabase"],"created_at":"2024-11-13T17:30:56.362Z","updated_at":"2025-04-08T06:31:12.616Z","avatar_url":"https://github.com/ClickHouse.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\" style=\"font-size:300%\"\u003e\n\u003cimg src=\"https://www.metabase.com/images/logo.svg\" width=\"200px\" align=\"center\"\u003e\n\u003cimg src=\".static/clickhouse.svg\" width=\"180px\" align=\"center\"\u003e\n\u003ch1 align=\"center\"\u003eClickHouse driver for Metabase\u003c/h1\u003e\n\u003c/p\u003e\n\u003cbr/\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/enqueue/metabase-clickhouse-driver/actions/workflows/check.yml\"\u003e\n\u003cimg src=\"https://github.com/enqueue/metabase-clickhouse-driver/actions/workflows/check.yml/badge.svg?branch=master\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/enqueue/metabase-clickhouse-driver/releases\"\u003e\n\u003cimg src=\"https://img.shields.io/github/release/enqueue/metabase-clickhouse-driver.svg?label=latest%20release\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://raw.githubusercontent.com/enqueue/metabase-clickhouse-driver/master/LICENSE\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n## About\n\n[ClickHouse](https://clickhouse.com) ([GitHub](https://github.com/ClickHouse/ClickHouse)) database driver for the [Metabase](https://metabase.com) ([GitHub](https://github.com/metabase/metabase)) business intelligence front-end.\n\n## Compatibility with ClickHouse\n\nThe driver aims to support the current stable and LTS releases (see [the related docs](https://clickhouse.com/docs/en/faq/operations/production#how-to-choose-between-clickhouse-releases)).\n\n| ClickHouse version      | Supported?  |\n|-------------------------|-------------|\n| 23.8+                   | ✔           |\n| 23.6 - 23.7             | Best effort |\n\nFor [connection impersonation feature](https://www.metabase.com/learn/permissions/impersonation), the minimal required ClickHouse version is 24.4; otherwise, the feature is disabled by the driver.\n\nThe [CSV Uploads feature](https://www.metabase.com/docs/latest/databases/uploads) currently works only with ClickHouse Cloud (see [this issue](https://github.com/ClickHouse/metabase-clickhouse-driver/issues/230) for more details).\n\n## Installation\n\n### Run using Metabase Jar\n\n1. Download a fairly recent Metabase binary release (jar file) from the [Metabase distribution page](https://metabase.com/start/jar.html).\n2. Download the ClickHouse driver jar from this repository's [Releases](https://github.com/enqueue/metabase-clickhouse-driver/releases) page\n3. Create a directory and copy the `metabase.jar` to it.\n4. In that directory create a sub-directory called `plugins`.\n5. Copy the ClickHouse driver jar to the `plugins` directory.\n6. Make sure you are the in the directory where your `metabase.jar` lives.\n7. Run `MB_PLUGINS_DIR=./plugins; java -jar metabase.jar`.\n\nFor example [(using Metabase v0.53 and ClickHouse driver 1.53.2)](#choosing-the-right-version):\n\n```bash\nexport METABASE_VERSION=v0.53.x\nexport METABASE_CLICKHOUSE_DRIVER_VERSION=1.53.2\n\nmkdir -p mb/plugins \u0026\u0026 cd mb\ncurl -o metabase.jar https://downloads.metabase.com/$METABASE_VERSION/metabase.jar\ncurl -L -o plugins/ch.jar https://github.com/ClickHouse/metabase-clickhouse-driver/releases/download/$METABASE_CLICKHOUSE_DRIVER_VERSION/clickhouse.metabase-driver.jar\nMB_PLUGINS_DIR=./plugins; java -jar metabase.jar\n```\n\n### Run as a Docker container\n\nAlternatively, if you don't want to run Metabase from a jar, you can use a Docker image:\n\n```bash\nexport METABASE_VERSION=v0.53.x\nexport METABASE_CLICKHOUSE_DRIVER_VERSION=1.53.2\n\nmkdir -p mb/plugins \u0026\u0026 cd mb\ncurl -L -o plugins/ch.jar https://github.com/ClickHouse/metabase-clickhouse-driver/releases/download/$METABASE_CLICKHOUSE_DRIVER_VERSION/clickhouse.metabase-driver.jar\ndocker run -d -p 3000:3000 \\\n  --mount type=bind,source=$PWD/plugins/ch.jar,destination=/plugins/clickhouse.jar \\\n  metabase/metabase:$METABASE_VERSION\n```\n\n## Choosing the Right Version\n\n| Metabase Release | Driver Version |\n| ---------------- | -------------- |\n| 0.50.x           | 1.50.7         |\n| 0.51.x           | 1.51.0         |\n| 0.52.x           | 1.52.0         |\n| 0.53.x           | 1.53.2         |\n\nThe minor version of the driver should always match the minor version of the Metabase release. For example, the driver version 1.**50**.0 means that it should be used with Metabase v0.**50**.x or Metabase EE 1.**50**.x _only_, and it is _not guaranteed_ that this particular version of the driver can work with the previous or the following versions of Metabase.\n\n## Creating a Metabase Docker image with ClickHouse driver\n\nYou can use a convenience script `build_docker_image.sh`, which takes three arguments: Metabase version, ClickHouse driver version, and the desired final Docker image tag.\n\n```bash\n./build_docker_image.sh v0.53.x 1.53.2 my-metabase-with-clickhouse:v0.0.1\n```\n\nwhere `v0.53.x` is Metabase version, `1.53.2` is ClickHouse driver version, and `my-metabase-with-clickhouse:v0.0.1` being the tag.\n\nThen you should be able to run it:\n\n```bash\ndocker run -d -p 3000:3000 --name my-metabase my-metabase-with-clickhouse:v0.0.1\n```\n\nor use it with Docker compose, for example:\n\n```yaml\nversion: '3.8'\nservices:\n  clickhouse:\n    image: 'clickhouse/clickhouse-server:24.8-alpine'\n    container_name: 'metabase-clickhouse-server'\n    ports:\n      - '8123:8123'\n      - '9000:9000'\n    ulimits:\n      nofile:\n        soft: 262144\n        hard: 262144\n  metabase:\n    image: 'my-metabase-with-clickhouse:v0.0.1'\n    container_name: 'metabase-with-clickhouse'\n    environment:\n      'MB_HTTP_TIMEOUT': '5000'\n      # Replace with a timezone matching your ClickHouse or DateTime columns timezone\n      'JAVA_TIMEZONE': 'UTC'\n    ports:\n      - '3000:3000'\n```\n\n## Using certificates\n\nIn the \"Advanced options\", add the following to the \"Additional JDBC connection string options\" input:\n\n```\nsslrootcert=/path/to/ca.crt\n```\n\nwhere `/path/to/ca.crt` is the absolute path to the server CA on the Metabase host or Docker container (depends on your deployment).\n\nMake sure that you tick \"Use a secure connection (SSL)\" as well.\n\n## Operations\n\nThe driver should work fine for many use cases. Please consider the following items when running a Metabase instance with this driver:\n\n* Create a dedicated user for Metabase, whose profile has `readonly` set to 2.\n* Consider running the Metabase instance in the same time zone as your ClickHouse database; the more time zones involved the more issues.\n* Compare the results of the queries with the results returned by `clickhouse-client`.\n* Metabase is a good tool for organizing questions, dashboards etc. and to give non-technical users a good way to explore the data and share their results. The driver cannot support all the cool special features of ClickHouse, e.g. array functions. You are free to use native queries, of course.\n\n## Known limitations\n\n* As the underlying JDBC driver version does not support columns with `AggregateFunction` type, these columns are excluded from the table metadata and data browser result sets to prevent sync or data browsing errors.\n* If the past month/week/quarter/year filter over a DateTime64 column is not working as intended, this is likely due to a [type conversion issue](https://github.com/ClickHouse/ClickHouse/pull/50280). See [this report](https://github.com/ClickHouse/metabase-clickhouse-driver/issues/164) for more details. This issue was resolved as of ClickHouse 23.5.\n* If introspected ClickHouse version is lower than 23.8, the driver will not use [startsWithUTF8](https://clickhouse.com/docs/en/sql-reference/functions/string-functions#startswithutf8) and fall back to its [non-UTF8 counterpart](https://clickhouse.com/docs/en/sql-reference/functions/string-functions#startswith) instead. There is a drawback in this compatibility mode: potentially incorrect filtering results when working with non-latin strings. If your use case includes filtering by columns with such strings and you experience these issues, consider upgrading your ClickHouse server to 23.8+.\n\n## Contributing\n\nCheck out our [contributing guide](./CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclickhouse%2Fmetabase-clickhouse-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclickhouse%2Fmetabase-clickhouse-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclickhouse%2Fmetabase-clickhouse-driver/lists"}