ClickHouse · slvrtrn · Apr 28, 2025 · Apr 22, 2025 · Apr 23, 2025 · Apr 23, 2025
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
@@ -6,11 +6,13 @@ on:
     branches:
       - master
     paths-ignore:
-      - "**.md"
+      - '**/*.md'
   pull_request:
+    paths-ignore:
+      - '**/*.md'
 
 env:
-  # Temporarily using a fork to disable a few failing tests
+  # Using a fork to disable a few failing tests
   METABASE_REPOSITORY: slvrtrn/metabase
   METABASE_VERSION: 0.53.x-ch
 
@@ -115,8 +117,6 @@ jobs:
         with:
           compose-file: "modules/drivers/clickhouse/docker-compose.yml"
           down-flags: "--volumes"
-          # FIXME: We only need to run a few specific tests with `clickhouse_older_version`
-          #        Currently, we run all tests with it, which is unnecessary.
           services: |
             clickhouse
             clickhouse_tls

diff --git a/README.md b/README.md
@@ -5,153 +5,44 @@
 </p>
 <br/>
 <p align="center">
-<a href="https://github.com/enqueue/metabase-clickhouse-driver/actions/workflows/check.yml">
-<img src="https://github.com/enqueue/metabase-clickhouse-driver/actions/workflows/check.yml/badge.svg?branch=master">
-</a>
-<a href="https://github.com/enqueue/metabase-clickhouse-driver/releases">
-<img src="https://img.shields.io/github/release/enqueue/metabase-clickhouse-driver.svg?label=latest%20release">
-</a>
 <a href="https://raw.githubusercontent.com/enqueue/metabase-clickhouse-driver/master/LICENSE">
 <img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg">
 </a>
 </p>
 
 ## About
 
