Apache Superset and MySQL integration

How Apache Superset connects to MySQL and MariaDB

A team that wants dashboards over MySQL or MariaDB data should not point Superset at the production primary. Superset reaches MySQL through the mysqlclient driver, using the connection string mysql://{username}:{password}@{host}/{database} on port 3306, as listed in the Superset database catalog. Superset itself is licensed under Apache-2.0 and has no paid edition, so the database connection is the part of this design that carries cost and risk. Confirm the driver package and string against the catalog entry for your Superset release before you build the image, because the packaging of database drivers is part of what you install into the container.

The MySQL connection is a database connection inside Superset, not a separate Superset module. You register it under Settings, Database Connections, and it becomes one of several sources that charts and datasets can use. This is easy to confuse with the metadata database, which holds Superset's own users, dashboards, charts and saved queries. The metadata database is configured through SQLALCHEMY_DATABASE_URI in the Superset configuration, and it should be a separate database from the MySQL analytics source. Keep the two apart in your design and in your credentials, so that a dashboard query can never touch the tables Superset uses to run itself.

MariaDB is handled the same way at the Superset level, but the server behavior differs, so confirm the driver and version support for the MariaDB release you run instead of assuming MySQL behavior carries over. Before you go live, decide which account Superset uses, whether it is read-only, and whether the source is a replica that has acceptable lag for dashboard freshness. Ask your platform team to confirm the replica's replication lag targets and the TLS settings they require, since the transport and the source choice both determine what a dashboard user actually sees.

What you need before connecting Superset to MySQL

Connecting Superset to MySQL involves two separate database roles: the metadata database Superset uses for its own state, and the analytics source it queries for charts. Confirm the versions, network path, TLS trust and account scope for each before you write the connection string.

Metadata database version

Superset stores its dashboards, users and settings in a metadata database, which is separate from the MySQL source you chart. The configuration documentation lists MySQL 5.7 and 8.x as supported for that role, alongside PostgreSQL 10 to 17. Confirm which of these your metadata database runs before you plan a MySQL analytics source on the same instance, and keep the two databases apart.

MySQL server line

Choose the MySQL line your organization will support before you pick a driver version. The MySQL Community Server download page currently offers 26.7.0 as an Innovation release, 9.7.2 LTS, 8.4.11 LTS and 8.0.46. Innovation releases are supported only until the next Innovation release, so an LTS line usually fits a dashboard source that changes slowly. Confirm the line with your database team and your support policy.

MariaDB as an alternative

MariaDB is a MySQL-compatible server that the Superset database catalog does not list under the MySQL entry, so treat it as a separate connection decision. Candidate lines to evaluate are 11.8, 12.3 LTS and 10.11. Confirm with your team that the connection string, driver and TLS behavior work on the exact MariaDB version you select, and that it matches the platform you already operate.

Network path on port 3306

The Superset web and worker processes open the database connection, not your browser, so the firewall rules must allow traffic from those hosts to the MySQL server on port 3306, the default port. Check each hop between the Superset network and the database, including security groups, host firewalls and any proxy. If you run Celery workers for async queries, include their hosts in the rule set.

CA certificate for TLS

Obtain the certificate authority that signed the MySQL server certificate and make it available to the Superset container or host. Without it, the driver cannot verify the server, and you may be tempted to disable verification. Ask your database team whether the server requires TLS for all connections, and confirm how the certificate will be mounted and rotated, since a renewed server certificate can break connections.

Read-only analytics account

Create a dedicated MySQL account for Superset that holds only SELECT on the schemas it charts, with no write, DDL or administrative privileges. Limit its host pattern to the Superset network, and do not reuse the application account or the metadata database account. Ask your DBA to confirm that the account can read replica data if you point dashboards at a read replica, and document who owns the credential and its rotation.

Configuring the MySQL connection in Superset step by step

This sequence takes a self-hosted Superset from no MySQL connection to a verified, queryable database that dashboards can use. Each step ends with a check so the team knows whether to move on or stop and fix the problem.

