Consolidate Superset instances into one

Consolidate Superset instances into one without losing access or dashboards

Consolidating several Superset instances into one is feasible on the documented export and import paths, but the effort is driven far more by access model redesign and database connection cleanup than by how many dashboards exist. Dashboard count is the easy part to estimate; the access model and connections decide the schedule. Each departmental or acquired instance carries its own users, roles, row level security rules, database connections and asset identifiers, and those four sets rarely line up without deliberate decisions. We do not give effort figures here because the scope depends on the inventory, and no two merges look alike once you list what each instance actually holds.

Treat the work as a planned, scoped project cut over in stages. Start with an inventory of every instance: dashboards, charts, datasets, saved queries, alerts and reports, owners, and the databases each one connects to, including which connections hold stored passwords that will not transfer in a ZIP export. Then decide the target role model and row level security design before moving any content, because roles and RLS rules are where data exposure risk concentrates after a merge. Check the source instances for asset UUID collisions, since the same dataset may have been created twice. Confirm with your Superset version's documentation how export and import handle overwrite behavior and passwords before you rely on it, and review the Superset architecture documentation for the metadata database and worker components the target will need.

Plan the cutover so both old and new instances can be checked side by side. Migrate users in groups, validate access for each department against the new roles, and keep the source instances read-only until owners confirm their dashboards render with the expected data. Back up each metadata database before any import, and test the whole sequence in staging first, following the project's upgrade guidance where versions differ. Ask your implementation partner for a written inventory, a role and RLS design review, a connection rationalization list and a cutover checklist as fixed-scope deliverables before committing to a timeline.

What maps cleanly from each source instance and what needs redesign

This table compares each asset and setting in a departmental Superset instance with its equivalent in the consolidated instance. Read the second column for what moves as an exported asset, and the third for what must be recreated or re-tied to the target's metadata database, SECRET_KEY and identity provider.

Source item	Consolidated target	Migration path
Dashboards and charts	Dashboards and charts in the target metadata database	Usually import as assets, but check that each chart's dataset and database reference resolves in the target
Datasets	Datasets bound to a target database connection	Import with their definitions, then confirm they point to the consolidated connection and not a duplicate
Saved SQL queries	Saved queries in SQL Lab, owned by the original user	Confirm whether saved queries are included in your export; otherwise recreate them under a service owner
Database connections	One connection per warehouse, shared across departments	Passwords are not carried in exports; re-enter credentials and test each connection before importing dependent assets
Roles and permissions	Target roles built from a shared permission model	Recreate; source roles often overlap or conflict, so map by job function rather than copying names
Row level security rules	RLS rules attached to target datasets and roles	Redesign; filters written for one department can expose or hide data in another, so re-test each rule
LDAP or OAuth group mappings	AUTH_ROLES_MAPPING in the target configuration	Rebuild against the consolidated identity provider; group names and tenant boundaries usually differ
Alerts and reports	Schedules tied to target workers, Redis and SMTP settings	Recreate; they depend on the target caching layer, Celery workers and owner accounts that must remain active
User accounts	Users in the target metadata database, linked to the identity provider	Recreate through SSO where possible; local passwords and inactive accounts need a deliberate decision
Encrypted credentials and secrets	Values encrypted with the target SECRET_KEY	Not portable across different keys; plan key handling, including PREVIOUS_SECRET_KEY, before any import

Why UUID conflicts and database connections break merges

Every Superset asset carries a UUID, and that identifier decides what happens when two instances meet. A dashboard, chart or dataset exported from one instance and imported into another keeps its UUID. If the target already holds an asset with the same UUID, the import has to either replace the existing object or create a second copy, and the outcome depends on the overwrite behavior the import uses. Two departmental instances often hold copies of the same dataset that were created by export and re-import, so they can share UUIDs without anyone noticing. Before any merge, list which UUIDs already exist on the target, decide which copy is authoritative for each asset, and confirm the exact overwrite and duplication behavior in the documentation for your target release, since it has changed across versions.

Database connections are the second break point. Exports do not carry database passwords, so every connection must be re-entered or re-keyed on the target, and dashboards and datasets that point at a connection with a different name or ID will fail until the reference is corrected. Ask each department for a register of its database connections, the owning team and the service account each one uses, then map every source connection to a single target connection. Plan the reconnection work before the import, because a merged dashboard that loads with broken datasets looks like a migration failure to business users even when the data moved correctly.

