duckdb-sqlalchemy 0.19.0__py3-none-any.whl

duckdb_sqlalchemy-0.19.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: duckdb-sqlalchemy
+Version: 0.19.0
+Summary: SQLAlchemy driver for duckdb
+Project-URL: Bug Tracker, https://github.com/leonardovida/duckdb-sqlalchemy/issues
+Project-URL: Changelog, https://github.com/leonardovida/duckdb-sqlalchemy/releases
+Project-URL: repository, https://github.com/leonardovida/duckdb-sqlalchemy
+Project-URL: Upstream, https://github.com/Mause/duckdb_engine
+Author-email: Leonardo Vida <leonardo@motherduck.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Requires-Python: <4,>=3.9
+Requires-Dist: duckdb>=0.5.0
+Requires-Dist: packaging>=21
+Requires-Dist: sqlalchemy>=1.3.22
+Provides-Extra: dev
+Requires-Dist: fsspec<2026.0.0,>=2025.2.0; extra == 'dev'
+Requires-Dist: github-action-utils<2.0.0,>=1.1.0; extra == 'dev'
+Requires-Dist: hypothesis<7.0.0,>=6.75.2; extra == 'dev'
+Requires-Dist: jupysql<0.12.0,>=0.11.1; extra == 'dev'
+Requires-Dist: numpy<2.0,>=1.24; (python_version < '3.12') and extra == 'dev'
+Requires-Dist: numpy<3.0,>=1.26; (python_version >= '3.12' and python_version < '3.13') and extra == 'dev'
+Requires-Dist: numpy<3.0,>=2.0; (python_version >= '3.13') and extra == 'dev'
+Requires-Dist: pandas<2.0,>=1; (python_version < '3.12') and extra == 'dev'
+Requires-Dist: pandas<3.0,>=2.2; (python_version >= '3.12') and extra == 'dev'
+Requires-Dist: pyarrow>=22.0.0; (python_version >= '3.10') and extra == 'dev'
+Requires-Dist: pytest-cov<6.0.0,>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-remotedata<0.5.0,>=0.4.0; extra == 'dev'
+Requires-Dist: pytest-snapshot<1.0.0,>=0.9.0; extra == 'dev'
+Requires-Dist: pytest<9.0.0,>=8.0.0; extra == 'dev'
+Requires-Dist: toml<0.11.0,>=0.10.2; extra == 'dev'
+Requires-Dist: ty; extra == 'dev'
+Provides-Extra: devtools
+Requires-Dist: pdbpp<0.12.0,>=0.11.0; extra == 'devtools'
+Requires-Dist: pre-commit>=4.0.0; (python_version >= '3.9') and extra == 'devtools'
+Description-Content-Type: text/markdown
+
+# duckdb-sqlalchemy
+
+[![PyPI version](https://badge.fury.io/py/duckdb-sqlalchemy.svg)](https://pypi.org/project/duckdb-sqlalchemy)
+[![Supported Python Versions](https://img.shields.io/pypi/pyversions/duckdb-sqlalchemy)](https://pypi.org/project/duckdb-sqlalchemy/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/duckdb-sqlalchemy.svg)](https://pypi.org/project/duckdb-sqlalchemy/)
+[![CI](https://github.com/leonardovida/duckdb-sqlalchemy/actions/workflows/pythonapp.yaml/badge.svg)](https://github.com/leonardovida/duckdb-sqlalchemy/actions/workflows/pythonapp.yaml)
+[![codecov](https://codecov.io/gh/leonardovida/duckdb-sqlalchemy/graph/badge.svg)](https://codecov.io/gh/leonardovida/duckdb-sqlalchemy)
+[![License](https://img.shields.io/pypi/l/duckdb-sqlalchemy)](LICENSE.txt)
+
+SQLAlchemy dialect for DuckDB and MotherDuck. Run DuckDB locally or connect to MotherDuck with the standard SQLAlchemy APIs. This maintained fork tracks current DuckDB releases and includes MotherDuck-specific helpers and reliability improvements compared to legacy forks.
+
+## Highlights
+
+- First-class SQLAlchemy dialect (Core + ORM) for DuckDB and MotherDuck.
+- Clean connection URL helpers for MotherDuck routing, attach modes, and read scaling.
+- Practical defaults for pooling, pre-ping, and long-lived app workloads.
+- Optional transient retry for idempotent reads.
+- Actively maintained with a long-term support mindset.
+
+## Compatibility
+
+| Component | Supported versions |
+| --- | --- |
+| Python | 3.9+ |
+| SQLAlchemy | 1.3.22+ (2.x recommended) |
+| DuckDB | 0.5.0+ (latest recommended) |
+
+## Install
+
+```sh
+pip install duckdb-sqlalchemy
+```
+
+Conda packages are available via conda-forge: https://github.com/conda-forge/duckdb-sqlalchemy-feedstock.
+
+## Quick start (DuckDB)
+
+```python
+from sqlalchemy import Column, Integer, String, create_engine
+from sqlalchemy.orm import declarative_base, Session
+
+Base = declarative_base()
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String)
+
+
+engine = create_engine("duckdb:///:memory:")
+Base.metadata.create_all(engine)
+
+with Session(engine) as session:
+    session.add(User(name="Ada"))
+    session.commit()
+    assert session.query(User).one().name == "Ada"
+```
+
+## Quick start (MotherDuck)
+
+```bash
+export MOTHERDUCK_TOKEN="..."
+```
+
+```python
+from sqlalchemy import create_engine
+
+engine = create_engine("duckdb:///md:my_db")
+```
+
+MotherDuck uses the `md:` database prefix. Tokens are picked up from `MOTHERDUCK_TOKEN` (or `motherduck_token`) automatically. If your token has special characters, URL-escape it or pass it via `connect_args`.
+
+## Connection URLs
+
+DuckDB URLs follow the standard SQLAlchemy shape:
+
+```
+duckdb:///<database>?<config>
+```
+
+Examples:
+
+```
+duckdb:///:memory:
+duckdb:///analytics.db
+duckdb:////absolute/path/to/analytics.db
+duckdb:///md:my_db?attach_mode=single&access_mode=read_only&session_hint=team-a
+```
+
+Use the URL helpers to build connection strings safely:
+
+```python
+from duckdb_sqlalchemy import URL, MotherDuckURL
+
+local_url = URL(database=":memory:", read_only=False)
+md_url = MotherDuckURL(database="md:my_db", attach_mode="single")
+```
+
+## Configuration and pooling
+
+This dialect ships with sensible defaults (NullPool for file/MotherDuck connections, SingletonThreadPool for `:memory:`) and lets you override pooling explicitly. For production services, use the MotherDuck performance helper or configure `QueuePool`, `pool_pre_ping`, and `pool_recycle`.
+
+See `docs/configuration.md` and `docs/motherduck.md` for detailed guidance.
+
+## Documentation
+
+- `docs/README.md` - Docs index
+- `docs/connection-urls.md` - URL formats and helpers
+- `docs/motherduck.md` - MotherDuck setup and options
+- `docs/configuration.md` - Connection configuration, extensions, filesystems
+- `docs/olap.md` - Parquet/CSV scans and ATTACH workflows
+- `docs/pandas-jupyter.md` - DataFrame registration and notebook usage
+- `docs/types-and-caveats.md` - Type support and known caveats
+- `docs/alembic.md` - Alembic integration
+
+## Examples
+
+- `examples/sqlalchemy_example.py` - end-to-end example
+- `examples/motherduck_read_scaling_per_user.py` - per-user read scaling pattern
+- `examples/motherduck_queuepool_high_concurrency.py` - QueuePool tuning
+- `examples/motherduck_multi_instance_pool.py` - multi-instance pool rotation
+- `examples/motherduck_arrow_reads.py` - Arrow results + streaming
+- `examples/motherduck_attach_modes.py` - workspace vs single attach mode
+
+## Release and support policy
+
+- Long-term maintenance: this project is intended to remain supported indefinitely.
+- Compatibility: we track current DuckDB and SQLAlchemy releases while preserving SQLAlchemy semantics.
+- Breaking changes: only in major/minor releases with explicit notes in `CHANGELOG.md`.
+- Security: please open an issue with details; we will prioritize fixes.
+
+## Changelog and roadmap
+
+- `CHANGELOG.md` - release notes
+- `ROADMAP.md` - upcoming work and priorities
+
+## Contributing
+
+See `AGENTS.md` for repo-specific workflow, tooling, and PR expectations. We welcome issues, bug reports, and high-quality pull requests.
+
+## License
+
+MIT. See `LICENSE.txt`.

duckdb_sqlalchemy-0.19.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+duckdb_sqlalchemy/__init__.py,sha256=ciVk4nVL75nVkZG1bi6_Og68MZVXciZ-qHbAlXQyHlU,49824
+duckdb_sqlalchemy/_supports.py,sha256=GCOH9nFB4MitnjYKx5V4BsDSCxIfTyXqm6W-BDkgbfE,598
+duckdb_sqlalchemy/bulk.py,sha256=lc6T258-BYQ8fp8xwNVePIrJorjFhg_1FGiEROHKqb8,5209
+duckdb_sqlalchemy/capabilities.py,sha256=Y9l-FaVPMw9CTpsG-42tiqltXECFXqIeTQdXPfSuxPY,719
+duckdb_sqlalchemy/config.py,sha256=uWtsAUyxz0wMn2FQmqknjxkowyICxnbkFWB9gP7vzy4,2203
+duckdb_sqlalchemy/conftest.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+duckdb_sqlalchemy/datatypes.py,sha256=kVUe1gXZuUe9UpzY30CQfEP4VAz308HilCG16sRGmkU,8296
+duckdb_sqlalchemy/motherduck.py,sha256=m6g-Qsd6mfYbKJTuhRYVT7MU6QItDirx4N3IiK0CVuA,7101
+duckdb_sqlalchemy/olap.py,sha256=POaNa8RemilRu0BMbqFhY88oZtyq8MPxx64yIQ85RRc,1078
+duckdb_sqlalchemy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+duckdb_sqlalchemy/requirements.py,sha256=jDDZyI6Pt2IfqeMX83hb-IhQWFMDjHxoW_9j6Txd5pg,112
+duckdb_sqlalchemy/url.py,sha256=y2rtgiHXXcgVpQt22eEIeP8MAeVKwBNC9tsh1i3j3OE,1539
+duckdb_sqlalchemy/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+duckdb_sqlalchemy/tests/conftest.py,sha256=GldGGf9wrY1hZvcl4hmzKmdirQYCltpZWfM3-WyOKqc,1498
+duckdb_sqlalchemy/tests/test_basic.py,sha256=CGTHkQfXIm07fxXnSb6jDXI8s9B0E_lCN6q5loDkgrI,21985
+duckdb_sqlalchemy/tests/test_core_units.py,sha256=gqMf4FKyMqNflQlvhoxAX-_WPUKqaJ72jDlnHhJEuOE,13740
+duckdb_sqlalchemy/tests/test_datatypes.py,sha256=g7WwxP6Kq6rhhWdpFUs1g6NA0jNYuaJMiolsRpG0qI8,7144
+duckdb_sqlalchemy/tests/test_execution_options.py,sha256=ov0YVVQLdKdw1K8grdzkpIQMD863dsyB0SG4rkevGks,964
+duckdb_sqlalchemy/tests/test_helpers.py,sha256=9KGRmNVvTVPvcEN3mHCwXIIKhdFe_GXmyBnfWisYiCs,2216
+duckdb_sqlalchemy/tests/test_integration.py,sha256=a9e8BTe4l1ZU8jT220qh0MLffe8Dzf1jAXLNBuVRhJQ,1460
+duckdb_sqlalchemy/tests/test_pandas.py,sha256=EchdBuVwqc1BuGQizg3Xu3WDiTmdVoSuUYA3PsRCd78,4037
+duckdb_sqlalchemy/tests/test_pyarrow.py,sha256=QtjxKTv7-J2LQ0rlB9xon9c46xoECkz4jM8A2a7dlGM,2304
+duckdb_sqlalchemy/tests/util.py,sha256=YHTtB19mxQO--nq1tCnQELcKL_Qh73T9mvdnH6rVlRI,257
+duckdb_sqlalchemy/tests/snapshots/test_datatypes/test_interval/schema.sql,sha256=ZXscZo4xepli7WSjbhWqTufIciscCDLoRznaA6KGiOI,47
+duckdb_sqlalchemy/tests/sqlalchemy_suite/conftest.py,sha256=BVvwaWDIXobKa-ziFyhmjkIkCd5vz0TbT77AFOPCHHc,263
+duckdb_sqlalchemy/tests/sqlalchemy_suite/test_suite.py,sha256=O2O52uLfENDAU_xl2_iZZgigLP1DB8IYaULqCEOnIA8,58
+duckdb_sqlalchemy-0.19.0.dist-info/METADATA,sha256=HWELJl086hxvK-GwxtbZDbLCEZypsS0JE2Az6c_PnsM,7070
+duckdb_sqlalchemy-0.19.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+duckdb_sqlalchemy-0.19.0.dist-info/entry_points.txt,sha256=MyXbmaqEhyBLIL2NnHrweY6EJ_Rke2HnVZR1wCz08cM,57
+duckdb_sqlalchemy-0.19.0.dist-info/licenses/LICENSE.txt,sha256=nhRQcy_ZV2R-xzl3MPltQuQ53bcURavT0N6mC3VdDE8,1076
+duckdb_sqlalchemy-0.19.0.dist-info/RECORD,,

duckdb_sqlalchemy-0.19.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

duckdb_sqlalchemy-0.19.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[sqlalchemy.dialects]
+duckdb = duckdb_sqlalchemy:Dialect

duckdb_sqlalchemy-0.19.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-present Elliana May
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.