Multi-tenant Superset design for SaaS analytics

Choosing a multi-tenant Superset design for SaaS analytics

A SaaS team that embeds Superset dashboards must show each customer only its own data, and the design decision comes down to three options: one shared Superset instance with row level security (RLS), a database or schema per tenant, or a separate Superset instance per tenant. The choice is driven by your isolation requirements, how many tenants you serve, and how much operations capacity your team can staff. Superset's documented architecture has four components, the Flask and React application, a metadata database, an optional caching layer and optional Celery worker and beat processes. In a shared design, the application, metadata database and workers serve every customer, and tenant separation depends on the data access rules you configure. In a per-tenant design, some or all of those components are replicated, which multiplies the upgrade, backup and monitoring work. No option removes the need to test guest tokens and RLS rules, because a per-tenant instance still relies on the access model inside each instance.

The shared option has the lowest number of components to run, but its isolation depends entirely on the RLS rules, the guest token resources and the database role behind each dataset. Ask your team to confirm how each customer's identity maps to a filter, and whether any dataset can be queried without one. The database or schema per tenant option moves part of the isolation into the warehouse, which can make the boundary easier to explain to auditors, but it adds connection, permission and dataset definitions for every tenant. The per-instance option gives the strongest separation of metadata, users and caches, and it is the most expensive to operate, because each instance needs its own upgrade cycle as described in the upgrade documentation. Each option has a recurring cost in staff time, and the one-time cost is the design and automation work needed to provision tenants reliably.

Before you decide, write down your tenant onboarding and offboarding process, the regulatory and contractual isolation terms in your customer agreements, and the number of Superset upgrades your team can test each year. Also confirm your metadata database choice, because the configuration documentation lists supported PostgreSQL and MySQL versions and the architecture documentation says SQLite is not recommended for production. Ask for a written trade-off comparison from any partner, with the assumptions behind each cost line, before committing to a design.

How the three tenant isolation models differ

All tenants share one Superset deployment, one metadata database, one set of workers and one cache. Separation is enforced inside Superset by roles, dataset permissions and row level security (RLS) rules that add filter predicates to queries before they reach the warehouse. Because every tenant sits in the same application, a single misconfigured role, a dataset exposed to the wrong group or a missing RLS rule can show one customer another customer's rows.

Enforcement point: Superset role assignments, dataset access and RLS clauses, which depend on the tenant identifier reaching Superset correctly.
Shared components: The metadata database, Celery workers, caching layer, dashboard thumbnails and alert schedules all serve every tenant.
Upgrades: One upgrade path covers all tenants, so a single backup, staging test and migration run applies to everyone.
Operational burden: Concentrated in the platform team, which must audit RLS rules and role changes continuously as tenants and datasets change.
Noisy neighbor risk: Heavy queries from one tenant consume the same workers and warehouse capacity as everyone else's.

Confirm with your security team how RLS rules are tested and reviewed before each release, and whether your auditors accept application-level tenant separation for the data classes you hold.

Configuration options and when each fits

This table compares one shared Superset with row level security, a database or schema per tenant, and an instance per tenant across isolation, metadata, caching, upgrades, branding, authentication and embedding. Read each row as a question to answer for your own tenant count and data sensitivity. The main takeaway is that isolation gains from separate instances come with a recurring operations cost that a quote must include.

