How Apache Superset connects to Oracle Database for reporting
Teams that want dashboards on Oracle data without building a separate analytics warehouse can usually start with a direct database connection. Superset reaches Oracle through SQLAlchemy, using the oracledb Python package and a connection string in the form oracle+oracledb://{username}:{password}@{hostname}:{port}, with the default port 1521. The Oracle side is an ordinary database connection, not a separate product, and the Superset database catalog notes that the oracledb package replaced the older cx_Oracle driver that earlier installations may still reference. Superset itself runs in your own infrastructure, so queries travel from your Superset hosts to your Oracle listener over the network paths you approve.
Before you enter a connection string, confirm three things with your Oracle DBA and your Superset platform owner. First, the image or virtual environment that runs Superset must include oracledb, because the driver is installed into the Superset environment, not into Oracle. Second, the connection must identify the database by the service name your DBA publishes for the reporting target, since the hostname and port alone do not select a database. Third, confirm the listener port with the DBA, because 1521 is the default and many sites run listeners on other ports or behind network controls. Note the exact driver version you install and test it against your Superset release, since driver requirements can change between releases.
Keep the metadata database separate from the Oracle connection. Superset stores its own users, dashboards and saved queries in the metadata database, and the Oracle account is only used to run analytical queries. Ask the DBA to create a dedicated account for Superset that holds read-only privileges on the schemas that reports need. Plan that account's credentials as secrets from the start, and test the connection from a staging Superset before any production user sees a chart. The details of query limits and permissions are covered in the sections that follow.
What you need before connecting Superset to Oracle
Connecting Superset to Oracle Database depends on decisions made before any connection is tested. The Superset release, metadata database, driver packaging, Oracle endpoint details and network path each have to be confirmed in your own environment. Work through these items in order so that a failed connection test points to one clear cause.
A supported Superset release
Start from the Superset release your organization has chosen and tested, not the newest tag. Confirm the release notes and UPDATING.md for any change to database drivers or connection handling in that version. Record the exact version in your change ticket, because the Oracle driver version you install must match what that release is tested with. Ask your DeployOpen or internal team to pin the version in the image rather than installing it loosely at build time.
Production metadata database
Superset stores dashboards, users, and connection definitions in its metadata database. Use PostgreSQL or MySQL for this role, not the SQLite default used by quick installs. Keep it separate from the Oracle source so that Superset's own state never depends on the reporting database being available. Confirm the version you run is within the range listed in the configuration documentation before you start.
The oracledb driver in the image
Superset connects to Oracle through the oracledb package, which replaced the older cx_Oracle package. The driver must be installed in the Superset web and worker images or environment before you test the connection, because Superset cannot reach Oracle without it. Add the package to your image build and confirm the connection dialog accepts the oracle+oracledb scheme. Rebuild and redeploy the image after every driver change.
Hostname, port and service name
Collect the Oracle hostname, listener port and service name from the database team. The default listener port is 1521, but confirm it, since many sites use a different port. Superset's connection string uses the service name rather than a bare SID, so ask whether the target is a service or a legacy SID. Get the exact values in writing before you build the connection string, and test them from a workstation on the Superset network first.
Network routes and firewall rules
Superset hosts must reach the Oracle listener on the agreed port, and the return traffic must be allowed by both sides. Confirm routes between the Superset network segment and the database segment, including any DNS resolution for the Oracle hostname from inside the Superset containers. Ask your network team to open only the required source address and port. If the database sits behind a bastion or SSH tunnel, document that path as part of the design.
Oracle client and TLS requirements
Confirm with your Oracle administrator whether the listener requires TLS, a wallet, or a specific authentication method, and whether the oracledb thin mode can be used for your configuration. Check the Oracle and Superset documentation for any client library or certificate step that applies to your database version. Do not assume a client install is unnecessary until the database team confirms the listener settings. Record the answer, since it changes the image contents and the connection options.
Configuring the Oracle connection in Superset, step by step
This sequence takes a self-hosted Superset from no Oracle access to a tested, read-only connection with datasets ready for charts. Each step ends with a check so you can confirm the previous step worked before moving on.
Install the oracledb driver into the image
Your platform team adds the oracledb Python package to the Superset image or, for a virtualenv install, to the environment that runs Superset and its workers. The Superset database catalog lists oracledb as the driver for Oracle and notes that it replaced cx_Oracle, so do not carry over older cx_Oracle instructions. Rebuild the image or restart the environment, then confirm the package imports from the same interpreter that serves the web and worker processes. The step is done when that check passes in every container or environment that runs Superset.
Confirm the service name with the DBA
Ask the Oracle DBA which service name, not just the SID, the reporting connection should use, along with the hostname, listener port and whether the database sits behind a load balancer or scan address. Superset's catalog gives the default port as 1521, but your DBA should confirm whether your listener uses it. Record the values in writing alongside the network path from the Superset hosts to the listener. The step is done when the DBA confirms the service name and a TCP connection from a Superset host reaches the listener.
Create a read-only Oracle account
The DBA creates a dedicated account for Superset that holds only the select privileges on the schemas and views that dashboards need, with no grants on DDL, DML or administrative roles. Keep this account separate from the metadata database credentials and from any application account. Ask the DBA to confirm in writing which objects are granted and whether the account has a password policy and expiry that your team can manage. The step is done when the account can read the approved objects and the checks in the following steps pass.
Build the connection string
Assemble the SQLAlchemy URI using the pattern oracle+oracledb://{username}:{password}@{hostname}:{port}, then append the service name as the path your DBA confirmed, following the Superset database documentation for Oracle. Keep the password out of the URI where possible by supplying it through your secrets handling, and URL-encode any special characters in it. Store the finished connection string in a secure location, not in a shared document. The step is done when the string parses without error in a local test using the same driver version as Superset.
Add the database in Superset and test it
An administrator opens the database connections page in Superset, selects Oracle as the engine, enters the connection string or its component fields, and runs the test connection action before saving. Enable only the options your policy allows, and keep query and export settings at restrictive values until the limits are reviewed in the security hardening pages. A successful test confirms the driver, network path, service name and credentials work together. The step is done when the test reports success and the saved connection appears in the list without errors.
Register datasets and check row counts
Add the tables or views the dashboards need as datasets, then run a simple query in SQL Lab that counts rows in each one. Compare the counts with figures the data owner provides for the same objects at the same point in time, allowing for normal change during the day. Confirm that the datasets show the expected column types and that date fields behave as the owners expect. The step is done when counts match the agreed reference and the first dataset loads into a basic chart.
Confirm the account cannot write
Using SQL Lab with the Superset connection, attempt a harmless write such as an insert into a scratch table, then confirm Oracle rejects it with a privilege error. Also check that the account cannot create objects or read data outside the granted set. Ask the DBA to review the account's effective privileges in the data dictionary and record the result. The step is done when every write attempt is refused and the DBA signs off on the privilege review.
Why service names and connection string details decide whether the connection works
The connection string is where most Oracle setups in Superset succeed or fail, so get its parts right before anything else. The catalog pattern for Oracle is oracle+oracledb://{username}:{password}@{hostname}:{port}, with a default port of 1521. The hostname and port identify the listener, but they do not identify the database. Your DBA defines a service name that the listener maps to a database instance, and that service name is what the connection needs to reach the right data. Many Oracle environments run several services behind one listener, such as a reporting service and a transactional one, so a correct hostname and port can still connect to the wrong place. Confirm with the DBA which service name the reporting account should use, and whether the environment expects extra parameters such as a protocol or SSL settings. The catalog example shows the general pattern only. The exact service name and any additional parameters must be confirmed in your target Oracle environment before you copy anything into Superset.
Credentials need the same care. Passwords containing characters such as @, :, /, # or % must be URL-encoded inside the connection string, or the URL parser will split it incorrectly and the login will fail in a way that looks like a bad password. Encode the value of the password (and the username, if needed) rather than editing the database account to avoid special characters. Then decide where the string lives. The password belongs in Superset's secret handling, not in a dashboard, a chart description, a saved query, a screenshot or an exported dashboard file. Superset stores connection details in its metadata database, so protect that database and its backups as carefully as the Oracle credentials themselves. Keep the metadata database and the Superset configuration documentation in view when you set the secret key and access controls, because both protect the stored connection.
Mapping Oracle schemas, grants and Superset roles
This table traces access from the Oracle account through the Superset database connection, the datasets and the Superset roles that decide what each user can open. Read it top to bottom to find which team owns each grant and what to check before a dashboard goes live. The main takeaway is that Superset roles limit what the interface shows, but the Oracle grants decide what the data can actually return.
| Oracle or Superset object | What it controls | Who owns the grant | What to verify |
|---|---|---|---|
| Reporting account (Oracle user) | The identity Superset uses to open every connection to the database | Oracle DBA, with approval from the data owner | Account is not the schema owner or a DBA account, and password rotation is planned |
| SELECT grants on schemas and tables | The rows and columns any Superset query can read, regardless of Superset role | Oracle DBA, based on a written list of reporting schemas | Only the agreed schemas and views are granted, and no write or DDL privileges are present |
| Views for reporting | A stable, narrower layer that hides base tables and sensitive columns from Superset | Data owner and Oracle DBA | Views expose only approved columns and are included in the grant list |
| Superset database connection | The oracle+oracledb connection string, port and service name used for one reporting account | Superset administrator, with the Oracle DBA supplying the values | Service name matches the target database, and the connection points to the intended environment |
| Superset dataset and schema name | Which Oracle schema and table or view a chart reads, and how it is named in Superset | Analytics developer who builds the dataset | Schema name matches the Oracle schema exactly, including case, and the dataset points to a view where one exists |
| Superset role and database access | Which connections and datasets each user or group can see and query in Superset | Superset administrator, mapped from identity groups | Roles grant only the connections and datasets the business owner approved, and no role grants unrestricted access by default |
| Superset user or group membership | Who holds each role, usually supplied by the identity provider or a manual list | Identity or access team, with business owners approving membership | Removed users lose access, and group changes are reviewed on a set schedule |
Securing the Oracle account and query path
A Superset connection to Oracle Database is only as safe as the account behind it and the path that queries take to reach the listener. The cards below cover the Oracle account, where credentials live, the network route, who in Superset can use the connection, and the limits that bound what a dashboard can run. Confirm specific Oracle profile and resource settings with your DBA before go-live.
Dedicated read-only Oracle account
Create a separate Oracle user for Superset that holds only SELECT on the reporting schemas or views it needs. Do not reuse an application owner or DBA account, because a dashboard query should never be able to write, drop or alter objects. Ask your DBA to review which schemas, synonyms and packages the account can reach, and to confirm whether any reporting views should be granted through a dedicated schema instead of base tables. Re-check grants whenever a new dataset is added in Superset.
Credentials stored through Superset
Enter the Oracle password in the Superset database connection form, where Superset stores it in its metadata database, rather than hardcoding it in superset_config.py or in a dashboard definition. The metadata database is encrypted with the SECRET_KEY, so that key must be protected and backed up with the same care as the password. Confirm with your security team where the metadata database is encrypted at rest and who can read connection records.
Network restriction to the Oracle listener
Allow traffic from the Superset web and worker hosts to the Oracle listener port only, which defaults to 1521 for the oracledb connection string, and deny it from other subnets. Place Superset in the same controlled network zone as its reporting replicas, not on the segment that carries OLTP application traffic. Ask your network team to confirm firewall rules, and ask your DBA whether listener access is also restricted by valid node checking or connection rules.
Role-based access to the connection
Limit who can open the Oracle database connection and who can build charts or SQL Lab queries against it. Superset roles decide which users can see a database and which can run SQL Lab queries, so map Oracle reporting audiences to specific Superset roles and avoid granting the Admin role for convenience. Review these assignments on a schedule, and confirm how group mapping from your identity provider is set up before relying on it for Oracle data.
SQL execution limits and export controls
Set row limits and query timeouts so a single dashboard cannot pull a full table or hold a long-running Oracle session open. Decide whether SQL Lab results can be downloaded as CSV or Excel, and restrict that permission to roles that need it. Confirm the Superset settings that enforce these limits for your version, then check with your DBA that matching resource limits in Oracle profiles, such as session and CPU limits, are in place for the Superset account.
Common Oracle connection failures and fixes
This table maps the errors teams most often hit when connecting Superset to Oracle Database to their likely causes and fixes. Read each row from the symptom down, and check the causes in order, since the driver and naming issues are the fastest to rule out.
| Symptom | Likely cause | Fix |
|---|---|---|
| Database dialect or driver not found when testing the connection | The oracledb package was never installed in the Superset image or virtual environment | Add oracledb to the image build, rebuild and redeploy, then confirm the package is present inside the running web and worker containers |
| Guides refer to cx_Oracle and the connection fails | The page is older, and Superset now uses the oracledb package in place of cx_Oracle | Use the oracle+oracledb dialect in the connection string and remove cx_Oracle references from your build and runbooks |
| ORA-12514 or a service name not recognized error | The connection string uses a service name the listener does not know, or an SID where a service name is expected | Ask the DBA for the service name registered with the listener and use it in the connection string instead of the SID |
| Connection times out or refuses on port 1521 | Listener is down, the port is blocked by a firewall or security group, or the database uses a custom port | Confirm the listener is running and reachable from the Superset host on the actual port, then update the port in the connection string |
| Authentication fails only for passwords with special characters | Characters such as @, :, / or # in the password break the URL parsing of the connection string | URL-encode the password in the connection string, or confirm with your DBA that the account password does not need those characters |
| Connection succeeds but charts or tables show no data or access errors | The read-only account lacks SELECT grants on the views or schema that dashboards query | Grant SELECT on the specific views and confirm the account can see them in the schema Superset introspects, then retest with a sample query |
Questions buyers ask before connecting Superset to Oracle
How much effort does an Oracle connection take compared with the full Superset build?
The Oracle connection is one of the smaller parts of a Superset project. Once the image includes the driver, the connection itself is a configuration step, a test query and a set of dashboards. The larger effort sits around it: the metadata database, authentication, role design, caching, export controls and the grants that decide what each user can see. Oracle work also adds a dependency on people outside the Superset team, mainly the DBA who creates accounts and confirms service names, and the network team who opens the path from Superset to the database. Those approvals often take longer than the configuration, so the schedule depends on how quickly those teams respond. A written scope should list each Oracle schema, the environments in scope and the dashboards to build, so the effort is visible before work starts.
What drives the cost of connecting Superset to Oracle?
Cost comes from the people and changes the connection needs, and each component has a different payer. DBA time is usually the largest external input. It covers creating a read-only account, granting access to named schemas or views, confirming service names and reviewing grants. Superset image changes cover adding the driver package, building and testing the image and deploying it to staging. Security review covers how credentials are stored, which network paths are open and how access is logged. Query tuning covers slow dashboards that push heavy queries into Oracle, which may call for views, indexes agreed with the DBA or caching. Each item grows with the number of schemas, environments and dashboards. When you request a quote, ask which items are included, who performs each one and what you must supply yourself.
Why does the Oracle driver need to be added to the Superset image?
The Oracle connection depends on a Python driver package that must be present in the environment running Superset. The Superset database catalog lists the oracledb package for Oracle and notes that the connector previously used cx_Oracle. If your team has older image definitions or installation notes that mention cx_Oracle, treat them as out of date and confirm the current package name against the catalog before you build. Installing the driver is a change to the image, so it follows the same build, test and deployment path as any other Superset change. Record the driver version in your image definition so that a later rebuild does not pull a different version without anyone noticing. The Superset database catalog is the natural first read for the current Oracle entry.
What work recurs after the Oracle connection goes live?
Several tasks recur and should be planned as ongoing operations. Driver updates happen whenever the image is rebuilt. Superset upgrades follow the upgrade guide: back up the metadata database, run superset db upgrade and superset init, test in staging first and check UPDATING.md for breaking changes between versions. Password rotation for the Oracle account means changing the stored credential in Superset and confirming that dashboards still refresh. Grant reviews are needed whenever schemas change, a dashboard owner leaves or a new dataset is added. Dashboard growth also brings periodic query reviews with the DBA. The cost of this work depends on your upgrade cadence and the number of environments. Ongoing support, upgrades and continuous testing are available as retainers, so ask whether these tasks belong in a retainer or in your own runbook.
Can our in-house team connect Superset to Oracle without a partner?
Yes, if the team already runs Superset and has a working relationship with the Oracle DBA group. The configuration steps are straightforward for an engineer who can build the image, edit the connection and read Oracle error messages. The harder parts involve other teams and judgment: agreeing the read-only grant model, deciding which schemas are exposed, checking that dashboards do not overload the production database and documenting the evidence that a security or compliance reviewer will request. A team without recent Superset upgrade experience should plan a staging run before production. Before you decide, confirm that your team can answer these questions in writing: who owns the account, who approves grants, who rebuilds the image after a driver change and who tests the next Superset upgrade.
What does the Oracle work need from our side?
Plan to provide access, information and decisions early. You will need the service names for each Oracle database the dashboards use, since the connection must point at the correct service. Confirm them with the DBA against current system records, not against old documentation. The network team must approve the path from Superset hosts to the Oracle listener, which uses port 1521 by default unless your DBA configures another port. A DBA contact must be available to create the read-only account, review grants and answer questions about schema ownership. You also need a staging Superset environment, test data where production data is restricted, a named business owner for each dataset and an approver for the written scope.
When is a quote based on a written scope?
Most engagements are fixed-scope, and the quote follows from a written scope agreed before work starts. DeployOpen does not publish a price list. For the Oracle connection, the scope should name the Oracle databases and schemas in scope, the environments (staging and production), the Superset image changes, the authentication model the connection depends on, the dashboards or datasets to build, any security testing included and the handover material such as runbooks. Anything outside that list, such as tuning Oracle itself or changing the schema, should appear as excluded or as a separate change. Ask for deliverables, acceptance criteria and your own dependencies in the same document, so the quote and the timeline rest on the same assumptions.
How should the Oracle account Superset uses be restricted?
Use a dedicated read-only account that exists only for Superset, with privileges limited to the schemas, tables or views the dashboards need. The account should hold no DBA privileges, no write access and no rights to create objects in shared schemas. Keep its password out of source control and out of exported dashboard definitions, and rotate it on a schedule your security policy sets. Confirm with the DBA which resource limits and timeouts apply to that account, and check the Superset configuration documentation for your version to see which query execution limits Superset can enforce itself. Review the grants whenever schemas change, and log which account runs which dashboards so an auditor can trace access. Ask your security reviewer which evidence they expect before the build starts.
Keeping Oracle reporting from slowing transactional workloads
Dashboards on an operational Oracle database need hard limits before they reach users, because a chart that scans a large table during month-end close competes with the orders, payments and batch jobs the database exists to run. Superset does not decide how much load the database can absorb, so the first step is a decision with your DBA: whether dashboards query a dedicated reporting replica or a read-only standby, or whether they query the primary. Most teams that run analytics against operational data choose a replica or standby, and the DBA should confirm that replication lag is acceptable for the reporting use case before any dashboard is published.
On the Superset side, the controls are query timeouts, row limits and caching. Query timeouts stop long-running statements, row limits cap how many rows a chart or SQL Lab query returns, and caching lets repeated dashboard loads reuse earlier results instead of hitting Oracle again. Confirm the exact timeout, row limit and cache settings for your version in the Superset configuration documentation, and confirm which of these apply to SQL Lab, charts and alerts in your deployment, since asynchronous queries and reports depend on the worker and caching components.
The Oracle side carries the controls Superset cannot enforce on its own. Ask the DBA to set a dedicated read-only account with a resource profile or resource manager plan that caps session CPU, idle time and concurrent sessions, to route reporting sessions to a separate service name so they can be monitored and throttled independently, and to confirm whether statement timeouts or result limits are enforced at the database layer. Test the setup with the heaviest dashboard you plan to publish, watch wait events and temporary tablespace use while it runs, and document the settings so the next change to a dashboard does not quietly undo them.
How DeployOpen scopes and delivers an Oracle connection for Superset
DeployOpen plans, builds, documents and supports self-hosted open-source platforms inside your own infrastructure, including the Apache Superset and Oracle Database connection described on this page. Engagements are fixed-scope, so the driver, network path, account model and query limits are agreed in writing before any connection is built.
How we scope
- Confirm the Oracle versions, service names and network paths Superset must reach from your environment.
- Agree which schemas, tables and views dashboards need, and document each read-only account and its grants.
- Define the written scope, deliverables and timeline together with your data owners and security team before work starts.
How we build
- Install the python-oracledb driver in the Superset image and verify the connection string with your service name.
- Configure read-only database accounts and test that write statements are rejected from Superset's SQL Lab.
- Set query timeouts, row limits and caching for Oracle-backed charts, then test performance against a staging copy.
How we hand over
- Deliver a record of the connection settings, service names, account grants and secret storage locations used.
- Provide test results for connectivity, read-only enforcement and query limits, with the steps to repeat them.
- Document the driver upgrade path and the checks to run before changing the Superset or Oracle versions.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after the fixed-scope delivery ends.
- Review the Oracle connection when Superset is upgraded, checking driver compatibility and changed account rights.
- Ask for a quote built from the written scope so your team can compare it with running this work internally.
