Connecting Metabase to ClickHouse

Connecting Metabase to ClickHouse with the ClickHouse Metabase driver

The supported way to connect a self-hosted Metabase to a self-managed ClickHouse cluster is the ClickHouse Metabase driver, a JAR file named clickhouse.metabase-driver.jar that you download from the clickhouse/metabase-clickhouse-driver releases and place in Metabase's plugins folder. ClickHouse lists this driver as a partner integration, and the ClickHouse Metabase guide is the vendor's reference for the steps. The connection itself does not require a paid Metabase plan: Metabase's open source edition, licensed under the AGPL, is enough to add the ClickHouse database and build questions and dashboards on it. Confirm the driver release that matches your Metabase version before you copy the JAR, since the driver and the host application must be kept in step.

The driver turns ClickHouse tables into databases that Metabase's query builder and SQL editor can read. Plan the connection around a dedicated, read-only ClickHouse user rather than the default user, which starts with all permissions, so that Metabase can query the analytics tables but cannot change them. Decide which databases and tables Metabase should expose, and confirm with your ClickHouse administrator how TLS, host names and ports for the HTTP interface are set on your cluster. Also decide where Metabase's own application database lives, because dashboard definitions, saved questions and user accounts are stored there, not in ClickHouse. Metabase recommends PostgreSQL for production over the embedded H2 database, so that choice should be made before the first dashboard is built.

This page covers the connection between Metabase and ClickHouse, including driver installation, connection settings and dashboard query patterns. It does not cover ClickHouse cluster design, replication, sizing or schema planning, which have their own sections in this series. Dashboards that run heavy aggregations over large tables are where most performance problems appear, so the query patterns and materialized views described below depend on a schema that already reflects how the data will be read. Treat the driver as one component in a larger system you run, and test each Metabase upgrade and driver change against a copy of your dashboards before rolling it into production.

What you need before connecting Metabase to ClickHouse

A working Metabase connection depends on four things lining up: a ClickHouse version that still receives security updates, a Metabase release still in its support window, a driver JAR matched to that Metabase, and network and credential paths that let the Metabase host reach the cluster safely. Confirm each of these before you touch the Metabase admin panel.

Supported ClickHouse version

Check the ClickHouse security policy before choosing a server version. It lists the versions currently receiving security updates, and every other version is unsupported. Pick a version from that list, prefer a stable or LTS line for production, and confirm the exact release on the releases page before you build the cluster. Use a pre-production copy with representative data to test your dashboard queries against that version first.

Metabase release in support

Confirm that your Metabase version is still inside its support window on the version support page. Non-LTS releases usually reach end of life after about two months, so a version installed last year may no longer receive fixes. Choose an LTS release where possible, and plan the upgrade path before you add the ClickHouse driver, because the driver must match the Metabase version you run.

Matching driver JAR

The ClickHouse Metabase driver is a single file, clickhouse.metabase-driver.jar, taken from the clickhouse/metabase-clickhouse-driver releases. Download the build whose release notes name your Metabase version, record its checksum, and keep a copy in your artifact store. Do not copy a driver file from an unrelated forum post, since an unverified JAR runs inside your analytics service with access to every connected database.

Application database choice

Metabase ships with an embedded H2 application database that suits demos only. Plan PostgreSQL or MySQL 8.4.0 or MariaDB 10.6.0 or later with utf8mb4 for production, and provision it before the first login so saved questions, dashboards and user accounts are not trapped in H2. Metabase documents a one-time load-from-h2 migration, but it must run with the same Metabase version that last wrote the H2 file.

Network paths to ClickHouse

Metabase connects to ClickHouse over the HTTP(S) interface, so the Metabase host needs a route and firewall rule to the HTTP or HTTPS port of each node or load balancer it will query. Confirm which port your cluster exposes for HTTPS and whether any native-protocol port is also opened for tools that need it. Limit the allowed source addresses to the Metabase hosts, and record the path for DNS, proxies and any load balancer in front of the cluster.

TLS certificates and trust

