What a Superset metadata backup protects and why teams need one
If the host running Superset fails tomorrow, the question is not whether the web server comes back but what state comes back with it. A running Superset holds dashboards, charts, users, roles and saved database connections, and most of that configuration lives in one place: the metadata database. The Superset architecture documentation describes four components: the Flask and React application, a metadata database, an optional caching layer and optional Celery worker and beat processes. The application and workers are largely replaceable from a container image or package. The metadata database is the component that holds what your analysts built and what your administrators configured, so it is the component to protect first.
Losing it means rebuilding by hand. Dashboard layouts, saved queries, row level security rules, role assignments and the connection records that point Superset at your warehouses would all need to be recreated. Alerts and reports, which depend on the caching layer and workers for execution, also rely on their definitions stored in that database. Before you plan a backup, confirm with your own environment which of these objects are stored only in the metadata database and which, such as files you have uploaded or external secrets, live elsewhere. Some encrypted fields in the metadata database also depend on the configured SECRET_KEY, which is covered in a later section.
The upgrade documentation tells operators to back up the metadata database before running superset db upgrade and superset init, and to test upgrades in staging first. Treat that instruction as the minimum reason to have a backup, since upgrades are the most common moment when a schema change goes wrong. Two deployment choices affect whether the backup is worth having at all. The architecture documentation says the SQLite default used by Quickstart and PyPI installs, and the PostgreSQL container in the Docker Compose setup, are not recommended for production, and that Superset is tested with PostgreSQL and MySQL. Confirm which engine and version your team will run before designing backups, because the database you choose determines the native backup tooling you can use.
Backup options and when each fits
This table compares native database dumps or snapshots, managed-service snapshots, Superset export bundles and configuration kept as code. Read each row for what it restores, what it leaves out and when it fits, because no single option covers a full recovery on its own.
| Option | What it restores and misses | When it fits |
|---|---|---|
| Native PostgreSQL dump or snapshot (PostgreSQL 10 to 17) | Restores dashboards, charts, datasets, users, roles and database connection records. Misses the SECRET_KEY, uploaded files and anything stored outside the metadata database. | Self-managed PostgreSQL where your team controls the dump schedule, storage and restore tests. |
| Native MySQL dump or snapshot (MySQL 5.7 and 8.x) | Restores the same metadata objects as PostgreSQL. Misses the SECRET_KEY, uploaded files and external configuration files. | Self-managed MySQL where your standard tooling already handles logical dumps and binary logs. |
| Managed-service snapshot or point-in-time restore | Restores the whole metadata database to a chosen point. Misses the SECRET_KEY and any file outside the database, and restores encrypted fields only with the matching key. | Managed PostgreSQL or MySQL where the provider already runs automated snapshots. Confirm retention and restore-to-new-instance steps with the provider. |
| Superset export bundles (dashboards and datasets) | Restores dashboard, chart and dataset definitions in a target instance. Misses users, roles, database connection credentials, the SECRET_KEY and row level security assignments. | A second layer for moving or recovering content, not a full backup. Useful when you need to rebuild a single dashboard quickly. |
| Configuration kept as code (superset_config.py and deployment manifests) | Restores settings, environment variables references and deployment definitions. Misses the metadata database contents, secret values and anything created through the UI. | Always, alongside a database backup, so a rebuilt environment matches the original settings. Store secrets in a separate vault, not in the repository. |
| Secret key and encryption material | Restores the value needed to decrypt encrypted fields such as stored database credentials. Misses nothing in the database, but its loss makes encrypted fields unreadable. | Required with every database backup. Keep it in a separate, access-controlled store and confirm rotation steps with the configuration documentation. |
Setting up backups and a tested restore
This sequence gives you a metadata database backup you can restore, a matching SECRET_KEY on record, and proof that a restored Superset works before any upgrade touches production. Each step ends with a check so the next step starts from a known state.
Record the version and SECRET_KEY securely
Record the exact Superset version, the image or package tag, and the SECRET_KEY value in a secrets store your operations team controls, not in the same repository as the deployment configuration. Superset requires a user-specified SECRET_KEY to start, and encrypted fields in the metadata database, such as stored database connection passwords, cannot be read without the key that wrote them. Done when a second administrator can retrieve the key and the version from the store and both match the running deployment.
Confirm the metadata database version is supported
Check the metadata database engine and version against the Superset configuration documentation, which lists PostgreSQL 10 to 17 and MySQL 5.7 and 8.x. Confirm that the production metadata database is PostgreSQL or MySQL, because the SQLite default and the Docker Compose PostgreSQL container are not recommended for production. Ask your database team to confirm the backup tooling supports that exact version. Done when the engine, version and backup tool are written next to the SECRET_KEY record.
Schedule consistent backups with retention
Configure scheduled logical or physical backups of the metadata database using the native tooling for your engine, and set a retention policy agreed with your data owners and compliance team. Backups must be taken with the database in a consistent state so the dashboards, users, roles and connection records restore together. Store copies outside the Superset host, encrypted, with access limited to the people who can already administer the database. Done when a scheduled job has produced at least one backup file and its checksum is logged.
Back up before every upgrade
Before you change the Superset version, take a fresh metadata database backup and label it with the version you are leaving. The upgrade guide directs you to back up the metadata database before running the upgrade commands, and to check UPDATING.md for breaking changes between versions. Keep this backup separate from the scheduled set so it is not rotated out during the upgrade window. Done when the labeled backup exists, its size is plausible for the database, and you can list it from the restore host.
Restore into a separate staging instance
Restore the backup into a staging metadata database and point a staging Superset at it, using the same SECRET_KEY recorded in step one. Keeping staging on a separate database prevents test changes from reaching production users. If the key differs, encrypted database connections will fail to decrypt, so this step also proves the key record is correct. Done when the staging instance starts and the restore log shows no errors.
Run the upgrade commands on staging
On the staging instance only, run superset db upgrade and then superset init as the upgrade documentation describes, and review the output for migration errors. Run these commands against the restored copy first so any failure is contained. If you are testing a version change, run them after the new version is installed and before any user traffic reaches the instance. Done when both commands complete without errors and the migration log is saved with the change record.
Verify logins, dashboards and queries
Test the restored instance end to end: sign in with a local administrator and with a representative SSO user, open several dashboards and charts, confirm that each saved database connection opens and tests successfully, and run a sample query against one connected analytics database. Compare the results with production for the same dashboard to confirm the data source is reached. Record each check as pass or fail with the tester's name. Done when every check passes, and any failure is traced to a cause and fixed before the backup is treated as valid.
Why a restored SECRET_KEY must match the original
Superset will not start without a SECRET_KEY that you set yourself, a requirement introduced in version 2.1.0, and that key is what protects sensitive values stored in the metadata database. Database connection passwords saved through the Superset interface are encrypted with it. A restore therefore has two parts that must agree: the metadata database dump and the SECRET_KEY the restored instance runs with. If you restore a complete, correct database into an environment whose key differs from the original, the dashboards, users and connection records will load, but the stored connection passwords can become unreadable, and queries against those databases will fail until someone re-enters each credential. Record the key in your secrets manager alongside the backup set, label it with the instance it belongs to, and include a check in your restore test that a saved connection can be opened and queried.
Superset supports rotation through PREVIOUS_SECRET_KEY, which lets the running instance read values encrypted under the old key while new writes use the new one. Treat rotation as a planned change with its own record, approval and rollback path, not as a step inside a backup job. Before you rotate, confirm with the Superset configuration documentation how your installed version re-encrypts existing values, whether a separate command is needed to migrate stored secrets, and when the previous key can be removed safely. Behavior can differ between releases, so verify it on a staging copy of your metadata database before production. Keep the previous key available until a restore test from a backup taken after rotation succeeds, because a backup taken during the transition may need both keys to read its encrypted fields.
Restore paths for different failures
When the host running Superset is lost but the platform is still available to rebuild on the same version and the same infrastructure, the restore is a rebuild followed by a database load. Start by installing the same Superset version as the one that produced the backup, because the metadata schema is tied to that release. Then restore the metadata database from your most recent dump and point the configuration at it.
- Match the version: Reinstall the exact Superset release that was running when the dump was taken, then restore before running any upgrade.
- Restore the SECRET_KEY: Set the same
SECRET_KEYused by the original deployment, or stored database connections and other encrypted fields will fail to decrypt. - Load the dump: Restore the PostgreSQL or MySQL dump into an empty database, then start the web tier and confirm migrations report no pending changes.
- Rebuild the supporting tiers: Recreate the caching layer and Celery workers, since alerts, reports and async queries depend on them.
- Verify afterward: Log in with an existing admin account, open a few dashboards, run a query against a saved connection, and confirm a scheduled report is still listed.
Confirm the restore against the environment you actually run, and record the exact version and the SECRET_KEY source in your runbook.
Restoring into a new instance, a new cluster or a different cloud account is a migration, so the restore has more moving parts. The new target may use different hostnames, a different metadata database server, different secrets management or a different container image. Each difference is a place where the restored metadata can point at the wrong thing.
- Plan the target: Confirm the metadata database version falls within the supported range for the release you are running, which the configuration documentation lists as PostgreSQL 10 to 17 and MySQL 5.7 and 8.x.
- Carry the secrets across: Move the
SECRET_KEYthrough your secrets store so the new cluster uses the identical value from the first start, and plan forPREVIOUS_SECRET_KEYif rotation is also happening. - Rewrite environment-specific values: Review stored database connection URIs, feature flags, base URLs and OAuth callback settings, since they often reference the old host.
- Rebuild the cluster deliberately: If you use Kubernetes, check the installation method first, since the Helm chart is marked deprecated in current development docs and the Kubernetes Operator is in alpha.
- Verify afterward: Test login through the identity provider, confirm stored connections resolve to reachable hosts, and check that workers see the same metadata.
Illustrative example: a restore onto a new cluster that still points at the old database hostname will appear to work until a user opens a connection that was never retested.
A failed upgrade is the case where the metadata database has already been changed by a newer release. The upgrade documentation says to back up the metadata database before running superset db upgrade and superset init, and that backup is what makes rollback possible. Rolling back means returning both the code and the schema to the earlier state, not just redeploying the older image.
- Freeze the failed state: Keep the failed database and logs for diagnosis, and restore the pre-upgrade dump into a separate database rather than overwriting the only copy.
- Return to the prior version: Redeploy the exact earlier image or package, because a newer schema generally cannot be read by an older release.
- Reuse the same keys: Keep the original
SECRET_KEYand configuration, since encrypted connection data was written under it during the attempt. - Check the breaking-change notes: Read UPDATING.md for the versions in between so you know which changes caused the failure before retrying.
- Verify afterward: Confirm the application starts without migration errors, dashboards and charts render, and scheduled jobs resume only after you have reviewed their state.
Do not rerun the upgrade on the same database until you have tested it in staging against a copy of the pre-upgrade dump.
When one dashboard, chart or database connection is damaged or deleted, restoring the whole metadata database would roll back every other change made since the backup. An export bundle lets you restore just that object. Export bundles are a second layer, not a replacement for the database backup, because they do not capture every user, role or log record.
- Locate the bundle: Find the export taken before the change, and confirm it contains the object type you need.
- Import into a test instance first: Import the bundle to staging to see what it recreates before touching production.
- Re-enter credentials: Database passwords and other secrets are typically not recoverable from an export, so plan to supply them again through your secrets process.
- Check ownership and access: Confirm the restored dashboard is still shared with the right roles, since permissions may need to be reapplied.
- Verify afterward: Open the dashboard, run its charts, test the connection and compare row-level filters with the approved design.
If the object was never exported, the metadata database backup remains the only source, so the recovery then becomes a partial database restore planned with your database administrator.
Protecting backups that contain credentials
A Superset metadata backup is more sensitive than most database dumps because it holds user accounts, saved database connections and encrypted secrets. The cards below cover the decisions that keep those contents protected from the moment a dump is taken until the last copy is deleted.
Restrict access to dumps
Backups hold hashed user passwords, connection details for your analytics databases and encrypted fields that only the running application can read. Treat every dump as a credential store. Limit read access to a small backup operator group, log who restores or copies a dump, and confirm that backup jobs run under service accounts rather than personal logins.
Keep SECRET_KEY apart from the dump
Encrypted fields in the metadata database can only be read with the SECRET_KEY that was active when they were written. Store that key in a secrets manager with its own access list and version history, separate from the dump storage. A dump without its matching key is useful for schema recovery but not for restoring working connections, so record which key version belongs to each backup.
Review what export bundles carry
Dashboard export bundles are a second copy that can travel outside the database. They may include SQL text from charts, dataset definitions and references to tables that reveal sensitive data structures. Decide whether bundles are part of your backup policy at all, who may create them, and where they are stored, and apply the same access rules as database dumps.
Set retention and deletion rules
Old dumps keep retired users, revoked connections and old passwords alive long after the source system has removed them. Write down how long each backup tier is kept, how deletion is confirmed across replicas and off-site copies, and who approves deleting a backup that a legal hold or audit request covers. Review these rules whenever the retention schedule changes.
Encrypt backup storage
Encrypt dumps at rest in the storage system and in transit to it, and keep the encryption keys separate from the backup files. Confirm with your storage team whether encryption is applied by the backup tool, the storage platform or both, and test that an encrypted backup restores on a clean host before relying on it. Unencrypted copies on laptops or shared drives are a common source of exposure.
Questions teams ask before backing up Superset
What does it cost to back up the Superset metadata database?
The cost is mostly the labor to design, build and test the backup and restore process, plus the storage and infrastructure to keep the copies. Storage cost grows with database size and retention period, and the number of environments (production, staging, and any development copies) multiplies both. Some costs are one-time, such as the initial setup and the first restore test. Others recur, such as storage, scheduled test restores and re-testing after each upgrade. No supplied figure gives a price for this work, so ask any partner for a quote built from a written scope that lists the databases, environments, retention period and restore test frequency. Ask which costs are one-time and which recur.
What drives the effort of a Superset backup project?
Four factors drive most of the effort: the size of the metadata database, the number of environments that need the same protection, the retention policy, and how thoroughly restores are tested. A small single-instance deployment with one database and one environment is a much smaller job than a multi-environment install with several metadata databases and audit requirements. Restore testing usually takes more effort than the backup job itself, because it requires a separate environment, a copy of the SECRET_KEY, and a check that dashboards, users and database connections work after the restore. Confirm each of these factors in writing before work starts.
How long does a Superset restore test take?
The duration depends on the size of the database, the speed of the storage and network between the backup and the restore target, and how much verification you require. Restoring a database is typically the shortest step, while starting Superset against the restored database, checking that the SECRET_KEY decrypts stored database connections, and verifying dashboards and user access takes longer. No supplied figure gives a duration. Ask for the restore time measured on a copy of your own database in a staging environment, and ask for the checklist used to confirm the restored instance works.
What does the internal team need to provide for a backup project?
The internal team needs to provide four things:
- Read access to the metadata database for the backup job, and write access to a restore target for tests
- A secure store for the SECRET_KEY used by the production instance, with its version history
- A staging host or cluster where restores can run without touching production
- Named owners who approve the retention period, the restore test schedule and any access to the backup files
Without the SECRET_KEY, a restored database can hold connection passwords that Superset cannot decrypt. Confirm access to all four items before scoping the work.
Can our own team back up and restore Superset without a partner?
Yes, if your team has database administration skills, access to the metadata database, a way to store secrets safely and a staging environment. The core steps are a database backup, a copy of the SECRET_KEY and the configuration, and a restore test on a separate instance. The harder parts are proving that a restore works end to end, documenting the procedure, and keeping it current through upgrades. The Superset upgrade documentation already tells you to back up the metadata database before running upgrades, so this process should exist regardless. Decide whether your team will own restore testing on a schedule, and whether a partner will support that work under a retainer.
Which PostgreSQL or MySQL versions does Superset support for its metadata database?
Superset's configuration documentation lists PostgreSQL 10 to 17 and MySQL 5.7 and 8.x as supported metadata database versions. The SQLite default used by Quickstart and PyPI installs is not recommended for production, and the Docker Compose PostgreSQL container is also not recommended for production, according to the architecture documentation. Backup tooling and procedures differ between these engines, so confirm which backup method your database platform supports and test it on your version before relying on it.
What recurring work follows a backup and restore project?
The recurring work includes running backup jobs and checking their results, rotating and retaining backup files according to policy, and running restore tests on a schedule. Restore tests should also follow every Superset upgrade. The upgrade guide says to back up the metadata database, run superset db upgrade and superset init, test in staging first, and check UPDATING.md for breaking changes. Each upgrade changes the schema, so a backup from before the upgrade should be restored and checked on the new version. Ask any partner to define this cadence in the written scope and to state who runs each step.
Does a backup protect the SECRET_KEY and encrypted connection passwords?
No. A database backup does not include the SECRET_KEY, so it must be stored and backed up separately. Superset requires a user-specified SECRET_KEY to start, and encrypted fields in the metadata database, such as database connection credentials, can only be read with the matching key. If the key is lost or does not match, restored connections will fail. The configuration documentation also describes rotating the key with PREVIOUS_SECRET_KEY, so record which key version each backup was taken with. Confirm where the key is stored, who can read it, and how it is restored during a test.
How DeployOpen scopes and tests Superset backups
A DeployOpen backup and restore engagement is a fixed-scope piece of work carried out inside your own cloud accounts, data center or restricted network. Before any work starts, we agree the scope in writing: which Superset instances are covered, which metadata database engine and version they run (PostgreSQL or MySQL, checked against the versions the configuration documentation lists), where backups are written, how long they are kept, and who holds the restore authority for each environment. The written scope also records the SECRET_KEY handling, the export bundle policy and the acceptance test that counts as a successful restore, so the deliverables are defined before the first backup job is configured.
The deliverables are a backup configuration for the metadata database, a documented runbook and a restore test that we run against a separate environment and record as evidence. The runbook covers the restore order, including the SECRET_KEY value that must match the encrypted fields in the restored database, the superset db upgrade and superset init steps when the target version differs, and the checks that prove dashboards, users and database connections are back. We test the restore to a staging instance first, then document what was observed, what took longer than planned and which steps your own staff must repeat. Ongoing retainers can cover recurring restore tests, backup monitoring and upgrade support for future Superset releases, which is where the upgrade guidance in the project's UPDATING.md notes becomes part of the routine work.
DeployOpen prepares the systems, runbooks and test evidence that your auditors or internal assurance teams may ask for, but we do not issue audit reports, attestations or certifications. Ask any partner, including us, to show the written scope, the restore test record and the list of items the client must provide, such as storage credentials, network paths, a staging environment and named approvers. Confirm the retention period, the recovery targets you need and who signs off on a successful restore with your own risk and compliance owners before the engagement starts, because those answers change what the test must prove.