Confirm the MySQL source and access account
Before touching Superset, the database owner confirms the MySQL or MariaDB host, port, database name and the account Superset will use. The account should be a dedicated read-only user with SELECT on the analytics schema and no write or administrative privileges. Ask the database team to confirm that the Superset host can reach the port, which is 3306 by default, and that the source is a read replica if one exists. Done when the team has a written list of host, port, database and account name, and a direct client login with that account succeeds from the Superset host.
Install the mysqlclient driver into the Superset environment
The platform team adds the mysqlclient package to the Python environment that runs Superset, including the web server and any Celery workers, so every process that runs queries can open MySQL connections. In containerized deployments this means building it into the image rather than installing it into a running container, so the change survives restarts and redeploys. Done when the driver imports cleanly inside the same environment that runs Superset, for example from a shell in the running web container, and the build pipeline records the version that was installed.
Build the SQLAlchemy connection string
The team writes the URI in the catalog format mysql://{username}:{password}@{host}/{database}, adding the port if the server does not use 3306. Passwords with special characters must be URL-encoded, and TLS options should be added according to the server's certificate setup, which the database team confirms. Store the password in a secret store or the Superset database connection settings rather than in a shared file or version control. Done when the complete URI has been assembled and reviewed by a second person, with the password supplied out of band.
Add the database in Superset
A Superset administrator adds the database through the UI under database connections, pasting the connection string and selecting the MySQL option so the correct dialect is used. Where the team manages configuration as code, the same connection is defined in the deployment configuration and loaded at startup instead. Limit which roles can create or edit database connections, since this step determines which data every dashboard can reach. Done when the database appears in the connection list with the expected name and no error is shown on save.
Test the connection from the Superset UI
The administrator uses the test connection action in the database settings. A successful result confirms that the driver loaded, the host resolved, the port accepted the connection and the credentials were accepted. If the test fails, the error message usually points to the driver missing from the image, a DNS or firewall block, a TLS mismatch or a wrong password, and each cause is fixed at its source before retrying. Done when the test returns success from the Superset host, and the same result is seen from the worker environment if Celery is used for async queries.
Confirm query results against a direct query
In SQL Lab, an analyst runs a bounded query against a known table, such as a SELECT COUNT(*) with a filter, and runs the same query directly with the MySQL client using the same read-only account. The two row counts and a sample of values should match. Mismatches usually come from a wrong database or schema selection, a different replica than expected, or time zone and character set differences in the connection. Done when the counts match and the team has recorded the test query for reuse.
Build a dataset and check a dashboard refresh
The analyst registers the table as a Superset dataset, creates a simple chart and adds it to a dashboard. The team then confirms that the chart renders, that the query appears in the query history, and that a second load within the cache window does not reach MySQL again. Cache behavior should be verified against the caching layer the team has configured, since the caching layer and workers are optional components. Done when the dashboard loads with values that match the direct query and the team can see from the query logs when a request reached the database.

Why mysqlclient, TLS settings and the read-only account matter

The Superset database catalog lists mysqlclient as the driver for MySQL, paired with the connection string mysql://{username}:{password}@{host}/{database} and default port 3306. Install the driver into the image or virtual environment used by every Superset process that runs queries, not only the web server. That includes Celery workers, which execute async queries, alerts, reports and thumbnail rendering when those features are enabled. A worker without the driver will fail on exactly the scheduled jobs that stakeholders rely on, so confirm the package in each container and test a scheduled report against the MySQL source before go-live. If you connect to MariaDB, confirm with your Superset version and image build that the same driver path works against your MariaDB release, since MariaDB keeps a high degree of MySQL compatibility but is a separate server product.

Encryption in transit is set per database connection. Depending on your setup, you pass the CA, client certificate and key through the engine parameters or the Secure Extra field in the connection settings, and you should require verification of the server certificate rather than accepting any certificate the server presents. Ask your DBA which CA signed the MySQL or MariaDB server certificate, whether the server requires client certificates, and what hostname the certificate names, because a mismatch will break verification in ways that look like network faults. Then confirm the TLS setup on the server side matches what Superset expects: the server should have TLS enabled for the account Superset uses, and the test connection should show an encrypted session. Check the exact parameter names against the Superset configuration and driver documentation for your release, because these settings are version-dependent.

Create a dedicated analytics account that holds only the SELECT privileges on the schemas and views Superset needs, and give it no write, DDL or administrative rights. This limits what a compromised Superset account or a mistaken SQL Lab query can change, and it gives auditors a clear identity to review. It is not a substitute for network controls, though. A SELECT-only user can still read everything it is granted, can still exhaust server resources with expensive queries, and can still reach the database from any host that has a route to it. Restrict the database port to the Superset and worker subnets, enforce TLS, and decide with the data owners whether the account should see personal data at all. Ask your team to document the grants, the source addresses allowed to connect and who approves changes to either.