Dimension	One shared Superset with RLS	Database or schema per tenant	Instance per tenant
Isolation strength	Relies on RLS rules and guest token resources being correct for every query; one misconfigured rule can expose data across customers	Data separation is enforced by database privileges and connection credentials, so a rule error is less likely to cross tenants	Strongest separation: no shared web tier, metadata or cache, so a fault in one tenant's instance does not reach another
Metadata database handling	One PostgreSQL or MySQL metadata database holds all tenants' dashboards, datasets and roles, which needs the backup and access controls of a single critical system	One metadata database still serves all tenants, so tenant data separation does not extend to Superset's own metadata	Each instance needs its own metadata database, backups and restore tests, multiplying storage and administration
Cache and worker sharing	Caching layer and Celery workers are shared, so one tenant's heavy queries can slow others unless limits are set	Shared caching and workers remain unless deployed separately, so noisy-neighbor control depends on query limits	Each instance runs its own caching and worker components, so capacity is sized per tenant and can be scaled independently
Upgrade effort	One upgrade path with a single backup, staging test and UPDATING.md review for all tenants	Still one Superset version, but database and schema changes must be checked across every tenant's objects	Every instance is upgraded separately, so the staging, backup and testing cycle repeats for each tenant's stack
Per-tenant branding and authentication	Branding is shared unless customized per request; authentication is one provider with group-to-role mapping such as AUTH_ROLES_MAPPING	Branding is shared; authentication is still shared, so tenant separation relies on roles and data access	Branding and identity provider settings can differ per instance, which suits tenants that need their own login or theme
Embedded guest tokens and RLS	Guest tokens scope each viewer to resources and RLS filters; the RLS rules become the main tenant boundary and need testing for leaks	Guest tokens can scope viewers to dashboards while database credentials add a second boundary beneath RLS	Guest tokens still scope viewers within each instance, and the instance boundary removes cross-tenant risk from RLS errors
Cost components a quote must cover	Hosting for one stack, RLS design and testing, and ongoing rule review as tenants change	Database provisioning and grants per tenant, plus automation for schema creation and connection management	Infrastructure per tenant, provisioning automation, per-instance upgrades, monitoring and backups for every stack
When it fits	Many tenants with similar data models and a strong, tested RLS and embedding design	Tenants with separate data stores or regulatory boundaries but a shared application tier	A small number of high-sensitivity tenants that need separate identity, data and failure domains

Where cross-tenant data leaks happen

In a multi-tenant Superset, a tenant boundary is only as strong as the weakest layer that enforces it. The risks below sit in different places: dataset rules, caching, public access, shared content, connection credentials and the warehouse account itself. Each one needs its own check before customer data goes live.

Missing RLS rules on datasets

Row level security rules are attached to individual datasets, so a dataset that a dashboard uses without a matching rule returns every tenant's rows to any viewer who can open it. This is the most common form of leak in a single-instance design. Check that every tenant-facing dataset has a rule, and test each one by querying as a user from another tenant and confirming that zero foreign rows come back.

Shared cached query results

Superset caches query results so repeated dashboard loads do not hit the warehouse. If the cache key does not include the tenant or the RLS filter applied to the viewer, one tenant can receive another tenant's cached result. Confirm that cache keys vary by the identity and filters that shape each result, and that alert and report output is not written to a location other tenants can read.

Broad Public or guest roles

The Public role and guest tokens grant access without a named user, so their dataset and dashboard permissions should be narrower than any tenant account. A Public role that can read a dataset holding several customers' rows exposes all of them to anyone with the link. Review which datasets the anonymous role and guest resources can reach, and remove any grant that is not needed for a specific embedded view.

Shared SQL Lab and chart ownership

Charts, saved queries and SQL Lab tabs have owners, and content created by one tenant's analyst can be shared to a role that another tenant also belongs to. Copied charts can also keep a filter or SQL that bypasses the intended scope. Map ownership to tenant-specific roles, restrict who may publish or share, and review saved SQL for hard-coded tenant identifiers during onboarding.

Misconfigured database connection credentials

A database connection in Superset stores credentials that determine what every query can read, regardless of who is logged in. A single connection configured with an administrative login, or reused for several tenants, makes RLS the only barrier. Keep separate connections where isolation requires them, store secrets outside the metadata database where your deployment allows, and confirm who can view or edit connection details.

Overly permissive warehouse service account

Superset sends queries to the warehouse under a service account, and that account's grants limit the damage any dashboard bug or SQL injection can cause. An account with read access to every schema in the warehouse exposes data no tenant should see, even when Superset's rules hold. Grant the account read access only to the schemas and tables each deployment uses, and test that it cannot query other tenants' schemas directly.

Designing and rolling out a tenant model