The SECRET_KEY setting must be settled before any data moves. Superset uses it to encrypt the database credentials it stores in the metadata database, so a target instance that starts with a different key cannot read connection secrets copied from a source instance. Choose the target key, store it in your secrets manager, and record any PREVIOUS_SECRET_KEY that a source instance still needs during the transition. Then test a single connection end to end on the target before importing anything else. The Superset configuration documentation covers key rotation and should be read against the version you run.

Documented export, import and API paths for moving assets

Consolidation moves four kinds of state: content, the metadata database, users and access rules. Each path below moves some of them and leaves others behind, so most plans combine several. Test every path in staging against the exact Superset versions involved before relying on it.

ZIP export and import from the interface

Exporting dashboards, charts and datasets from the Superset interface produces ZIP bundles that another instance can import. The bundle carries dashboard layouts, chart definitions and dataset definitions, which makes it the most direct way to bring one department's work into a consolidated instance. Expect to recreate user accounts and roles yourself, and confirm whether row level security rules and database passwords travel in the bundle. Also confirm, in the release notes for your version, how imports treat existing UUIDs and whether they overwrite matching assets.

Command-line export and import

The superset command line includes export and import commands for assets, which suits scripted batches when a department holds many dashboards. Scripts can run against a staging target and repeat until the result matches the expected inventory. Command names, flags and file formats change between releases, so take them from the documentation for the exact version you run and check any older guidance against it. Confirm how reruns handle existing UUIDs, because that decides whether a second run updates assets or duplicates them.

Metadata database backup and restore

The metadata database holds dashboards, charts, datasets, database connections, users and roles, so a full backup is the only path that moves all of them in one step. The upgrade guide asks teams to back up the metadata database before any schema change, and the same backup can seed a rehearsal of the consolidated instance. A restore overwrites the target database, so this path fits a new, empty target only. Confirm which stored values depend on SECRET_KEY, because the target must be configured with the matching key before those values can be read.

REST API for inventory and user listing

The Superset REST API can list dashboards, charts, datasets, databases and users on each source instance, which lets you build a complete inventory before any move starts. Read-only inventory calls are the safest starting point, and a service account with only read permissions keeps the audit trail clear. Endpoint names, pagination and returned fields vary by version, so confirm them in the API reference for your release. Also check what the service account can see, because a narrowly scoped account can hide ownership gaps from the inventory.

Auth role mapping configuration

The configuration file controls how login groups become Superset roles. AUTH_ROLES_MAPPING translates LDAP or OAuth groups into roles, so migrated users receive their access from the directory without manual role edits on the consolidated instance. The mapping moves only the group-to-role logic. Permissions inside each role, datasets, and the users themselves still need separate work. Confirm how the mapping treats roles that exist on a source instance but not on the target, and check that group names match exactly between the directory and both instances.

How to sequence inventory, pilot, parallel run and cutover

This sequence moves departmental Superset instances into one target without losing assets or access, because each phase closes with a written exit check before the next one starts. Source instances stay readable until the reconciliation and cutover checks pass.

Inventory every instance and its assets
Record each source instance's Superset version, metadata database, cache and worker setup, and authentication method. Then list every database connection, dataset, chart, dashboard, saved query, alert, report, role, user and row level security rule, with its owner and the department that relies on it. Your data team and each department lead confirm the list. The exit check is a signed inventory with an owner for every asset and a named decision for each duplicate or unused item.
Decide the target model and upgrade prerequisites
Choose the target layout for roles, row level security, database connections and folders before any data moves. If the source instances run different Superset versions, plan an upgrade of each source to a single version first, and check the upgrade notes for breaking changes in each version step. Confirm the target uses a supported metadata database, since PostgreSQL and MySQL are the tested options. The exit check is an approved design record and an upgrade plan that the source owners have reviewed.
Build and harden the target instance
Your platform team builds the target from the same version and configuration standard, with a production metadata database, a required SECRET_KEY and the authentication setup from the design record. Database connection credentials are re-entered in the target from your secrets store, not copied from source files. Your security team runs the hardening checks against the target before any user or data arrives. The exit check is a signed build record and a passing security review of the target configuration.
Back up each source metadata database
Take a verified backup of every source metadata database and keep it in a location that the source owners cannot modify. Test the restore on a separate host so you know the backup is usable before you touch any asset. Keep the source secret key values with the backups, because encrypted connection passwords depend on them. The exit check is a restore test that completes and a recorded backup identifier for each source.
Pilot one department with a copy of its assets
Move one department's assets to the target in a copy, using its inventory list, and rebuild the roles and row level security rules for that group only. Ask five to ten representative users to check their dashboards, filters, scheduled reports and data results against the source. Record every difference and fix the cause before the next department starts. The exit check is a pilot sign-off from the department lead and a list of closed defects with no open data access issues.
Run source and target in parallel with reconciliation
Keep the source instances in read use while the target receives the remaining departments. Compare row counts, dashboard results, dataset definitions and access checks between source and target on a schedule your data owners agree. Confirm that scheduled reports and alerts run from exactly one place to avoid duplicate sends. The exit check is a reconciliation report with no unexplained differences and an owner sign-off for each department.
Cut over users by group
Move users to the target one group at a time, starting with the pilot department, and point their links and bookmarks to the target. Remove the source login for each group after its users confirm access, and disable scheduled reports in the source for that group. Keep a short rollback path for each group until its first business cycle ends. The exit check is a user access list where every active user has a working target login and no active source reports remain for that group.
Decommission source instances after retention
Once every group has cut over, make the source instances read-only and keep their backups for a retention period set by your records policy and any regulatory duties that apply to your sector. Confirm with your compliance lead that audit logs needed for the migration are archived before shutdown. Then remove the source hosts, credentials and database connections. The exit check is a decommission record that lists retained backups, archived logs and removed credentials, approved by the data owner.

