How Apache Superset connects to Amazon Redshift
If your team runs self-hosted Superset and needs dashboards over data in Amazon Redshift, the supported route is the sqlalchemy-redshift driver, reached through a SQLAlchemy connection string of the form redshift+psycopg2://{username}:{password}@{host}:5439/{database}. Superset can also authenticate with IAM instead of a stored password when the AWS_DATABASE_IAM_AUTH feature flag is enabled. This section is for the platform engineers and data owners who will decide how Superset reaches Redshift, which identity it uses, and where the load lands. It assumes you already have a Superset deployment running or planned.
Superset is the application layer in this path. Its Flask and React web application, metadata database, optional caching layer and optional Celery workers all run in your infrastructure, and only the query workload travels to Redshift. The metadata database holds dashboards, charts, users and connection definitions, so it should stay separate from the analytics source. The caching layer and Celery workers matter here because alerts, reports, async queries and dashboard thumbnails depend on them, and those features are the ones that issue repeated queries against the warehouse. Confirm with your team which of these components will run in the same network segment as Redshift, since that determines whether the port 5439 connection can stay private or must cross a boundary you need to document.
Plan the driver into the image before you configure the connection. The Superset database catalog lists the Redshift package, so the driver is installed as a build-time dependency in the Superset container, not added by hand on a running server. Decide early between a password-based connection and IAM authentication, because IAM changes what the Superset host role must be allowed to do and how credentials rotate. Review the Superset AWS IAM documentation before you pick an approach, and ask your Redshift administrator to confirm which cluster or workgroup endpoint, database name and network path your environment uses.
What you need before connecting Superset to Redshift
Connecting Superset to Redshift depends on four things settled before any connection is configured: the driver in the Superset image, the endpoint and credentials, the choice between provisioned and Serverless, and the network path from Superset workers. Confirm each one with your Redshift team so the connection test is the last step, not the first.
The sqlalchemy-redshift driver in the image
Superset's database catalog lists the sqlalchemy-redshift package as the driver for Redshift, and the connection uses the redshift+psycopg2 dialect. Neither ships in a default image, so it must be installed into the image that runs the web server, Celery workers and any scheduled jobs. Confirm the driver version against the Superset release you run, since driver and SQLAlchemy pairings can change between releases. Record the pairing in your image build so upgrades do not silently break the connection.
Endpoint, port and database name
Redshift connections use the cluster or workgroup endpoint on port 5439, followed by the target database. Use the endpoint from the cluster or workgroup you intend to query, not a leader-node address copied from an old runbook. Confirm the database name, the schema visibility each analytics role needs, and whether the endpoint is public or private. Those three answers decide the connection string and the network rules that follow.
Database users or IAM identities
You can connect with a database user and password, or use IAM authentication behind the AWS_DATABASE_IAM_AUTH feature flag so no password is stored in Superset. Password users need a rotation process and a secret store that Superset can read. IAM users need a role that Superset assumes, with permission to request temporary database credentials. Decide which model fits your identity governance before you create the first database connection.
Provisioned or Serverless
Provisioned clusters and Redshift Serverless workgroups use different IAM actions for temporary credentials. Provisioned clusters need redshift:GetClusterCredentials, while Serverless needs redshift-serverless:GetCredentials and GetWorkgroup. Confirm which service your data sits in, because the policy, the endpoint format and the cost model all differ. Mixed estates need one connection and one policy per target.
Network path from workers to the warehouse
Every Superset process that runs queries, including web workers and Celery workers, must reach the Redshift endpoint on port 5439. Check security group rules, VPC routing, subnet placement and any private DNS or VPC endpoint in use. If Superset runs in another account or VPC, confirm peering or transit routing before debugging credentials. Network gaps often look like authentication failures, so test from the same host and network context that runs Superset.
Version pairing to confirm
Before you build the image, confirm the Superset release you run, the sqlalchemy-redshift version it supports and the Python and psycopg2 versions in the image. Treat the pairing as a release-specific check, not a fixed rule. Ask your DeployOpen team, or your own engineers, to record the tested combination in the build and to repeat the check during each Superset upgrade.
Configuration sequence for the Redshift connection
This sequence takes a self-hosted Superset from an image without a Redshift driver to a tested database connection that authenticates to either a provisioned cluster or Redshift Serverless. Each step ends with a check the reader can run before moving on.
Add sqlalchemy-redshift to the Superset image
The platform team adds the sqlalchemy-redshift package to the Superset image through the build or the Python requirements file used for the deployment, then rebuilds and redeploys the web and worker containers. The Superset database catalog lists this package for Redshift, so confirm the version pins against the Superset release you run. Done means a running container can import the driver: open a shell in the web container and confirm the package is installed in the Python environment Superset uses, then load the Redshift database option in the Superset UI.
Choose password or IAM authentication
Decide before you build the connection whether Superset will hold a database password or obtain temporary credentials from AWS at connection time. Password authentication uses the connection string form redshift+psycopg2 with a username, password, host and port 5439. IAM authentication removes stored database passwords but adds IAM permissions, a feature flag and a role for Superset to assume. Record the decision in your change request, since the rest of the sequence depends on it. Done means a written decision naming the authentication method, the Redshift deployment type (provisioned or Serverless) and the AWS account that owns the cluster or workgroup.
Enable the AWS_DATABASE_IAM_AUTH feature flag
If you chose IAM authentication, set the AWS_DATABASE_IAM_AUTH feature flag in the Superset configuration file and restart the web and worker processes so the setting loads. Superset documents this flag as the switch that enables IAM authentication for Amazon Redshift and Aurora. Keep the change in version-controlled configuration rather than editing a running container. Done means the flag appears in the loaded configuration of every web container and the restarted pods or containers pass their health checks.
Grant the Redshift IAM permissions
A cloud or security engineer creates an IAM policy for the role Superset uses. For a provisioned cluster, the policy needs redshift:GetClusterCredentials. For Redshift Serverless, it needs redshift-serverless:GetCredentials and redshift-serverless:GetWorkgroup. Scope both actions to the specific cluster, workgroup and database user where your IAM model allows it, and confirm the exact resource ARN format with AWS documentation. If Superset runs in a different AWS account from the database, add the cross-account role assumption through STS AssumeRole in the same step. Done means the engineer simulates the policy against the target resource and confirms the allowed actions, and the Superset role can request credentials from a test session.
Create the Redshift database connection in Superset
A Superset administrator opens Database Connections, selects Amazon Redshift, and enters the host, port 5439, database name and the database user that the IAM policy allows. With IAM enabled, the connection uses the Superset role to obtain short-lived credentials rather than a stored password. Keep the connection's database user a read-only account created in Redshift, and avoid using a superuser. Done means the connection record saves without errors and the object shows the expected host and database in the connection list.
Test the connection and run a sample query
Use the Test Connection action in the database settings, then open SQL Lab, select the new connection, and run a simple read-only query such as selecting the current database and user, followed by a query against a small known table. The test confirms network reachability, authentication and the driver path together. If the test fails, check the security group or VPC route to port 5439, the IAM policy simulation result and the assumed role trust policy in that order. Done means Test Connection reports success, the sample query returns the expected row, and the query appears in the Superset query history under the expected user.
Password, IAM and cross-account authentication compared
The simplest option is a Redshift database user with a password, placed in the SQLAlchemy URI using the redshift+psycopg2://{username}:{password}@{host}:5439/{database} pattern from the Superset database catalog. Superset needs only the database user and its grants, and no AWS API permissions. The trade-off is that a long-lived password must be stored in Superset's metadata database or configuration, rotated by hand and removed from every place it was copied to.
- Secret location: the password sits in the connection configuration, so it is visible to anyone who can edit database connections in Superset.
- Rotation: changing the password requires updating every connection that uses it and coordinating a restart or reconfiguration.
- Least privilege: create a dedicated read-only Redshift user with grants limited to the schemas that dashboards need.
- Audit trail: Redshift sees one shared database user, so per-person activity is hard to trace from the database side.
- Exposure: confirm that connection secrets are encrypted at rest and that only administrators can view or edit them in Superset.
Before choosing this option, confirm with your security team whether a shared database password is acceptable under your access control policy.
For a provisioned Redshift cluster, Superset can request short-lived database credentials from AWS instead of holding a password. This depends on the AWS_DATABASE_IAM_AUTH feature flag and on the Superset process having an IAM identity that is allowed to call redshift:GetClusterCredentials. Redshift then accepts the temporary credentials for a database user, so the password no longer needs to be stored.
- Principal: the IAM role attached to the Superset host, container or service account needs
redshift:GetClusterCredentialson the target cluster and database user. - Removed secret: no static Redshift password is kept in Superset configuration.
- Feature flag: confirm that
AWS_DATABASE_IAM_AUTHis enabled in your release and that the connection is configured to use it. - Database user mapping: confirm which Redshift database user the IAM request maps to and that this user has only the grants dashboards need.
- Cluster settings: confirm that the cluster's IAM and database user settings allow temporary credentials for that user.
Ask your AWS account team and your Redshift administrator to confirm these permissions in a non-production account before the production role is granted.
Redshift Serverless uses a different credential API, so the IAM policy differs from the provisioned cluster case. The Superset principal needs redshift-serverless:GetCredentials and redshift-serverless:GetWorkgroup for the target workgroup. As with provisioned clusters, this removes the stored database password, but the permission scope is written against the workgroup rather than a cluster identifier.
- Principal: the IAM role for Superset needs
redshift-serverless:GetCredentialsandredshift-serverless:GetWorkgroupon the target workgroup. - Removed secret: the stored database password is no longer required for this connection.
- Workgroup scope: restrict the policy to the specific workgroup ARN rather than a wildcard, so that other workgroups in the account are not reachable.
- Feature flag: confirm that
AWS_DATABASE_IAM_AUTHis enabled, as with provisioned clusters. - Serverless specifics: confirm the namespace, workgroup and database names in the connection, and whether your workgroup's access settings match the database user you intend to use.
Because the permissions differ from the provisioned case, do not reuse a provisioned-cluster policy for a Serverless workgroup without checking each action against the AWS documentation for your region.
When Superset runs in one AWS account and Redshift runs in another, the Superset identity can assume a role in the Redshift account through STS AssumeRole. The role in the Redshift account carries the Redshift permissions described above, and its trust policy names the Superset role as the principal allowed to assume it. This separates the ability to request credentials from the ability to use them and keeps the trust relationship visible in each account.
- Principal in the Superset account: the Superset role needs
sts:AssumeRoleon the target role ARN. - Principal in the Redshift account: the target role needs the Redshift credential permissions and a trust policy that allows the Superset role.
- Removed secret: no long-lived access key for the Redshift account is stored in Superset.
- External ID and conditions: decide whether the trust policy should require an external ID or other conditions, and confirm this with your security team.
- Session duration: confirm the session length and whether your organization permits it for dashboard workloads.
Ask your AWS administrators to review both trust and permission policies together, since a misconfiguration on either side will block the connection or widen access more than intended.
How Superset roles and Redshift identities map
This table compares the layers that decide what a Superset user can read in Redshift: the Superset role, the database identity Superset connects as, the AWS role used for AssumeRole and the Redshift grants. Read it as a chain, because a permission only works when every layer agrees, and Superset itself does not create any Redshift grants.
| Layer | What it controls | Who sets it | What to confirm |
|---|---|---|---|
| Superset role | Which dashboards, charts and databases a user can open in Superset | Superset admins, often mapped from identity provider groups | Which roles can edit the Redshift connection and which can run SQL Lab against it |
| Database identity | The Redshift user or IAM principal Superset connects as, and so the base grants applied to queries | Your Redshift and AWS administrators | Whether one shared identity serves all users or separate identities map to separate Superset roles |
| AWS role for AssumeRole | The IAM role Superset assumes through STS when the connection crosses accounts | Your AWS account owners, through trust and permission policies | The trust policy names the Superset host role and the permissions allow GetClusterCredentials or GetCredentials for the target cluster or workgroup |
| Redshift schemas and tables | The schemas and tables the database identity can select from | Redshift administrators, through GRANT statements | Grants are designed and tested in Redshift, separately from Superset role settings |
| Row or column restrictions | Which rows or columns a given user sees within a table | Redshift views or policies, plus Superset row level security where used | Whether restrictions are enforced in the warehouse, since a shared identity can reach any row it has been granted |
| Audit trail | Which identity ran each query in Redshift | Your logging configuration in Redshift and AWS | Whether query logs show the database identity only, so per-user attribution needs a design decision |
Securing the Redshift connection and limiting dashboard load
A Redshift connection gives every dashboard a path into your warehouse, so the identity, privileges and query behavior behind it matter as much as the charts. The cards below cover how Superset authenticates to Redshift, how to scope the IAM and database roles it uses, and how to keep dashboards from becoming an unplanned source of warehouse load.
Passwordless IAM authentication
With the AWS_DATABASE_IAM_AUTH feature flag enabled, Superset requests temporary database credentials from AWS instead of holding a static Redshift password. Confirm that the connection is configured for IAM rather than a stored password, and that no long-lived Redshift user password remains in the connection string or in Superset's metadata database. Test the flow in staging before enabling it for production dashboards.
Least-privilege IAM policies per cluster
Scope the IAM role Superset assumes to the specific resource it needs. For provisioned clusters, this means redshift:GetClusterCredentials limited to the target cluster and database user. For Redshift Serverless, it means redshift-serverless:GetCredentials and GetWorkgroup limited to the named workgroup. Avoid wildcard resource ARNs, since a broad policy lets a compromised Superset host reach every cluster in the account.
Cross-account role assumption
If the warehouse lives in a different AWS account from Superset, Superset reaches it through STS AssumeRole. The trust policy on the target role should name only the Superset host's role as principal, and the session duration should be as short as your workloads allow. Ask your AWS team who owns the trust relationship and how it is reviewed when accounts change.
Read-only Redshift roles for dashboards
Create a dedicated database user or role for Superset that holds only SELECT on the schemas its dashboards query. Keep it separate from the ETL and administrative accounts, and do not grant CREATE or write privileges on production schemas. Verify the grants with a test query from that user before publishing dashboards, because a grant mistake is easier to catch then than after a dashboard is shared widely.
Storing connection secrets
Keep any remaining secrets, such as the database connection details and the AWS role configuration, out of dashboards and out of plain configuration files in source control. Store them in a secrets manager or your deployment's secret store and inject them at runtime. Document who can edit database connections in Superset, since that permission controls which credentials every chart can use.
Limiting SQL execution and caching
Dashboards issue queries every time they refresh, so a popular dashboard can multiply warehouse load. Set query timeouts and row limits in Superset, enable result caching for dashboards that do not need live data, and review which datasets are exposed with expensive joins. Ask your Redshift administrator for workload management (WLM) queue settings that isolate Superset queries from ETL, and confirm them in a load test with realistic concurrency.
Secret key and session settings
Superset requires a user-specified SECRET_KEY before it starts, and that key protects the credentials Superset stores in its metadata database. Generate a strong value, keep it out of source control, and use PREVIOUS_SECRET_KEY when rotating it so existing encrypted values remain readable during the transition. Review session lifetime and cookie settings with your security team, since a stolen session can reuse the database access that a dashboard already has.
Controlling query load from dashboards on Redshift
Dashboards generate load in bursts that a single analyst's ad hoc query never does. Every chart on a dashboard issues its own SQL, and when many users open the same dashboard at once, or a filter change refreshes a dozen charts together, Redshift receives a fan-out of concurrent queries. Superset does not know how much your cluster or workgroup can absorb, so the limit has to be set on both sides: in Superset's caching and query behavior, and in the Redshift controls that decide how concurrent work is queued, prioritized and billed. Plan this before rollout, not after the first slow Monday morning.
On the Superset side, the levers are the caching layer, async query execution and the worker processes. The architecture documentation ties async queries and alerts and reports to the caching layer and worker components, and most installations use Redis and Celery for them. Caching lets repeated chart requests reuse results instead of hitting Redshift again, which matters most for popular shared dashboards. Async execution moves long queries off the web request path, so a slow chart does not hold a web worker. Confirm the cache timeout and async settings in the configuration documentation for your release, and decide which datasets are safe to cache for how long given how fresh the data must be. Scheduled reports and thumbnails also run queries, so size their schedules deliberately.
On the Redshift side, confirm the controls with AWS documentation before rollout rather than relying on defaults. For a provisioned cluster, review workload management (WLM) queues, concurrency and memory allocation, and whether a dedicated queue for the Superset service user can cap how much work dashboards can take. For Redshift Serverless, confirm how base capacity and maximum capacity settings, and any usage limits, bound compute and cost. Ask your AWS account team which current options apply to your edition. Give the Superset service role its own database user so these queues and limits can target it, and agree with analysts which dashboards may run on demand and which must read cached or precomputed tables.
Common Redshift connection failures and fixes
This table lists the failures teams most often hit when connecting self-hosted Superset to Redshift, with the likely cause and fix for each. Read it top to bottom when a connection test fails, then check the IAM and network rows if the error only appears on worker or scheduled jobs.
| Failure | Likely cause | Fix |
|---|---|---|
| Driver not found when testing the connection | The sqlalchemy-redshift package is missing from the Superset image, so the redshift+psycopg2 dialect cannot load. | Add sqlalchemy-redshift to the image build and redeploy web and worker containers together. Confirm the package is present in every container that runs queries. |
| Connection times out or refuses | The connection string uses a port other than 5439, the default Redshift port in the Superset catalog. | Set the port to 5439 in the connection string, or confirm the port your cluster or workgroup endpoint actually uses. |
| AccessDenied on GetClusterCredentials | The IAM role used by Superset lacks redshift:GetClusterCredentials for the provisioned cluster. | Attach the permission to the role used by the Superset runtime, scoped to the cluster and database user, then test again. |
| AccessDenied on GetCredentials or GetWorkgroup | The IAM role lacks redshift-serverless:GetCredentials or redshift-serverless:GetWorkgroup for a Serverless workgroup. | Grant both actions on the target workgroup. Check the workgroup ARN and region match the connection settings. |
| Cannot assume role in another account | The trust policy on the target role does not allow the Superset role as a principal, or sts:AssumeRole is not allowed on the source role. | Review trust and permission policies on both accounts. Confirm the external ID or session settings match what the Superset configuration expects. |
| Login failed for the database user | The IAM database user does not exist, was dropped, or its name differs from the one configured in Superset. | Create or recreate the database user in Redshift, align the name in the connection configuration, and confirm grants on the target schemas. |
| Connection fails only from workers or scheduled reports | The security group or network ACL blocks traffic from the worker subnet to the cluster or workgroup endpoint on port 5439. | Allow inbound 5439 from the worker's security group or subnet. Test from the worker container, since the web container may have different network rules. |
| Dashboards are slow or stall the warehouse | Charts issue unbounded queries across large tables, with no row limits, time filters or caching. | Add time filters and default row limits, use caching for shared dashboards, and set workload management limits in Redshift for the Superset user. Confirm limits with your Redshift administrator. |
Questions buyers ask about Superset and Redshift
What does a Superset and Redshift integration cost in effort, and what drives it?
Effort depends mostly on how many Redshift environments you connect, how many AWS accounts are involved, and how your access model maps to database roles. The work splits into a one-time build (image changes, driver installation, IAM role design, network paths, Redshift grants and validation) and recurring work (credential rotation review, upgrades and access reviews). Costs rise when Redshift runs across several accounts, when you need per-user or per-group database access, or when dashboards must be tested against production-sized data. Ask any partner for a quote that lists each of these as a separate line, and confirm which items are one-time and which recur. DeployOpen fixed-scope quotes follow from the written scope.
How long does it take to connect Superset to Redshift and validate it?
The duration depends on how quickly your team can grant AWS and Redshift access and how many connections must be validated. The technical connection is short once the driver is in the image and the role and network paths exist. Most of the elapsed time goes to waiting on approvals, cross-account trust setup, security review and testing dashboards against real queries. Validation should cover a connection from each Superset environment, a dashboard load under expected concurrency and a check that the database user sees only the schemas it should. Agree on a timeline only after these dependencies are listed in the written scope.
What must our team provide before the integration can start?
You need to provide the AWS accounts that host the Redshift clusters or Redshift Serverless workgroups, permission to create or update IAM roles, and a network path from the Superset workers and web servers to the Redshift endpoint on port 5439. On the database side, you need a plan for Redshift grants, including which schemas and tables each reporting role can read. Confirm whether Superset runs in the same account as Redshift or whether you will use cross-account role assumption through STS. Also confirm who owns the Superset host, the metadata database and the secret store that holds any passwords still in use.
Can our internal team set up Superset with Redshift without a partner?
Yes, a capable platform team can do it alone if it has experience with Superset deployment, AWS IAM and Redshift administration. The main risks for an internal team are IAM policy scope, cross-account trust mistakes and assuming that a connection string that works also enforces the right data access. The IAM authentication path depends on the AWS_DATABASE_IAM_AUTH feature flag, and the policies differ for provisioned clusters and Redshift Serverless, so confirm the exact permissions against the Superset AWS IAM documentation before building. A partner adds most value when you need repeatable validation, a documented runbook and an independent review of the access model before go-live.
Do I need to change the driver when I upgrade Superset?
Often yes, because Superset upgrades can change the Python environment and the supported versions of database drivers. The Redshift connection uses the sqlalchemy-redshift package with the redshift+psycopg2 dialect, so a change in the base image, the Python version or the SQLAlchemy version can break the connection. Before each upgrade, check the breaking change notes in UPDATING.md for your target version, rebuild the image with a pinned driver version and test the Redshift connection in staging. Back up the metadata database first, then run the documented upgrade commands. Keep the driver version in your build file so that an upgrade is a deliberate change, not an accident.
Should Superset use IAM authentication or a database password for Redshift?
IAM authentication is generally the stronger choice for production because it avoids a long-lived database password stored in Superset. Superset supports it for Redshift and Aurora behind the AWS_DATABASE_IAM_AUTH feature flag, using STS AssumeRole for cross-account access. Provisioned clusters need the redshift:GetClusterCredentials permission, while Redshift Serverless needs redshift-serverless:GetCredentials and GetWorkgroup. Password-based connections using the username and password in the connection string remain possible, but then the secret must be stored, rotated and kept out of dashboard owners' view. Confirm the choice with your security team before the build, because it changes the IAM policies, the rotation process and the audit trail.
How do we stop dashboards from overloading the Redshift cluster?
Control query load at three layers: the Redshift workload design, the Superset caching and the Superset query limits. On the Redshift side, use a dedicated database user or group for Superset with workload management rules that cap concurrency and runtime for that group. In Superset, enable caching so repeated dashboard loads do not hit the warehouse each time, and set row limits and timeouts for chart queries. Dashboard design matters too: a chart that scans a wide table on every filter change costs far more than a pre-aggregated table. Ask your partner to test the heaviest dashboards under expected concurrency before you open access to users.
How DeployOpen scopes and delivers the Redshift integration
DeployOpen scopes the Redshift integration in writing before any work starts. The written scope names the Redshift deployment type (provisioned cluster or Redshift Serverless), the AWS accounts and Regions involved, whether cross-account role assumption is needed, which Superset environments will connect, and who approves the database privileges and IAM policies. Deliverables and acceptance tests are agreed at the same time, so the reader knows what is handed over and how it will be checked. Most engagements are fixed-scope, and a quote follows from that written scope rather than from a generic price list.
Delivery happens inside your own AWS accounts and under your change control. DeployOpen builds the Superset image with the sqlalchemy-redshift driver, configures the database connection and IAM authentication behind the AWS_DATABASE_IAM_AUTH feature flag, and wires the STS role chain where the warehouse sits in another account. Testing covers a connection from each Superset environment, token expiry and refresh under load, denial tests for principals that should not reach the cluster or workgroup, and a check that dashboard queries land under the agreed concurrency limits. The configuration, IAM policies and runbook are documented so your platform team can operate the integration without us.
Ongoing support and upgrade work can be covered by a retainer after handover. Superset releases change configuration and dependencies, so a retainer typically covers patching the image, retesting the Redshift connection against new Superset and driver versions, and reviewing IAM policy changes. Confirm during scoping which of these your team will own, what response expectations apply to your environment, and how changes to the Redshift side, such as a cluster resize or a move to a new workgroup, are handled and priced.