Decide how the Metabase JVM will trust the ClickHouse server certificate before you enter connection settings. Use a certificate issued by your internal CA or a public CA, and confirm its subject names match the hostname Metabase will use. Add the CA to the Java truststore that Metabase runs with, and test the connection from the Metabase host itself rather than from your workstation, since trust stores differ between the two.

Dedicated read-only ClickHouse user

Create a separate ClickHouse user for Metabase instead of reusing the default user, which starts with all permissions. Grant it only SELECT on the databases and tables that dashboards need, and consider a settings profile with query limits. Restricting this account is what keeps a mis-built question from changing data or consuming the whole cluster, and it gives your audit logs a clear identity for Metabase traffic.

How to install the driver and configure the connection

This sequence takes a self-hosted Metabase from its current state to a working ClickHouse connection, with the driver installed, the database registered and a test query returning results. Each step ends with a check so the team knows it can move on.

Confirm the Metabase version and back up the application database
Record the Metabase version that is running now and confirm it is one your team intends to keep. Metabase runs database migrations automatically during upgrades, so the Metabase documentation recommends backing up the application database first. Take a backup of the PostgreSQL or MySQL application database, or of the H2 file if you still run the embedded default, and store it outside the Metabase host. Done when the backup file exists, you have confirmed you can read it, and you have written down the current version number for the rollback plan.
Download the ClickHouse driver JAR
Open the releases page of the clickhouse/metabase-clickhouse-driver repository and download the file named clickhouse.metabase-driver.jar. Choose the release that ClickHouse's Metabase guide points to for your Metabase line, and confirm the release notes list compatibility with your Metabase version. Store the file in your configuration management or artifact repository so the same JAR is used across staging and production. Done when the JAR is on your admin workstation with a recorded version and checksum.
Place the JAR in the plugins folder and restart Metabase
Copy clickhouse.metabase-driver.jar into the plugins folder of the Metabase installation, which is set by the MB_PLUGINS_DIR environment variable or the default location for your deployment method. Confirm the file owner matches the user that runs Metabase, then restart the Metabase service or container. Watch the startup log for a line confirming the plugin loaded without errors. Done when the log shows the driver loaded and the Metabase web interface starts normally.
Open the database settings and select ClickHouse
Sign in to Metabase as an administrator and open the Admin settings, then the Databases section, and choose to add a database. The ClickHouse option should appear in the database type list once the driver has loaded. If it does not appear, check the startup log for plugin errors and confirm the JAR is in the folder Metabase is reading. Done when the ClickHouse option is visible in the database type list.
Enter host, port, database, user and TLS settings
Fill in the connection form with the host name or address of a ClickHouse node or load balancer, the HTTP or HTTPS port your cluster exposes, the database name, and a dedicated read-only user created for Metabase. Enable TLS if your ClickHouse endpoint uses it and supply the certificate trust settings your security team has approved. Confirm the port matches the protocol you enabled, since an HTTPS setting against a plain HTTP port fails at connection time. Done when the form is complete and saved without validation errors.
Run a test query and verify metadata sync
Use the connection test in the database form, then wait for Metabase to complete its initial metadata sync. Open the data browser and confirm the expected databases and tables appear with their column types. Run a simple count query on a known table from the Metabase query builder or SQL editor and compare the result with a count taken directly in ClickHouse. Done when the test succeeds, the tables are listed, and the count matches the value from the ClickHouse client.
Record the configuration for repeatable rebuilds
Document the driver version, the JAR location, the connection settings excluding credentials, and the user that Metabase connects with. Store credentials in your approved secrets store rather than in the notes. Confirm with your team which upgrade procedure applies when Metabase or the driver changes, since the driver must be checked against each new Metabase release. Done when the record is stored with the team's runbook and a second engineer can repeat the steps from it.

How the driver, the cluster and the application database fit together

Three separate stores are involved, and keeping them apart is the first design decision. ClickHouse holds the analytical data: the event, log or telemetry tables your analysts query. Metabase's application database holds what Metabase itself creates: users, groups, saved questions, dashboards and their settings. The ClickHouse Metabase driver is the query path between the two. When a dashboard tile refreshes, Metabase builds a query, sends it through the driver to the ClickHouse cluster, and renders the result. Nothing in that chain moves business data into Metabase's own database, so the application database can be small and disposable compared with the analytical store.

