duckdb-sqlalchemy 0.19.1__py3-none-any.whl → 0.19.3__py3-none-any.whl

duckdb_sqlalchemy/__init__.py

@@ -60,7 +60,7 @@ try:
 except ImportError:  # pragma: no cover - fallback for older SQLAlchemy
     PGExecutionContext = DefaultExecutionContext
 
-__version__ = "0.19.1"
+__version__ = "0.19.3"
 sqlalchemy_version = sqlalchemy.__version__
 SQLALCHEMY_VERSION = Version(sqlalchemy_version)
 SQLALCHEMY_2 = SQLALCHEMY_VERSION >= Version("2.0.0")
@@ -583,6 +583,8 @@ class Dialect(PGDialect_psycopg2):
         config.update(cparams.pop("url_config", {}))
         for key in DIALECT_QUERY_KEYS:
             config.pop(key, None)
+        if cparams.get("database") in {None, ""}:
+            cparams["database"] = ":memory:"
         _apply_motherduck_defaults(config, cparams.get("database"))
         path_query = extract_path_query_from_config(config)
         if path_query:
@@ -626,6 +628,8 @@ class Dialect(PGDialect_psycopg2):
             return pool.SingletonThreadPool
         if pool_override in {"null", "nullpool"}:
             return pool.NullPool
+        if not url.database:
+            return pool.SingletonThreadPool
         if url.database and url.database.startswith(":memory:"):
             return pool.SingletonThreadPool
         if _looks_like_motherduck(url.database, dict(url.query)):

duckdb_sqlalchemy/tests/test_core_units.py

@@ -5,6 +5,7 @@ import duckdb
 import pytest
 from sqlalchemy import Integer, String, pool
 from sqlalchemy import exc as sa_exc
