---
id: duckdb-engine
version: "0.17.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# duckdb-engine — SQLAlchemy driver for duckdb

License: permissive · Maintenance: active · Downloads: 2.1M/mo

## What it is and what it does

duckdb_engine is a SQLAlchemy dialect that bridges DuckDB and SQLAlchemy, letting you write standard SQLAlchemy code against DuckDB databases. It works by registering itself as a SQLAlchemy driver, so you can create engines with the duckdb:// URL scheme and use the full ORM and expression language as you would with any other database. The package depends on duckdb, sqlalchemy, and packaging.

The driver supports both in-memory and file-backed DuckDB instances, pandas DataFrame registration, Alembic migrations, extension preloading, and fsspec filesystem registration. It derives from the PostgreSQL dialect, which means some PostgreSQL-specific features (like SERIAL auto-increment) are not directly supported and require workarounds such as SQLAlchemy Sequence objects. The package is designed for developers who want to use DuckDB's analytical capabilities within a familiar SQLAlchemy interface.

Use it for:

- Build data analysis pipelines using SQLAlchemy ORM against DuckDB for fast in-memory or persistent queries
- Query pandas DataFrames registered with DuckDB using standard SQL through SQLAlchemy
- Prototype or migrate applications from PostgreSQL to DuckDB by swapping the connection string
- Run interactive SQL queries in Jupyter notebooks with IPython-SQL and duckdb_engine
- Manage database schema evolution with Alembic migrations on DuckDB-backed applications

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A SQLAlchemy driver that enables you to use DuckDB as a database backend, allowing standard SQLAlchemy ORM and SQL operations against DuckDB instances.

Yes. The package has low install friction, active maintenance, no known vulnerabilities, and permissive licensing. It is a solid choice if you need SQLAlchemy integration with DuckDB. Be aware of PostgreSQL-derived dialect quirks (e.g., SERIAL not supported, use Sequence instead) and test edge cases involving advanced SQL features.

## Install

pip install duckdb-engine
uv add duckdb-engine
poetry add duckdb-engine

## Installing duckdb-engine

Before you install: Low friction installation with three straightforward runtime dependencies (duckdb, packaging, sqlalchemy). The package is actively maintained with recent commits and has been stable since its early releases.

License in practice: MIT license is permissive and places no restrictions on use, modification, or distribution in proprietary or open-source contexts.

Quickstart:

from sqlalchemy import Column, Integer, Sequence, String, create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm.session import Session

Base = declarative_base()

class FakeModel(Base):
    __tablename__ = "fake"
    id = Column(Integer, Sequence("fakemodel_id_sequence"), primary_key=True)
    name = Column(String)

eng = create_engine("duckdb:///:memory:")
Base.metadata.create_all(eng)
session = Session(bind=eng)
session.add(FakeModel(name="Frank"))
session.commit()

Requires Python 3.9 or later; DuckDB does not support SERIAL datatype, so auto-incrementing IDs must use SQLAlchemy Sequence objects instead.

Verify before relying:

- Whether all DuckDB configuration parameters documented in DuckDB's configuration guide are fully supported through connect_args
- Current status of pandas.read_sql() chunksize compatibility (note indicates it was resolved in duckdb >=0.5.0, but confirmation needed)
- Extent of PostgreSQL feature parity and which specific SQL constructs may fail due to DuckDB's PostgreSQL parser limitations

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sqlalchemy duckdb driver, duckdb sql database adapter, in-memory sql query engine, duckdb orm integration, sqlalchemy dialect duckdb, python sql database connector, duckdb dataframe queries, sqlalchemy-dialect, duckdb-integration, analytics-sql

[View on SkillFed](https://skillfed.io/packages/duckdb-engine) · [View on PyPI](https://pypi.org/project/duckdb-engine/)