Metabase reads from ClickHouse as an analytical source and does not write business data back. Questions and dashboards are metadata about how to query, not copies of rows. This matters for the access model: the database user in the connection settings determines what every Metabase user can ever see, so a read-only account scoped to the tables your analysts need is the control to plan first. Confirm with your team which user Metabase will connect as, which databases and tables that user can read, and whether any ClickHouse write path exists for it. Metabase's own permission features sit on top of that database-level grant, not in place of it.

The Metabase backend runs as a Java application packaged as a JAR, and the driver is loaded by that process at startup. This is why plugin placement matters: the driver file must sit in the plugins folder that the running Metabase instance reads, and a container, service or package install may use a different path than the one you expect. After any change, confirm the driver appears as available in the admin settings before you rely on it. The application database also needs to stay on a supported engine, since Metabase recommends PostgreSQL for production; the ClickHouse connection itself is configured inside Metabase, not in that database.

Mapping ClickHouse users, roles and tables to Metabase access

Analysts who should see only part of a table need enforcement that does not depend on which dashboard they open. On the open source edition of Metabase, the Metabase pricing page places row and column level permissions in the Pro and Enterprise plans, so the practical enforcement point is the ClickHouse side. Create one ClickHouse user per analyst group, grant it a role with SELECT on the required tables only, and attach a row policy that filters rows by region, tenant or business unit. Metabase then connects with a database user whose visible data is already limited, and the restriction holds for native SQL questions as well as the query builder.

Row policies as the boundary: Define CREATE ROW POLICY rules on the tables that hold sensitive rows, so filtering happens inside the server.
Roles over direct grants: Grant privileges to roles and assign roles to users, which keeps changes in one place as teams change.
Separate connection per restriction level: Use one Metabase database connection per distinct row scope, since a single connection cannot present different row sets to different people.
No reliance on Metabase filters alone: Dashboard filters and saved question filters are presentation controls, not access controls.

Before go-live, log in as a restricted user and confirm that row counts match the policy, including through native SQL.

Administrators own the Metabase database connection, its credentials and the ClickHouse account behind it. The ClickHouse access control documentation recommends managing users, roles, row policies, settings profiles and quotas through SQL and restricting the default user, which starts with all permissions. A dedicated, read-only service account for Metabase keeps write privileges, DDL and administrative settings out of reach of the BI layer, and a settings profile can cap query resource use so one dashboard cannot starve the cluster.

Dedicated service account: Create a named user for Metabase with SELECT and no write grants.
Default user restricted: Disable or lock down the default user before connecting any BI tool.
Settings profiles and quotas: Limit memory, execution time and query counts for the Metabase account.
Credential storage: Keep the Metabase connection password in your secrets process and rotate it on a schedule you set.
Connection ownership: Record who can edit database connections in Metabase, since that setting allows changing which ClickHouse account is used.

Confirm with your ClickHouse administrators which authentication method (password, LDAP, Kerberos, certificates or JWT) your environment uses for this account before writing the connection settings down.

Field and type mapping between ClickHouse and Metabase

This table maps common ClickHouse column types to how Metabase typically displays, filters and groups them through the ClickHouse driver. Read each row as a design check: the column type you choose in ClickHouse decides which filter widgets and time bucketing your dashboard users get. Confirm each mapping against the driver release you install, because type handling changes between driver versions.

ClickHouse type	How Metabase treats it	Schema decision that simplifies dashboards
Date or Date32	Shown as a date, offers date filters and day-level grouping	Store event day as Date for day-level time filters and grouping
DateTime or DateTime64	Shown as a timestamp, offers time bucketing such as hour or minute	Use one timezone per column so bucketed charts match business reporting
LowCardinality(String)	Shown as text, filterable as a category with a dropdown of values	Apply LowCardinality to status, region and channel columns used in filters
Nullable(T)	Shown as the underlying type with empty values, which may appear as a separate group	Avoid Nullable on dimension columns, use a default value and document it
Array(T)	Confirm in the driver documentation whether arrays render as text or are filterable	Flatten frequently filtered array values into separate rows or columns
Map(K, V)	Confirm in the driver documentation how map keys and values are exposed for filtering	Promote commonly queried map keys to dedicated typed columns
Enum8 or Enum16	Shown as text values, typically usable in filters and grouping	Use Enum for fixed code sets so filter values stay consistent
Decimal or UInt64	Shown as numeric, usable in aggregations such as sum and average	Pick numeric types that match the units shown on dashboards

