How to plan an Apache Superset upgrade from 5.x to 6.x
Upgrading a production Superset from 4.x or 5.x to the 6.x line is a planned change that needs a metadata database backup, a staging run and defined rollback points before anyone changes the package version. Dashboards, alerts and reports often depend on this instance, and the 6.x line changed authentication, theming and exports in ways that can break them without an obvious error. The 6.0.0 release was published on December 18, 2025 and 6.1.0 on May 13, 2026, so choose a target within that line and confirm the supported path in the Upgrading Superset guide and the breaking change notes in UPDATING.md. Superset is released under Apache-2.0 with no paid edition, so the cost is planning and testing effort, whether your team or a partner carries it.
Start with the changes most likely to break an existing instance. If you still rely on AUTH_OID, the OpenID 2.0 login removed with Flask-AppBuilder 5 in Superset 6.0, you need a replacement login method in place before the upgrade, with existing user records matched to it. If you customized the look through THEME_OVERRIDES, that setting was dropped for Ant Design based themes, so branding must be rebuilt and checked page by page. Review the SQL and export notes in UPDATING.md as well, since newly disallowed SQL functions can cause affected charts to fail. For rollback, back up the metadata database before running superset db upgrade and superset init, keep the previous image or package version pinned, and record the SECRET_KEY and configuration files so you can restore the prior state.
Test the upgrade on a staging copy built from a recent production backup, with the same configuration, SECRET_KEY and connected databases, so results reflect your real data. Run a fixed list: every dashboard that executives or external users open, a sample of charts that use custom plugins or SQL, scheduled alerts and reports delivered to a test mailbox, thumbnails, and CSV and image exports. Record what passes and what fails, fix the configuration or content, and repeat until the list is clean. Agree the go or no-go decision and the rollback trigger before the production window. Effort scales with the number of dashboards, reports, custom visualization plugins and identity integrations, so ask any partner for a quote built from a written inventory of those items and an agreed test list, with staging and test cycles itemized separately.
Which Superset 6.x changes affect your deployment
This table compares the 6.x changes most likely to break an existing 5.x or 4.x deployment, with the impact on dashboards, logins and images and the action each one needs. Confirm every row line by line against UPDATING.md for the exact 6.0.0 and 6.1.0 lists before you schedule the upgrade, since those notes are the authoritative record. Treat any row that touches a login path, a custom theme or a custom image as a blocking item for staging.
| Change | Impact | Action needed |
|---|---|---|
| AUTH_OID removal with Flask-AppBuilder 5 in 6.0 | OpenID 2.0 logins stop working after the upgrade, so users relying on AUTH_OID cannot sign in | Confirm the removal in UPDATING.md, identify every user path that depends on AUTH_OID, and plan the switch to OAuth, OIDC or LDAP before the upgrade |
| THEME_OVERRIDES replaced by Ant Design theme tokens | Custom branding configured through THEME_OVERRIDES no longer applies, so dashboards and pages can revert to default styling | Inventory current overrides, rebuild them as theme tokens, and review each dashboard in staging against the new theme |
| APP_NAME replaced by brandAppName in 6.1 | Configuration that sets the application name through APP_NAME may not display the intended title after moving to 6.1 | Confirm the 6.1.0 change in UPDATING.md, update the setting, and check login, header and email text in staging |
| Custom fonts moved to per-theme settings | Fonts loaded through CUSTOM_FONT_URLS may not render after the theming change | Confirm the replacement setting in the 6.x documentation and test font rendering on the main dashboard views |
| Lean image and Chromium changes in 6.0 | Images built without Chromium cannot produce report screenshots or thumbnails, so alerts and reports may fail | Confirm image contents in UPDATING.md, choose the image variant deliberately, and test a report send from staging |
| Export and screenshot behavior | Exported files and report images can differ in layout or content from earlier releases | Compare sample exports and reports from 5.x with 6.x output before cutover |
| Newly disallowed SQL functions | Charts or virtual datasets that call functions now blocked will return errors | Confirm the exact function list in UPDATING.md for 6.0.0 and 6.1.0, search saved charts and datasets for those functions, and rewrite or allowlist them as your policy permits |
| Metadata migrations run with superset db upgrade | Schema changes must complete before the new code serves users, and failures leave the database partly changed | Back up the metadata database, run superset db upgrade and superset init in staging first, and record the rollback path |
What to back up and inventory before touching production
These six items give you a restore point, a record of what the upgrade must preserve, and a staging copy that behaves like production. Each one produces an artifact you can check before the first production change, so the upgrade starts from known state rather than memory.
Metadata database backup
Take a full backup of the metadata database before running any migration, because superset db upgrade changes its schema in place. Superset is tested with PostgreSQL and MySQL for this role, and the configuration documentation lists PostgreSQL 10 to 17 and MySQL 5.7 and 8.x as supported versions. Confirm your server version is on that list, then record the backup file name, size, checksum and a successful test restore into a scratch database. A backup you have not restored is not yet a restore point.
SECRET_KEY and PREVIOUS_SECRET_KEY record
Superset will not start without a user-specified SECRET_KEY, and it encrypts stored database credentials with that key. Store the current value in your secrets manager, with its version and date, and confirm that the configuration loads it from the environment rather than a file in the image. If you rotate keys during the upgrade, set PREVIOUS_SECRET_KEY to the old value so existing encrypted data remains readable. Losing this key can make stored connection credentials unrecoverable.
Custom configuration and login settings
Export your effective superset_config.py and every environment variable that overrides it, then diff that output against the 6.x configuration documentation. Pay particular attention to OAuth, LDAP and AUTH_ROLES_MAPPING entries, because group-to-role mapping decides who can see which data after the upgrade. Record each provider, callback URL and mapped role in a table. Removed settings such as the retired OpenID 2.0 login must be replaced before cutover, not discovered at login time.
Custom plugins and image inventory
List every custom visualization plugin, its package version and its Ant Design and React dependencies, along with the base image and build command used to produce your running container. Note whether the image installs packages with pip or uv, and whether it bundles Chromium for reports. Each item on this list is a candidate for breakage, so mark which ones you must rebuild and retest in staging. Keep the image tag and digest so you can roll back to the exact previous build.
Staging environment with production-like access
Build a staging stack from the same metadata database engine, the same Superset configuration and the same identity provider settings, pointed at a recent copy of production metadata. Confirm that staging can reach the same analytics databases with the same service accounts and network paths, because a staging copy with broader data access can hide permission failures. Record the restore date and row counts for dashboards, charts, datasets and users so you can show the copy is current. Test first here, never on production.
Alert, report and thumbnail schedules
Export the list of alerts, scheduled reports and their recipients, cadence, dashboard target and screenshot settings. Scheduled reports and thumbnails depend on the caching layer and Celery workers, so also record the Redis or broker and worker queue configuration. After the upgrade, compare each schedule against this list and confirm that a test run delivers output to a sample recipient. Missing schedules are often noticed only when a business owner asks for a report that did not arrive.
Which upgrade path applies to your current release
A 5.x install is the closest starting point to 6.x, so the upgrade mostly depends on which 6.0 changes touch your configuration and customizations. Read the 6.0 entries in UPDATING.md and the upgrade guide, then compare them with your own settings.
- Theming and branding: Confirm whether you set THEME_OVERRIDES or custom font URLs, because 6.0 moved theming to an Ant Design based system.
- Authentication: Check for AUTH_OID settings, since OpenID 2.0 login was removed in the 6.0 line.
- Exports and SQL: Review export settings and any SQL functions that charts or datasets use, since newly disallowed functions can make queries fail after the upgrade.
- Custom images: If you build your own image, confirm that browser and translation packages still match what your reports and alerts need.
Record which items apply to your instance. A 5.x install with no custom theming, no OpenID login and no custom image needs a shorter test list than one with all four, so confirm each item before estimating the work.
A 4.x install crosses the 5.0 release before reaching 6.x, so you must review the breaking changes for both the 5.x and 6.x lines in UPDATING.md. Confirm in the upgrade guide whether the documented path from 4.x to 6.x is a direct upgrade or whether it expects a stop along the way. Do not assume either answer until you have read the guide for your exact version.
- Cumulative changes: Read every UPDATING.md entry between your current release and 6.x, because the 5.0 changes apply to you as well as the 6.0 changes.
- Dependencies: Check your Python runtime, drivers and any custom packages against the release notes for each line you cross.
- Feature flags and dashboards: Confirm that the dashboards and charts you rely on do not depend on settings or features removed in the 4.x to 5.x changes.
- Metadata database: Take a full backup before any migration, and confirm that your database version is supported by the configuration documentation.
Add a staging run that loads every business dashboard and sends one scheduled report through each delivery channel. Involve an outside team if the 4.x instance has years of custom configuration or if the staging results show changes you cannot explain from the release notes.
Releases older than 4.x, and installs built from custom images or deployed with Helm, have the most unknowns. Begin by identifying your exact version and install method, then confirm each change in the upgrade guide and UPDATING.md against that baseline. The official Helm chart is described in the 6.1.0 documentation, while the current development documentation marks it as deprecated and points new deployments to the Kubernetes Operator.
- Secret key and sessions: Confirm that a user-specified SECRET_KEY is set, since Superset requires one to start, and plan any rotation with PREVIOUS_SECRET_KEY.
- Metadata database: Confirm that your installation uses PostgreSQL or MySQL, because the SQLite default is not recommended for production.
- Helm and operator: Review the Kubernetes installation guide and the operator documentation, which is in alpha with a v1alpha1 API that may change between releases.
- Custom builds: Rebuild custom images against the new release and test every package they add.
Get outside help when the installation uses SQLite, skips several releases, runs a heavily modified image, or relies on a Helm chart that you plan to replace with the operator.
Why authentication and theme settings need a decision before the upgrade
Removing AUTH_OID is a login decision, not a configuration tweak. Users who signed in through OpenID 2.0 will not have that path in 6.x, so before cutover you need a replacement ready in staging: an OAuth2 provider, OpenID Connect, LDAP or database login. Choose it with your identity team, then confirm that existing user records match the identities the new provider returns. If they do not match, the upgrade may create new accounts, and dashboard ownership, role assignments and row level security rules tied to the old accounts will not follow the user. Test a real login for each user type, including administrators, before you schedule the production window.
The theme change follows the same pattern. Branding built on THEME_OVERRIDES does not carry into the Ant Design based theming system, so dashboards and the application shell can look wrong until you rebuild the theme tokens and related settings. Decide early what the brand must look like, who owns the theme files, and how the theme is tested. Capture before and after screenshots of representative dashboards in staging, since a theme that looks correct on the login page can still break chart colors or fonts further in. The detailed steps for each change are covered on the sibling pages for the AUTH_OID migration and the THEME_OVERRIDES rebuild. Both decisions shape who can sign in on cutover day, so settle them before the upgrade plan is approved.
Running the Apache Superset upgrade sequence with rollback points
This sequence moves a Superset 4.x or 5.x deployment to the 6.x line in an order that keeps a known-good state available until the upgraded staging copy has passed its tests. Each step names a check and the rollback action that applies if the check fails.
Freeze changes and prove the backup restores
The platform owner stops configuration changes, dashboard edits and role changes on the production instance for the duration of the upgrade window. Take a backup of the metadata database, then restore it into a separate scratch database and confirm that the restored copy starts a Superset web process that loads dashboards, charts and saved queries. The step is done when the restore has been tested and the restored database is recorded as the rollback point. Ask your database team to confirm the backup format and the restore procedure in writing before you rely on it.
Deploy the 6.x build to staging
The deployment engineer builds or pulls the 6.x image and deploys it to a staging environment that mirrors production: the same SECRET_KEY handling, the same metadata database engine and version, the same caching layer, Celery workers and beat processes, and the same authentication settings. Compare the Superset configuration against the release notes and UPDATING.md for 6.x, since the AUTH_OID removal and theming changes can affect configuration keys. Staging is ready when the web process starts and the login page loads. Rollback at this point costs nothing in production because production still runs 5.x.
Run database migrations and initialization on staging
Against the staging copy of the metadata database, run superset db upgrade and then superset init, as the upgrade documentation describes. Review the migration output for errors and record the start and end state. The step is complete when both commands exit cleanly and the application starts without database errors. If a migration fails, discard the staging database copy, restore the backup into a fresh staging database, and investigate before retrying. Do not run these commands against production until staging passes the full test plan.
Run migrations on production and restart processes
Once staging is approved, the platform owner repeats the same backup check, runs superset db upgrade and superset init against the production metadata database, then restarts the web and worker processes so that every node runs the 6.x build. Confirm that the Celery workers and beat process are running the new image and that scheduled reports are re-registered. This is the point of no clean return: after migrations succeed on production, reverting to 5.x requires restoring the metadata database backup taken in step one, and any changes made to production after that backup will be lost. Say so in the change record before you start.
Verify health and application logs
The operations engineer checks that the web processes respond, that the metadata database connection pool is healthy, and that the worker logs show tasks completing without import or schema errors. Confirm that cached queries and thumbnail generation work, since these rely on the caching layer and workers. The step is done when a smoke test of login, a dashboard load and a chart query succeeds on production. If health checks fail and the cause is in the application rather than the data, redeploy the 5.x image against the restored backup as the rollback.
Run the dashboard and report test plan
The QA owner runs the agreed test plan on production or a read-only validation copy: dashboards render with the 6.x theme, charts return the same results as before the upgrade, exports produce the expected files, SQL that depends on functions newly disallowed in 6.x is reviewed and fixed, and alerts and reports send. Record each result against the test case and the owner who signed it off. The plan passes when every critical dashboard and scheduled report has a documented outcome. Any failed case that cannot be fixed in the window triggers the rollback decision made in the change record.
Close the change or roll back
The platform owner closes the change only after the test plan is signed off and the post-upgrade backup of the 6.x metadata database has been taken and restore-tested. If the decision is to roll back, redeploy the 5.x image, restore the step-one backup, restart the web and worker processes, and rerun the smoke test to confirm the 5.x state. The close-out record should list the image versions, migration output, backup identifiers and test results so that the next upgrade starts from a documented baseline.
How to test dashboards and reports in staging before production
Before any production cutover, build a fixed test list and agree the pass criteria in writing before anyone runs it. Pick the critical dashboards the business relies on, and for each one record the expected row count, the default native filter values and the saved charts it depends on. Run the same checks against the 5.x environment first so that any difference in the 6.x staging results is a difference you can explain, not a baseline you invented after the fact. Cover the export formats your finance, operations and compliance readers actually use, such as CSV, Excel or PDF, and compare the files cell by cell against the 5.x output, since theming and rendering changes can shift layout even when the data is correct.
Alerts, scheduled reports and thumbnails need their own tests because they run through the caching layer and worker components rather than the browser session. Point every test alert and report recipient at a controlled test inbox, confirm each scheduled report is delivered on time with the expected attachment, and check that thumbnails render for large dashboards. Log role-based access for representative users in each role, including row level security filters, and confirm that users see only what their roles allow. Ask your team to confirm which Superset features each dashboard depends on before the test, because gaps found in production are far more costly than gaps found here.
Record every result in a signed-off test log that names the tester, the Superset version, the environment, the date and the outcome of each check, with a named owner who approves the go decision. Keep the 5.x environment running, with its metadata database backup intact, until your rollback window closes, and confirm with your own change process how long that window is. Treat any failed check as a blocker unless the business owner of that dashboard accepts the difference in writing. Review the Superset upgrade guide and the breaking change notes in UPDATING.md again just before the test starts, since the test list should follow the changes that actually apply to your deployment.
What makes a Superset 6.x upgrade take longer
This table lists the factors that most often stretch a 5.x or 4.x to 6.x upgrade and what to measure for each before you set a schedule. Use it to size your own staging work, and treat any item with a high count or an unclear answer as a reason to add test time.
| Driver | Why it adds effort | What to measure |
|---|---|---|
| Custom plugins and chart overrides | Custom visualization plugins and overridden chart code must be rebuilt against the 6.x React and Ant Design versions and tested chart by chart. | Count plugins, overrides and forked files, and note which ones rely on THEME_OVERRIDES or old form data fields. |
| Metadata database size and age | The superset db upgrade step runs schema migrations that can lock tables on a large or long-lived database, and older installs may carry more migration history. | Database size, row counts in large tables, database version against the supported PostgreSQL and MySQL range, and time since last migration. |
| Dashboards and reports to test | Each dashboard, chart and scheduled report must be checked for rendering, filters, data results and screenshot output after the upgrade. | Number of dashboards, active alerts and reports, and how many are owned by teams that must sign off. |
| Authentication setup | AUTH_OID was removed with Flask-AppBuilder 5 in Superset 6.0, so OpenID 2.0 logins must move to OAuth, OpenID Connect, LDAP or database login before go-live. | Which login methods are configured, whether any use AUTH_OID, and how group mappings through AUTH_ROLES_MAPPING are maintained. |
| Custom Docker images and dependencies | Custom images, Python packages and database drivers must be rebuilt and checked against the new base image and runtime requirements. | Number of custom Dockerfile layers, extra driver packages, and whether the build pulls in packages from private indexes. |
| Deployment method | PyPI, container and Kubernetes installs change in different ways, and the Helm chart is marked deprecated in current development docs, which can add rework when moving to the Kubernetes Operator, which is in alpha. | Install method in use, whether Helm values are customized, and whether the team will need to adopt the Operator's v1alpha1 resources. |
| Maintenance window | Migrations, rollback planning and report testing need a window in which no users or scheduled jobs are writing changes, and the window length depends on the database and job load. | Whether a window is approved, how long it must be, who can approve a rollback, and when scheduled reports run. |
What buyers ask before hiring help with a Superset upgrade
What does a Superset 5.x to 6.x upgrade cost?
The cost is set by the written scope, not by a list price. DeployOpen does not publish prices, so a quote follows from the scope agreed before work starts. The main components are discovery of your current version, configuration and metadata database, the backup and migration rehearsal, the AUTH_OID and theming changes that apply to your deployment, staging test work for dashboards and reports, and the production cutover with rollback notes. Costs rise with the number of dashboards, custom chart plugins, custom Docker builds, authentication integrations and report schedules. Ask any quote to separate one-time work from recurring support, and to list which items are in scope and which are client tasks.
How long does a Superset upgrade take?
Duration depends on what the upgrade touches, not on the version number alone. The biggest drivers are the size of the metadata database and whether its migrations lock tables, how many dashboards and scheduled reports need checking in staging, whether you use alerts and reports that depend on the caching layer and worker components, and how many custom plugins or authentication changes must be rebuilt. Your team also sets the pace through test user availability and sign-off cycles. Ask for a timeline that names the staging window, the production change window and the dates on which client approvals are needed.
What does our team need to provide for the upgrade?
Plan for four kinds of input before the work starts. First, access to the metadata database, the deployment configuration and the secret handling used for SECRET_KEY, along with a current backup location. Second, test users in each role your access model defines, so dashboards and reports can be checked as the people who use them. Third, approvals from the owners who sign off change windows and production cutover. Fourth, named data owners who can confirm that key dashboards and charts show the expected results after the move. Ask the provider to list these inputs in the written scope so gaps show up early.
Can our own team run the Superset upgrade without a partner?
Yes, if your team has the skills and time to run the official steps. The project's upgrade guide 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 between versions. The engineering risk is in the details: the AUTH_OID removal in 6.0, theming changes that replace THEME_OVERRIDES, and any custom visualization plugins or Docker image builds that depend on removed components. Compare your team's capacity against those items. A partner is most useful when the release notes touch systems your team does not run often, or when the staging window is tight.
What happens if the Superset upgrade fails in production?
A failed upgrade should be recoverable because the metadata database was backed up before any migration ran. The rollback plan should name the backup you restore, the version you return to, and the checks that confirm dashboards, users and reports are back. Migrations that fail partway are the highest-risk case, so rehearse them in staging on a copy of production data first. Ask the provider to document the rollback steps, who decides to roll back, and how long the service may be unavailable during that decision. Confirm the exact restore procedure for your database engine with your database administrator.
How should we compare upgrade quotes from different providers?
Compare the written scope first, then the price. Two quotes are only comparable if they cover the same Superset version path, the same deployment (PyPI, containers or Kubernetes), the same staging test plan and the same cutover and rollback work. Check whether each quote includes the metadata database backup and migration rehearsal, the review of AUTH_OID and theming changes, testing of reports and scheduled deliveries, and documentation handed over at the end. Ask whether ongoing support is separate, and whether it is a retainer. Also ask for named deliverables and client responsibilities, so you can hold the provider to them.
Which Superset components need extra attention during the upgrade?
Engineers should check the components that other pieces depend on. Alerts and reports, async queries and dashboard thumbnails require the caching layer and worker components, and most installations use Redis and Celery for them, so both the web application and the workers must move to the new release together. Confirm the metadata database is on PostgreSQL or MySQL, since the SQLite default and the Docker Compose PostgreSQL container are not recommended for production. Check the supported metadata database versions for the release you target, which the configuration documentation lists as PostgreSQL 10 to 17 and MySQL 5.7 and 8.x. Verify that SECRET_KEY and any PREVIOUS_SECRET_KEY settings survive the change.
How DeployOpen scopes, tests and supports a Superset upgrade
DeployOpen treats the move from Superset 5.x to 6.x as a planned change to a running system, not a version bump. We scope the work in writing, build and test it in a staging copy of your deployment, and hand over runbooks your team can repeat. Engagements are fixed-scope, and ongoing support is available as a retainer.
How we scope
- We inventory your current Superset version, metadata database, caching and worker components, and custom extensions before quoting.
- The written scope lists which 6.x breaking changes apply to your deployment, such as AUTH_OID, theming and export settings.
- We agree in writing which dashboards, reports and users are in the staging test set and what counts as a passing result.
How we build
- We take and verify a metadata database backup, then rehearse superset db upgrade and superset init against a staging copy first.
- We update configuration for the 6.x settings you use, including SECRET_KEY handling, authentication and role mapping.
- We run the staging test plan for dashboards, alerts, reports and thumbnails, and record every failure with its fix before production.
How we hand over
- You receive the upgrade runbook with backup, migration, rollback and post-upgrade verification steps written for your environment.
- Configuration changes are documented against your deployment files, so your team can reproduce them in later releases.
- We walk your platform and security staff through the test results, open items and the decisions that still belong to your organization.
How we support
- Post-upgrade issues found in the agreed scope are handled under the written engagement terms.
- Ongoing support, upgrades and continuous testing for Superset are available as a retainer.
- We can plan the next major step, such as the 7.0 line, once you confirm which 6.x features and configuration you rely on.