Pointing dashboards at a read replica or the primary

Connecting Superset straight to the primary is the simplest option. There is no second endpoint to maintain, no replication to monitor, and dashboards show the latest committed rows. The cost is that every chart query, filter change and scheduled report competes with the application for CPU, memory, I/O and locks on the system that serves customers. Analytical queries scan many rows, which is the opposite of what a transactional workload is tuned for.

Simplicity: one connection, one set of credentials, and no lag to explain to users.
Load risk: long dashboard queries can slow application writes and reads, especially at peak business hours.
Lock exposure: large scans and long-running statements can hold resources the application needs.
Limit control: you can restrict the Superset database user with privileges and session timeouts, but you cannot isolate the work from the primary's hardware.
Fit: reasonable for small datasets, low concurrency or read-only reference data that dashboards query lightly.

Before choosing this option, ask your DBA to measure current primary utilization at peak and confirm which queries Superset will generate under real filter use.

How Superset database settings map to MySQL objects

This table shows which Superset database settings point at which MySQL objects, so you can see what changes between development, staging and production. Read each row as a question to answer for your environment: which account, which endpoint, which schema and which privileges. The main takeaway is that the Superset connection should use a dedicated read-only MySQL account pointed at a replica or reporting endpoint, not an application account on the primary.

Superset setting	MySQL object	What to set or confirm
Database connection name	Schema or database	Name the Superset connection after the MySQL database it reads, so dashboards and audits trace back to one schema.
Username in the SQLAlchemy URI	MySQL account	Use a dedicated analytics account, not the application account, and confirm it exists for the right host pattern.
Password in the SQLAlchemy URI	Account credential	Store it in a secrets mechanism your team controls and rotate it on a schedule your security policy sets.
Host in the SQLAlchemy URI	Network endpoint	Point to the replica or reporting endpoint for dashboards, and confirm the Superset host can reach port 3306 or your custom port.
Database in the SQLAlchemy URI	Default schema	Set the schema Superset opens by default; dataset queries can still reference other schemas the account can read.
TLS options (SSL parameters)	Server certificate and TLS mode	Confirm the server offers TLS, the driver verifies the certificate chain and hostname, and the CA file is available to the Superset image.
Replica endpoint	Read replica or reporting server	Confirm replication lag is acceptable for the dashboard's freshness requirement before connecting Superset to it.
Superset role (Gamma, Alpha or custom)	MySQL GRANT set	Superset roles control what users see in Superset; MySQL grants control what the database returns, so both must be scoped.
Dataset definition	Table or view	Point datasets at views where possible, so column exposure and business logic are controlled in MySQL.

Hardening the MySQL connection for production

A Superset connection to MySQL is only as safe as the account, network path and secrets behind it. The five controls below cover what the database account can do, how traffic is protected, where the password lives, who can reach the database from Superset, and what Superset users can run through the connection.

Dedicated SELECT-only analytics account

Create a separate MySQL account for Superset that holds only SELECT on the schemas and tables dashboards need. Grant nothing for writes, DDL, or administrative privileges, and do not reuse the application account that writes production data. Confirm the exact grant set with your DBA against your MySQL version, and review it after every schema change, since new tables do not inherit grants you did not give explicitly.

TLS with certificate verification

Encrypt the connection between Superset and MySQL and configure the client to verify the server certificate against your internal certificate authority, not just accept any certificate. Confirm how your mysqlclient build and Superset's SQLAlchemy URI pass the SSL options, and test that a connection fails when the certificate is wrong. Ask your DBA whether the server requires TLS for accounts that connect remotely.

Password kept out of dashboards

Store the database password in an environment variable or a secrets manager that injects it at startup, and reference it from the connection configuration rather than typing it into the connection form in the Superset UI. Database connections saved through the UI are stored in the metadata database, so anyone who can read that database or export connection details may see the credential. Rotate the password on a schedule and after staff changes.

Network path limited to Superset hosts

Allow inbound connections to MySQL only from the Superset web and worker hosts, using firewall rules, security groups or host-based account restrictions such as user@host grants. Keep the MySQL port, which defaults to 3306, off public networks and out of shared subnets used by unrelated workloads. Verify the path with a test from a host outside the Superset tier, which should be refused.

