Superset 4: Zero‑Code Guide to Connecting Hundreds of Databases

Overview

Apache Superset does not ship with any database drivers. To connect to a data source you must install the appropriate Python DB‑API driver and the matching SQLAlchemy dialect in the Superset environment.

Installing database drivers

Use pip install <package> to add a driver. For Docker‑based deployments add the package name to ./docker/requirements-local.txt and rebuild the image.

# MySQL example
pip install mysqlclient

After updating the requirements file, rebuild the image and start Superset:

docker compose build --force-rm

docker compose up

Verify the driver is present inside the container:

docker exec -it <container_name> bash -c "pip freeze | grep mysqlclient"

Supported databases and example connection strings

AWS Athena

Driver: pip install pyathena[pandas] && pip install PyAthenaJDBC JDBC URI:

awsathena+jdbc://{access_key_id}:{secret_key}@athena.{region}.amazonaws.com/{schema}?s3_staging_dir={s3_staging_dir}&...

REST URI (PyAthena):

awsathena+rest://{access_key_id}:{secret_key}@athena.{region}.amazonaws.com/{schema}?s3_staging_dir={s3_staging_dir}&...

AWS DynamoDB

Driver: pip install pydynamodb URI:

dynamodb://{aws_access_key_id}:{aws_secret_access_key}@dynamodb.{region}.amazonaws.com:443?connector=superset

AWS Redshift

Driver: pip install sqlalchemy-redshift psycopg2 URI:

redshift+psycopg2://<user>:<password>@<aws_endpoint>:5439/<database>

redshift_connector URI:

redshift+redshift_connector://<user>:<password>@<aws_endpoint>:5439/<database>

IAM‑based (cluster) example:

{
    "connect_args": {
        "iam": true,
        "database": "<database>",
        "cluster_identifier": "<cluster_id>",
        "db_user": "<db_user>"
    }
}

Use the redshift+redshift_connector:// scheme together with the JSON above in the Extra field.

ClickHouse

Driver: pip install clickhouse-connect URI:

clickhousedb://<user>:<password>@<host>:<port>/<database>

MySQL

Driver: pip install mysqlclient URI:

mysql://<username>:<password>@<host>/<database>

PostgreSQL

Driver bundled with Superset Docker images: psycopg2 URI:

postgresql://<username>:<password>@<host>:<port>/<database>

Google BigQuery

Driver: pip install sqlalchemy-bigquery URI: bigquery://{project_id} (service‑account JSON must be supplied in the Secure Extra field)

Snowflake

Driver: pip install snowflake-sqlalchemy URI:

snowflake://{user}:{password}@{account}.{region}/{database}?role={role}&warehouse={warehouse}

Docker‑based installation example (MySQL)

Create ./docker/requirements-local.txt if it does not exist.

Add the driver name:

echo "mysqlclient" >> ./docker/requirements-local.txt

Rebuild the image: docker compose build --force-rm Start Superset: docker compose up Verify the driver inside the container:

docker exec -it <container_name> bash -c "pip freeze | grep mysqlclient"

Connecting through the Superset UI

The UI workflow consists of three steps:

Choose the engine on the /available endpoint – only drivers that are installed in the environment are listed.

Enter engine‑specific parameters in a dynamic form (available for Redshift, MySQL, PostgreSQL, BigQuery). The form validates fields on blur and shows immediate errors.

Optionally configure advanced settings such as SSL, extra engine parameters, or custom logos.

After saving, click the “Test Connection” button to confirm that Superset can reach the database.

Advanced settings

SSL

{
  "engine_params": {
    "connect_args": {
      "sslmode": "require",
      "sslrootcert": "/path/to/ca.pem"
    }
  }
}

Schemas – for PostgreSQL, Redshift, etc., set the schema name in the table‑edit form (Sources → Tables → Edit).

External password store Define a callable in SQLALCHEMY_CUSTOM_PASSWORD_STORE that receives a SQLAlchemy URL and returns the password. This allows integration with secret‑management systems.

Custom logos and preferred databases

Define a mapping in superset_text.yml to associate an engine name with a logo URL or static path:

DB_IMAGES:
  postgresql: "static/img/postgres.png"
  bigquery: "https://s3.amazonaws.com/bucket/bq.png"
  snowflake: "static/img/snowflake.png"

Set the order of preferred databases (shown first in the “Add Database” dialog) in superset_config.py:

PREFERRED_DATABASES = ["PostgreSQL", "Presto", "MySQL", "SQLite"]

Meta‑database feature (cross‑database queries)

Enable the experimental meta‑database by setting ENABLE_SUPERSET_META_DB = true and adding a new database with the SQLAlchemy URI superset://. Queries can reference any registered database using the syntax:

SELECT * FROM "database_name.[[catalog.].schema].table_name";

Spaces are allowed; periods inside identifiers must be URL‑encoded as %2E. The meta‑database pushes filters, limits and ordering to the underlying engines but performs joins and aggregations in memory. Because of the in‑memory processing, it should be used asynchronously and with a row limit (default SUPERSET_META_DB_LIMIT = 1000).

Security considerations:

The meta‑database respects the original database permissions – users can only query tables they have access to.

You can restrict which databases are reachable by adding {"allowed_dbs": ["Google Sheets", "examples"]} to the Extra field of the meta‑database connection.

Troubleshooting

Use the “Test Connection” button to surface connection errors.

Inspect container logs or run a Python REPL inside the container to manually create an engine and execute a simple query.

For IAM‑based Redshift connections, ensure the Superset IAM role has redshift:GetClusterCredentials (cluster) or redshift-serverless:GetCredentials and redshift-serverless:GetWorkgroup (serverless) permissions.

References

https://superset.apache.org/docs/

https://superset.apache.org/docs/configuration/databases

https://github.com/apache/superset