-[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.
-
-## Compatibility with ClickHouse
-
-The 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)).
-
-| ClickHouse version      | Supported?  |
-|-------------------------|-------------|
-| 23.8+                   | ✔           |
-| 23.6 - 23.7             | Best effort |
-
-For [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.
-
-The [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).
-
-## Installation
-
-### Run using Metabase Jar
-
-1. Download a fairly recent Metabase binary release (jar file) from the [Metabase distribution page](https://metabase.com/start/jar.html).
-2. Download the ClickHouse driver jar from this repository's [Releases](https://github.com/enqueue/metabase-clickhouse-driver/releases) page
-3. Create a directory and copy the `metabase.jar` to it.
-4. In that directory create a sub-directory called `plugins`.
-5. Copy the ClickHouse driver jar to the `plugins` directory.
-6. Make sure you are the in the directory where your `metabase.jar` lives.
-7. Run `MB_PLUGINS_DIR=./plugins; java -jar metabase.jar`.
-
-For example [(using Metabase v0.53 and ClickHouse driver 1.53.2)](#choosing-the-right-version):
-
-```bash
-export METABASE_VERSION=v0.53.x
-export METABASE_CLICKHOUSE_DRIVER_VERSION=1.53.2
-
-mkdir -p mb/plugins && cd mb
-curl -o metabase.jar https://downloads.metabase.com/$METABASE_VERSION/metabase.jar
-curl -L -o plugins/ch.jar https://github.com/ClickHouse/metabase-clickhouse-driver/releases/download/$METABASE_CLICKHOUSE_DRIVER_VERSION/clickhouse.metabase-driver.jar
-MB_PLUGINS_DIR=./plugins; java -jar metabase.jar
-```
-
-### Run as a Docker container
-
-Alternatively, if you don't want to run Metabase from a jar, you can use a Docker image:
-
-```bash
-export METABASE_VERSION=v0.53.x
-export METABASE_CLICKHOUSE_DRIVER_VERSION=1.53.2
-
-mkdir -p mb/plugins && cd mb
-curl -L -o plugins/ch.jar https://github.com/ClickHouse/metabase-clickhouse-driver/releases/download/$METABASE_CLICKHOUSE_DRIVER_VERSION/clickhouse.metabase-driver.jar
-docker run -d -p 3000:3000 \
-  --mount type=bind,source=$PWD/plugins/ch.jar,destination=/plugins/clickhouse.jar \
-  metabase/metabase:$METABASE_VERSION
-```
-
-## Choosing the Right Version
-
-| Metabase Release | Driver Version |
-| ---------------- | -------------- |
-| 0.50.x           | 1.50.7         |
-| 0.51.x           | 1.51.0         |
-| 0.52.x           | 1.52.0         |
-| 0.53.x           | 1.53.2         |
-
-The 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.
-
-## Creating a Metabase Docker image with ClickHouse driver
-
-You 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.
-
-```bash
-./build_docker_image.sh v0.53.x 1.53.2 my-metabase-with-clickhouse:v0.0.1
-```
-
-where `v0.53.x` is Metabase version, `1.53.2` is ClickHouse driver version, and `my-metabase-with-clickhouse:v0.0.1` being the tag.
-
-Then you should be able to run it:
-
-```bash
-docker run -d -p 3000:3000 --name my-metabase my-metabase-with-clickhouse:v0.0.1
-```
-
-or use it with Docker compose, for example:
+The Metabase team promoted the ClickHouse driver to the core level as of Metabase 54 ([release notes](https://github.com/metabase/metabase/releases/tag/v0.54.1), [driver source](https://github.com/metabase/metabase/tree/v0.54.x/modules/drivers/clickhouse)).
 
-```yaml
-version: '3.8'
-services:
-  clickhouse:
-    image: 'clickhouse/clickhouse-server:24.8-alpine'
-    container_name: 'metabase-clickhouse-server'
-    ports:
-      - '8123:8123'
-      - '9000:9000'
-    ulimits:
-      nofile:
-        soft: 262144
-        hard: 262144
-  metabase:
-    image: 'my-metabase-with-clickhouse:v0.0.1'
-    container_name: 'metabase-with-clickhouse'
-    environment:
-      'MB_HTTP_TIMEOUT': '5000'
-      # Replace with a timezone matching your ClickHouse or DateTime columns timezone
-      'JAVA_TIMEZONE': 'UTC'
-    ports:
-      - '3000:3000'
-```
+For the end user, this means the following:
 
-## Using certificates
+- Installing the driver manually is unnecessary, as it is now bundled with Metabase.
+- Starting from April 2025, the Metabase team will continue maintaining the driver. Please report new issues in [the main Metabase repository](https://github.com/metabase/metabase/issues).
 
-In the "Advanced options", add the following to the "Additional JDBC connection string options" input:
+The ClickHouse team recommends avoiding older Metabase versions (53.x and earlier) with manual driver installation; instead, please use the updated Metabase distribution with the driver built-in.
 
-```
-sslrootcert=/path/to/ca.crt
-```
+## History
 
-where `/path/to/ca.crt` is the absolute path to the server CA on the Metabase host or Docker container (depends on your deployment).
+The request for a ClickHouse Metabase driver was formulated in 2016 in [Metabase issue #3332](https://github.com/metabase/metabase/issues/3332). Several impatient ClickHouse users started the development in the main Metabase repo. In March 2019, after releasing the plugin SDK, the Metabase team [asked to publish the driver separately](https://github.com/metabase/metabase/pull/8491#issuecomment-471721980) in its own repository, and later that month, with Felix Mueller ([@enqueue](https://github.com/enqueue)) leading the efforts, the [initial version of the driver](https://github.com/ClickHouse/metabase-clickhouse-driver/releases/tag/v0.1) was out.
 
-Make sure that you tick "Use a secure connection (SSL)" as well.
+The original implementation of the driver was based on the following pull requests:
 
-## Operations
+- [metabase#8491](https://github.com/metabase/metabase/pull/8491)
+- [metabase#8722](https://github.com/metabase/metabase/pull/8722)
+- [metabase#9469](https://github.com/metabase/metabase/pull/9469)
 
-The driver should work fine for many use cases. Please consider the following items when running a Metabase instance with this driver:
+The source base in these PRs comprises major contributions from these authors:
 
-* Create a dedicated user for Metabase, whose profile has `readonly` set to 2.
-* Consider running the Metabase instance in the same time zone as your ClickHouse database; the more time zones involved the more issues.
-* Compare the results of the queries with the results returned by `clickhouse-client`.
-* 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.
+- [@tsl-karlp](https://github.com/tsl-karlp)
+- Andrew Grigorev ([@ei-grad](https://github.com/ei-grad))
+- Bogdan Mukvich ([@Badya](https://github.com/Badya))
+- Felix Mueller ([@enqueue](https://github.com/enqueue))
 
-## Known limitations
+> [!NOTE]
+> Special thanks to Felix Mueller ([@enqueue](https://github.com/enqueue)), who was the sole maintainer of the project from 2019 to 2022 before transferring it to ClickHouse.
 
-* 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.
-* 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.
-* 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+.
+Starting from November 2022, Serge Klochkov ([@slvrtrn](https://github.com/slvrtrn)) joined as a maintainer.
 
-## Contributing
+In early 2023, the repository was transferred to the ClickHouse organization, promoting it as an [official integration](https://clickhouse.com/blog/metabase-clickhouse-plugin-ga-release). Around that time, the driver also became available in [Metabase Cloud](https://www.metabase.com/cloud).
 
-Check out our [contributing guide](./CONTRIBUTING.md).
+In April 2025, the driver source code [was moved](https://github.com/metabase/metabase/pull/54740) to the main Metabase repository. Since [Metabase 54](https://github.com/metabase/metabase/releases/tag/v0.54.1), it is now available as a part of the official Metabase bundle.