Choosing one shared instance, shared instance with workspaces or separate instances

A single Superset instance serves every business unit. Separation happens inside the application: each team gets roles that limit which dashboards, charts, datasets and SQL Lab features it can reach, and row level security (RLS) filters the rows a user can see inside a shared dataset. This model keeps one metadata database, one set of workers and one upgrade cycle, but every access decision then depends on role design and RLS rules being correct and tested.

Access model: Custom roles mapped to business units, plus RLS clauses on shared datasets. Expect to test that a user in one unit cannot see another unit's charts through shared datasets, saved queries or exports.
Migration effort: Dashboards, datasets and databases from each source instance must be re-keyed to avoid UUID collisions, and every existing ownership and role assumption must be redesigned rather than copied.
Operational load: Lowest. One platform to patch, back up and monitor, with one set of connection credentials to rotate.
Shared risk: A misconfigured role or RLS rule exposes data across units, and a single outage affects all units at once.
Questions to answer first: Do auditors accept logical separation for this data? Who owns role and RLS changes? Can the warehouse enforce its own row policies for the sensitive tables?

Confirm with your auditors and data owners that application-level isolation meets their expectations before you commit to this model.

What drives cost and duration in a Superset consolidation

This table lists the factors that raise or lower the effort of merging several Superset instances, with what increases each factor and how to keep it manageable. Read it as a checklist for the written scope: the larger each driver, the more discovery, redesign, migration engineering, testing and cutover time a quote will need to cover.

Driver	What increases it	What reduces it
Source instances and versions	Many instances, each on a different Superset version, with custom plugins or forked images	Fewer instances, a common version before migration, and documented differences between instances
Database connections and credentials	Many connections to the same warehouse, unknown owners, and credentials that must be rotated during the move	A connection inventory with owners, one shared connection per source system, and a rotation plan agreed early
RLS and role complexity	Row level security rules and custom roles that overlap across departments and must be merged into one model	A target role model agreed before migration, with RLS rules reduced to documented business rules
Users and group sources	Local accounts, several LDAP directories or OAuth tenants, and unclear group-to-role mappings	One identity provider, a single group source, and a mapping table reviewed by each department owner
Alerts and reports	Scheduled reports and alerts with recipients outside the target owner's team, and worker or cache dependencies on each source	Retiring unused alerts, reassigning owners, and confirming delivery channels before cutover
Embedded dashboards	Embedded dashboards in other products, with guest token or tenant logic tied to the source instance	Keeping embedding endpoints stable, or scheduling a coordinated change with the product teams that embed them
Regulatory approvals	Personal data or regulated data moving between legal entities, or access by staff in other jurisdictions	Early involvement of privacy, compliance and legal owners, and a written data flow for each source
Inventory cleanup	Duplicate dashboards, abandoned charts, stale datasets and undocumented ownership	A pruning decision per asset, made by the business owner before migration starts

Questions buyers ask before consolidating Superset instances

How much effort does it take to consolidate several Superset instances?

Effort depends on how many instances, databases, dashboards and users are being merged, and on how much of the existing access model has to be redesigned rather than copied. The main drivers are the number of datasets that point at the same warehouse under different connection settings, the number of dashboards that rely on row level security, and the number of role definitions that overlap across departments. Each source instance adds an inventory and a review step. Ask any partner to base its quote on a written inventory of assets, connections, roles and users for every instance, because that inventory is what turns a vague estimate into a fixed scope. Most of the cost is labor for analysis, redesign and verification, and the cost of hosting the target instance is small by comparison.