Securing the Metabase to ClickHouse connection

Metabase is a window into ClickHouse, so every control here decides who can read which rows and who can change the system. The cards cover the database account Metabase uses, the transport, row-level and quota limits, central identity, and the Metabase application database and driver files that sit alongside it.

Dedicated read-only ClickHouse user

Create a separate ClickHouse user for Metabase with only the SELECT grants on the databases it must query, and never reuse the default user or an administrator account. The default user starts with all permissions, so restrict it as well before exposing the server. Confirm the Metabase connection cannot run INSERT, ALTER or DROP by testing those statements with its credentials. Keep the grant list in version control so reviewers can see every change.

TLS on the Metabase connection

Encrypt traffic between the Metabase server and ClickHouse with TLS, so queries, results and the Metabase login are not sent in clear text across the network. Decide which port and protocol the driver uses, then confirm the certificate chain is trusted by the Metabase JVM, not only by the operating system. Ask your ClickHouse operator to confirm that plaintext listeners are disabled on the path Metabase uses.

Row policies and query quotas

Use ClickHouse row policies to limit which rows the Metabase user can see, for example by tenant or region, because Metabase's open source edition does not enforce row-level permissions for you. Pair them with a settings profile or quota that caps query volume for the account, so a heavy dashboard cannot starve ingestion. Test each policy with a sample query from the Metabase account, since a missing policy silently returns more rows than intended.

LDAP or JWT for central identity

Where the organization requires central identity for database access, ClickHouse can authenticate users through LDAP, Kerberos, SSL X.509 certificates, an HTTP authenticator or JWT as external authenticators. Decide whether analysts log in to ClickHouse directly or only Metabase holds a service account, because that choice sets where access reviews happen. Confirm with your identity team which external authenticator fits, and test a revoked user before go-live.

Identity gap in open source Metabase

Open source Metabase supports Google sign-in and LDAP, but SSO through JWT, OIDC or SAML, advanced LDAP group sync, SCIM provisioning, row and column level permissions and usage auditing require the Pro or Enterprise plans. Plan this before rollout, because a team that needs SAML-based offboarding cannot meet it on the free edition. Ask Metabase for the current feature matrix before you commit to a plan.

Metabase application database and driver files

Metabase stores saved questions, dashboards, users and connection details in its application database, so restrict that PostgreSQL or MySQL account to the Metabase service, and encrypt its backups. Keep the clickhouse.metabase-driver.jar and the plugins folder writable only by the deployment account and verify file checksums against the driver release before deployment. Treat a changed JAR as a change request, not a routine update.

Keeping Metabase dashboards fast with materialized views

Dashboards over large event tables become slow for a simple reason: every filter a viewer changes makes Metabase send a query that scans raw rows again. A materialized view that aggregates into a target table lets dashboards read a much smaller summary table instead. In ClickHouse, a materialized view runs on each insert into a source table and writes its aggregated output into a target table, so the aggregation cost is paid as data arrives rather than every time someone opens a dashboard. Point the Metabase questions behind the dashboard at the target table, and keep the raw table for drill-downs and ad hoc investigation.

The most important design decision is the grain of the summary. Choose the time bucket (for example, hour or day) and the dimensions (for example, region, product or status) by reading the filters on each dashboard, then include only those columns in the aggregation. A grain that is too fine keeps the summary nearly as large as the raw data, while a grain that is too coarse blocks filters the business actually uses. Metabase's own filter widgets and any dashboard parameters should map to columns in the target table, so confirm with the dashboard owners which combinations they need before the view is created. Aggregate states and the target table engine also determine how partial results merge, so confirm the correct aggregate functions with your ClickHouse version's documentation.

