How Apache Superset connects to ClickHouse for real-time dashboards
Superset reaches ClickHouse through the clickhouse-connect driver, which Superset uses via a SQLAlchemy connection string added to the Superset environment. Superset itself does not store or process your event data. It sends SQL to ClickHouse, receives result sets, and renders charts and dashboards from them. That split decides who owns what: your team owns the Superset deployment, its metadata database, the driver installed into the Superset image, the database connection definitions, the roles that govern who can query which tables, and the network path between Superset and ClickHouse. ClickHouse owns query execution, storage, replication and its own user and access controls, which you still have to configure for the accounts Superset uses.
Both products are open source under the Apache License 2.0 (SPDX: Apache-2.0). Apache Superset is an Apache Software Foundation project with no paid edition, and the ClickHouse server is open source under the same license. ClickHouse Inc. separately sells ClickHouse Cloud as a managed service. Choosing self-hosted ClickHouse keeps the data plane in your infrastructure, but it also means you own cluster sizing, Keeper nodes, upgrades and backups. Choosing ClickHouse Cloud moves some of that operational work to the vendor and changes the network, identity and data residency questions you need to answer. Confirm with your ClickHouse provider which options apply to your region and compliance scope before you commit to an architecture.
Before you build, confirm three things in your environment: which ClickHouse version you will run, which driver version your chosen Superset release expects, and which ClickHouse account Superset will use for dashboards. The driver and version requirements change across Superset releases, so check the Superset documentation for the release you deploy and test the connection in a staging environment with representative tables. Pay attention to the account: a dashboard service account that can read every database is the most common way a convenient integration becomes an over-permissioned one. Plan the ClickHouse user, its quotas and its allowed databases as part of the design, not as a cleanup step after the first dashboards go live.
What you need before connecting Superset to ClickHouse
Connecting Superset to ClickHouse depends on four sets of choices: the Superset release and its metadata database, the Python driver inside the image, the ClickHouse release line and account the connection uses, and the network and TLS path between them. Settle these before any connection string is written, because a mismatch in any one of them shows up later as a connection failure or as an access problem nobody expected.
Superset release and metadata database
Start by fixing the Apache Superset release, since driver requirements and supported platform versions change between releases. The metadata database must be PostgreSQL or MySQL for production, and the configuration documentation lists PostgreSQL 10 to 17 and MySQL 5.7 and 8.x as supported versions. Confirm your chosen Superset release against those lists. Keep the metadata database separate from ClickHouse, because Superset stores its own users, roles and dashboards there.
Driver inside the Superset image
Superset does not ship every database driver, so the image must contain clickhouse-connect. Pin its version to the one that matches your Superset release, and confirm that pairing in the Superset documentation for that release rather than assuming the latest package works. Build the image from your own Dockerfile or pinned base so the driver version is recorded, tested in staging and reproducible during upgrades.
Supported ClickHouse release line
Choose a ClickHouse release line that appears in the security policy as supported with security updates. The policy lists 26.9, 26.8, 26.7 and 26.3 as supported, and all other versions as unsupported. Stable releases ship roughly monthly, while LTS releases ship twice a year and are supported for a year. Decide which line you will track and who applies patches, because an unsupported ClickHouse version left in place becomes a security exposure on the analytics path.
Read-only ClickHouse account
Create a dedicated ClickHouse user for Superset with read-only grants on the databases and tables that dashboards need. Do not reuse an administrative or write-capable account, and do not let Superset's SQL Lab run statements the dashboard owners never intended. Access control in ClickHouse is defined through users, roles and grants, so confirm the grant model and any row-level restrictions with your data owners before the first dashboard is built.
Network path to the ClickHouse port
Map the route from the Superset web and worker containers to ClickHouse, including any load balancer, proxy or firewall rule in between. Confirm which ClickHouse port your deployment exposes for HTTP and which for the native protocol, and open only those from the Superset hosts. Superset workers also run queries for alerts and reports, so the path must work from the worker network segment, not only from the web tier.
TLS certificates and trust chain
Decide whether the connection uses TLS and which certificate authority signs the ClickHouse server certificate. The Superset container must trust that authority, which usually means adding the CA bundle to the image and referencing it in the connection settings. Check certificate expiry dates and hostnames against the name Superset will use, because a mismatched name or an expired certificate fails at connection time, often only after deployment.
Replicated ClickHouse and failover targets
If ClickHouse runs as replicas coordinated by ClickHouse Keeper, decide which host or endpoint Superset connects to and what happens when that node is down. Replication keeps data available, but it does not protect against human error or corruption, so backups remain a separate prerequisite. Ask your ClickHouse operators which endpoint is stable for dashboards and confirm that a restore test has been planned on a spare cluster.
Configuring the ClickHouse connection in Superset
This sequence takes a self-hosted Superset from a standard image to a ClickHouse dashboard that a restricted role can open. Each step ends with a check you can run, so a failure is caught where it was introduced. Confirm driver, URI and port details against the Superset and ClickHouse versions you deploy.
Build the image with the ClickHouse driver
Your platform team adds the
clickhouse-connectPython driver to the Superset image, since the stock image does not include it. Build the image in your own registry, pin the driver version, and record both in your image manifest. Done means the new image starts in staging, the web and worker containers load without import errors, and the driver version appears in the image's installed package list. Ask your Superset provider or internal team to confirm which driver version matches the Superset release you run.Create a read-only ClickHouse user
A ClickHouse administrator creates a dedicated user for Superset that can only read the analytics databases it needs. Use the access control model in ClickHouse to create the user, grant SELECT on specific databases or tables, and deny write and administrative privileges. Keep this account separate from Superset's own metadata database and from any ingestion accounts. Done means a query run as this user succeeds on the permitted tables and fails with an access error on a table outside the grant.
Confirm the port and build the SQLAlchemy URI
The Superset admin enters the database connection in the Superset UI under Settings, then Database Connections, using the SQLAlchemy URI for the ClickHouse dialect supplied by the driver. The URI carries the user, password reference, host, port and default database. Confirm the HTTP or HTTPS port your ClickHouse cluster exposes with the ClickHouse administrator, because the port depends on how your cluster is configured. Store the password through your secrets process instead of typing it into a shared document. Done means the connection form saves without a validation error.
Set the SSL options for the connection
The Superset admin enables TLS on the connection so credentials and result data travel encrypted between Superset and ClickHouse. Set the secure option in the connection parameters, and if your organization uses an internal certificate authority, mount that CA bundle into the Superset containers and point the driver at it. Confirm the exact parameter names in the driver's documentation for your version. Done means the connection test in the next step succeeds with certificate verification enabled, not with verification turned off.
Test the connection and run a query in SQL Lab
The Superset admin uses the Test Connection button in the database dialog, then opens SQL Lab and runs a short query against a permitted table, such as a count with a LIMIT clause. The test confirms network reachability, authentication and TLS, while the SQL Lab query confirms that the read-only user can see the expected schema. Done means the test returns success and the query returns rows. If the query returns an error on a table you granted, check the grant and the default database in the URI before changing anything else.
Create a dataset and chart as a restricted role
The Superset admin creates a dataset from the ClickHouse table, then builds a first chart on a time-series column. Next, sign in as a user assigned only the role that should see this data, and open the chart from a dashboard. Test that the restricted user sees the dataset and cannot open the database connection settings or run SQL Lab against it if your policy forbids that. Done means the chart renders for the restricted role, the data matches the SQL Lab result, and the role cannot reach tables outside its grant.
Driver version requirements across Superset releases
Apache Superset 6.0.0 was published on December 18, 2025, according to PyPI. Teams that run this line and connect ClickHouse should first record the clickhouse-connect version their image installs, because that version is the baseline every later upgrade is measured against. Confirm the driver release named in the 6.0.0 documentation for ClickHouse before treating the current install as a supported combination.
- Baseline record: Capture the Superset image tag and the exact clickhouse-connect version inside it before making any change.
- Documentation check: Read the 6.0.0 database connection notes for ClickHouse and note the driver and minimum version they name.
- Dashboard inventory: List the charts, datasets and SQL Lab saved queries that read from ClickHouse, since these are the first items to fail after a driver change.
- Patch releases: Review the 6.0.x entries on the releases page to see whether any patch changed driver expectations.
Before planning any move off this line, read the 6.0.0 entries in UPDATING.md so you know which breaking changes apply to your ClickHouse connections.
Apache Superset 6.1.0 was published on May 13, 2026, according to PyPI, and its documentation describes Kubernetes installs with the official Helm chart. An upgrade from 6.0.x to 6.1.0 crosses every release in between, so the driver check should cover each UPDATING.md entry in that range, including entries that look unrelated to databases. Treat the driver expectation for 6.1.0 as a separate fact to confirm, because the documentation for one line does not automatically carry over to the next.
- Upgrade range: List every release between your current version and 6.1.0, then read each UPDATING.md section in that range.
- Driver expectation: Confirm the clickhouse-connect version named for 6.1.0 and compare it with the version you have pinned.
- Deployment path: If you deploy with the Helm chart, confirm the chart version and the Superset image tag it references, since the chart and the image can drift apart.
- Migration steps: Run the database upgrade and init steps in staging against a copy of the metadata database, following the upgrade guide.
Do not promote a 6.1.0 image to production until a ClickHouse dashboard test passes against the pinned driver in staging.
The GitHub releases page lists 7.0.0rc2 as a pre-release published on October 16, 2026. A release candidate is a test artifact, so any driver expectation recorded for it can change before the final 7.0.0 release. Use it to learn what is likely to change and to start your test plan.
- Status check: Confirm on the releases page whether a final 7.0.0 release exists before you set a production date.
- Early testing: Build a separate test image from the release candidate and run your ClickHouse dashboards against it.
- Documentation drift: Watch for changes to the ClickHouse connection notes in the documentation and UPDATING.md between the candidate and the final release.
- ClickHouse versions: Test against the ClickHouse lines listed as supported in its security policy, which currently include 26.9, 26.8, 26.7 and 26.3.
- Driver records: Log every clickhouse-connect version you test, with the result, so the final decision rests on recorded evidence.
Repeat the full check against the final release, because a candidate result does not show that the final build behaves the same way.
A container build that installs the latest clickhouse-connect picks up a new driver whenever the image is rebuilt, even if Superset itself has not changed. Pinning the driver version in the requirements that your image build reads makes the driver a reviewed change. Retesting after every Superset upgrade confirms that the pinned pair still works, and both steps should sit in the same change record so the decision can be traced later.
- Exact pin: Set clickhouse-connect to a specific release in the build input rather than a version range that can float.
- Image tag: Tag each image with both the Superset version and the driver version so a rollback restores both together.
- Retest set: Test the connection, schema browsing, chart queries, SQL Lab queries, caching behavior and any restricted function checks you have configured.
- Rollback path: Keep the previous image and a verified metadata database backup until the new release has run in production for an agreed period.
Ask your team to confirm, in writing, which driver version each production image contains and when that version was last tested against your ClickHouse dashboards.
Mapping ClickHouse users, roles and databases to Superset
This table separates the four access layers in a Superset and ClickHouse setup: the ClickHouse login, the ClickHouse grants, the Superset roles and the Superset data rules. Read each row as a decision to make on its own, because a user can be allowed in one layer and blocked in another. The main takeaway is that Superset roles do not replace ClickHouse grants, so the database account behind each Superset connection should hold only the privileges its dashboards need.
| Layer | What it controls | Decision to make | Where it usually fails |
|---|---|---|---|
| ClickHouse login | Who can authenticate to ClickHouse using LDAP, Kerberos, X.509, HTTP or JWT external authenticators | Whether Superset connects with a shared service account or with per-user credentials | Shared service accounts hide the real user in ClickHouse logs and query history |
| ClickHouse grants | Which databases, tables and columns the connecting account can read, set by users, roles and grants | A read-only role per dashboard area, granted only the databases and tables it needs | Broad grants on default or all databases, or write privileges left on the Superset account |
| Superset database connection | The SQLAlchemy URI and credentials that Superset uses for one ClickHouse data source | One connection per access tier, not one connection for every team | A single connection with admin rights shared across all dashboards |
| Superset datasets and roles | Which datasets, charts and dashboards each Superset role can see and edit | Role design in Superset that matches the business groups who need each dataset | Users who receive the Admin role or extra data access by default |
| Superset row level security | Filters added to every query on a dataset based on the logged-in user's attributes or roles | Filter rules for tenant, region or department data held in shared ClickHouse tables | Filters defined only in Superset, so anyone with direct ClickHouse access bypasses them |
| Group mapping with AUTH_ROLES_MAPPING | Translates LDAP or OAuth groups from the identity provider into Superset roles at login | Which directory groups map to which Superset roles, and who maintains that mapping | Stale group names after directory changes, or groups mapped to roles that are broader than intended |
| Audit and attribution | Whether query logs show the person or only a service account | Whether per-user ClickHouse identities are required by your audit or access review process | Logs show one account for every dashboard viewer, weakening access review evidence |
Hardening the Superset to ClickHouse connection
Superset sends whatever SQL its users are allowed to run straight to ClickHouse, so the database account, the transport, the stored credentials and the Superset application settings all share the job of limiting what a dashboard user can reach. Each card below covers one of those layers and the check to run before go-live.
Read-only ClickHouse accounts
Give Superset its own ClickHouse user that can only read the databases and tables that dashboards need. Use the grant model described in the access control documentation to scope SELECT rights per database and table, and confirm the exact privilege names against your ClickHouse version. Do not reuse the default account or an administrator login. Test the account by attempting an INSERT or DDL statement through SQL Lab and confirming it is refused.
TLS on the ClickHouse connection
Encrypt traffic between Superset workers and ClickHouse, and between the browser and Superset. Confirm which ClickHouse port and protocol your clickhouse-connect configuration uses, enable TLS on that endpoint, and set certificate verification on the Superset side so the client checks the server certificate instead of accepting any certificate. Ask your platform team which CA signs internal certificates and whether it must be added to the Superset image.
Credentials kept out of plain config
Database passwords entered in the Superset UI are stored in the metadata database, and a password written into superset_config.py is visible to anyone who can read the image or repository. Load the connection password from an environment variable or a secrets manager at container start, and restrict who can open database connection settings in Superset. Plan how the secret is rotated on the ClickHouse side and updated in Superset without a rebuild.
SECRET_KEY and session settings
Superset requires a user-specified SECRET_KEY to start, and that key signs sessions and encrypts stored connection secrets. Generate a strong value, keep it in the same secret store as the ClickHouse password, and use PREVIOUS_SECRET_KEY when rotating so existing sessions and stored secrets remain readable. Review session lifetime and cookie flags in the configuration documentation, and confirm the chosen values with your security team before the first production login.
Disallowed functions and SQL Lab limits
Superset restricts certain SQL functions by default, and ClickHouse offers table functions that read files or reach remote hosts. Review the disallowed-function list in your Superset version, then decide whether any ClickHouse table functions that reach outside the cluster should also be blocked at the database account level. Limit who can use SQL Lab, and set query timeouts and row limits so a single analyst query cannot scan a full event table.
Verification before go-live
Write a short test list covering the read-only account, the refused write statements, the TLS handshake, the absence of plain-text passwords in config and the SECRET_KEY rotation path. Run it in staging against a copy of production schemas, then repeat it after each Superset or ClickHouse upgrade. Keep the results as evidence, since security reviewers will ask how each control was tested rather than how it was described.
Questions teams ask before connecting Superset to ClickHouse
What drives the cost of connecting Superset to ClickHouse?
The main cost drivers are the number of datasets, dashboards and users in scope, and how ready your ClickHouse cluster and access model already are. Costs fall into a few parts: design and build work in a written scope, testing of queries and roles, the infrastructure that runs Superset and ClickHouse in your environment, and any replication or backup work on ClickHouse itself. The ClickHouse server is open source under the Apache License 2.0, so the server carries no license fee, while ClickHouse Cloud is a separately sold managed service if you choose it. One-time costs are design, build and initial testing. Recurring costs are infrastructure, staff time for upgrades and any support retainer. Ask any quote to list these lines separately and to state who pays for each.
How long does a first ClickHouse connection and dashboard take?
A basic connection test can be short once network paths and credentials exist, but the first useful dashboard usually takes longer because of data modeling and query tuning. The biggest timing factors are whether the ClickHouse cluster is ready, how quickly firewall changes and access requests are approved, how many tables and sources are involved, and how well table design fits the queries your dashboards run. Columnar tables that were not designed around filter and sort patterns often need rework before dashboards feel responsive. Review, staging and sign-off also add time. Your partner should give a timeline in the written scope, and you should ask which of these steps it assumes you will complete.
What must our team provide before the integration starts?
Your team typically provides three things: access, network changes and sample data. Access means an administrator who can create a read-only ClickHouse user and roles, as described in the ClickHouse access control documentation, plus admin rights in your Superset instance. Network changes mean allowing traffic from the Superset hosts to the ClickHouse ports used by your chosen driver, which you should confirm against the driver documentation for your Superset release. Sample data means representative tables and the queries your business users actually ask, so the team can test performance and results before anything goes live. A staging environment and change windows are also needed.
Can our internal team connect Superset to ClickHouse alone?
Yes, a team that already runs Superset and operates ClickHouse can usually make the basic connection without outside help. The harder parts are usually elsewhere: designing ClickHouse tables for dashboard query patterns, defining roles and row-level access that match your access model, setting resource limits so dashboards do not overload the cluster, and proving that backups restore. Those skills are less common than basic configuration knowledge. Check whether your team has experience with columnar storage, replicated tables and restore testing. A partner can cover the gaps in a fixed-scope engagement, or your team can handle the work and bring in help only for specific reviews.
How do driver and version upgrades affect existing Superset dashboards?
Upgrades can change generated SQL, type handling or which functions are allowed, so dashboards that worked before may fail or show different numbers afterward. Upgrade risk comes from three sources: the Superset release, the ClickHouse driver version it requires, and the ClickHouse server version. Confirm the driver version required by your Superset release in its documentation before you upgrade anything. Follow the Superset upgrade guide, which asks you to back up the metadata database, test in staging and review UPDATING.md for breaking changes. Keep a set of key charts with known results so you can compare values after each change. Read the ClickHouse changelog too, because minor backward-incompatible changes can occur.
Which ClickHouse versions should we connect Superset to?
Connect to a ClickHouse version that still receives security updates. ClickHouse's security policy lists versions 26.9, 26.8, 26.7 and 26.3 as currently supported, and all other versions as unsupported. Stable releases ship roughly monthly, and LTS releases ship twice a year and are supported for a year after release. The ClickHouse production guidance recommends stable releases for most production use, with a pre-production environment that uses representative data and queries. Choose a release line that matches your patching cadence, then confirm the current support status on the security policy page before you set up the connection, because support windows move with each release.
What happens to dashboards if a ClickHouse node fails?
Replicated tables keep data available if one replica fails, but replication is not a backup. ClickHouse replicates data with ReplicatedMergeTree tables coordinated by ClickHouse Keeper, and its replication guide recommends at least three Keeper nodes on dedicated hosts in production, with about 4 GB of RAM each. A recovered replica automatically syncs missing data from a healthy replica. Replication does not protect against human error, bad deletes or corruption that spreads to every copy. For that, use the BACKUP and RESTORE commands to local disk, S3-compatible storage or Azure Blob Storage, and test restores on a spare cluster on a regular schedule, because an untested backup often fails when you need it.
Common ClickHouse connection failures in Superset and their fixes
This table lists the failures teams most often hit when connecting self-hosted Superset to ClickHouse, with the likely cause and the fix for each. Use it as a triage checklist: match the error to a row, confirm the cause in your own image, configuration and ClickHouse grants, then apply the fix in staging before production.
| Failure | Likely cause | Fix |
|---|---|---|
| Driver not found when adding the database | The Superset image was built without the clickhouse-connect package, so the ClickHouse option cannot load. | Add clickhouse-connect to the image build, rebuild, and confirm it imports inside both the web and worker containers. |
| Errors after a Superset upgrade | The new release changed bundled dependencies or the driver range it supports. Check the breaking change notes in UPDATING.md for the target version. | Pin a driver version the target release supports, back up the metadata database, test in staging, then run the documented upgrade steps. |
| Connection refused or protocol errors | The connection string points at a port or protocol that the ClickHouse server does not expose, or TLS is set on a plain port. | Confirm the HTTP and native interface ports and TLS settings in the ClickHouse server configuration, then test the same string from inside the Superset container. |
| TLS certificate verification fails | The ClickHouse certificate comes from an internal authority that the Superset image does not trust, or the certificate name does not match the host in the connection. | Mount your CA bundle into the image and reference it in the connection's TLS settings. Keep certificate verification on in production. |
| Permission denied on tables or databases | The database user lacks grants on the target database or tables. ClickHouse grants apply per user and per role. | Create a read-only role with SELECT on the required databases and tables, assign it to the Superset user, and test with that exact user and default database. |
| Timeouts on large scans | Dashboard queries read more data than the web request or proxy timeout allows, or they run synchronously against large time ranges. | Add time filters, use aggregated views or materialized tables for dashboards, enable async queries with caching, and raise timeouts only after reviewing query cost. |
| Disallowed function errors | Superset blocks certain SQL functions by default, so a ClickHouse-specific function in a chart or virtual dataset is rejected. | Rewrite the query with an allowed equivalent. If the function is needed, review the disallowed list with your security team, change it deliberately, and record the decision. |
| Async queries, alerts or thumbnails never finish | The caching layer or Celery worker and beat processes are not running, so work that depends on them stays queued. | Confirm the cache and worker services are running and connected to the same configuration as the web application, then retry a test report. |
Keeping ClickHouse behind Superset reliable and recoverable
Replication is not a backup. ClickHouse keeps data available by replicating ReplicatedMergeTree tables across nodes coordinated by ClickHouse Keeper, and a recovered replica catches up from a healthy one without manual work. That protects against hardware loss, but a bad DROP TABLE, a faulty ETL job or a corrupted part is copied to every replica. For a Superset deployment, the practical decision is to schedule backups with the BACKUP and RESTORE statements to storage outside the cluster, covering full and incremental backups of the databases that dashboards read. Confirm with your team where those backups land (local disk, S3-compatible storage or Azure Blob Storage) and who holds the credentials to restore them.
A backup that has never been restored is an assumption. Plan regular restore tests on a spare cluster, and time them, so you know how long a dashboard outage would last before an incident forces the question. Check that the restored tables answer the queries in your saved Superset charts, not just that the restore command finished. Keep the Superset metadata database on its own backup schedule, because charts, datasets and dashboard definitions live there, not in ClickHouse.
Upgrades need the same discipline. ClickHouse's security policy lists 26.9, 26.8, 26.7 and 26.3 as the release lines currently receiving security updates, and all other versions are unsupported, so a cluster on an older line should be on the roadmap before it falls out of support. The production FAQ recommends stable releases for most production use, a pre-production environment with representative data and queries, and reading the changelog first because minor backward-incompatible changes can occur. Test each upgrade against the query patterns your Superset dashboards actually run, and confirm the driver version in Superset still connects to the target release before you change the production cluster.
How DeployOpen scopes and delivers the Superset and ClickHouse integration
DeployOpen plans, builds, tests and documents the connection between self-hosted Apache Superset and ClickHouse inside your own infrastructure. Each engagement starts from a written scope that covers the driver, the access model, the network path and the handover, so your team knows what was built and how to run it.
How we scope
- Written scope covers the Superset release, ClickHouse version line and driver versions agreed up front.
- Scope lists which datasets, dashboards and real-time use cases the connection must serve.
- Scope records the ClickHouse users, roles and network paths that Superset will use to connect.
How we build
- We install the clickhouse-connect driver into the Superset image and verify the connection string and port.
- We configure read-only ClickHouse accounts and restrict functions Superset disallows by default.
- We test query limits, timeouts and dashboard refresh behavior against representative data before go-live.
How we hand over
- Handover documents the connection configuration, driver pinning, role mappings and the ClickHouse access model.
- Runbooks explain how to test a ClickHouse backup restore and how to plan Superset and driver upgrades.
- Your team receives a verification checklist that confirms the integration after each change.
How we support
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
- Ongoing support, upgrades and continuous testing are available as a retainer.
- Retainers can cover driver and ClickHouse version reviews when your team plans an upgrade.
