ClickHouse driver for Metabase

About

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

Installation

Run using Metabase Jar

1. Download a fairly recent Metabase binary release (jar file) from the Metabase distribution page.
2. Download the ClickHouse driver jar from this repository's 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.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.1
0.45.x	1.0.4

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'

Using certificates

In the "Advanced options", add the following to the "Additional JDBC connection string options" input:

sslrootcert=/path/to/ca.crt

where /path/to/ca.crt is the absolute path to the server CA on the Metabase host or Docker container (depends on your deployment).

Make sure that you tick "Use a secure connection (SSL)" as well.

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.

Known limitations

• As the underlying JDBC driver version does not support columns with (Simple)AggregationFunction type, these columns are excluded from the table metadata and data browser result sets to prevent sync or data browsing errors.

Contributing

Check out our contributing guide.