ClickHouse driver for Metabase

About

ClickHouse (GitHub) database driver for the Metabase (GitHub) business intelligence front-end.

Installation

Run using Metabase Jar

Download a fairly recent Metabase binary release (jar file) from the Metabase distribution page.
Download the ClickHouse driver jar from this repository's Releases page
Create a directory and copy the metabase.jar to it.
In that directory create a sub-directory called plugins.
Copy the ClickHouse driver jar to the plugins directory.
Make sure you are the in the directory where your metabase.jar lives.
Run MB_PLUGINS_DIR=./plugins; java -jar metabase.jar.

For example (using Metabase v0.45.1 and ClickHouse driver 0.9.1):

mkdir -p mb/plugins && cd mb
curl -o metabase.jar https://downloads.metabase.com/v0.45.1/metabase.jar
curl -L -o plugins/ch.jar https://github.com/enqueue/metabase-clickhouse-driver/releases/download/0.9.1/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 Jar, you can use a Docker image:

mkdir -p mb/plugins && cd mb
curl -L -o plugins/ch.jar https://github.com/enqueue/metabase-clickhouse-driver/releases/download/0.9.1/clickhouse.metabase-driver.jar
docker run -d -p 3000:3000 \
  --mount type=bind,source=$PWD/plugins/ch.jar,destination=/plugins/clickhouse.jar \
  --name metabase metabase/metabase:v0.45.1

Choosing the Right Version

Metabase Release	Driver Version
0.33.x	0.6
0.34.x	0.7.0
0.35.x	0.7.1
0.37.3	0.7.3
0.38.1+	0.7.5
0.41.2	0.8.0
0.41.3.1	0.8.1
0.42.x	0.8.1
0.44.x	0.9.0
0.45.x	0.9.1

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.

./build_docker_image.sh v0.44.6 0.8.3 my-metabase-with-clickhouse:v0.0.1

where v0.44.6 is Metabase version, 0.8.3 is ClickHouse driver version, and my-metabase-with-clickhouse:v0.0.1 being the tag.

Then you should be able to run it:

docker run -d -p 3000:3000 --name my-metabase my-metabase-with-clickhouse:v0.0.1

or use with Docker compose, for example:

version: '3.8'
services:
  clickhouse:
    image: 'clickhouse/clickhouse-server:22.10.2-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'
    ports:
      - '3000:3000'

Operations

The driver should work fine for many use cases. Please consider the following items when running a Metabase instance with this driver:

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.

Contributing

Check out our contributing guide.

License

The contents of this repository are made available under the GNU Affero General Public License v3.0 (AGPL), see LICENSE.