This sequence turns a tenancy decision into a working Superset setup in which each customer's data access is defined, enforced, tested and documented before the first customer sees a dashboard.

Define tenant identity and data ownership
Write down what a tenant is in your product (an account, a workspace, a legal entity), which tables and events belong to each tenant, and which shared reference data every tenant may read. Your product and data owners sign off on this in writing, and the tenant identifier that every dataset will carry is named and agreed. The step is done when a reviewer can point to a single column or key that decides whether a row belongs to a given customer.
Pick the isolation model against written requirements
Compare one Superset instance with row level security, a database or schema per tenant, and an instance per tenant against the requirements from the previous step, including customer contract terms, regulatory scope, number of tenants and who will operate the platform. Record the trade-offs in cost, isolation strength and operational load for each option. The step closes with a signed decision record that names the model and the conditions under which it would be revisited.
Map datasets and tenant access rules
Build the dataset inventory, then define the row level security rules or database permissions that restrict each tenant to its own rows or schema. Include every route into the data, such as virtual datasets, saved charts, dashboards and exports, because a rule on one dataset does not protect a chart that queries another. Confirm the exact RLS behavior and dataset access requirements in the Superset version you will run. The step is complete when every dataset has an owner and a documented tenant rule.
Set up the metadata database and shared components
Deploy the Superset metadata database on PostgreSQL or MySQL, not the SQLite default, and place the caching layer and Celery workers where the chosen model requires them. Generate and store a SECRET_KEY before first start, and plan how it will be rotated with PREVIOUS_SECRET_KEY. The check is a running staging instance that starts cleanly with the production configuration, reports healthy components and survives a restart of the web process.
Configure guest token issuance from your backend
For embedded tenants, have your backend request guest tokens after it authenticates the end user, and bind each token to the dashboard and the tenant RLS rule for that user only. Keep token lifetimes short and never let the browser choose the tenant identifier. The check is a set of test requests where a valid user for tenant A receives a token that returns no tenant B data, and a tampered request is refused.
Run cross-tenant leakage tests
Create at least two test tenants with distinct, recognizable data and run every dashboard, chart, filter, export and API path as each tenant, then compare results against the expected rows. Include negative cases such as a missing tenant claim, an expired token and a direct call to chart data endpoints. Record the results and fix any failure before onboarding a customer. The step is done when the test suite passes in staging and the results are retained as evidence.
Document the upgrade and onboarding procedure
Write the runbook for adding a tenant, including dataset grants, RLS rules or schema creation, and the leakage test to rerun. Add the upgrade procedure: back up the metadata database, run the documented upgrade commands, test in staging, and check UPDATING.md for breaking changes before each version change. The step is complete when an engineer who did not build the model can onboard a test tenant and perform a staging upgrade by following the document alone.

What drives cost and operations effort over time

The largest cost in a multi-tenant Superset design is rarely the first install. It is the recurring work of operating every tenant boundary you chose. Design and testing of the isolation model is one-time work: the RLS rules, role mapping, database connection strategy and the automated tests that prove one customer cannot see another's rows. Per-tenant onboarding automation is also front-loaded, but it recurs with every new customer, and every manual step you leave in it becomes a support ticket. Ongoing costs come from metadata database and worker capacity, which grow with tenant count, dashboard count and scheduled reports, plus the monitoring you must run to notice when any of them degrade.

Upgrades are the cost that compounds. The Superset upgrade documentation sets a fixed sequence for each release: back up the metadata database, run superset db upgrade and superset init, test in staging first, and check UPDATING.md for breaking changes. In a shared instance, that sequence runs once for all tenants. With an instance per tenant, the same sequence, the same staging test and the same rollback plan run once per instance, and any patch cycle multiplies the same way. Ask any partner to show how many instances a single upgrade touches and how long a full rollout would take with your current tenant count.

Deployment tooling adds a planning risk. The Superset 6.1.0 documentation describes Kubernetes installs with the official Helm chart, but the current development documentation marks that chart as deprecated and points new deployments to the Apache Superset Kubernetes Operator. That operator is in alpha with a v1alpha1 API whose custom resource schemas may change between releases. Before you commit to a per-tenant fleet, confirm which path your platform team will support, budget for rewriting manifests if the API changes, and decide whether a single-instance design avoids that dependency altogether.