Validate the view before any dashboard depends on it. Load a representative slice of data, run the questions your dashboards ask against both the raw table and the summary, and compare the results for totals, distinct counts and edge dates such as time zone boundaries. Check that the view still produces correct rows after a backfill, because a materialized view only processes data inserted after it was created unless you populate it deliberately. Ordering keys and projections on the target table then determine how quickly the remaining filters run, and the performance tuning group covers those choices in detail. Record the validated queries so you can rerun them after each ClickHouse or Metabase upgrade.

Testing the connection and dashboards before users rely on them

Metabase can show a dashboard that looks right while the connection, permissions or upgrade path are wrong. The cards below cover one test each, from the first sync to a restore check after an upgrade. DeployOpen does not set performance targets for your dashboards, so your team should define the acceptance criteria before the test run starts.

Connection and sync checks

Confirm that the ClickHouse connection in Metabase uses the read-only database user you created for analytics, not an administrative account. Run a sync and a field value scan, then check that the tables, columns and types Metabase shows match the schema in ClickHouse. Record which databases and tables were synced, because a missing or mistyped column found here is cheaper to fix than one found in a published dashboard.

Query results against direct queries

For each question that feeds a dashboard, run the same logic directly in ClickHouse and compare the totals, row counts and date boundaries. Pay attention to time zones, null handling and aggregations over partitions that Metabase may group differently. Keep the reference queries in version control so the comparison can be repeated after each Metabase or ClickHouse upgrade.

Dashboard load timing on representative data

Test dashboards against a dataset that has the volume, date range and cardinality of production, not a small sample. Time the first load and a filtered reload for each dashboard, and check how many queries each one sends to the cluster. Your team should set the acceptable load time in writing before the test. If the results miss it, review materialized views and aggregated tables as described in the performance guidance for this topic.

Permission checks for each role

Create one test user in each Metabase group and sign in as each one. Check that collections, saved questions, the native SQL editor and the database schemas each role can see match the access model you designed. Confirm that a user who should not see a table cannot reach it through a saved question, a filter or a drill-through. Record the results so an auditor or security reviewer can trace each role to what it can access.

Restore test after a Metabase upgrade

Before the production upgrade, back up the Metabase application database and restore it to a separate environment running the target version. Confirm that users, groups, dashboards, saved questions and database connections all come back and that the dashboards still render. Metabase runs application database migrations automatically during upgrades, so this test shows whether the migration succeeded on your data. Keep the restore procedure written down so it can be repeated during an incident.

Common Metabase to ClickHouse connection failures and fixes

This table pairs each common failure with its likely cause and a check you can run before changing settings. Work through the rows in order, since a missing driver or broken certificate chain hides every later symptom. The main takeaway is that most failures trace to file placement, network trust, grants or query shape rather than to ClickHouse itself.

Failure	Likely cause	Fix and check
ClickHouse missing from the database list after restart	The clickhouse.metabase-driver.jar file sits outside Metabase's plugins folder, or the folder is not the one the running Metabase process reads	Confirm the JAR is directly inside the plugins folder used by the running instance, restart Metabase, then check the startup log for the driver loading message
TLS handshake error when adding the database	The ClickHouse HTTPS certificate is issued by an internal CA that the Metabase JVM does not trust, or the chain is incomplete	Export the full chain from the ClickHouse endpoint and import the CA into the Java truststore used by Metabase; test the chain with an HTTPS client from the Metabase host first
Connection test times out	Firewall or load balancer between Metabase and ClickHouse blocks the HTTP(S) port, or the host resolves to an unexpected address	From the Metabase host, confirm name resolution and that the HTTP port is reachable; check the ClickHouse server is listening on the interface you configured
Queries time out on large tables	Dashboards run unaggregated scans over raw event tables with no filters or pre-aggregated tables	Add default date filters, check query duration in ClickHouse system query logs, and move repeated aggregations into materialized views as described in the performance section
Tables or schemas missing from the browser	The connecting user has no SHOW and SELECT grants on the target databases, or the default user was restricted and the Metabase user was not granted access	Run SHOW GRANTS for the Metabase user and confirm SELECT on each database and table; grant through a role rather than per user so access is repeatable
Nullable columns return unexpected blanks or zeros	Nullable columns are read without a null-aware filter, or aggregations treat NULL differently from the value the team expects	Compare a sample of rows in SQL with the Metabase result; add explicit IS NULL handling in the question or view and document how NULL is treated
Dates shift by hours in charts	Server timezone, column timezone and the Metabase report timezone differ, so DateTime values are converted twice	Check the column type for a timezone parameter, set the Metabase report timezone deliberately, and compare one known event timestamp across the database, SQL and dashboard