Superset SQL limits and dataset rights

Review which Superset roles may add databases, create datasets, and run SQL Lab against the MySQL connection, and set a row limit and query timeout that suit your dashboards. Only trusted analysts should write free-form SQL, because a SELECT-only account still permits expensive queries that load a transactional server. Confirm these settings against the Superset version you run, since the names and defaults of the related configuration keys may change between releases.

When running analytics on a transactional MySQL database breaks down

Analytical scans and transactional traffic compete for the same resources. A Superset chart that aggregates years of order rows runs on the same MySQL server that takes checkouts, updates inventory and writes audit records. Long scans consume buffer pool memory, I/O and CPU, which can slow the application queries your customers depend on. Dashboards that refresh on a schedule add a repeatable load on top of ad hoc exploration, and each refresh is a fresh set of queries unless caching absorbs it. Superset's cache settings decide how often a chart hits MySQL at all, so the cache timeout for each dataset is a capacity decision, not only a display setting. Wide joins across large tables are the other common failure: a query that is acceptable in a test schema can lock up a production instance once real row counts arrive. Before you open the connection to a production database, confirm with your DBA which queries the business needs, how often they run and what the peak transaction window looks like.

Move analytics off the primary once the workload needs its own capacity. A read replica separates reporting from writes and is usually the first step, provided your team accepts that replica lag means dashboards show data slightly behind the primary. Confirm the replication topology you run and how lag is monitored before pointing Superset at it. When dashboards need to join MySQL data with other sources, need long history or need to serve many concurrent users, a separate analytical store is the better fit. Columnar engines are designed for that pattern, and ClickHouse is one option covered in the sibling topic on ClickHouse. Use the sibling topics for Snowflake, PostgreSQL and other engines when you compare options. Write down which dashboards must stay on MySQL and which can move, because that split determines the replication, access and sync work your team will own.

Common MySQL connection failures in Superset and their fixes

This table lists the failures teams most often hit when connecting Superset to MySQL or MariaDB, with the likely cause and the fix for each. Read it when a database connection test fails or a dashboard misbehaves, and start from the symptom in the first column.

Symptom	Likely cause	Fix
Unknown database or driver error when testing the connection	The mysqlclient package is installed in the web container but not in the Celery worker image, or not installed at all	Install mysqlclient in every image that runs Superset, including workers and beat, then rebuild and restart all of them. Confirm with the team that owns the image build.
Connection times out or refuses on port 3306	Wrong host or port in the connection string, or a firewall, security group or network policy blocks traffic from the Superset host	Confirm the default port 3306 or the port your MySQL or MariaDB server uses, then test reachability from the Superset container itself, not from your workstation.
TLS handshake error or certificate verification failure	The certificate name does not match the host in the connection string, the CA bundle is missing from the Superset image, or the server requires TLS that the client does not request	Match the host name to a name on the server certificate, mount the CA file into all Superset containers, and set the SSL options in the database connection settings. Confirm the required TLS version with your DBA.
Access denied for user	The grant is missing, or the account is scoped to a host pattern such as localhost that does not match the Superset server address	Create or update the read-only account for the Superset host address with SELECT on the required schemas, and check the account in the mysql.user table or with SHOW GRANTS. Confirm the host pattern with your DBA.
Garbled text, errors on non-ASCII values or unexpected sort order	Character set or collation of the connection, database or column differs from what dashboards and filters expect	Set the character set on the connection and align the database default with the data. Test a dashboard filter on a known non-ASCII value before release.
Query fails with a lost connection or timeout on long queries	Server-side limits, proxy or load balancer idle timeouts, or heavy dashboard queries running against the transactional primary	Raise the timeout only after checking the query, add indexes or summary tables, and point dashboards at a read replica. Confirm timeout settings with your database and network teams.
Dashboard shows old numbers after the source changed	Superset cache is serving previous results because the cache timeout is set to a long value or a dashboard refresh was not triggered	Review the cache timeout for the database and charts, then force a refresh from the dashboard. Agree with data owners how fresh each dashboard must be before you set the timeout.

Questions teams ask before connecting Superset to MySQL

What does the effort of connecting Superset to MySQL depend on?

The effort depends on how many schemas and tables Superset must expose, whether connections must use TLS, whether dashboards should query a read replica instead of the primary, and how database credentials are stored today. A single schema with a read-only account and a plain connection is a small job. Multiple schemas, certificate validation, a replica with its own lag rules, and integration with an existing secrets store add design decisions, testing and documentation. Ask any partner to base its estimate on a written list of these four factors.