Security and operational considerations for tenant isolation

Whichever tenancy model you choose, the controls that keep one customer's data from reaching another run through the same application configuration, identity mapping, backups and upgrade process. The cards below cover the decisions and checks that connect those controls and that most often get tested after the fact.

Shared secret key across tenants

Superset requires a user-specified SECRET_KEY to start, and one key signs sessions for every user of that instance. In a shared deployment, a leaked key affects all tenants at once. Confirm who can read the key, where it is stored, and how it reaches each container. Plan rotation with PREVIOUS_SECRET_KEY so sessions survive the change, and record each rotation as a change event.

Group-to-role mapping drift

In a shared instance, tenant access depends on which roles each identity receives. AUTH_ROLES_MAPPING translates identity provider groups into Superset roles, so a group mapped too broadly can expose another tenant's dashboards. Review mappings whenever a customer onboards, and confirm that tenant groups never map to shared admin roles. Test one account per tenant after each change.

Per-tenant audit evidence

When a customer or assessor asks who viewed a dataset, you need logs that tie each action to a tenant, a user and a dataset. Decide where Superset's event logging is stored, how long it is kept, and whether a tenant's entries can be exported without exposing other tenants' records. Ask your auditor which evidence they will sample before you design the log pipeline, since that choice drives the retention and export work.

Backups separated by tenant

Backups of the metadata database hold dashboard definitions, dataset references, roles and user records for every tenant in one place. Restoring the whole database to recover one tenant can overwrite other tenants' changes. Decide whether restores are whole-instance or tenant-scoped, encrypt backup storage, and rehearse a restore that proves one tenant's data is absent from another's recovered state. The upgrade guide asks for a metadata backup before every upgrade, so that backup is the one to protect first.

Metadata database requirements

The architecture documentation says the SQLite default used by Quickstart and PyPI installs is not recommended for production, and that the Docker Compose PostgreSQL container is also not recommended for production. Use PostgreSQL or MySQL in a supported version range, which the configuration documentation lists as PostgreSQL 10 to 17 and MySQL 5.7 and 8.x. Confirm that the database host has its own backup, access control and patch schedule.

Isolation tests after every upgrade

Each upgrade can change how roles, row level security and permissions behave, and the project asks you to check UPDATING.md for breaking changes between versions. Keep a standing test suite that logs in as one user per tenant and confirms they see only their own datasets, charts and exports. Run it in staging before every production upgrade and again after the upgrade completes, and store the results as evidence.

How data residency, switching and assurance reports shape the design

The tenancy model you choose also determines what you can promise customers about where their data sits, how they can leave, and what independent assurance you can show. A SOC 2 report covers the system as you describe it, not the architecture a partner might later recommend. A Type 1 report describes your system and the design of your controls as of a date, while a Type 2 report adds an opinion on whether those controls operated over a period. If you run one shared Superset with row level security, your system description must explain how tenant filters, the Public role, guest tokens and the metadata database are controlled. If you run an instance per tenant, the description and the control evidence multiply with it. DeployOpen prepares controls, configuration records and evidence for an assessment, but an independent CPA firm issues the report. ISO/IEC 27001 works differently: an accredited certification body, not the implementer, certifies the organization against the Annex A controls it has scoped in.

If your customers are in the EU, GDPR Article 28(3) shapes the contract before the architecture. Your processor terms must bind you to process personal data only on documented instructions, including for transfers, and to apply the security measures required by Article 32. Confirm with counsel which tenant data is personal data, where your Superset metadata database, caches, logs and exported files are stored, and which subprocessors touch them. The EU Data Act, Regulation (EU) 2023/2854, has applied since 12 September 2025 and requires data processing service providers to let customers switch to another provider or to on-premises infrastructure. Its switching provisions, including the maximum two-month notice period and 30-day transitional period, should be checked against your offering. This requirement matters most for instance-per-tenant designs, where exporting a tenant means moving a whole Superset stack, its metadata database and its dashboards, not just one tenant's rows.