Questions teams ask before connecting Metabase to ClickHouse

Does the ClickHouse driver for Metabase cost anything, and which Metabase edition do I need?

The driver itself is a JAR file you download and place in Metabase's plugins folder, and the connection does not require a paid Metabase plan. Metabase's pricing page lists four plans: Open Source (free), Starter, Pro and Enterprise. Starter is listed at $100 per month, or $90 per month billed yearly, with the first 5 users included. Pro is listed at $575 per month, or $517.50 per month billed yearly, with the first 10 users included. Enterprise is priced by quote, starting at $20,000 per year. Confirm current prices on the pricing page before budgeting, since the cost you carry depends on user count and the plan you choose. Open Source is enough to connect a self-hosted ClickHouse cluster, so the main cost in your budget is usually the people and infrastructure that run it.

How much effort does a basic ClickHouse connection take compared with dashboard tuning?

A basic connection is mostly configuration: install the driver, create a read-only ClickHouse user, enter host, port, database and credentials, then confirm that Metabase can list tables. Dashboard tuning usually takes more time because it depends on table design. Dashboards that scan large event tables with unfiltered queries can slow down or load the cluster heavily. Effort goes up with the number of dashboards, the size of the largest tables, how often data refreshes, and how many questions use raw events rather than summarized data. Materialized views that pre-aggregate common queries are often the main tuning step, and their cost grows with the number of distinct breakdowns you need.

Can my team connect Metabase to ClickHouse without a partner?

Yes, a team with administrators for both systems can usually make a basic connection without an outside partner, because the driver is documented by ClickHouse and the steps are short. The harder parts are the ones that need judgment: choosing which tables and views dashboards should query, sizing the cluster for peak dashboard load, and deciding how analysts' access maps to ClickHouse users and roles. If your team has not run ClickHouse in production before, or if dashboards must serve many users under a governance model, a partner can help scope the work in writing before build starts. Ask any partner for a fixed scope and deliverables, since DeployOpen agrees scope, deliverables and timelines in writing before work starts.

What does this work need from my ClickHouse admins and Metabase owner?

The work needs at least two named owners. A ClickHouse administrator creates a dedicated read-only user, restricts the default user, grants access to the relevant databases and views, and confirms the network path from Metabase to the cluster. A Metabase owner installs the driver in the plugins folder, configures the connection, manages collections and permissions, and decides which data sources are exposed to which groups. Both should agree on the list of tables for dashboards, the expected query load, and the owner for refresh schedules. Where you run Metabase's application database on PostgreSQL, a platform or database team also needs to back it up before upgrades.

How do Metabase upgrades and driver upgrades interact?

Treat the Metabase version and the ClickHouse driver version as a pair that you test together. Metabase runs application database migrations automatically on upgrade, and its documentation recommends backing up the application database first. For major upgrades, Metabase recommends reducing a cluster to a single node because of a migration lock, and upgrading release by release when coming from versions older than 40. Metabase LTS versions are supported for 14 months, while non-LTS versions usually reach end of life after 2 months. Metabase 64 is an LTS release published on 16 September 2026 with end of life on 1 December 2027, and Metabase 65 was released on 12 October 2026. Confirm which driver release matches your Metabase version in the driver's release notes before upgrading either component, and test dashboards on a staging copy first.

Does SSO with Metabase require a paid plan?

