Database Driver Integration#

Superset connects to external databases through two complementary layers: DB engine specs (Python classes that encode SQL dialect knowledge) and SQLAlchemy drivers (Python packages that provide the actual network connectivity). Both must be present for a database connection to work.

DB Engine Specs#

Every supported database has a corresponding engine spec class in superset/db_engine_specs/. 50+ specs ship with Superset. Each inherits from BaseEngineSpec and overrides dialect-specific behavior.

Key class-level attributes on BaseEngineSpec:

Key methods that subclasses override:

• convert_dttm() — converts a Python datetime to a database-appropriate SQL literal
• epoch_to_dttm() / epoch_ms_to_dttm() — epoch → datetime SQL expressions
• fetch_data() — post-processes cursor results (e.g. Oracle returns empty [] when cursor.description is falsy) 1
• adjust_engine_params() — modifies the SQLAlchemy URL and connect args for schema/catalog selection

Oracle Engine Spec Example#

OracleEngineSpec illustrates a typical minimal spec:

• engine = "oracle", engine_name = "Oracle" 2
• force_column_alias_quotes = True, max_column_name_length = 30 — enforces Oracle's 30-character identifier limit 3
• _time_grain_expressions uses Oracle TRUNC() and CAST() syntax 4
• convert_dttm() emits TO_DATE() / TO_TIMESTAMP() literals 5

Engine Spec Discovery#

Specs are loaded at runtime by load_engine_specs() in superset/db_engine_specs/__init__.py, which scans both the built-in db_engine_specs package and any third-party entry points registered under the "superset.db_engine_specs" group. get_engine_spec(backend, driver) resolves the spec for a given SQLAlchemy URL — matching by driver first, then by backend alone, then falling back to BaseEngineSpec.

Installing Database Drivers#

Most database drivers are not bundled with the default Docker image; they must be added separately. Superset ships cx-Oracle>8.0.0,<8.1 as the oracle optional extra in pyproject.toml, alongside 40+ other optional database extras 6.

Option 1 — requirements-local.txt (Docker, no Dockerfile change)#

The simplest path for Docker-based setups 7:

1. Create ./docker/requirements-local.txt and add the driver package(s), e.g. cx-Oracle==8.0.1
2. Run docker compose down -v && docker compose up

docker/docker-bootstrap.sh checks for this file at startup and installs it via uv pip install -r (or pip install -r on older images) before starting the Flask app or Celery workers. The file is git-ignored by convention, keeping driver installs local and out of source control.

Option 2 — pyproject.toml optional extras (pip install)#

When installing via pip outside Docker, install the database extra directly:

pip install "apache-superset[oracle]"
# or for multiple:
pip install "apache-superset[oracle,postgres,mysql]"

The oracle extra pulls in cx-Oracle>8.0.0, <8.1 8. Available extras include bigquery, mysql, postgres, snowflake, trino, hive, mssql, databricks, and many others 6.

Option 3 — Custom Dockerfile#

For production images, COPY a requirements-local.txt into the image and run pip install during the build, or extend the lean stage of the Dockerfile. The lean image installs from the pinned requirements/base.txt 9; customizations should layer on top.

Key Files Reference#