Treat these as questions for your counsel and auditors, not conclusions from this page. Whether the Data Act, GDPR or a sector rule applies depends on your customers, data and contracts, and the assurance scope depends on which criteria you commit to. Ask your auditor which controls they will test in each model and what evidence they expect from configuration, logs and access reviews. Ask counsel how switching obligations apply to a multi-tenant service and whether a per-tenant export is enough. Record the answers before you choose the model, because changing tenancy after customers and audits depend on it is expensive.

Limits to confirm in your environment

Each multi-tenant pattern depends on capabilities that vary by Superset version, deployment route and identity setup. The items below are the checks to finish before you choose a design, because each one can rule out an option or change its cost.

Superset version and metadata database

Confirm the exact Superset version you will run and check its tested metadata database versions in the configuration documentation before you size anything. The project lists PostgreSQL 10 to 17 and MySQL 5.7 and 8.x as supported metadata databases, and it does not recommend the SQLite default for production. Tenant-scoped designs multiply metadata rows for users, roles, datasets and dashboards, so plan the database for that growth. Confirm the version in your staging environment first, since upgrade steps differ between releases.

Per-tenant RLS in your version

Confirm that the embedding approach you plan to use supports row level security rules scoped to each tenant in the Superset version you run. Test this against your own datasets rather than assuming the behavior carries over from the docs for another release. Check whether RLS rules apply to every dataset a tenant can reach, including virtual datasets built from SQL. A gap here means one tenant's rows can reach another tenant's view, so treat it as a blocking check.

Warehouse capacity for the fan-out

Estimate how many concurrent queries your tenant count and refresh schedule will send to the warehouse. In a shared-database design, every tenant's dashboard load runs against the same compute pool, so one large tenant can slow others. In an instance or database per tenant design, the load spreads out but the number of connections and cached metadata grows. Ask your warehouse team for concurrency limits, query timeouts and the cost model for idle compute before you choose.

Kubernetes route for the Operator

If you plan to run one instance per tenant on Kubernetes, confirm how you will deploy it. The official Helm chart is marked deprecated in current development docs, and the Apache Superset Kubernetes Operator is in alpha with a v1alpha1 API whose custom resource schemas may change between releases. Decide whether your team accepts that churn, pin versions in your deployment code, and plan the migration path for each tenant instance when the schemas change.

Tenant claims from your identity provider

Confirm that your identity provider can issue a tenant or organization claim in the tokens Superset receives, and that the claim maps cleanly to a Superset role or group. Superset supports OAuth2 providers and LDAP, and it maps groups to roles through AUTH_ROLES_MAPPING, but that mapping only helps if the groups are tenant-specific. Ask your identity team whether the claim is signed, how it is refreshed when a customer is offboarded, and who can change it.

Questions SaaS teams ask before choosing a tenant model

Which tenant model should a SaaS team start with for Superset?

Most teams should start with one shared Superset instance using row level security, unless contract terms, data residency or a tenant's own compliance rules require stronger separation. A shared instance has one upgrade path, one set of workers and one metadata database to back up, so the operating load stays flat as tenants grow. The choice still depends on how sensitive the data is and whether any tenant needs its own database credentials. Ask whether the answer is different for regulated customers, and whether you can isolate those tenants later without rebuilding the whole analytics layer.

What does the tenant model design work cost, and who pays for it?

You pay for the design work in three parts: the data model and access rules, the identity and token design, and the test plan that proves tenants cannot see each other's rows. Your internal staff cover business decisions such as which customer contracts require separation. A partner or internal platform team covers the Superset configuration, the warehouse grants and the test harness. Costs recur when tenant counts, datasets or customer requirements change. Ask any quote to list each part separately, state which items are one-time, and name the retesting work that follows each upgrade.

How long does a multi-tenant Superset rollout take, and what drives the duration?