Yes, SSO for most providers requires a paid plan. According to Metabase's pricing page, SSO, row and column level permissions, multi-tenant data segregation and usage analytics and auditing are included only in the Pro and Enterprise plans, not in Open Source or Starter. Open Source and Starter support Google sign-in and LDAP. JWT, OIDC, SAML (with documented setups for Auth0, Entra ID, Google, Keycloak and Okta), advanced LDAP group and attribute sync and SCIM provisioning require Pro or Enterprise. ClickHouse access itself is separate: the ClickHouse side can use its own authentication methods, so confirm early which identity model your dashboards need, because it affects both licensing and the user mapping you set up.

What should I check about the Metabase application database before connecting ClickHouse?

Metabase ships with an embedded H2 database that suits demos, and its documentation recommends PostgreSQL for production. MySQL 8.4.0 or MariaDB 10.6.0 and later with utf8mb4 are also supported. If you start on H2 and later move, Metabase documents a one-time load-from-h2 command, which must be run with the same Metabase version that last updated the H2 file. Decide this before building dashboards, because migrating later adds a step to your upgrade plan and needs a tested backup. Ask your team which database platform already has backup and restore procedures, and include that in the scope.

Upgrading Metabase and the driver without breaking dashboards

Treat every Metabase upgrade as a database migration first and an application upgrade second. Metabase runs application database migrations automatically when it starts a new version, so the application database must be backed up before any upgrade. Metabase's upgrading documentation recommends this backup, and it is the only practical rollback path if a migration fails midway. If your instance still uses the embedded H2 file, move the application database to PostgreSQL first, using the one-time load-from-h2 command run with the same Metabase version that last wrote the H2 file. Plan that move as its own change, not as part of an upgrade window.

For major upgrades, the documentation recommends reducing a clustered deployment to a single node because of a migration lock, so plan a short maintenance window in which only one instance is serving. If you are upgrading from a version older than 40, move through each release in order rather than jumping straight to the newest line. Choose your target line deliberately. Metabase 64 is an LTS release published on 16 September 2026 with end of life on 1 December 2027, according to the version support page, and LTS lines receive support for 14 months. Non-LTS releases, such as Metabase 65 (released 12 October 2026), usually reach end of life after about 2 months. Most organizations serving governed dashboards to business users should stay on an LTS line and move during its support window, while teams that need newer features accept more frequent upgrades.

The ClickHouse Metabase driver is a separate artifact, clickhouse.metabase-driver.jar, placed in the plugins folder. After every Metabase upgrade, confirm that the driver version you run is the one listed as compatible with the new Metabase release, and replace it in the same change if not. Then test on a staging instance restored from a recent application database backup. Open your most-used dashboards, run the saved questions that drive scheduled reports, and compare row counts and filter results against production. Confirm that the connection to ClickHouse still uses the read-only user you configured. Check the Metabase version support page and the driver release notes for the exact compatibility statement before you schedule the change.

How DeployOpen scopes and delivers a Metabase to ClickHouse connection

DeployOpen plans, installs, configures and documents the Metabase to ClickHouse connection inside infrastructure you control. We start from a written scope that names the ClickHouse cluster, the Metabase deployment and the dashboards in use, then build and test the connection in a pre-production environment before anything reaches users.

How we scope

We list the ClickHouse cluster, databases and tables that Metabase will query, with owners for each.
We agree which Metabase version, application database and plan features the connection depends on.
We define the read-only ClickHouse users, network paths and TLS requirements before any build work begins.

How we build

We install the ClickHouse Metabase driver JAR in the plugins folder and confirm it loads on your Metabase version.
We configure connection settings, test query behavior on representative data, and tune slow dashboards with materialized views where needed.
We test restores of the Metabase application database and rehearse the upgrade path in a spare environment.

How we hand over

You receive a written record of connection settings, user roles, driver version and the dashboard query patterns adopted.
We walk your operators through the upgrade steps, driver replacement and backup checks for the Metabase application database.
Deliverables are agreed in writing at the start, and handover is complete only when they are accepted against that scope.

How we support

Engagements are fixed-scope, so changes after handover go through a written change request with its own scope.
Ongoing support, upgrades and continuous testing are available as a retainer if you want DeployOpen to keep the connection current.
Before any Metabase or ClickHouse upgrade, we review release notes and run the connection against a pre-production copy.