What Apache Superset SQL Lab for analysts does and when to enable it
Enable SQL Lab when analysts need to write and run their own SQL against warehouses faster than a BI build queue allows, and when you are prepared to govern that access before anyone logs in. SQL Lab is Superset's browser-based SQL editor, where a user picks a connected database, writes a query, inspects the results and optionally saves the query or turns the output into a chart. It is a different tool from charts and dashboards. Charts and dashboards query datasets that someone has defined and published, so the shape of the data is fixed in advance. SQL Lab queries whatever the user writes against the tables that the connected database account can reach, which makes it the most direct path from a user to your data in the platform.
Superset does not connect to databases on its own behalf in SQL Lab. Every query runs against a database connection that an administrator has already configured, using the credentials and network path defined for that connection. Access is controlled in layers. The sql_lab role grants access to the feature itself, and per-database permissions decide which connections each user can query. Admin users can query all databases by default, while Alpha and Gamma users need access granted to each database individually. Before rollout, decide which analysts receive the role, which databases they may query, whether a shared database account is acceptable, and who owns the list of exceptions. Those decisions shape everything that follows, including row-level filtering, query limits and audit evidence.
Treat the rollout as a governance project, not a switch. Confirm with your own team which databases hold sensitive data, whether the database accounts behind each connection are read-only, and how analysts will be told what they may and may not query. Plan the controls covered in the rest of this page before the first analyst gets access, because changing them later affects saved queries and working habits. If your team cannot yet answer who should see which database, the feature is not ready to enable for everyone.
Access and execution options and when each fits
This table compares the access and execution options that shape SQL Lab rollout, from role grants and per-database access to async execution and cost estimation. Read each row as a decision: who it suits, what it allows, and what it trades off against exposure, cost and user experience.
| Option | What it allows | When it fits | Trade-off to plan for |
|---|---|---|---|
| sql_lab role | Grants access to open SQL Lab for the user | Any analyst who needs ad hoc SQL and has been approved for at least one database | Access alone does not limit which databases are queryable; pair it with per-database grants |
| Admin access to all databases | Admin users can query every connected database by default | A small platform team that maintains connections and troubleshoots queries | Broad exposure; confirm that few accounts hold the Admin role before go-live |
| Alpha users with per-database grants | Alpha users query only the databases granted to them | Analysts who build datasets and need access to specific warehouses | Each new database needs an explicit grant, which adds administrative work as sources grow |
| Gamma users with per-database grants | Gamma users query only the databases granted to them, with narrower permissions | Business users who explore approved datasets with limited SQL needs | Confirm with your own tests which features Gamma users can reach in your version |
| Synchronous execution | Query runs in the web request and returns results directly | Short exploratory queries against fast sources | A heavy query holds the user's session and ties up web capacity |
| Async execution with Celery | Long queries run on workers and the user is notified when results are ready | Teams that run large scans or joins, with worker and broker already in place | Needs the caching layer and worker components; adds operational and sizing work |
| 6 hour default query limit | Queries may run up to six hours before Celery ends them, per the Superset FAQ | Environments where long runs are rare and the default is acceptable after review | Six hours can load the warehouse heavily; lower the timeout in configuration if your policy requires it |
| Query history retention | Saved query records remain available to users and administrators for review | Teams that need to investigate usage or support audit questions | Stored SQL may contain sensitive text; set a pruning policy and confirm who can read history |
| can_estimate_query_cost permission | Lets users estimate cost before running a query | Teams paying per scan on cloud warehouses that want cost awareness | Estimates depend on database support; confirm behavior with your engine before relying on them |
| can_format_sql permission | Lets users format SQL in the editor | Analysts who need readable SQL for review and handoff | Low risk on its own, but grant it separately so it is a deliberate choice |
Rolling out SQL Lab in sequence
This sequence moves SQL Lab from a working Superset instance to a pilot group of analysts with access limited to the databases and features each group needs. Each step ends with a check so the team knows the control is working before the next one starts.
Confirm the metadata database and deployment
Before any access work, confirm that Superset runs on a metadata database the project tests for production, which means PostgreSQL or MySQL, and that the SQLite default used by Quickstart and PyPI installs is not in use. Confirm the supported versions for your chosen database against the configuration documentation, and confirm that the SECRET_KEY is set to a value you control. Owner: platform engineering. Check: a backup of the metadata database completes and restores to a scratch instance, and the Superset instance starts with the production configuration.
Map analyst groups to Superset roles
List the analyst groups that need SQL Lab and decide which Superset role each one receives. If you sign in through an identity provider, use AUTH_ROLES_MAPPING to map directory or OAuth groups to roles so that membership changes flow from the directory rather than from manual edits in Superset. Owner: the identity team with the data platform lead. Check: a test account in each group signs in and shows exactly the roles on the agreed mapping, and no account holds Admin by accident.
Grant the sql_lab role
Assign the sql_lab role to the groups approved in the previous step. The role grants access to SQL Lab itself, but it does not grant data access, so an analyst with only this role can open the editor and see no databases to query. Owner: Superset administrators. Check: a pilot account opens SQL Lab and sees the editor, while an account without the role receives no access to the page.
Grant access to each database explicitly
Grant per-database access for Alpha and Gamma users to only the connections each group needs, because Admin users can query all databases by default. Record which group holds which database in a change log so reviewers can trace the grant later. Owner: Superset administrators with the owners of each data source. Check: a pilot Gamma user can query the approved database and receives a permission error on a database outside the grant, which you confirm by running one query against each.
Set the query timeout and history settings
Review the query timeout for SQL Lab. The Superset FAQ says long queries run for up to 6 hours by default before Celery stops them, and the timeout can be changed in configuration. Choose a value that matches what your warehouse tolerates, and set a history retention policy for query history so that stored SQL and result metadata are pruned on a schedule you define. Owner: platform engineering with the warehouse team. Check: a deliberately slow test query stops at the configured limit, and the history table shows pruning working on the schedule you set.
Enable cost estimation and formatting selectively
Estimating query cost and formatting SQL in SQL Lab require the separate can_estimate_query_cost and can_format_sql permissions. Grant them only to groups that need them, and leave them off for groups that do not, since cost estimation sends queries to the warehouse planner and should be a deliberate choice. Owner: Superset administrators. Check: a pilot user in the granted group sees the cost estimate and format options, and a user outside it does not see them.
Test with a pilot group before wider rollout
Run a pilot with a small analyst group that matches the production role and database grants. Ask the pilot to run representative queries, including one long query, one query against a database they should not reach, and a query that should be blocked by your disallowed functions list if you have one. Review the results with the warehouse owner and record any change to roles, grants or timeouts. Owner: the data platform lead with the pilot group. Check: the pilot signs off on the access map in writing, every planned denial behaves as designed, and the change log matches the live configuration before you widen access.
Security risks in SQL Lab that need owners
SQL Lab gives analysts a direct path to write SQL against the databases behind your dashboards, so its risks are access risks more than interface risks. Each card below names one risk, the control that addresses it and the owner who should confirm that control is in place before analysts get access.
Unrestricted write SQL on production
SQL Lab accepts any statement the database account allows, including inserts, updates and deletes. If the connection uses a credential with write privileges, an analyst can change production tables from a browser tab. The control is a read-only database account for SQL Lab connections, with write access limited to separate, named pipelines. Ask the data owner to confirm which credentials each Superset database entry uses.
Admin users querying every database
The Admin role can query all databases by default, so an admin account used for day-to-day analysis reaches every connection, including ones that hold sensitive data. Alpha and Gamma users need access granted per database. Check which people hold the Admin role, keep admin accounts separate from analyst accounts and review the list of database grants each quarter.
Sensitive values in query history
Superset keeps a record of queries that users run in SQL Lab, and those statements often contain customer identifiers, account numbers or other literal values typed into WHERE clauses. Anyone with access to that history can read values they were never allowed to query directly. Confirm who can view query history, decide how long it is kept and document how pruning is scheduled in your environment.
Database credentials used through Superset
Superset connects to each database with the credential stored in its database connection, and analysts run queries under that identity rather than their own. A broad service account therefore grants every SQL Lab user its full reach. Ask who owns each connection, how its secret is stored and rotated, and whether the database itself logs queries by Superset account so that activity can be traced.
Row level security in SQL Lab
Database-level grants decide which tables an analyst can reach, but they do not limit which rows come back. Row level security filters must be applied to the datasets and roles that SQL Lab users rely on, and they must be tested with real analyst accounts. Confirm that the filters cover the same data that dashboards expose, since analysts can write queries that bypass dashboard-only filtering.
Disallowed functions and cost permissions
Some SQL functions can read files, call external hosts or run expensive scans, and the cost estimation and SQL formatting features depend on their own permissions. Use the disallowed functions setting to block the functions your databases should never run from SQL Lab, and grant can_estimate_query_cost and can_format_sql only to roles that need them. Ask the security team to review the blocked list against your database engines.
How async execution and the 6 hour limit change long queries
The 6 hour default matters most for analysts who run heavy queries from the SQL Lab editor. The Superset FAQ says a long query can run for up to 6 hours before Celery kills it, so a query that is still running after that point ends without a result. The limit is set in Superset configuration, not in the SQL Lab interface, which means the platform team owns the decision. Before rollout, confirm with your analysts which queries genuinely need hours of runtime, and confirm with your warehouse team whether that runtime is acceptable on the database side. A longer timeout keeps more queries alive but also keeps more load on the warehouse and ties up worker capacity for longer. A shorter one protects shared resources but may cut off legitimate work. Set the value deliberately and document it for analysts.
Running heavy queries asynchronously moves them off the web tier. With async execution, SQL Lab submits the statement to a Celery worker, which runs it and stores the result, so the browser session does not hold a connection open while the warehouse works. This keeps the web application responsive for other users and lets analysts close the tab and return later. Async execution depends on the caching layer and worker components described in the Superset architecture documentation, and on a results backend the workers can write to. An installation without workers may still accept queries, but long-running statements will tie up the web process and behave poorly under load. Ask your team to confirm the worker and results backend setup in staging before enabling async SQL Lab for analysts. Worker design, broker choices and sizing are covered on the Apache Superset async queries with Celery page of this series, so read that before committing to a topology.
Limits to confirm in your environment
SQL Lab's behavior depends on the Superset version you run, the databases behind it and the limits your warehouse enforces. The cards below list the settings to confirm with the vendor documentation or a test environment before analysts get broad access.
The effective query timeout
The Superset FAQ says long queries run for up to 6 hours by default before Celery kills them, and the value can be changed in configuration. Confirm the timeout your version applies to synchronous and async SQL Lab runs, and whether your reverse proxy or load balancer cuts connections earlier. A proxy limit shorter than the Superset limit produces errors that look like query failures.
Disallowed functions per database
Decide which SQL functions analysts may call, such as file access, shell-style or administrative functions, and confirm whether your Superset version lets you configure a disallowed function list for each database connection. Test each entry against the actual engine, because function names and syntax differ between warehouses. Record the list as part of the access review.
Query history pruning
Query history stores the SQL analysts ran, which can include sensitive filters and values. Confirm how your version prunes or retains that history, whether pruning runs on a schedule or on demand, and who can read the history of other users. Write the retention period you need into your data handling standard before rollout.
Warehouse cost and concurrency
Superset sends the SQL, but the warehouse pays for the compute, so unbounded analyst queries can drive cost and queue delays for production workloads. Ask the warehouse team for its own query timeouts, resource groups, concurrency caps and per-user spend controls. Check whether cost estimation in SQL Lab reflects the engine's real pricing model before anyone relies on it.
Database feature support
SQL Lab features such as async execution, cost estimation, SQL formatting and result handling do not behave the same on every engine. Confirm which features your Superset version supports for each database you connect, and run a test query on each one. Record any gaps so analysts know which databases need a different workflow.
Async execution requirements
Long queries that run asynchronously depend on the caching layer and Celery workers, and those components need their own capacity and failure handling. Confirm the broker, results backend and worker timeouts in your deployment, then test a long query that finishes after the browser tab closes. The test shows whether results stay available and whether the worker releases the warehouse session.
Questions teams ask before enabling SQL Lab
What drives the cost of rolling out SQL Lab for analysts?
The cost depends on how many databases analysts will query, how many distinct analyst groups need different access, and how much of the surrounding platform you must build first. Most of the spend is labor: someone designs the role model, configures per-database access, sets up the metadata database and any worker processes, and tests that analysts see only what they should. Ask any provider for a quote that separates one-time setup from recurring costs such as patching, upgrades and access reviews. Your own infrastructure costs for compute, storage and backups also recur and are not included in a services quote. Superset itself is Apache-2.0 licensed with no paid edition, so license cost is not a driver.
How long does a SQL Lab pilot take to set up?
No researched figure is available for this, so confirm the duration with any provider against a written scope. The timeline depends on the number of databases in the pilot, whether the metadata database and workers are already running, how many analyst groups must be mapped, and whether your identity provider is ready to supply groups. A pilot limited to one database and one analyst group takes far less time than one that covers several warehouses with separate data owners. Ask for the phases, the deliverables at each phase and the sign-off each one needs from your team.
What does a SQL Lab rollout need from our team?
Plan for four inputs before work starts. First, a named owner for the access model who approves which analyst groups can query which databases. Second, read-only database credentials or accounts for each target database, which your data team must provision. Third, a production-grade metadata database, since the Superset architecture documentation says SQLite and the Docker Compose PostgreSQL container are not recommended for production, and supported versions are PostgreSQL 10 to 17 and MySQL 5.7 and 8.x. Fourth, a Celery worker and broker if you want async execution for long queries, because the architecture documentation says async queries require the caching layer and worker components.
Can our internal team deploy SQL Lab without an outside partner?
Yes, a capable internal platform team can deploy Superset alone, and the upgrade and configuration documentation is public. The harder work is usually governance: deciding who may query what, testing permissions across roles, and keeping the setup correct as people and databases change. Assess whether your team has spare capacity for the build, has experience with Flask-based applications and Celery, and can run security testing against the deployment. Many teams keep the build in-house and bring in a partner for a fixed-scope review of the role model or a security check before analysts get access.
How do analyst groups map to Superset roles?
Superset is built on Flask-AppBuilder and can map LDAP or OAuth groups to roles through the AUTH_ROLES_MAPPING setting, so group membership in your directory can drive role assignment. The sql_lab role grants SQL Lab access, but the security documentation notes that Admin users can query all databases by default, while Alpha and Gamma users need access granted per database. Design the mapping so analysts sit in a gamma-style role with explicit database grants, and keep Admin rights to a small platform group. Test each mapping with a non-admin account before rollout.
Which SQL Lab permissions should we restrict first?
Start with the permissions that change cost and data exposure. Estimating query cost and formatting SQL need the separate can_estimate_query_cost and can_format_sql permissions, so grant them deliberately rather than bundling them into every analyst role. Review which databases each group can reach, and confirm that database accounts behind Superset are read-only where analysts do not need writes. Also decide the query timeout: the Superset FAQ says long queries run for up to 6 hours by default before Celery kills them, and you can change this in configuration. Set it to match what your warehouse can absorb.
What does ongoing review of SQL Lab access look like?
Review access on a schedule your governance process already uses, and tie each review to role and database changes. Check group-to-role mappings against the directory, confirm that only approved people hold Admin or the cost estimation and formatting permissions, and confirm that database grants still match data owner decisions. Review query history pruning settings so that retention matches your policy. Upgrades need their own step: back up the metadata database, run the documented upgrade commands in staging first, and check UPDATING.md for breaking changes before each version move. Ask any provider whether these reviews are a one-time task or a retainer.
Should we enable async queries before opening SQL Lab to analysts?
Decide this before rollout, because async execution changes how long queries behave and what infrastructure must be running. Without workers, heavy queries run on the web tier, which can slow the interface for everyone. With Celery workers and a broker, long queries move off the web tier, but you must size workers, set timeouts and choose a broker and results backend. The Superset architecture documentation says most installations use Redis and Celery for these features. Test a few long queries against realistic data volumes in staging before you tell analysts the feature is available.
Testing SQL Lab changes before each Superset upgrade
Every Superset upgrade can change how SQL Lab behaves for analysts, so the sql_lab role grants, per-database access, the query timeout, query history settings and the can_estimate_query_cost and can_format_sql permissions should be retested each time, not assumed to carry over. Treat this as part of the upgrade itself, with a written test list that covers each of these settings before the new version reaches analysts.
Start with the upgrade guidance in the Superset documentation. Back up the metadata database first, because it holds the roles, permissions and saved queries that SQL Lab depends on. Then run superset db upgrade and superset init against a staging copy of your production metadata database, not against an empty instance. Check UPDATING.md in the release for breaking changes between your current version and the target, and confirm whether any permission names, configuration keys or query behavior changed. Your own team should confirm these steps against the release notes for the exact versions involved.
In staging, log in as one Admin, one Alpha user and one Gamma user, then confirm that each sees only the databases they were granted before the upgrade. Run a long query to check that the timeout still matches your configured value, since the default limit is 6 hours before Celery stops it. Confirm that query history still prunes as you expect and that cost estimation and SQL formatting appear only for users who hold those permissions. Record the results so you can compare them after each upgrade. For the full upgrade procedure, read the Upgrading Superset documentation before scheduling the change window.
How DeployOpen scopes and delivers SQL Lab rollouts
The sequence turns SQL Lab from a broad database login into a written access model that analysts use on a pilot basis before wider release. Each step ends with a document or check the client can review.
Agree the written scope and access goals
DeployOpen and the client agree in writing which Superset instance, databases, schemas and user groups are in scope, and which analyst populations will use SQL Lab. The client confirms who owns each database and who approves access to it. The step closes when the signed scope lists deliverables, exclusions and the acceptance checks both parties will use.
Inventory databases and existing user roles
The team reviews the connected databases, the current Admin, Alpha and Gamma assignments, and any custom roles already in the instance. Admin users can query all databases by default, so the review flags every account that holds that reach. The output is an inventory showing which roles can reach which databases today, reviewed by the client's data owners.
Design the sql_lab role and per-database grants
DeployOpen drafts the access model: which groups receive the sql_lab role, which databases each group may query, and which cost estimation and SQL formatting permissions are granted separately. Alpha and Gamma users need access granted per database, so the design lists each grant explicitly. The step closes when the client approves the model as a written matrix of groups, databases and permissions.
Configure roles and query limits in your environment
The team applies the approved roles and database grants in the client's own Superset instance, using the client's identity source where group mapping is in use. It also reviews the query timeout, since long queries run for up to 6 hours by default before Celery stops them, and decides whether that value should change in configuration. The output is a configuration change record that the client can reproduce in staging.
Test access with a pilot group of analysts
A small pilot group of analysts runs representative queries in SQL Lab against each granted database, and the team checks that unapproved databases refuse access. Pilot users also test async behavior for heavy queries and the query history view. The step closes with a test log listing each role, database and expected result, with every failure resolved or accepted by the client.
Document the access model and operating rules
DeployOpen writes the access model, the role and permission matrix, the query history retention decision, and the list of disallowed functions the client chose to block. Operators and data owners receive a short procedure for granting and removing access. The step closes when the client confirms the documents match the live configuration and are stored where auditors and administrators can find them.
Hand over and plan ongoing support
The team walks the client's administrators through the configuration, the test log and the change procedure, then confirms who will approve future grants. Where the client wants help with upgrades, reviews of new databases, or periodic access reviews, the parties agree a retainer in writing. The handover closes when the client's administrators can make a routine access change without assistance.