How long does a Superset consolidation take?

The timeline is set by the decisions that have to be made before technical work starts, more than by the export and import steps themselves. Timing is usually driven by how quickly data owners confirm which dashboards are still in use, how long role and row level security redesign takes to approve, how many source instances must be migrated in sequence, and how much testing the business asks for before cutover. Reorganizations and acquisitions often add pressure from outside the project, such as a shared warehouse cutover or a reporting deadline. Ask for a schedule that separates inventory, design, migration, verification and cutover, and that names the approvers for each gate. Do not accept a duration that is not tied to those gates.

What must our internal team provide before a consolidation starts?

Your team must provide the facts and the decisions that a partner cannot infer from the instances alone. The list usually includes:

A complete inventory of dashboards, charts, datasets, saved queries and alerts on every source instance, with owners named for each.
The list of database connections, with the warehouse accounts behind them and the people who can approve credential changes.
The group structure in your identity provider, with an owner for each group and an approver for access changes.
Written decisions on which dashboards are retired, which are merged and which must keep their current audience.

Without these inputs, the work stops at the design stage, because roles, row level security and connection ownership cannot be settled without them.

Can our internal team run a Superset consolidation alone?

Yes, an internal team can run a consolidation if it has engineers who can operate Superset and databases, a named owner for each data domain, and time to review the work. The project documentation covers the core steps: back up each metadata database, run the upgrade commands on the target in staging first, and check UPDATING.md for breaking changes between versions. Where a partner adds value is in the parts that are easy to get wrong, such as UUID conflicts during dashboard import, redesigning roles and row level security so that access is not widened by accident, and building verification evidence that an auditor or internal reviewer can follow. Decide early which of these you will do yourself and which you will buy as a fixed-scope piece.

Can dashboards be moved between Superset instances without rebuilding them?

In many cases dashboards can be exported and imported without rebuilding charts, because Superset supports ZIP export and import of dashboards, charts and datasets. Results depend on version, on whether the target uses the same database connections, and on whether UUIDs collide with objects already on the target. Connection passwords are not carried in a way you can rely on, so each imported database connection needs its credentials supplied again. Datasets that refer to a database under a different name or with different schemas may need edits before the charts work. Test one representative dashboard from each source first, and confirm the import behavior for your Superset version in the documentation before you plan the bulk move.

What happens to users, roles and passwords during consolidation?

Users need a single login path on the target, and roles need to be redesigned rather than copied one for one. If sign-in is delegated to an identity provider through OAuth2 or LDAP, user accounts can be created from directory groups, and AUTH_ROLES_MAPPING can map those groups to Superset roles. Local accounts with passwords need a deliberate decision: either they are recreated with password reset, or they are retired in favor of the directory. Before cutover, confirm which roles on each source grant more access than the target should allow, and review row level security rules together with those roles. Passwords should not be copied between systems, and the SECRET_KEY on the target needs to be managed as a long-lived secret because encrypted connection data depends on it.

How do we keep source instances running during the parallel run?

Keep each source instance read-only or clearly marked as retiring once its dashboards are copied, and run the target alongside it until users have confirmed their views match. Plan the parallel run with explicit rules: which instance is the record for each dashboard, how changes made during the run are reconciled, and which source is switched off first. Do not let two instances serve edits to the same dataset without a reconciliation plan. Use the parallel period to compare key dashboards, check alert and report schedules so they do not fire twice, and confirm that scheduled work on the sources has stopped before the sources are retired. Document the cutover date and the rollback path in writing.

What usually goes wrong in a consolidation and how to prevent it

Consolidations fail in predictable places: assets that collide, connections that break, and access that widens without anyone deciding it should. Each failure below has a prevention step to build into the plan and a check that confirms the step worked before users move over.

Duplicated or overwritten assets

Dashboards, charts and datasets carry UUIDs, and importing an export from one instance into another can overwrite an asset that shares an identifier with one that already exists. Assign each source instance a naming prefix and a target owner for every asset before any import runs. Check by importing into staging and confirming that the asset count per instance matches the inventory and that no existing dashboard changed its last-modified time.

Broken database connections after credential reset

Database connections imported from another instance often arrive without their passwords, so charts that worked yesterday fail on the first query. Credentials may also have been rotated during the reorganization, which leaves stored values stale. Record every connection, its owner and its credential source, then re-enter secrets in the target instance under a controlled change. Check by running a test query from each dataset and confirming that the warehouse audit log shows the expected service account.

RLS rules that expose rows across departments

