This organization maintains sqlalchemy-d1, the SQLAlchemy dialect behind the Cloudflare D1 support in Apache Superset. Superset ships the D1 engine spec itself. Since apache/superset#44505, its d1 extra installs sqlalchemy-d1 alone.

You need:

• Your Cloudflare account ID
• A Cloudflare API token with D1 read permission
• Your D1 database ID

1. Install the dialect in the same environment as Superset. Pick the version that matches the SQLAlchemy version of your Superset.

A plain pip install sqlalchemy-d1 on SQLAlchemy 1.4 would upgrade SQLAlchemy and break Superset.

2. Connect. In Superset, open Settings > Database Connections > + Database and use this SQLAlchemy URI:

d1://<CF_ACCOUNT_ID>:<CF_API_TOKEN>@<D1_DB_ID>

Your tables are listed under the main schema.

flowchart LR
    superset["Apache Superset<br>D1 engine spec"]
    dialect["sqlalchemy-d1<br>d1 dialect, reflection, type mapping"]
    upstream["sqlalchemy-cloudflare-d1<br>base dialect and DBAPI driver"]
    d1[("Cloudflare D1")]

    superset -- "d1://" --> dialect --> upstream --> d1

    classDef ours stroke:#20A7C9,stroke-width:3px
    class dialect ours

• The D1Dialect in sqlalchemy-d1 handles schema reflection and type mapping for D1. It reflects dates, booleans and views the way Superset expects.
• Superset ships the D1 engine spec itself, in superset/db_engine_specs/d1.py.
• Since sqlalchemy-d1 0.2.0, DBAPI operations come from sqlalchemy-cloudflare-d1. Always use parameterized queries to avoid injection issues.

The sqlalchemy-d1 README lists everything the dialect adds and its known limits.

Each repository is independent, uses Poetry for dependency management, and contains its own virtual environment. sqlalchemy-d1 also works with plain pip:

git clone https://github.com/sqlalchemy-cf-d1/sqlalchemy-d1.git
cd sqlalchemy-d1
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -m "not integration" --disable-socket

With Poetry, run poetry install --all-extras instead. The integration tests need a real D1 database. See the sqlalchemy-d1 README.

The original setup guide for the 0.1.0 stack, with all repositories and a local Superset, is in SETUP.md.

1. Fork the relevant repository.
2. Create a feature branch.
3. Write tests for new functionality.
4. Submit a pull request.

Please follow PEP8, Poetry dependency management, and Superset coding conventions. In sqlalchemy-d1, CI runs ruff, mypy and the unit tests on every pull request.

Some changes belong in another project:

All repositories in this organization are licensed under the Apache License 2.0. sqlalchemy-cloudflare-d1 is a separate project under the MIT license.

For questions or support, open an issue in the relevant repository or reach out to:

Chad Rossouw Original author

Murphy Lee

Shreyas Rao

Daniel Alyoshin Lead maintainer

Alan Zhang