Why a Superset 3.x deployment needs a planned 4.x upgrade
Moving a self-hosted Superset 3.x instance to the 4.x line is a planned change to the dashboards, filters, metadata database and security headers that analysts depend on, not a routine package bump. Superset 4.0.0 removed Filter Box code and migrated it automatically to native filters, removed Filter Sets and the Profile feature, and enabled DASHBOARD_VIRTUALIZATION and DRILL_BY by default. Each of those changes alters what analysts see on a dashboard, so the work needs owners, a test plan and a sign-off step before production is touched.
The supported path follows the Apache Superset upgrade documentation. Back up the metadata database first, run superset db upgrade and then superset init, and test the whole sequence in staging before production. Read the breaking change notes in UPDATING.md for every release between your current version and the target, because the 4.0.0 notes also flag that several columns moved to MediumText, which can lock tables on MySQL metadata databases. Confirm the exact MySQL version and table sizes in your environment before you pick a maintenance window.
Superset is licensed under Apache-2.0 and has no paid edition, so the upgrade cost is the effort to plan, test and run it. Your own platform team can carry that work, or a partner can take it under a written scope. Either way, decide early who owns dashboard validation, who approves the Talisman header setting that changed in 4.0, and who signs off the rollback plan. Those decisions drive the effort more than the upgrade command itself.
Which 4.0 and 4.1 changes affect your dashboards and database
This table lists the Superset 4.0 and 4.1 changes that most often affect existing dashboards, saved content and the metadata database. Read each row as a check to run in staging before the production upgrade. The full list of breaking changes is in UPDATING.md, so confirm any change that is not covered here against that file.
| Change | Impact on your deployment | Action needed |
|---|---|---|
| Many deprecated feature flags removed | Any flag you set in superset_config.py for a removed feature no longer has an effect, and behavior tied to it may change or disappear. | Compare your FEATURE_FLAGS settings with UPDATING.md and remove or replace flags that no longer exist. |
| Filter Box migrated to native filters | Existing Filter Box charts are converted automatically into native dashboard filters, so layouts and filter scopes can look different. | Open a sample of dashboards in staging and confirm filter values, scoping and default selections match what users expect. |
| Filter Sets and Profile removed | Saved filter sets and the user Profile page are no longer available to users, so anyone relying on them loses that workflow. | Tell affected users in advance, identify who depends on filter sets, and confirm they have an alternative such as saved native filter defaults. |
| DASHBOARD_VIRTUALIZATION enabled by default | Dashboards load through a different rendering path, which can change performance and behavior on large or heavy dashboards. | Test your largest dashboards for load time and rendering. Set the flag explicitly if you need the previous behavior, after checking UPDATING.md. |
| DRILL_BY enabled by default | Users see drill-by options they did not have before, which can expose dimensions you did not intend to present. | Review which charts and datasets allow drill-by and confirm the exposed fields fit your data access rules. |
| MediumText column changes (4.0.0) | On MySQL metadata databases, the column type change can lock tables, and on large deployments the migration can take a long time. | Back up the metadata database, schedule a maintenance window, and rehearse the superset db upgrade on a copy of production data. |
| Index on query.sql_editor_id (4.1.0) | Adding the index may cause downtime on large deployments because the query table is written often. | Measure the size of the query table in staging, plan a window for the 4.1.0 migration, and confirm your database engine behavior for index creation. |
| Talisman security headers disabled by default | Browsers may no longer receive the security headers your deployment relied on, which can weaken your browser-side protection after the upgrade. | Set TALISMAN_ENABLED and its header configuration explicitly, then verify the response headers with your security team as described in the production security guide. |
How the Filter Box migration changes dashboard behavior
In Superset 4.0.0, the Filter Box code was removed and existing Filter Box filters are migrated automatically to native filters. Your dashboards should keep their filtering after the upgrade, but the filter controls may look and behave differently, and the converted layout is not guaranteed to match the original on every dashboard. Treat the migration as a change you verify, not one you assume.
- Filter placement: Check where each converted filter sits in the filter bar and whether it still appears on the tabs or charts where users expect it.
- Default values: Confirm that each filter's default value and any preselected options still match what viewers should see on first load.
- Scoping: Confirm which charts each filter applies to, since native filters use explicit scoping that may differ from the old Filter Box behavior.
- Cross-filtering and drill behavior: Test interactions between charts, because DRILL_BY is enabled by default from 4.0.0 and may change how users navigate.
- Owner notes: Record any dashboard that needed manual repair so the next owner knows what changed.
Compare your most-used dashboards against their pre-upgrade behavior in a staging copy before the production upgrade, and confirm the results with the people who use them daily.
Filter Sets and the Profile feature were removed in Superset 4.0.0. Analysts who saved named combinations of filter values, or who relied on a Profile view of their own settings, will no longer find those tools after the upgrade. Nothing in the migration recreates Filter Sets as equivalent saved objects, so you should plan a replacement workflow before users lose access.
- Inventory saved combinations: Ask analysts which dashboards and filter combinations they use, and record them before the upgrade.
- Replacement options: Decide whether analysts will use native filter defaults, saved dashboard views or bookmarked URLs with filter parameters. Confirm each option behaves as expected in your version.
- Profile dependencies: Identify any process, training note or runbook that tells users to open Profile.
- Communication: Tell analysts which feature disappears, the date it changes and the replacement workflow, ahead of the upgrade window.
- Lost habits: Note that a user's saved filter combinations will not carry over, so recreate the important ones manually.
Walk through one or two analyst workflows end to end in staging, and confirm with users that the replacement still answers their questions.
Administrators own the upgrade plan and the sign-off. The migration runs as part of the database upgrade, so the metadata database backup and staging test must happen first. The Superset upgrade documentation directs you to back up the metadata database, run superset db upgrade and superset init, and check UPDATING.md for breaking changes between versions. Filter Box migration is one item on that list, not the whole plan.
- Backup first: Take and verify a metadata database backup before running any migration, and document how you would restore it.
- Staging sign-off: Require owners of key dashboards to approve the staging results before production is scheduled.
- Feature flags: Review feature flags that Superset 4.0.0 removed or changed, since dashboards may depend on them.
- Talisman headers: From 4.0, Talisman security headers are disabled by default, so enable them explicitly if your security baseline requires them.
- Long migrations: Check the MediumText and 4.1.0 index changes with your database team, because they can lock tables on MySQL metadata databases or cause downtime on large deployments.
Record the staging comparison results and the owners who approved them as part of your change record.
What to inventory and back up before touching the metadata database
The metadata database holds the dashboards, users, roles and settings that the 4.x migrations rewrite, so a clean rollback depends on what you capture first. The cards below cover the backup, the configuration inventory, the secret key, the custom code, the staging copy and the test list that together make the upgrade reversible.
Metadata database backup
Take a full backup of the metadata database before running any migration. The configuration documentation lists supported metadata databases as PostgreSQL 10 to 17 and MySQL 5.7 and 8.x, so confirm your engine and version fall in that range. Test that the backup restores to a scratch instance, because a backup you have never restored is not yet a rollback plan. Note that SQLite and the Docker Compose PostgreSQL container are not recommended for production, so a deployment on either needs a move to a supported database first.
Feature flag and config inventory
Record every entry in FEATURE_FLAGS and every custom override in superset_config.py, including values set through environment variables. Version 4.0.0 removed many deprecated flags and enabled DASHBOARD_VIRTUALIZATION and DRILL_BY by default, so a flag you rely on may be gone or behave differently. Keep the inventory in version control next to the config file so you can compare before and after the upgrade.
SECRET_KEY and PREVIOUS_SECRET_KEY
Confirm where SECRET_KEY is stored and that every web and worker container reads the same value. Changing it without a plan invalidates encrypted values in the metadata database, such as database connection credentials. Superset supports rotation through PREVIOUS_SECRET_KEY, so decide whether you rotate during the upgrade or keep the current key, and record the decision. Keep the key in your secrets manager, not in the image.
Custom plugins and image changes
List every custom visualization plugin, theme, translation and Dockerfile change in your build. Any of them can break when the front-end bundle or base image changes between releases. Pin the base image and plugin dependencies in your build records so you can rebuild the previous image if the upgrade fails. Ask your team who owns each customization so that someone can test it.
Staging copy at production size
Build a staging environment with the same Superset version, metadata database engine and config as production, and with a copy of the metadata database at production size. The 4.0.0 MediumText changes and the 4.1.0 index on query.sql_editor_id can lock tables or cause downtime on large MySQL databases, and a small test database will not reveal that. Time the migration on staging and use that measurement to plan the maintenance window.
Dashboards, alerts and reports to test
Build a written list of the dashboards, alerts, scheduled reports and Talisman-dependent embeds that users rely on, with an owner for each. The 4.0 upgrade removed Filter Box charts, which migrate to native filters, and removed Filter Sets and Profile, so review those dashboards first. Talisman security headers are disabled by default from 4.0, so check whether your deployment relied on them. Run each item after the upgrade and record the result.
Why MediumText migrations on MySQL need a maintenance window
Superset 4.0.0 changed several columns to MediumText, and on a MySQL metadata database that change can lock tables while it runs. The lock length depends on how much data sits in the affected tables, so the migration can be quick on a small installation and slow on one that has accumulated years of query history, logs and dashboard metadata. Superset 4.1.0 adds an index on query.sql_editor_id, which can also cause downtime on large deployments. Before you schedule anything, check the row counts and on-disk size of the metadata tables that the release notes name, and confirm the exact column changes in the Superset UPDATING notes for every version between your current release and the target.
Once you know the sizes, book a maintenance window long enough to cover the slowest plausible run, not the average one. Tell the users who depend on dashboards, alerts and scheduled reports that Superset will be unavailable, and pause scheduled reports and async query workers so they do not write to tables mid-migration. Take a verified backup of the metadata database immediately before the window, and record how you would restore it if the migration stalls. Your DBA should confirm which ALTER operations run as online schema changes on your MySQL version and which block writes, because that determines whether a read-only period is acceptable.
Rehearse the full upgrade against a restored copy of production, with the same MySQL version, table sizes and configuration, and time each step including superset db upgrade and superset init. The rehearsal result tells you whether the window you booked is large enough and whether the plan needs an online schema change tool or a different sequence. Confirm the behavior for your exact versions with the vendor release notes rather than relying on this guidance alone, and record the rehearsal timings and any errors as evidence for your change approval.
The upgrade sequence with checks and rollback points
This sequence moves a production Superset 3.x deployment to 4.x only after the change has been rehearsed on production-like data, so each step ends with a verified state and a known way back. The output is a production instance on 4.x with migrated dashboards, confirmed security headers and a record of every checkpoint.
Freeze changes and announce the window
The platform owner stops configuration and dashboard changes on the current instance and tells dashboard owners, analysts and anyone with alert or report schedules when the window opens and closes. Confirm the scheduled reports and alerts that will be paused or may fail during the change. Done means a written freeze notice exists and a named person can answer questions during the window. Rollback point: none needed, since nothing has changed yet.
Back up the metadata database and configuration
The platform owner takes a full backup of the metadata database and copies superset_config.py, environment variables and the secret key material into a restricted location. Store the SECRET_KEY separately from the database dump, because a restored instance must read existing encrypted values with the same key. Done means the backup restores into a scratch database and the config copy is complete. Rollback point: this backup is the restore source for every later step.
Rebuild staging from production data
The platform team restores the production backup into a staging metadata database and deploys the current 3.x configuration and image against it. Check that staging logs in, lists dashboards and runs a sample of charts against the same warehouse connections. Done means staging matches production on dashboards, databases and roles before any upgrade is attempted. Rollback point: discard the staging copy and restore again if the rebuild differs.
Review breaking changes and filter boxes
Before running any migration, the platform owner reads the 4.0.0 entries in the project's UPDATING.md and lists configuration keys and feature flags in use that were removed. Export a list of dashboards that use Filter Box charts, since those are migrated automatically to native filters. Done means the team has a signed-off list of removed flags, affected dashboards and Filter Sets or Profile usage to rebuild. Rollback point: no change yet; the list drives the staging checks.
Run the upgrade in staging
An engineer deploys the 4.x image in staging and runs superset db upgrade followed by superset init, capturing the full output. On MySQL, check whether the MediumText column changes and the query.sql_editor_id index in 4.1.0 will lock large tables, and schedule that time within the window. Done means both commands exit cleanly and the migration log shows no errors. Rollback point: restore the staging backup and redeploy the 3.x image if the migration fails.
Verify native filters and dashboards in staging
Dashboard owners open every dashboard on the affected list and compare filter values, cross-filters and drill behavior with the pre-upgrade screenshots or notes. Confirm that the new DASHBOARD_VIRTUALIZATION and DRILL_BY defaults do not change results, and rebuild any Filter Set or Profile workflows as native filters or saved configuration. Also test one alert and one report end to end. Done means each dashboard has a sign-off entry and the report output matches. Rollback point: restore staging and fix the failing dashboards before production.
Set Talisman headers explicitly
From 4.0, Talisman security headers are disabled by default, so the platform team decides whether policy requires them and sets the enabling configuration explicitly in staging. Check the response headers from the browser and confirm the embedding or login flows still work with the chosen policy. Done means the headers returned by staging match the written policy. Rollback point: remove the Talisman setting and redeploy staging if an embedded or login flow breaks.
Repeat the upgrade in production and run post-upgrade checks
Run the same backup, migration and verification steps in production during the approved window, and compare the results against the staging log. After go-live, confirm login through the production identity provider, dashboard rendering, database connections and scheduled report delivery, then reopen change control. Done means the checklist is signed by the platform owner and the dashboard owners. Rollback point: if checks fail, stop the new containers, restore the production metadata backup and redeploy the 3.x image.
What makes a 3.x to 4.x upgrade longer or shorter
This table compares the factors that expand or shrink the work of moving a 3.x deployment to 4.x, and what to do about each. Read each row as a question to answer during inventory, since the answers set the scope. No duration is given here because the quote follows from a written scope and a completed inventory of your environment.
| Driver | What increases effort | What reduces effort |
|---|---|---|
| Metadata database size and engine | Large MySQL metadata database with MediumText changes that may lock tables during the 4.0.0 migration | Small PostgreSQL metadata database, or a tested maintenance window and a rehearsed copy restore |
| Filter Box and Filter Sets usage | Many dashboards built on Filter Box or Filter Sets, each needing review after automatic migration to native filters | Few affected dashboards, or dashboards already moved to native filters in 3.x |
| Feature flags enabled in 3.x | Deprecated flags removed in 4.0.0 that custom code or configuration still depend on | Flags left at defaults, with a documented list of what is switched on |
| DASHBOARD_VIRTUALIZATION and DRILL_BY defaults | Dashboards whose layout or drill behavior changes once these features are on by default | Explicit settings reviewed in staging before cutover |
| Talisman security headers | Production security headers that were relied on implicitly and now need explicit enablement | Headers already set in configuration and verified after upgrade |
| Custom plugins and Docker images | Custom chart plugins or image builds that must be rebuilt and retested against the 4.x front end | Stock images and no custom visualization code |
| Celery workers, alerts and reports | Scheduled reports, alerts and thumbnails that need a test run through workers and the caching layer | Few scheduled jobs, or a documented test list with expected outputs |
| SSO and role mapping | Group-to-role mappings in AUTH_ROLES_MAPPING that need checking against the current identity provider | Existing mappings documented and reproduced in a staging login test |
| Number of environments | Separate development, staging and production instances, each upgraded and tested in turn | A single staging copy refreshed from production, used for every test pass |
Questions teams ask before upgrading Superset to 4.x
What does a Superset 3.x to 4.x upgrade cost?
The cost depends on the size of your Superset estate and who does the work. Internal cost is staff time for inventory, staging tests, change approval and cutover, plus any downtime your business accepts. If you use a partner, the fee follows from a written, fixed scope that lists the instances, dashboards, database connections and environments in play. Ask every quote to separate one-time work (inventory, migration, testing, runbook) from recurring work (patching and support after the upgrade). The biggest drivers are the number of custom features that touch removed items, the size of your metadata database, and how many environments need to match production. DeployOpen does not publish a price list, so the written scope is the basis for any figure.
How long does the upgrade take, and what sets the window?
The window is set by the metadata database migration, the number of dashboards you must verify, and the approval cycle for downtime. Superset 4.0.0 changed several columns to MediumText, which can lock tables on MySQL metadata databases or take time on large deployments, and 4.1.0 added an index on query.sql_editor_id that may cause downtime on large deployments. Measure the size of your largest tables in staging before you set a window, and confirm the lock behavior with your database team. Staging rehearsals usually decide the schedule, so plan at least one full rehearsal before production.
What must our team provide before the upgrade starts?
Expect to provide four things before work starts:
- A current inventory of Superset instances, versions, metadata database engines and versions, and the connected warehouses
- Administrative access to the staging and production hosts, the metadata database and any caching or worker components
- Named test users for each role, including owners of the dashboards that use filter boxes, Filter Sets or embedded features
- Written approval for the downtime window and a named owner who can sign off the cutover
The inventory is the input that most affects scope, so start there. Your team should also confirm which Talisman security headers you rely on, because they are disabled by default from 4.0.
Can our internal team run the 4.x upgrade without a partner?
Yes, many teams run it internally if they have an engineer who can administer the Superset host, the metadata database and the deployment tooling, and a person who knows the business dashboards. The upgrade documentation asks you to back up the metadata database, run superset db upgrade and superset init, test in staging first, and check UPDATING.md for breaking changes. The team should be ready to own the Filter Box migration review, the MediumText lock risk on MySQL, and the header settings. A partner adds most value when the estate is large, when several instances must move together, or when there is no spare staff time for rehearsal and testing.
What breaks most often on dashboards after upgrading?
Most breakage comes from features removed in 4.0.0. Filter Box code was removed with automatic migration to native filters, so dashboards need a visual check of the converted filters. Filter Sets and the Profile feature were removed, so any dashboard or process that relied on them needs a replacement plan. Dashboards may also behave differently because DASHBOARD_VIRTUALIZATION and DRILL_BY are enabled by default. Removed feature flags can break custom configuration that still sets them. Test each critical dashboard with a named user for each role, compare filter results with the pre-upgrade values, and record any differences in the runbook.
How does rollback work if the migration fails?
Rollback depends on the metadata database backup you take before you run superset db upgrade. Take a verified backup, record the previous application version and configuration, and keep the old images or packages available until the new version passes acceptance tests. If a migration fails partway, restoring the database from that backup and redeploying the previous version is the safe path, because schema changes such as MediumText conversions and new indexes may not reverse cleanly on their own. Rehearse this restore in staging so the team knows how long it takes and which steps need a named owner.
Does the upgrade change our security settings?
It can. From Superset 4.0, Talisman security headers are disabled by default and must be enabled explicitly, so a production instance that relied on the default can lose headers after the upgrade. Check your configuration for Talisman settings before cutover, and confirm the header policy with your security team. Also review the SECRET_KEY and PREVIOUS_SECRET_KEY handling, since Superset requires a user-specified SECRET_KEY to start and supports rotation with PREVIOUS_SECRET_KEY. Document the result so auditors can see the setting was reviewed.
How the web app, metadata database and workers change together
The four components named in the Superset architecture documentation are the Flask and React application, the metadata database, the optional caching layer, and the optional Celery worker and beat processes. For a 3.x to 4.x upgrade, the metadata database and the application code are the two parts that change. The migration runs superset db upgrade against the metadata database, and the 4.0.0 changes to several columns becoming MediumText and the 4.1.0 index on query.sql_editor_id both land there. Your plan should treat the database step as the one with lock and downtime risk, and the code step as the one that must match the database schema before users return.
The caching layer and workers do not change in the same way, but they are the parts most likely to look healthy while failing. The architecture documentation says alerts and reports, async queries and dashboard thumbnails depend on the caching layer and worker components, and most installations use Redis and Celery for them. After the upgrade, restart the web tier and every worker and beat process so they load the new code, then confirm that a scheduled report runs, a thumbnail renders and an async query completes. Clear or review cached entries if your team sees stale charts after the switch, and confirm which of these components your deployment actually runs before you schedule the window.
Plan the cutover so the three layers move in a fixed order: back up the metadata database, stop or drain workers and beat, run the migration and initialization steps, start the new web application, then start workers and beat last. Ask your platform owner to confirm the Python, Redis and Celery versions that the 4.x release requires in your environment, since those are not covered by the facts available for this page. Record which worker queues handle alerts and reports so the post-upgrade test covers each one, because a stopped beat process can silently skip scheduled work.
How to test dashboards, reports and rollback before go-live
The 4.x upgrade changes what users see on dashboards, how sessions and secrets behave, and what the metadata database has to do during migration. Each card below is a check to run in staging before the production window, and each needs a pass criterion agreed with dashboard owners before the window opens.
Dashboard parity for native filters
Filter Box code was removed in 4.0.0 and existing filters were migrated automatically to native filters. Compare every production dashboard in staging against a recorded baseline: filter values, default selections, cross-filter behavior and chart counts. Ask each dashboard owner to sign off on the filters they use most, and log any filter that migrated with a different scope or default.
Alert and report delivery through workers
Alerts, reports and thumbnails depend on the caching layer and Celery workers, so a web tier that loads correctly does not prove delivery works. Trigger a test alert and a scheduled report against staging, confirm that the worker and beat processes pick them up, and check that the recipient receives the output with the expected content. Record the results against the pass criteria set by report owners.
SSO and role login checks
Test each login path with a named account for every role your organization uses: the identity provider flow, LDAP if configured, and local fallback accounts. Confirm that group-to-role mapping through AUTH_ROLES_MAPPING still assigns the same roles after the upgrade, and that a user who should lose access is denied. Keep the test accounts and their expected roles in the change record.
SECRET_KEY and session behavior
Superset requires a user-specified SECRET_KEY to start, and rotation uses PREVIOUS_SECRET_KEY. Confirm that the staging configuration uses the same key handling as production, that existing sessions and encrypted database credentials still work after restart, and that a rotation test follows your documented procedure. Also check that Talisman security headers are enabled explicitly, because they are disabled by default from 4.0.
Metadata database performance after the index change
Version 4.1.0 adds an index on query.sql_editor_id, which may cause downtime on large deployments, and the 4.0.0 MediumText changes can lock MySQL tables. Measure migration duration on a copy of production, then time SQL Lab history loads, dashboard listing and chart opens after the migration. Confirm with your DBA whether the index build runs online on your database engine and version.
Tested restore from the pre-upgrade backup
A backup only counts once a restore has been performed. Restore the pre-upgrade metadata database dump into a separate instance, start Superset against it, and confirm that dashboards, users and saved queries load. Time the restore and record the steps, so the rollback decision in the change window rests on a known procedure rather than an assumption about how long recovery will take.
How DeployOpen scopes and delivers a Superset 4.x upgrade
DeployOpen approaches the Apache Superset 3.x to 4.x upgrade as a fixed-scope engagement that starts from your current deployment, not from a generic checklist. The work covers the removed feature flags, the Filter Box migration, the MediumText changes and the Talisman default, each tested against your own dashboards and metadata database before anything reaches production.
How we scope
- Inventory your current Superset version, feature flags, dashboards using Filter Box, and any use of Filter Sets or Profile.
- Confirm your metadata database engine and version, and whether MediumText column changes could lock tables at your data size.
- Agree the written scope, deliverables and timeline before work starts; ongoing support is available as a retainer.
How we build
- Take a metadata database backup and run the upgrade in a staging copy first, following the project's upgrade guide.
- Review UPDATING.md for each release between your version and 4.x, and record every breaking change that affects your deployment.
- Re-test filter-driven dashboards and security headers after the Talisman default changes, and document each configuration decision.
How we hand over
- Deliver a runbook covering backup, migration order, rollback steps and the maintenance window for production.
- Provide a dashboard test record showing which charts, native filters and embedded views were checked and their results.
- Walk your platform and data teams through the new configuration, including the explicit settings needed to keep headers enabled.
How we support
- Offer post-upgrade support as a retainer for issues found in production after cutover.
- Plan patching and the next major upgrade against the project's release notes so that each step has a written scope.