Can our team connect Superset to MySQL without a partner?

Yes, if your team already runs Superset and has someone comfortable with Python packages, SQLAlchemy connection strings and MySQL user grants. The core steps are installing the mysqlclient driver into the Superset image, creating a read-only database account, and entering a mysql:// connection string in Superset. Teams usually need outside help when they must validate TLS certificates, separate dashboard traffic onto a replica, or review the setup against their own access and audit controls before production use.

What do we need from the database team and the security team?

The database team needs to create a dedicated read-only account, grant it access only to the schemas dashboards use, confirm which host or replica Superset should reach, and provide the TLS settings the server accepts. The security team needs to approve the account's privileges, where the password is stored, network paths from the Superset hosts to the database, and how connection changes are logged. Agree on these owners and approvals in writing before the build starts, so no one is waiting on a grant or certificate late in the project.

How long do a basic connection and a hardened connection take?

Duration depends on scope, so DeployOpen gives estimates only from a written scope. A basic connection covers the driver, one read-only account and a test dashboard. A hardened connection adds TLS verification, replica routing, credential handling through your secrets tooling, and documented verification steps. Ask for a timeline that lists each deliverable, the environments it covers (staging and production), and the customer reviews it depends on. Any figure given without that scope should be treated as a placeholder.

Does MariaDB work with the same driver and connection string?

MariaDB is designed for a high degree of MySQL compatibility, so teams often start with the same mysqlclient driver and the same mysql:// connection string format, using port 3306 by default. Compatibility is not a guarantee for every feature, though. Confirm the exact MariaDB release you run, test the driver against it in staging, and check which SQL features your dashboards depend on. MariaDB has its own release tracks and support windows, so the version you choose should be confirmed against the MariaDB Foundation's current policy before you commit.

Do we need MySQL Enterprise Edition features to connect Superset?

No. Superset connects to MySQL through a standard driver and an ordinary database account, and that works on MySQL Community Edition. Enterprise features such as Transparent Data Encryption, Enterprise Audit, Enterprise Firewall or Enterprise Backup are relevant only if your organization requires them for its own database controls. Decide that on the database side, based on your compliance and support needs, and confirm licensing with Oracle before assuming any Enterprise feature is included.

Should dashboards query the primary MySQL server or a read replica?

Dashboards should usually query a read replica when the primary handles live transactions, because heavy analytical queries compete with application writes. A replica adds replication lag, so dashboards may show data a few moments behind the primary, and that trade-off should be explained to report owners. Confirm that your replication setup, replica sizing and account privileges support the query load you expect, and set limits on Superset query runtime so one dashboard cannot starve the replica.

How DeployOpen scopes and delivers the MySQL integration

DeployOpen plans and implements the Superset to MySQL connection inside your own infrastructure, whether that is your cloud accounts, your data centers or an isolated network. The engagement starts with a written scope that names the MySQL or MariaDB endpoints Superset may reach, the database accounts it will use, the schemas and tables exposed to dashboards, the TLS settings for each connection, and the replica or reporting target that will serve queries. Deliverables and timelines are agreed in writing before work starts, so you know what is built, what is tested and what you receive at handover. Most engagements are fixed-scope, and the quote follows from that written scope rather than from a price list.

Delivery covers the parts of the integration that depend on your environment: installing the mysqlclient driver into the Superset image, creating the connection in the database settings, verifying the TLS certificate chain, checking that the read-only account cannot write, and confirming that dashboard queries run against the agreed replica. Your team should confirm early which MySQL major version and distribution you run, which Superset release you deploy, and who owns the database account lifecycle, because those answers change the test plan. DeployOpen can also prepare the evidence that a compliance assessment asks for, such as configuration records, access settings and test results. It does not issue audit reports, attestations or certifications; independent auditors and certification bodies do that work.

After go-live, the integration needs ongoing attention when the MySQL server, the MariaDB distribution or the Superset release changes. DeployOpen can support that work through a retainer that covers reviewing driver and release changes, re-running connection and permission tests, and updating documentation as your data model evolves. Ask any provider for a written statement of what the retainer includes, how changes are requested, and which responsibilities stay with your own staff, including credential rotation and replica capacity planning.