Row level security filters are written against table and role names, and a filter copied from one department can silently apply to the wrong population or to no one after roles are merged. A missing filter on a shared dataset is the most serious case because it returns rows without any error. Rewrite every RLS rule against the target role model and assign it explicitly to the roles that should see it. Check by logging in as one representative user per department and confirming that row counts match what the source system returns for that user.

Group mappings that grant too much access

When identity groups from several directories are mapped to Superset roles, a single broad group can carry admin or data-access roles from a former organization. Mapping configuration is also easy to copy without review. Map each identity group to the narrowest role that covers its job, and remove any mapping that cannot be traced to a current owner. Check by exporting the role-to-user assignments from the target and comparing them against the approved access list for each department.

Lost alerts and scheduled reports

Alerts and scheduled reports live in the metadata database and depend on the caching layer and worker components. A migration that moves dashboards without moving these schedules, or that starts a second set of workers pointing at the old instance, leaves recipients with no reports or duplicate ones. Inventory every alert and report with its recipients, then recreate them on the target and disable the source schedules at cutover. Check that each scheduled item has a recorded next run on the target and that the first run delivers to the expected recipients.

Users cut over before data is verified

Moving user accounts before dashboards and data have been reconciled sends people to numbers that do not yet match the source. Early complaints then erode trust in the consolidated platform. Gate each department's user cutover on a signed reconciliation of its key dashboards against the source instance. Check by confirming that the agreed metrics match within the tolerance the data owner accepted, and that a rollback path to the source instance is tested before users are switched.

What acquisition and regulatory obligations change the consolidation plan

Consolidating Superset instances after an acquisition can touch more than the BI team's schedule. Depending on your listing status, sector and footprint, the merge may fall inside internal control reporting, cybersecurity disclosure, third-party oversight or data transfer rules. Confirm with counsel and your auditors which of these apply before you fix the migration order. The SEC allows management to exclude a newly acquired business from its internal control over financial reporting assessment, but only for a limited period, not beyond one year from the acquisition date, and the exclusion must be disclosed. If Superset feeds financial reporting, the access and change controls on its roles, datasets and row level security still need documented evidence in the period you are merging.

The SEC's guidance on IT general controls names program changes and access to programs and data as areas to evaluate where they support financial reporting controls. For this topic, that means keeping a dated record of who was granted Admin, Alpha or dataset-level access during the merge, who approved each import, and which database connections were repointed. Under NIS2, an entity in scope must give its competent authority its contact details, IP ranges, sector and Member States of service, and notify changes without delay and in any event within two weeks, so an instance moving to a new network range or a new legal entity may trigger a notice. DORA requires financial entities to keep a register of ICT service arrangements and tested exit strategies for services supporting critical or important functions, so a consolidated Superset that depends on an outside host or support provider belongs in that register.

GDPR adds two checks. If a non-EEA acquirer's staff will reach EU personal data in the merged instance, including for support or administration, EDPB Guidelines 05/2021 treat that remote access as a transfer that needs a Chapter V transfer tool. Any processor handling the data must act only on your documented instructions under Article 28(3)(a), and your records of processing should describe the Article 32 measures for the merged instance. DeployOpen can prepare the controls, configuration evidence and runbooks these reviews ask for, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those determinations.

How DeployOpen works on this

DeployOpen plans and delivers this consolidation inside your own infrastructure, starting with a written scope that covers the instances, databases, roles and users involved. The work moves through inventory, a tested staging rehearsal and a controlled cutover, with documentation and operating handover for the team that will run the merged Superset afterward.

How we scope

The written scope lists every source instance, metadata database, database connection and user population in the consolidation.
We agree in writing which dashboards, datasets and charts move, which are retired and which are rebuilt.
The scope states who approves the role and row level security redesign and who signs off the cutover.

How we build

We build the target instance in your infrastructure and rehearse the merge in staging before any production change.
Duplicate UUIDs and conflicting dataset names are resolved from a documented mapping, not by ad hoc edits.
Each role, row level security rule and database connection is tested against the access model your reviewers defined.

How we hand over

You receive the inventory, mapping decisions, configuration and runbooks in your own repositories and systems.
Operators walk through the merged instance, including backups taken before upgrade and the verification checks used at cutover.
The handover lists open decisions and items your team must confirm with data owners after go-live.

How we support

Engagements are fixed-scope, and the written scope defines when handover is complete.
Ongoing support, upgrades and continuous testing are available as a retainer after the consolidation.
Requests to add users, sources or roles after cutover follow the same written change process as the original scope.

Consolidating several Superset instances into one