The duration depends on how many tenant models you support, how clean your warehouse schemas already are, and how much identity work sits in front of Superset. A single shared model with row level security usually takes less time than per-schema or per-instance designs, because each extra isolation boundary adds provisioning, testing and monitoring work. Delays most often come from unclear tenant identifiers, missing data ownership, and slow warehouse access approvals. Ask the partner to tie the timeline to a written scope with named deliverables and to show which dependencies sit with your team.

Can an internal team build a multi-tenant Superset design without outside help?

Yes, a team with Superset, SQL and identity experience can build a shared-instance design internally, but the work tends to be underestimated in three areas: row level security rules, guest token scoping and leak testing. Per-schema and per-instance models add provisioning automation, secret handling and monitoring that most teams have not built before. Assess your team against those areas honestly. If the people who would own the design are also carrying production duties, a fixed-scope engagement can separate the design review from ongoing operations.

What does the partner need from our team before the design starts?

The partner needs five inputs: your data model with tenant keys on each table, your identity provider and how tenant membership is asserted, read-only warehouse access for a staging environment, a list of customer contract and residency requirements, and a staging Superset environment that matches production versions. Without the tenant keys and the identity mapping, row level security rules cannot be written or tested. Ask for these inputs to be listed in the statement of work with owners and dates, so that delays appear early.

How do upgrades change for each tenant model?

In a shared instance, one upgrade covers every tenant, but each upgrade must be tested against the row level security rules and guest token behavior before release. With a database or schema per tenant, the same upgrade still runs once on Superset, while the warehouse-side grants and provisioning scripts add tests for every schema. With an instance per tenant, you repeat the upgrade for each instance and need a rollout order across all of them. Before any upgrade, back up the metadata database, run the upgrade steps in staging, and check the UPDATING.md notes for breaking changes between your current and target versions.

Which tenant model fits a regulated SaaS product that customers audit?

A stricter model can help when customer contracts or auditors expect evidence of separation beyond row filters, but the choice should follow the controls you must demonstrate rather than the model that sounds most isolated. Auditors typically test access control, logging and change management, and those controls apply to every model. Start by mapping each requirement to an owner, a test and an evidence source. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors issue any report. Confirm with your auditor which evidence they expect before you commit to a model.

Does separating tenants into different schemas or instances remove the risk of data leaks?

No. Separation reduces some risks, such as a mistaken filter, but it adds others, such as credential sprawl, misconfigured grants and more places where a secret can leak. Leaks in embedded analytics often come from guest tokens that carry the wrong resource scope, dataset permissions granted to the public role, or SQL Lab access that bypasses the dashboard layer. Whichever model you pick, write tests that log in as each tenant and attempt to read other tenants' charts, datasets and exports, and run those tests after every change.

How DeployOpen scopes and delivers a multi-tenant Superset design

DeployOpen starts multi-tenant Superset design with a written scope that compares the tenancy models against your customer count, data sensitivity and team capacity. We then build, test and document the chosen model inside infrastructure you control, so your team can run it after handover.

How we scope

Inventory which customer datasets, warehouses and row-level rules the tenancy model must separate.
Compare one shared instance with RLS, schema per tenant and instance per tenant against your isolation and cost requirements.
Agree deliverables, timelines and exclusions in writing before any build work starts, since engagements are fixed-scope.

How we build

Deploy the chosen topology with the metadata database, caching layer and workers that Superset requires for your load.
Configure RLS rules, database connections and role mappings, then test that one tenant cannot query another tenant's rows.
Set up provisioning scripts so new tenants follow the same repeatable steps, with configuration kept in version control.

How we hand over

Document the tenancy model, provisioning steps, RLS rules, upgrade procedure and the reasons behind each design decision.
Deliver isolation test cases and results so your engineers can rerun them after each change or upgrade.
Walk your platform and security teams through operations, including backups, the Superset upgrade steps and access reviews.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover.
Retainer work can cover Superset version upgrades, rerunning tenant isolation tests and reviewing new tenants before go-live.
Confirm with us during scoping which evidence your auditors will need, so we prepare the system, controls and records they can assess.