Moving Superset dashboards between instances and environments without breaking them
A dashboard built in development is only useful in production if promotion keeps its charts, datasets and database connections intact. Superset's ZIP export and import is the built-in way to move dashboards, charts, datasets and database connections between instances. Superset is an *Apache Software Foundation* project under the Apache-2.0 license, with no paid edition, so the cost of promotion is the engineering time to run it safely, not a license fee. Use the export when production must match a reviewed development build, including layouts, chart definitions and dataset logic. Rebuild by hand when the target needs a different data source, a different access model or a redesigned set of metrics, because an import carries over what was built, including its assumptions about the database it queries. The Superset architecture documentation describes the components that sit behind these assets.
Assets are identified by UUIDs, and the import behavior around them decides whether production receives a new copy or overwrites an existing object. Before the first promotion, rehearse the full cycle in a staging instance on the same release line as production, and record which dashboards, charts and datasets already exist there with matching identifiers. Confirm in your version's documentation how overwrite applies to each asset type, whether connection passwords are included in the archive or must be re-entered on import, and how dataset files are named inside the ZIP since 6.0. Check the upgrade guide too: if source and target run different versions, back up the metadata database and review UPDATING.md for breaking changes before you import.
Promotion touches more than the metadata database. Dashboards and charts are stored in the metadata database, but their queries run through the database connections of the target instance, and scheduled reports, alerts and dashboard thumbnails depend on the caching layer and Celery workers being configured in production. Plan a post-import check: open each dashboard, confirm that every connection points to production and not development, run the queries against production data, and verify that scheduled deliveries stay paused until the dashboard owner signs off. Keep each exported ZIP under change control so the version you reviewed is the version you import, and record the Superset release and the export date with it.
What transfers in a Superset export and what does not
A Superset export moves the dashboards, charts and datasets you built, but it leaves behind the access model, runtime state and secrets that keep them working in production. The cards below separate what travels from what you must recreate or confirm in the target instance. Treat each unchecked item as a gap in your promotion checklist.
Dashboards, charts and datasets
The export carries the dashboard layouts, chart definitions and dataset definitions built in the source instance. Each object keeps its UUID, and that identifier is how the target decides whether an incoming object is new or an update to one it already holds. Before you import, check whether the target already contains objects with the same UUIDs, because a matching import can overwrite the work already there. Confirm the overwrite behavior for your version in the release notes before you promote to production.
Database connections without passwords
The export describes each database connection, including its name, driver and host, so the target can recreate the connection objects. The stored password should not be assumed to arrive with them. Plan to supply the credential during import or set it in the target afterward. Every dataset and chart depends on a working connection, so an import that succeeds without credentials can still show errors on every chart. Use a dedicated service account per environment and keep its password in your secrets store, outside the ZIP file.
Dataset file naming since 6.0
Since version 6.0, the files for datasets inside an export follow a naming pattern that scripts written for earlier exports may not expect. If your promotion process unzips archives, edits YAML files or diffs exports in Git, test those steps against an export from 6.0 or later before you rely on them. Confirm the current naming convention in the release notes for the version you run. Do not assume that file names match the dataset names shown in the interface.
Users, roles and row level security
Users, role assignments and row level security rules are not part of a dashboard export, so the target starts without them. Recreate the roles the dashboards expect, map your identity provider groups to those roles, and rebuild each RLS rule with the same filter logic. Confirm how owner and permission references resolve in the target when the matching accounts are missing. Then test each dashboard with a non-admin account, because an admin view can hide a missing rule.
Caches, alerts and reports
Cached query results, dashboard thumbnails, and alerts and reports are runtime state tied to the instance that produced them, so none of them should be promoted as content. The architecture documentation states that alerts and reports, async queries and thumbnails depend on the caching layer and worker components. Confirm that the target runs those components, then recreate alert and report schedules in the target and point recipients at the production schedule only after you have checked the first run.
Metadata database state and SECRET_KEY
Sessions, operational state and the SECRET_KEY that encrypts stored credentials are specific to each instance. The target needs its own key, and it must match the source key if you move the metadata database itself, or stored credentials will not decrypt. Record which key each environment uses, store it in your secrets manager, and confirm the rotation steps, including PREVIOUS_SECRET_KEY, before you change it. Treat a key change as a planned event with its own test.
How UUIDs decide whether an import creates or overwrites
Each exported dashboard, chart, dataset and database connection carries a UUID, and that identifier, not the object name, decides what an import does. When you import a ZIP, Superset compares each incoming UUID with the objects already in the target metadata database. A match updates the existing object, and no match creates a new one. Before any import to production, list the UUIDs of the target objects you care about, open the export's YAML files and note the matching uuid fields, and confirm in the documentation for your version exactly how the overwrite option applies. A dashboard renamed in development can still overwrite production if its UUID already exists there.
Copied instances are the most common source of conflicts. If a production metadata database is restored into a staging instance, or staging is cloned from production and then edited, both environments hold the same UUIDs. Exporting from the copy and importing into the original then overwrites production with the copy's version, including any changes made only in staging. Illustrative example: a chart is fixed in a cloned staging instance, the staging export is imported into production with overwrite enabled, and the production dashboard silently takes the staging logic. Decide which environment is the source of truth for each asset, and make sure development and production were not cloned from one another without a plan for their identifiers.
Dashboards depend on charts, charts depend on datasets, and datasets depend on database connections, all referenced by UUID. If a dependency arrives with a different identifier than the dashboard expects, the dashboard layout can break or point at the wrong object. For that reason, move the whole bundle together rather than importing dashboards one at a time, and verify after each import that every chart resolves to the intended dataset. Confirm with the project documentation how your version handles references when a dependency already exists in the target, and record the UUID mapping for each promotion so that later changes can be traced.
Import options and when each fits a promotion
This table compares overwrite and non-overwrite imports, how database passwords must be supplied, and how the dataset file naming change in Superset 6.0.0 (published December 18, 2025) affects promotion. Read each row against the release notes for the versions on both sides. The main takeaway is that the import option decides what happens to production edits, so back up the metadata database before any import.
| Aspect | Overwrite existing assets | Import without overwriting | Confirm before use |
|---|---|---|---|
| Matching assets by UUID | Existing dashboards, charts and datasets with the same UUID are updated. | Conflicting assets are reported and nothing is applied to them. | Exact conflict result for your version in a staging import. |
| Best fit | Development is the source of truth and production edits should be replaced. | First-time loads or production teams have edits to keep. | Who owns production changes made outside the pipeline. |
| Main risk | Direct production edits to charts, datasets or filters can be lost. | Duplicates appear if the same asset arrives with a new UUID. | Whether your asset UUIDs stay stable across environments. |
| Database connection passwords | The export does not carry passwords in clear form, so they must be supplied during import. | The same supply step applies, and new connections cannot work without it. | How your version prompts for passwords and whether it updates existing connections. |
| Dataset file naming since 6.0.0 | ZIPs from 6.0.0 onward use the changed dataset file names. | Scripts or tooling that read ZIP paths must match the new names. | Naming in the 6.0.0 release notes and UPDATING.md. |
| Mixed versions between environments | Test whether a ZIP from one version imports cleanly into the other. | Same test applies, and duplicate checks matter more. | Compatibility notes for each version pair in the upgrade guide. |
| Rollback | Restore from the metadata backup taken before the import. | Remove duplicates by UUID, then restore if needed. | Your backup and restore steps tested in staging. |
Dataset file naming changes since Superset 6.0.0
Dataset file naming in Superset ZIP exports changed starting with version 6.0.0, which was published on December 18, 2025. Any promotion script written against an older export layout should be treated as unverified until it has been checked against the version you run. Do not infer the new naming pattern from older runbooks or from a sample taken from another instance. Confirm the exact convention in UPDATING.md for your source and target versions, since that file is where the project records breaking changes between releases.
The risk is most acute when exports and imports cross the 6.0.0 boundary. A file exported from a pre-6.0 instance and imported into a 6.0 or later instance, or the reverse, can leave the archive contents in a form the other side does not expect. A promotion script that unzips the archive and looks for dataset files at a fixed path may skip datasets without raising an error, and charts that depend on a missing dataset will fail later in the process. Keep source and target on the same minor line during a promotion where you can, and run a test import in staging to confirm every dataset arrives before the production run. The Upgrading Superset documentation sets out the wider upgrade sequence, including staging tests.
Before you write or change any promotion script, export a small, known set of datasets from the source instance and list the archive contents with a tool such as unzip -l. Record the file layout alongside the Superset version that produced it, then repeat the check on the target version. Build the script against the observed layout and have it fail loudly when an expected dataset file is missing, instead of continuing with a partial import. Store the version pair and the layout check in your change record so that a future upgrade on either side triggers a fresh check, and repeat the export test after any upgrade on the source or target.
How to run a dashboard promotion from development to production
This sequence moves dashboards, charts and datasets from a development Superset to production in a controlled way, so each asset arrives with its identifiers, connections and filters intact and a rollback copy exists before anything changes.
Inventory every asset in development
Before exporting anything, list the dashboards, charts, datasets, saved queries and database connections that the promotion must carry. Record each dashboard's owner, the datasets it depends on, and any dashboards that embed filters or reference other charts. Mark assets that are work in progress so they stay out of the bundle. The step is done when the list is agreed with the dashboard owners and every item has a named owner and a clear include or exclude decision.
Confirm version parity between instances
Check that development, staging and production run the same Apache Superset version, because exports from a newer release may not import cleanly into an older one. Read the release notes and UPDATING.md for any version gap, and confirm the metadata database and dataset file naming conventions match across the instances. Record the version strings from each instance. The step is done when all three instances report the same version or the gap is documented and approved.
Export the assets as a ZIP bundle
Export the agreed dashboards, charts and datasets from development using the Superset export function, which produces a ZIP archive containing YAML definitions for each asset. Store the archive in version control or an approved artifact location with a date and the source version in its name. Expect the export to include database connection definitions but not the stored passwords, so plan for that in the next step. The step is done when the archive opens, lists every inventoried asset, and carries a recorded checksum.
Prepare database connections and passwords in production
Confirm that each database connection referenced in the bundle exists in staging and production with the correct host, database name and service account, and that the password is supplied through your secrets process rather than stored in the ZIP. Use a read-only account for analytics queries where possible. The step is done when every connection the bundle references has a verified target, a named secret owner and a test query that succeeds from the Superset host.
Import the bundle into staging first
Import the ZIP into the staging instance, supplying the database passwords when prompted and choosing overwrite only for assets that already exist there and are meant to be replaced. Watch the import log for errors, warnings about missing connections and any asset that was skipped. The step is done when the import completes without unexplained warnings and the staging instance shows the same asset count as the bundle.
Verify UUIDs, charts, datasets and filters in staging
Check that each imported asset keeps the UUID it had in development, since UUIDs are how Superset matches assets on later imports and how embedded or linked references resolve. Open each dashboard and confirm that charts render, datasets point to the intended database and table, native filters have their default values and scopes, and cross-filters still apply. Record any chart that errors or returns different row counts from development. The step is done when a written checklist shows each dashboard passed and every exception has an owner and a fix.
Promote to production with a rollback copy
Before importing into production, export the current production assets that the bundle will overwrite, and back up the production metadata database so you can restore it if needed. Run the same import used in staging, with the same choices, then repeat the checks from the staging verification on production dashboards. Keep the rollback export available until the business owners sign off. The step is done when production passes the verification checklist, the rollback copy is stored and tested for import, and the change is recorded with the bundle checksum and version.
Security risks in exports and promotions
A ZIP export moves dashboards, charts, datasets and database connections out of the environment where they were governed. The cards below cover the places where that movement creates exposure, from credentials in the bundle to access rules that do not travel with it. Check each one before the first promotion, and again whenever the export process changes.
Secrets inside export bundles
A Superset export can include database connection definitions, and the handling of connection passwords in the bundle decides whether a file is safe to move. Confirm with the Superset version you run whether passwords are exported, masked or left as placeholders, and test with a sample export before any production file leaves its source. Treat a bundle that contains any credential as a secret in its own right.
Who can export and import
Export and import are permissions on the Superset role model, so anyone holding them can copy dashboards, datasets and connection metadata out of the instance. Review which roles hold export and import rights in each environment, and keep them narrower in production than in development. Record who performed each export so that a later question about a file has an answer.
Metadata database backup first
An import writes into the metadata database, and a bad import can overwrite objects that other teams rely on. Take a backup of the metadata database before every production import, and confirm you can restore it into a test instance. Keep the backup linked to the change record so that rollback is a planned step, not an emergency rebuild.
Row level security and roles to reapply
Row level security rules, roles and dataset access are not a substitute for the data controls in your warehouse, and they must be checked after every import. Confirm which rules and role assignments arrive with the bundle and which must be recreated by hand in the target instance. Test with a non-administrator account that the same rows are visible before and after promotion.
ZIP files in controlled storage
Export files are a copy of governed analytics content and often carry metadata about internal databases, schemas and users. Store them in a restricted location with access logging, retention limits and encryption at rest, and delete copies that are no longer needed. Do not attach bundles to tickets or email, where access cannot be audited.
Questions teams ask before promoting Superset dashboards
What does promoting Superset dashboards cost, and what drives the price?
Cost follows the amount of work the promotion touches, including how many dashboards, charts and datasets move and how many database connections must be remapped. A fixed-scope engagement is priced from a written scope that lists these assets, the environments involved and the security settings that travel with them. The main cost components are asset inventory, remapping datasets to the target databases, rebuilding anything that does not transfer cleanly, access and credential setup, staging test runs, a production change window and a handover runbook. Most of this work is one-time. Recurring cost appears when you promote new content later or keep a scripted process current with each Superset release. To compare quotes, ask each provider to itemize these components and to state which connections and roles are in scope.
How long does promoting dashboards between Superset instances take?
Duration depends mainly on how many assets move, how many database connections need remapping and how much security configuration sits behind them. A few dashboards on one database is a different job from dozens of dashboards spanning several warehouses with row level security. Dependencies on roles, RLS rules and scheduled or embedded content add review and testing time. No single duration applies across these cases, so ask for a timeline tied to the written scope, with milestones for inventory, staging import, production cutover and post-import verification. Check any proposed dates against the asset list and connection count you provide before you accept them.
What must our team provide before a Superset promotion starts?
Start with the exact Superset version running on the source and target instances, because export formats and import behavior depend on the version. Provide admin access to both instances, a staging copy that mirrors production as closely as possible and a list of database connections with their named owners. Name the person who can supply or rotate each connection password, since passwords should be re-entered on the target rather than assumed to carry over. Confirm the production change window and approval path. Agree on a secure channel for credentials before the work begins, and keep live passwords out of tickets and chat.
Can our own team promote Superset dashboards with the docs and a staging copy?
Yes, for a small and well-understood set of assets. The Superset documentation covers exporting and importing, and a staging copy lets you rehearse the full path before touching production. Apply the same discipline the upgrade guide recommends: back up the metadata database, test in staging first and check release notes for breaking changes when source and target versions differ. Your team should own UUID conflict checks, password re-entry and post-import review. Consider a partner when assets share many datasets, several databases carry row level security or no one on the team has time to own repeated rehearsals.
How do UUIDs and overwrite settings affect Superset dashboard imports?
Superset identifies exported assets by UUID, and the import behavior around those identifiers decides whether an incoming object updates an existing one or creates a new one. An import into a copy of production can therefore overwrite work that users depend on, or create duplicates that confuse ownership. Check how your version matches existing objects and how its overwrite options apply to dashboards, charts and datasets. Dataset file naming has been handled differently since 6.0, so bundles exported from earlier releases may need review before import. Rehearse on a non-production target, compare object counts and identifiers afterward and record the mapping so later promotions reuse it.
What should a promotion check before cutover to production Superset?
Confirm that every chart and dataset points at the intended production database and that no development connection remains in use. Check that the roles and row level security rules referenced by the dashboards exist in the target and that users who need access hold the correct roles. Verify that alerts, reports and any embedded or public content still reference valid objects, and that cached results do not show development data. Confirm that database users have only the privileges the dashboards need. Keep a dated checklist with query results or screenshots for each dashboard, and keep a tested rollback path ready, based on a verified backup of the metadata database.
How do you keep a scripted Superset promotion working over time?
Treat a promotion script as code with a named owner and a repeatable test. Keep the exported bundles and the script in version control, record the Superset version each script was written for and rerun the rehearsal against staging after every upgrade. Read the release notes and UPDATING.md before changing versions, because export formats and import options can change between releases. Store connection secrets in your secrets manager and keep them out of the script. Review the process on a fixed schedule and document who responds to failures. Ongoing upkeep is a recurring cost, and a support retainer is one way to cover it. Ask for its scope in writing, including which versions and environments it covers.
How DeployOpen scopes and delivers Superset promotions
DeployOpen treats a dashboard promotion as a controlled change to a self-hosted Superset in your own infrastructure. We agree the asset inventory, target environments and verification steps in writing first, then build and test the export and import path before anything reaches production.
How we scope
- Inventory the dashboards, charts, datasets and database connections that must move, and which ones stay environment-specific.
- Agree in writing how UUID conflicts, overwrite behavior and connection passwords will be handled for each target instance.
- Confirm the Superset version on source and target, since dataset file naming changed in 6.0 and affects export files.
How we build
- Build a repeatable export and import procedure with a documented order for datasets, charts and dashboards.
- Test promotions in a staging instance that mirrors production versions, database drivers and access roles before any production run.
- Verify that dashboards render, datasets query the correct databases and role-based access behaves as the source instance did.
How we hand over
- Deliver a runbook covering each promotion step, the rollback path and the values that must be re-entered after import.
- Document the environment-specific settings, such as connection secrets and database URIs, and who holds them in your infrastructure.
- Walk your team through a live promotion so they can repeat it without DeployOpen involvement.
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 for teams that promote assets regularly.
- Confirm with us how a retainer would cover Superset version upgrades that change export formats or import behavior.