+from sqlalchemy.engine import URL as SAURL
 
 from duckdb_sqlalchemy import (
     URL,
@@ -13,14 +14,20 @@ from duckdb_sqlalchemy import (
     Dialect,
     MotherDuckURL,
     _apply_motherduck_defaults,
+    _is_idempotent_statement,
+    _is_transient_error,
     _looks_like_motherduck,
+    _normalize_execution_options,
     _normalize_motherduck_config,
+    _parse_register_params,
+    _pool_override_from_url,
     _supports,
     create_engine_from_paths,
     olap,
     stable_session_hint,
 )
 from duckdb_sqlalchemy import datatypes as dt
+from duckdb_sqlalchemy import motherduck as md
 from duckdb_sqlalchemy.config import TYPES, apply_config, get_core_config
 
 
@@ -472,3 +479,141 @@ def test_struct_or_union_requires_fields() -> None:
     assert rendered.startswith("(")
     assert rendered.endswith(")")
     assert '"first name"' in rendered
+
+
+def test_parse_register_params_dict_and_tuple() -> None:
+    view_name, df = _parse_register_params({"view_name": "v", "df": "data"})
+    assert view_name == "v"
+    assert df == "data"
+
+    view_name, df = _parse_register_params(("v2", "data2"))
+    assert view_name == "v2"
+    assert df == "data2"
+
+
+def test_parse_register_params_errors() -> None:
+    with pytest.raises(ValueError):
+        _parse_register_params(None)
+
+    with pytest.raises(ValueError):
+        _parse_register_params({"name": "v"})
+
+    with pytest.raises(ValueError):
+        _parse_register_params(("only-one",))
+
+
+def test_normalize_execution_options_insertmanyvalues() -> None:
+    original = {"duckdb_insertmanyvalues_page_size": 123}
+    normalized = _normalize_execution_options(original)
+    assert normalized["insertmanyvalues_page_size"] == 123
+    assert "insertmanyvalues_page_size" not in original
+
+    already = {
+        "duckdb_insertmanyvalues_page_size": 5,
+        "insertmanyvalues_page_size": 10,
+    }
+    normalized = _normalize_execution_options(already)
+    assert normalized["insertmanyvalues_page_size"] == 10
+
+
+def test_idempotent_statement_detection() -> None:
+    assert _is_idempotent_statement("SELECT 1")
+    assert _is_idempotent_statement("  show tables")
+    assert _is_idempotent_statement("pragma version")
+    assert not _is_idempotent_statement("insert into t values (1)")
+
+
+def test_transient_error_detection() -> None:
+    assert _is_transient_error(RuntimeError("HTTP Error: 503 Service Unavailable"))
+    assert not _is_transient_error(RuntimeError("connection reset by peer"))
+    assert not _is_transient_error(RuntimeError("HTTP Error: 503 connection reset"))
+
+
+def test_pool_override_from_url_and_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    url = URL(database=":memory:", query={"duckdb_sqlalchemy_pool": ["Queue"]})
+    assert _pool_override_from_url(url) == "queue"
+
+    monkeypatch.setenv("DUCKDB_SQLALCHEMY_POOL", "Null")
+    url = URL(database=":memory:")
+    assert _pool_override_from_url(url) == "null"
+
+
+def test_pool_class_for_empty_database() -> None:
+    url = SAURL.create("duckdb")
+    assert Dialect.get_pool_class(url) is pool.SingletonThreadPool
+
+
+def test_apply_config_handles_none_path_decimal() -> None:
+    import decimal
+    from pathlib import Path
+
+    dialect = Dialect()
+
+    class DummyConn:
+        def __init__(self) -> None:
+            self.executed = []
+
+        def execute(self, statement: str) -> None:
+            self.executed.append(statement)
+
+    conn = DummyConn()
+    ext = {
+        "memory_limit": None,
+        "data_path": Path("/tmp/data"),
+        "ratio": decimal.Decimal("1.5"),
+    }
+
+    apply_config(
+        dialect,
+        conn,
+        cast(dict[str, str | int | bool | float | None], ext),
+    )
+
+    string_processor = String().literal_processor(dialect=dialect)
+    expected = [
+        "SET memory_limit = NULL",
+        f"SET data_path = {string_processor(str(Path('/tmp/data')))}",
+        f"SET ratio = {string_processor(str(decimal.Decimal('1.5')))}",
+    ]
+    assert conn.executed == expected
+
+
+def test_motherduck_helpers() -> None:
+    url = md.MotherDuckURL(
+        database="md:db",
+        query={"memory_limit": "1GB"},
+        path_query={"user": "alice", "session_hint": "team"},
+    )
+    assert url.database.startswith("md:db?")
+    assert url.query == {"memory_limit": "1GB"}
+
+    appended = md.append_query_to_database("md:db?user=alice", {"session_hint": "s"})
+    assert appended == "md:db?user=alice&session_hint=s"
+
+    normalized = md._normalize_path_item("duckdb:///tmp.db")
+    assert normalized.drivername == "duckdb"
+
+    normalized = md._normalize_path_item("md:db")
+    assert normalized.database == "md:db"
+
+
+def test_merge_and_copy_connect_args() -> None:
+    base = {"config": {"threads": 2}, "url_config": {"memory_limit": "1GB"}}
+    extra = {"config": {"threads": 4}, "url_config": {"s3_region": "us-east-1"}}
+    merged = md._merge_connect_args(base, extra)
+
+    assert merged["config"] == {"threads": 4}
+    assert merged["url_config"] == {"memory_limit": "1GB", "s3_region": "us-east-1"}
+
+    copied = md._copy_connect_params(merged)
+    copied["config"]["threads"] = 1
+    copied["url_config"]["memory_limit"] = "2GB"
+    assert merged["config"]["threads"] == 4
+    assert merged["url_config"]["memory_limit"] == "1GB"
+
+
+def test_create_engine_from_paths_driver_mismatch() -> None:
+    url1 = SAURL.create("duckdb", database=":memory:")
+    url2 = SAURL.create("sqlite", database=":memory:")
+    with pytest.raises(ValueError):
+        create_engine_from_paths([url1, url2])

{duckdb_sqlalchemy-0.19.1.dist-info → duckdb_sqlalchemy-0.19.3.dist-info}/METADATA

@@ -1,14 +1,29 @@
 Metadata-Version: 2.4
 Name: duckdb-sqlalchemy
-Version: 0.19.1
-Summary: SQLAlchemy driver for duckdb
+Version: 0.19.3
+Summary: DuckDB SQLAlchemy dialect for DuckDB and MotherDuck
 Project-URL: Bug Tracker, https://github.com/leonardovida/duckdb-sqlalchemy/issues
 Project-URL: Changelog, https://github.com/leonardovida/duckdb-sqlalchemy/releases
+Project-URL: Documentation, https://leonardovida.github.io/duckdb-sqlalchemy/
 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>
+Author-email: Leonardo Vida <lleonardovida@gmail.com>
 License-Expression: MIT
 License-File: LICENSE.txt
+Keywords: analytics,database,dialect,duckdb,motherduck,olap,sqlalchemy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
 Requires-Python: <4,>=3.9
 Requires-Dist: duckdb>=0.5.0
 Requires-Dist: packaging>=21
@@ -41,16 +56,16 @@ Description-Content-Type: text/markdown
 [![PyPI Downloads](https://img.shields.io/pypi/dm/duckdb-sqlalchemy.svg)](https://pypi.org/project/duckdb-sqlalchemy/)
 [![codecov](https://codecov.io/gh/leonardovida/duckdb-sqlalchemy/graph/badge.svg)](https://codecov.io/gh/leonardovida/duckdb-sqlalchemy)
 
-The production-grade SQLAlchemy dialect for DuckDB and MotherDuck. Use the full SQLAlchemy Core and ORM APIs with DuckDB's analytical engine, locally or in the cloud via MotherDuck.
+duckdb-sqlalchemy is a DuckDB SQLAlchemy dialect for DuckDB and MotherDuck. It supports SQLAlchemy Core and ORM APIs for local DuckDB and MotherDuck connections.
 
-This dialect handles connection pooling, bulk inserts, type mappings, and cloud-specific configuration so you can focus on queries instead of driver quirks.
+The dialect handles pooling defaults, bulk inserts, type mappings, and cloud-specific configuration.
 
 ## Why this dialect
 
-- **Full SQLAlchemy compatibility**: Core, ORM, Alembic migrations, and reflection work out of the box.
-- **MotherDuck support**: Automatic token handling, attach modes, session hints, and read scaling helpers.
-- **Production defaults**: Sensible pooling, transient retry for reads, and bulk insert optimization via Arrow/DataFrame registration.
-- **Actively maintained**: Tracks current DuckDB releases with long-term support commitment.
+- **SQLAlchemy compatibility**: Core, ORM, Alembic, and reflection.
+- **MotherDuck support**: Token handling, attach modes, session hints, and read scaling helpers.
+- **Operational defaults**: Pooling defaults, transient retry for reads, and bulk insert optimization via Arrow/DataFrame registration.
+- **Maintained**: Tracks current DuckDB releases with a long-term support posture.
 
 ## Compatibility
 
@@ -127,19 +142,23 @@ Use the URL helpers to build connection strings safely:
 ```python
 from duckdb_sqlalchemy import URL, MotherDuckURL
 
-local_url = URL(database=":memory:", read_only=False)
+local_url = URL(database=":memory:", memory_limit="1GB")
 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`.
+This dialect defaults to `NullPool` for file/MotherDuck connections and `SingletonThreadPool` for `:memory:`. You can override pooling explicitly. For long-lived MotherDuck pools, use the performance helper or configure `QueuePool`, `pool_pre_ping`, and `pool_recycle`.
 
 See `docs/configuration.md` and `docs/motherduck.md` for detailed guidance.
 
 ## Documentation
 
+- `docs/index.md` - GitHub Pages entrypoint
 - `docs/README.md` - Docs index
+- `docs/overview.md` - Overview and quick start
+- `docs/getting-started.md` - Minimal install + setup walkthrough
+- `docs/migration-from-duckdb-engine.md` - Migration guide from older dialects
 - `docs/connection-urls.md` - URL formats and helpers
 - `docs/motherduck.md` - MotherDuck setup and options
 - `docs/configuration.md` - Connection configuration, extensions, filesystems
@@ -148,6 +167,12 @@ See `docs/configuration.md` and `docs/motherduck.md` for detailed guidance.
 - `docs/types-and-caveats.md` - Type support and known caveats
 - `docs/alembic.md` - Alembic integration
 
+Docs site (GitHub Pages):
+
+```
+https://leonardovida.github.io/duckdb-sqlalchemy/
+```
+
 ## Examples
 
 - `examples/sqlalchemy_example.py` - end-to-end example
@@ -159,10 +184,10 @@ See `docs/configuration.md` and `docs/motherduck.md` for detailed guidance.
 
 ## 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.
+- Long-term maintenance: intended to remain supported.
+- Compatibility: 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.
+- Security: open an issue with details; fixes are prioritized.
 
 ## Changelog and roadmap
 

{duckdb_sqlalchemy-0.19.1.dist-info → duckdb_sqlalchemy-0.19.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-duckdb_sqlalchemy/__init__.py,sha256=78p0lVyEZVA_Zl9xnSmJx-00qRPX2G867Grqcs8hc24,49824
+duckdb_sqlalchemy/__init__.py,sha256=jQTzFo4TvnZJOS2-dU60hQsfK68iBSkQuf00_hkEnI8,49992
 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
@@ -13,7 +13,7 @@ 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_core_units.py,sha256=rcG48lCNCB-qMXxDoUZSWQ5RjDpW8QvoMj9v_74-88A,18584
 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
@@ -24,8 +24,8 @@ duckdb_sqlalchemy/tests/util.py,sha256=YHTtB19mxQO--nq1tCnQELcKL_Qh73T9mvdnH6rVl
 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.1.dist-info/METADATA,sha256=U4WaQ-EvMa7ua2iRLIXD8bI1ZanrrfvQWosyocSYpUs,6740
-duckdb_sqlalchemy-0.19.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-duckdb_sqlalchemy-0.19.1.dist-info/entry_points.txt,sha256=MyXbmaqEhyBLIL2NnHrweY6EJ_Rke2HnVZR1wCz08cM,57
-duckdb_sqlalchemy-0.19.1.dist-info/licenses/LICENSE.txt,sha256=nhRQcy_ZV2R-xzl3MPltQuQ53bcURavT0N6mC3VdDE8,1076
-duckdb_sqlalchemy-0.19.1.dist-info/RECORD,,
+duckdb_sqlalchemy-0.19.3.dist-info/METADATA,sha256=SSjKpjGqQV1FqjqEOSXlH9UMQj1-B4FQH-88KwlLJ48,7680
+duckdb_sqlalchemy-0.19.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+duckdb_sqlalchemy-0.19.3.dist-info/entry_points.txt,sha256=MyXbmaqEhyBLIL2NnHrweY6EJ_Rke2HnVZR1wCz08cM,57
+duckdb_sqlalchemy-0.19.3.dist-info/licenses/LICENSE.txt,sha256=nhRQcy_ZV2R-xzl3MPltQuQ53bcURavT0N6mC3VdDE8,1076
+duckdb_sqlalchemy-0.19.3.dist-info/RECORD,,