Since version 0.2.0 this package is a thin layer over sqlalchemy-cloudflare-d1. That project is the real dialect and the real driver. This package registers it under the d1 name and adds the few things Superset needs.

Why this package exists

Superset ships a built-in Cloudflare D1 engine spec that expects d1:// connection strings. See the Superset D1 docs page.

Version 0.1.0 of this package only worked with SQLAlchemy 1.4. When Superset moved to SQLAlchemy 2.0, it held its d1 extra back because of that. Version 0.2.0 works with SQLAlchemy 2.0. Since apache/superset#44505, merged on 29 September 2026, the d1 extra installs this package alone. See Superset's UPDATING.md.

Not using Superset? Install sqlalchemy-cloudflare-d1 directly and use its cloudflare_d1:// connection string.

Installation

pip install sqlalchemy-d1

This also installs sqlalchemy-cloudflare-d1 and SQLAlchemy 2.0. Python 3.11 or newer is required.

Superset on SQLAlchemy 1.4? Superset 6.1.0, for example. Stay on version 0.1.0. Newer versions would upgrade SQLAlchemy and break it.

pip install "sqlalchemy-d1==0.1.0"

Compatibility

Usage

Connection string

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

SQLAlchemy

from sqlalchemy import create_engine, text

engine = create_engine("d1://<CF_ACCOUNT_ID>:<CF_API_TOKEN>@<D1_DB_ID>")

with engine.connect() as conn:
    print(conn.execute(text("SELECT 1")).scalar())

Apache Superset

In Superset, open Settings > Database Connections > + Database and use the same URL as the SQLAlchemy URI of the database connection. Your tables are listed under the main schema.

What it adds

Everything else comes from sqlalchemy-cloudflare-d1 unchanged. That includes the connection, the cursor, the SQL compiler, and the reflection of foreign keys, indexes and unique constraints.

Known limits

In this package

• Tables created through SQLAlchemy are identical to the ones upstream creates. A DateTime column is declared as TEXT and a Boolean column as INTEGER, so they are reflected as text and integer afterwards. Values still round trip correctly when you use the same Table object.
• Tables created with plain SQL and a DATETIME column, which is the normal case for D1, are reflected as dates. A table reflected from D1 keeps its declared types when SQLAlchemy creates it again on D1. On another database the same columns compile like SQLAlchemy's generic date and boolean types.
• Only the first word of a declared type is matched, so TIMESTAMP WITH TIME ZONE is a date and UPDATED_INT is an integer.
• CHECK constraints are not reflected. get_check_constraints returns an empty list, and get_table_comment returns no comment because SQLite has none.

From sqlalchemy-cloudflare-d1

These come from the upstream driver and dialect, so this package has them too.

• Date and time values are written with a T, such as 2026-09-21T09:00:00. Data from other tools often has a space instead, and Superset writes its time filters with a space. SQLite compares both forms as text and a T sorts after a space, so comparing one form with the other can give the wrong rows. Keep dates in one form. SQLite's datetime() turns either form into the one with a space.

Development

Setup

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]"

With Poetry, run poetry install --all-extras instead.

Checks

ruff check . && ruff format --check . && mypy src
pytest -m "not integration" --disable-socket

Integration tests

The integration tests need a real D1 database. Use a throwaway one. They create and drop their own tables.

export CF_ACCOUNT_ID=<CF_ACCOUNT_ID>
export CF_API_TOKEN=<CF_API_TOKEN>
export CF_D1_DATABASE_ID=<D1_DB_ID>
pytest -m integration

Contributing

Issues and pull requests are welcome on GitHub. CI runs the checks and unit tests above on Python 3.11 to 3.14 for every pull request. It also runs them once a week, so a new upstream release that breaks the dialect is noticed.

Some changes belong in another project:

License

This package is licensed under the Apache License 2.0. See LICENSE.

sqlalchemy-cloudflare-d1 is a separate project under the MIT license. It is a dependency and none of its code is copied here.