sqlalchemy-cloudflare-d1 0.3.10__tar.gz → 0.4.0__tar.gz

{sqlalchemy_cloudflare_d1-0.3.10 → sqlalchemy_cloudflare_d1-0.4.0}/.github/workflows/release.yml

@@ -62,7 +62,13 @@ jobs:
         run: |
           set -eu
           pkg_name=$(grep '^name = ' pyproject.toml | sed 's/name = "\(.*\)"/\1/')
-          version=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          # The version is dynamic: hatchling reads __version__ from the
+          # package, so there is no `version = ` line in pyproject to grep.
+          version=$(uv run python -c "import sqlalchemy_cloudflare_d1; print(sqlalchemy_cloudflare_d1.__version__)")
+          if [ -z "$version" ]; then
+            echo "::error::could not determine package version" >&2
+            exit 1
+          fi
           echo "pkg-name=$pkg_name" >> $GITHUB_OUTPUT
           echo "version=$version" >> $GITHUB_OUTPUT
 
@@ -89,7 +95,8 @@ jobs:
           path: dist/
 
       - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc
+        # v1.14.2 - bundles twine 7.0.0, which understands Metadata-Version 2.5
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33
         with:
           packages-dir: dist/
           verbose: true

{sqlalchemy_cloudflare_d1-0.3.10 → sqlalchemy_cloudflare_d1-0.4.0}/.gitignore

@@ -214,3 +214,6 @@ testing/
 node_modules/
 python_modules/
 .DS_Store
+
+# pywrangler generated lock for Worker examples
+pylock.toml

{sqlalchemy_cloudflare_d1-0.3.10 → sqlalchemy_cloudflare_d1-0.4.0}/CHANGELOG.md

@@ -13,6 +13,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 
+## [0.4.0]
+
+### Added
+
+- Cloudflare Hyperdrive support for Python Workers
+  - `create_engine_from_hyperdrive()` builds a SQLAlchemy engine from a Hyperdrive binding, deriving the URL from the binding's connection fields
+  - `hyperdrive_connection()` yields a connection while holding an isolate-wide `asyncio.Lock`, since concurrent synchronous driver I/O is unsupported in Workers
+  - Driver is auto-detected from the binding's `scheme`, falling back to `connectionString`, and can be overridden with `driver=`
+  - Engines use `NullPool`: a Worker cannot reuse sockets across requests, and Hyperdrive pools server-side
+  - New `[hyperdrive]` extra installing `pg8000`, and `[hyperdrive-mysql]` installing `pymysql`, kept separate so a PostgreSQL deployment does not carry a MySQL driver
+  - A missing driver raises an error naming the extra that provides it, rather than a bare import error from inside SQLAlchemy
+  - `examples/workers-hyperdrive/` example Worker, verified both locally and deployed against a live Hyperdrive config
+- 6 Worker integration tests and 22 unit tests covering the Hyperdrive path
+
+### Notes
+
+- No custom dialect is involved. Hyperdrive speaks the PostgreSQL and MySQL wire protocols, so SQLAlchemy's own `postgresql+pg8000` and `mysql+pymysql` do the work; this package supplies only the binding-to-engine glue.
+- PostgreSQL via `pg8000` is the supported path. MySQL via `pymysql` is best effort — verified manually against MySQL 8, but with no automated coverage.
+- `psycopg` is not supported: psycopg3 requires libpq, which the Workers Pyodide build does not provide.
+- `asyncpg` and `aiomysql` cannot be used despite being Cloudflare's recommended drivers. They are async-only, and driving them from SQLAlchemy requires greenlet, which is unavailable in Python Workers. Only synchronous SQLAlchemy works.
+
+### Fixed
+
+- `__version__` in `sqlalchemy_cloudflare_d1` was stale at `0.3.1` while the package version had moved on; it now tracks the released version
+- The Hyperdrive I/O lock is created per event loop rather than at import. On Python 3.9 `asyncio.Lock()` binds to whichever loop is current when constructed, so a module-level lock raised "attached to a different loop" under any other loop
+
+
+## [0.3.11]
+
+### Added
+
+- Added REST API and Worker integration coverage for composite primary key DDL and constraint reflection
+
+### Fixed
+
+- Fixed composite primary key DDL emitting duplicate `PRIMARY KEY` clauses, which D1 rejects with `SQLITE_ERROR`
+- Fixed foreign key reflection to include SQLAlchemy's expected `referred_schema` key
+- Implemented unique constraint reflection for D1 tables, including inline and named table-level unique constraints
+
+
 ## [0.3.10]
 
 ### Added

{sqlalchemy_cloudflare_d1-0.3.10 → sqlalchemy_cloudflare_d1-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: sqlalchemy-cloudflare-d1
-Version: 0.3.10
+Version: 0.4.0
 Summary: A SQLAlchemy dialect for Cloudflare's D1 Serverless SQLite Database
 Project-URL: Homepage, https://github.com/collierking/sqlalchemy-cloudflare-d1
 Project-URL: Repository, https://github.com/collierking/sqlalchemy-cloudflare-d1
@@ -53,6 +53,10 @@ Requires-Dist: mypy>=1.0.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: ruff==0.12.4; extra == 'dev'
+Provides-Extra: hyperdrive
+Requires-Dist: pg8000>=1.30.0; extra == 'hyperdrive'
+Provides-Extra: hyperdrive-mysql
+Requires-Dist: pymysql>=1.1.0; extra == 'hyperdrive-mysql'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -70,6 +74,7 @@ A SQLAlchemy dialect for [Cloudflare's D1 Serverless SQLite Database](https://de
 - Full SQLAlchemy ORM and Core support
 - **Sync and async engines** via D1 REST API (`create_engine` and `create_async_engine`)
 - **Python Workers support** with direct D1 binding (`create_engine_from_binding`)
+- **Cloudflare Hyperdrive support** for PostgreSQL/MySQL in Workers (`create_engine_from_hyperdrive`)
 - SQLite/D1 compatible SQL compilation
 - Prepared statement support with parameter binding
 - pandas `DataFrame.to_sql()` with upsert support
@@ -408,6 +413,74 @@ engine = create_engine(
 )
 ```
 
+## Cloudflare Hyperdrive
+
+Hyperdrive fronts an existing PostgreSQL or MySQL database. It needs no custom
+dialect — SQLAlchemy's own `postgresql+pg8000` speaks the wire protocol — so
+this package supplies only the binding-to-engine glue for Python Workers.
+
+```bash
+pip install sqlalchemy-cloudflare-d1[hyperdrive]         # PostgreSQL (pg8000)
+pip install sqlalchemy-cloudflare-d1[hyperdrive-mysql]   # MySQL (pymysql)
+```
+
+The extras are separate so a PostgreSQL deployment does not carry a MySQL
+driver. Install the one matching your Hyperdrive origin — the driver must also
+be declared in your Worker's `pyproject.toml` dependencies.
+
+```python
+from sqlalchemy import MetaData, Table, select
+from sqlalchemy_cloudflare_d1.hyperdrive import (
+    create_engine_from_hyperdrive,
+    hyperdrive_connection,
+)
+
+class Default(WorkerEntrypoint):
+    async def fetch(self, request):
+        engine = create_engine_from_hyperdrive(self.env.HYPERDRIVE)
+
+        metadata = MetaData()
+        users = Table("users", metadata, autoload_with=engine)
+
+        async with hyperdrive_connection(engine) as conn:
+            rows = conn.execute(select(users).limit(10)).fetchall()
+```
+
+The driver is chosen from the binding's scheme and can be overridden with
+`driver=`. The engine uses `NullPool`, since a Worker cannot reuse sockets
+across requests and Hyperdrive pools server-side. `hyperdrive_connection()`
+holds an isolate-wide `asyncio.Lock`, because concurrent synchronous driver
+I/O is not supported.
+
+### Driver support
+
+Cloudflare documents five drivers as working in Python Workers. Only two can
+back a SQLAlchemy engine — verified from inside a Worker:
+
+| Driver | Status | Notes |
+|---|---|---|
+| `pg8000` | ✅ Supported | PostgreSQL. Covered by integration tests running in a Worker |
+| `pymysql` | ⚠️ Best effort | MySQL. Confirmed working in a Worker against MySQL 8, but that check was manual — there is **no automated test coverage**, so nothing guards against a regression |
+| `psycopg` | ❌ | Needs libpq, and the Workers Pyodide build has none (`no pq wrapper available`) |
+| `asyncpg` | ❌ | Async-only — see below |
+| `aiomysql` | ❌ | Async-only — see below |
+
+PostgreSQL via `pg8000` is the supported path. MySQL works but is not exercised
+by CI, so treat it as best effort.
+
+**Only synchronous SQLAlchemy works.** `asyncpg` and `aiomysql` run fine in
+Python Workers on their own — that is why Cloudflare recommends them — but
+driving them from SQLAlchemy means `create_async_engine()`, which requires
+greenlet, and greenlet is unavailable in Workers. So the two recommended
+drivers are precisely the two that cannot back a SQLAlchemy engine.
+
+Both supported drivers need TLS explicitly switched off, which
+`create_engine_from_hyperdrive()` handles: pg8000 gets `ssl_context=False` and
+pymysql gets `ssl_disabled=True`. Hyperdrive terminates TLS itself, and
+attempting it from inside a Worker corrupts the connection.
+
+See `examples/workers-hyperdrive/` for a complete Worker.
+
 ## Limitations
 
 This dialect has some limitations due to D1's REST API nature:

{sqlalchemy_cloudflare_d1-0.3.10 → sqlalchemy_cloudflare_d1-0.4.0}/README.md

@@ -13,6 +13,7 @@ A SQLAlchemy dialect for [Cloudflare's D1 Serverless SQLite Database](https://de
 - Full SQLAlchemy ORM and Core support
 - **Sync and async engines** via D1 REST API (`create_engine` and `create_async_engine`)
 - **Python Workers support** with direct D1 binding (`create_engine_from_binding`)
+- **Cloudflare Hyperdrive support** for PostgreSQL/MySQL in Workers (`create_engine_from_hyperdrive`)
 - SQLite/D1 compatible SQL compilation
 - Prepared statement support with parameter binding
 - pandas `DataFrame.to_sql()` with upsert support
@@ -351,6 +352,74 @@ engine = create_engine(
 )
 ```
 
+## Cloudflare Hyperdrive
+
+Hyperdrive fronts an existing PostgreSQL or MySQL database. It needs no custom
+dialect — SQLAlchemy's own `postgresql+pg8000` speaks the wire protocol — so
+this package supplies only the binding-to-engine glue for Python Workers.
+
+```bash
+pip install sqlalchemy-cloudflare-d1[hyperdrive]         # PostgreSQL (pg8000)
+pip install sqlalchemy-cloudflare-d1[hyperdrive-mysql]   # MySQL (pymysql)
+```
+
+The extras are separate so a PostgreSQL deployment does not carry a MySQL
+driver. Install the one matching your Hyperdrive origin — the driver must also
+be declared in your Worker's `pyproject.toml` dependencies.
+
+```python
+from sqlalchemy import MetaData, Table, select
+from sqlalchemy_cloudflare_d1.hyperdrive import (
+    create_engine_from_hyperdrive,
+    hyperdrive_connection,
+)
+
+class Default(WorkerEntrypoint):
+    async def fetch(self, request):
+        engine = create_engine_from_hyperdrive(self.env.HYPERDRIVE)
+
+        metadata = MetaData()
+        users = Table("users", metadata, autoload_with=engine)
+
+        async with hyperdrive_connection(engine) as conn:
+            rows = conn.execute(select(users).limit(10)).fetchall()
+```
+
+The driver is chosen from the binding's scheme and can be overridden with
+`driver=`. The engine uses `NullPool`, since a Worker cannot reuse sockets
+across requests and Hyperdrive pools server-side. `hyperdrive_connection()`
+holds an isolate-wide `asyncio.Lock`, because concurrent synchronous driver
+I/O is not supported.
+
+### Driver support
+
+Cloudflare documents five drivers as working in Python Workers. Only two can
+back a SQLAlchemy engine — verified from inside a Worker:
+
+| Driver | Status | Notes |
+|---|---|---|
+| `pg8000` | ✅ Supported | PostgreSQL. Covered by integration tests running in a Worker |
+| `pymysql` | ⚠️ Best effort | MySQL. Confirmed working in a Worker against MySQL 8, but that check was manual — there is **no automated test coverage**, so nothing guards against a regression |
+| `psycopg` | ❌ | Needs libpq, and the Workers Pyodide build has none (`no pq wrapper available`) |
+| `asyncpg` | ❌ | Async-only — see below |
+| `aiomysql` | ❌ | Async-only — see below |
+
+PostgreSQL via `pg8000` is the supported path. MySQL works but is not exercised
+by CI, so treat it as best effort.
+
+**Only synchronous SQLAlchemy works.** `asyncpg` and `aiomysql` run fine in
+Python Workers on their own — that is why Cloudflare recommends them — but
+driving them from SQLAlchemy means `create_async_engine()`, which requires
+greenlet, and greenlet is unavailable in Workers. So the two recommended
+drivers are precisely the two that cannot back a SQLAlchemy engine.
+
+Both supported drivers need TLS explicitly switched off, which
+`create_engine_from_hyperdrive()` handles: pg8000 gets `ssl_context=False` and
+pymysql gets `ssl_disabled=True`. Hyperdrive terminates TLS itself, and
+attempting it from inside a Worker corrupts the connection.
+
+See `examples/workers-hyperdrive/` for a complete Worker.
+
 ## Limitations
 
 This dialect has some limitations due to D1's REST API nature:

{sqlalchemy_cloudflare_d1-0.3.10 → sqlalchemy_cloudflare_d1-0.4.0}/examples/workers/src/entry.py

@@ -41,8 +41,12 @@ class Default(WorkerEntrypoint):
             return await self.test_sqlalchemy_select()
         elif path == "sqlalchemy-crud":
             return await self.test_sqlalchemy_crud()
+        elif path == "sqlalchemy-composite-pk":
+            return await self.test_sqlalchemy_composite_pk()
         elif path == "sqlalchemy-reflect":
             return await self.test_sqlalchemy_reflect()
+        elif path == "sqlalchemy-reflect-constraints":
+            return await self.test_sqlalchemy_reflect_constraints()
         # Empty result set tests (GitHub issue #4)
         elif path == "empty-result":
             return await self.test_empty_result()
@@ -188,7 +192,9 @@ class Default(WorkerEntrypoint):
                 "/parameterized": "Test parameterized queries",
                 "/sqlalchemy-select": "Test SQLAlchemy Core SELECT (no raw SQL)",
                 "/sqlalchemy-crud": "Test SQLAlchemy Core CRUD (no raw SQL)",
+                "/sqlalchemy-composite-pk": "Test SQLAlchemy composite primary key DDL",
                 "/sqlalchemy-reflect": "Test SQLAlchemy table reflection",
+                "/sqlalchemy-reflect-constraints": "Test SQLAlchemy constraint reflection",
                 "/empty-result": "Test empty result set description (issue #4)",
                 "/empty-result-sqlalchemy": "Test SQLAlchemy empty result (issue #4)",
                 "/json-filter": "Test filtering on JSON array columns",
@@ -548,6 +554,76 @@ class Default(WorkerEntrypoint):
                 status=500,
             )
 
+    async def test_sqlalchemy_composite_pk(self):
+        """Test SQLAlchemy composite primary key DDL against D1 binding."""
+        from sqlalchemy import Column, MetaData, String, Table, select
+
+        table_name = f"test_composite_pk_{uuid.uuid4().hex[:8]}"
+
+        try:
+            engine = self.get_engine()
+            metadata = MetaData()
+
+            test_table = Table(
+                table_name,
+                metadata,
+                Column("tenant_id", String, primary_key=True),
+                Column("record_key", String, primary_key=True),
+                Column("value", String),
+            )
+
+            metadata.create_all(engine)
+
+            with engine.connect() as conn:
+                conn.execute(
+                    test_table.insert().values(
+                        tenant_id="tenant_a",
+                        record_key="label_a",
+                        value="value_a",
+                    )
+                )
+                conn.commit()
+
+                result = conn.execute(
+                    select(
+                        test_table.c.tenant_id,
+                        test_table.c.record_key,
+                        test_table.c.value,
+                    )
+                )
+                row = result.fetchone()
+                columns = list(result.keys())
+
+            metadata.drop_all(engine)
+
+            success = row is not None and tuple(row) == (
+                "tenant_a",
+                "label_a",
+                "value_a",
+            )
+
+            return Response.json(
+                {
+                    "test": "sqlalchemy_composite_pk",
+                    "success": success,
+                    "table_name": table_name,
+                    "columns": columns,
+                    "row": list(row) if row is not None else None,
+                }
+            )
+        except Exception as e:
+            try:
+                engine = self.get_engine()
+                metadata = MetaData()
+                test_table = Table(table_name, metadata)
+                metadata.drop_all(engine)
+            except Exception:
+                pass
+            return Response.json(
+                {"test": "sqlalchemy_composite_pk", "success": False, "error": str(e)},
+                status=500,
+            )
+
     async def test_sqlalchemy_reflect(self):
         """Test SQLAlchemy table reflection.
 
@@ -628,6 +704,100 @@ class Default(WorkerEntrypoint):
                 status=500,
             )
 
+    async def test_sqlalchemy_reflect_constraints(self):
+        """Test SQLAlchemy foreign key and unique constraint reflection."""
+        parent_table_name = f"test_reflect_parent_{uuid.uuid4().hex[:8]}"
+        child_table_name = f"test_reflect_child_{uuid.uuid4().hex[:8]}"
+        unique_constraint_name = f"uq_{uuid.uuid4().hex[:12]}"
+
+        try:
+            from sqlalchemy import (
+                Column,
+                ForeignKey,
+                Integer,
+                MetaData,
+                String,
+                Table,
+                UniqueConstraint,
+                inspect,
+            )
+
+            engine = self.get_engine()
+            metadata = MetaData()
+
+            Table(
+                parent_table_name,
+                metadata,
+                Column("id", Integer, primary_key=True),
+                Column("slug", String, unique=True),
+            )
+            Table(
+                child_table_name,
+                metadata,
+                Column("id", Integer, primary_key=True),
+                Column("parent_id", Integer, ForeignKey(f"{parent_table_name}.id")),
+                Column("tenant_id", String),
+                Column("record_key", String),
+                UniqueConstraint(
+                    "tenant_id",
+                    "record_key",
+                    name=unique_constraint_name,
+                ),
+            )
+
+            metadata.create_all(engine)
+
+            inspector = inspect(engine)
+            foreign_keys = inspector.get_foreign_keys(child_table_name)
+            unique_constraints = inspector.get_unique_constraints(child_table_name)
+            parent_unique_constraints = inspector.get_unique_constraints(
+                parent_table_name
+            )
+
+            metadata.drop_all(engine)
+
+            expected_child_unique = {
+                "name": unique_constraint_name,
+                "column_names": ["tenant_id", "record_key"],
+            }
+            expected_parent_unique = {"name": None, "column_names": ["slug"]}
+            foreign_key = foreign_keys[0] if foreign_keys else {}
+            success = (
+                foreign_key.get("constrained_columns") == ["parent_id"]
+                and foreign_key.get("referred_schema") is None
+                and foreign_key.get("referred_table") == parent_table_name
+                and foreign_key.get("referred_columns") == ["id"]
+                and expected_child_unique in unique_constraints
+                and expected_parent_unique in parent_unique_constraints
+            )
+
+            return Response.json(
+                {
+                    "test": "sqlalchemy_reflect_constraints",
+                    "success": success,
+                    "foreign_keys": foreign_keys,
+                    "unique_constraints": unique_constraints,
+                    "parent_unique_constraints": parent_unique_constraints,
+                }
+            )
+        except Exception as e:
+            try:
+                conn = self.get_connection()
+                cursor = conn.cursor()
+                await cursor.execute_async(f"DROP TABLE IF EXISTS {child_table_name}")
+                await cursor.execute_async(f"DROP TABLE IF EXISTS {parent_table_name}")
+                conn.close()
+            except Exception:
+                pass
+            return Response.json(
+                {
+                    "test": "sqlalchemy_reflect_constraints",
+                    "success": False,
+                    "error": str(e),
+                },
+                status=500,
+            )
+
     # MARK: - Empty Result Set Tests (GitHub issue #4)
 
     async def test_empty_result(self):

{sqlalchemy_cloudflare_d1-0.3.10 → sqlalchemy_cloudflare_d1-0.4.0}/examples/workers/uv.lock

@@ -115,7 +115,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f8/0a/a3871375c7b9727edaeeea994bfff7c63ff7804c9829c19309ba2e058807/greenlet-3.3.0-cp312-cp312-macosx_11_0_universal2.whl", hash = "sha256:b01548f6e0b9e9784a2c99c5651e5dc89ffcbe870bc5fb2e5ef864e9cc6b5dcb", size = 276379, upload-time = "2025-12-04T14:23:30.498Z" },
     { url = "https://files.pythonhosted.org/packages/43/ab/7ebfe34dce8b87be0d11dae91acbf76f7b8246bf9d6b319c741f99fa59c6/greenlet-3.3.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:349345b770dc88f81506c6861d22a6ccd422207829d2c854ae2af8025af303e3", size = 597294, upload-time = "2025-12-04T14:50:06.847Z" },
     { url = "https://files.pythonhosted.org/packages/a4/39/f1c8da50024feecd0793dbd5e08f526809b8ab5609224a2da40aad3a7641/greenlet-3.3.0-cp312-cp312-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e8e18ed6995e9e2c0b4ed264d2cf89260ab3ac7e13555b8032b25a74c6d18655", size = 607742, upload-time = "2025-12-04T14:57:42.349Z" },
-    { url = "https://files.pythonhosted.org/packages/77/cb/43692bcd5f7a0da6ec0ec6d58ee7cddb606d055ce94a62ac9b1aa481e969/greenlet-3.3.0-cp312-cp312-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c024b1e5696626890038e34f76140ed1daf858e37496d33f2af57f06189e70d7", size = 622297, upload-time = "2025-12-04T15:07:13.552Z" },
     { url = "https://files.pythonhosted.org/packages/75/b0/6bde0b1011a60782108c01de5913c588cf51a839174538d266de15e4bf4d/greenlet-3.3.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:047ab3df20ede6a57c35c14bf5200fcf04039d50f908270d3f9a7a82064f543b", size = 609885, upload-time = "2025-12-04T14:26:02.368Z" },
     { url = "https://files.pythonhosted.org/packages/49/0e/49b46ac39f931f59f987b7cd9f34bfec8ef81d2a1e6e00682f55be5de9f4/greenlet-3.3.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:2d9ad37fc657b1102ec880e637cccf20191581f75c64087a549e66c57e1ceb53", size = 1567424, upload-time = "2025-12-04T15:04:23.757Z" },
     { url = "https://files.pythonhosted.org/packages/05/f5/49a9ac2dff7f10091935def9165c90236d8f175afb27cbed38fb1d61ab6b/greenlet-3.3.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:83cd0e36932e0e7f36a64b732a6f60c2fc2df28c351bae79fbaf4f8092fe7614", size = 1636017, upload-time = "2025-12-04T14:27:29.688Z" },
@@ -123,7 +122,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/02/2f/28592176381b9ab2cafa12829ba7b472d177f3acc35d8fbcf3673d966fff/greenlet-3.3.0-cp313-cp313-macosx_11_0_universal2.whl", hash = "sha256:a1e41a81c7e2825822f4e068c48cb2196002362619e2d70b148f20a831c00739", size = 275140, upload-time = "2025-12-04T14:23:01.282Z" },
     { url = "https://files.pythonhosted.org/packages/2c/80/fbe937bf81e9fca98c981fe499e59a3f45df2a04da0baa5c2be0dca0d329/greenlet-3.3.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9f515a47d02da4d30caaa85b69474cec77b7929b2e936ff7fb853d42f4bf8808", size = 599219, upload-time = "2025-12-04T14:50:08.309Z" },
     { url = "https://files.pythonhosted.org/packages/c2/ff/7c985128f0514271b8268476af89aee6866df5eec04ac17dcfbc676213df/greenlet-3.3.0-cp313-cp313-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7d2d9fd66bfadf230b385fdc90426fcd6eb64db54b40c495b72ac0feb5766c54", size = 610211, upload-time = "2025-12-04T14:57:43.968Z" },
-    { url = "https://files.pythonhosted.org/packages/79/07/c47a82d881319ec18a4510bb30463ed6891f2ad2c1901ed5ec23d3de351f/greenlet-3.3.0-cp313-cp313-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:30a6e28487a790417d036088b3bcb3f3ac7d8babaa7d0139edbaddebf3af9492", size = 624311, upload-time = "2025-12-04T15:07:14.697Z" },
     { url = "https://files.pythonhosted.org/packages/fd/8e/424b8c6e78bd9837d14ff7df01a9829fc883ba2ab4ea787d4f848435f23f/greenlet-3.3.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:087ea5e004437321508a8d6f20efc4cfec5e3c30118e1417ea96ed1d93950527", size = 612833, upload-time = "2025-12-04T14:26:03.669Z" },
     { url = "https://files.pythonhosted.org/packages/b5/ba/56699ff9b7c76ca12f1cdc27a886d0f81f2189c3455ff9f65246780f713d/greenlet-3.3.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ab97cf74045343f6c60a39913fa59710e4bd26a536ce7ab2397adf8b27e67c39", size = 1567256, upload-time = "2025-12-04T15:04:25.276Z" },
     { url = "https://files.pythonhosted.org/packages/1e/37/f31136132967982d698c71a281a8901daf1a8fbab935dce7c0cf15f942cc/greenlet-3.3.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:5375d2e23184629112ca1ea89a53389dddbffcf417dad40125713d88eb5f96e8", size = 1636483, upload-time = "2025-12-04T14:27:30.804Z" },
@@ -131,7 +129,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d7/7c/f0a6d0ede2c7bf092d00bc83ad5bafb7e6ec9b4aab2fbdfa6f134dc73327/greenlet-3.3.0-cp314-cp314-macosx_11_0_universal2.whl", hash = "sha256:60c2ef0f578afb3c8d92ea07ad327f9a062547137afe91f38408f08aacab667f", size = 275671, upload-time = "2025-12-04T14:23:05.267Z" },
     { url = "https://files.pythonhosted.org/packages/44/06/dac639ae1a50f5969d82d2e3dd9767d30d6dbdbab0e1a54010c8fe90263c/greenlet-3.3.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0a5d554d0712ba1de0a6c94c640f7aeba3f85b3a6e1f2899c11c2c0428da9365", size = 646360, upload-time = "2025-12-04T14:50:10.026Z" },
     { url = "https://files.pythonhosted.org/packages/e0/94/0fb76fe6c5369fba9bf98529ada6f4c3a1adf19e406a47332245ef0eb357/greenlet-3.3.0-cp314-cp314-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:3a898b1e9c5f7307ebbde4102908e6cbfcb9ea16284a3abe15cab996bee8b9b3", size = 658160, upload-time = "2025-12-04T14:57:45.41Z" },
-    { url = "https://files.pythonhosted.org/packages/93/79/d2c70cae6e823fac36c3bbc9077962105052b7ef81db2f01ec3b9bf17e2b/greenlet-3.3.0-cp314-cp314-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:dcd2bdbd444ff340e8d6bdf54d2f206ccddbb3ccfdcd3c25bf4afaa7b8f0cf45", size = 671388, upload-time = "2025-12-04T15:07:15.789Z" },
     { url = "https://files.pythonhosted.org/packages/b8/14/bab308fc2c1b5228c3224ec2bf928ce2e4d21d8046c161e44a2012b5203e/greenlet-3.3.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5773edda4dc00e173820722711d043799d3adb4f01731f40619e07ea2750b955", size = 660166, upload-time = "2025-12-04T14:26:05.099Z" },
     { url = "https://files.pythonhosted.org/packages/4b/d2/91465d39164eaa0085177f61983d80ffe746c5a1860f009811d498e7259c/greenlet-3.3.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:ac0549373982b36d5fd5d30beb8a7a33ee541ff98d2b502714a09f1169f31b55", size = 1615193, upload-time = "2025-12-04T15:04:27.041Z" },
     { url = "https://files.pythonhosted.org/packages/42/1b/83d110a37044b92423084d52d5d5a3b3a73cafb51b547e6d7366ff62eff1/greenlet-3.3.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:d198d2d977460358c3b3a4dc844f875d1adb33817f0613f663a656f463764ccc", size = 1683653, upload-time = "2025-12-04T14:27:32.366Z" },
@@ -139,7 +136,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a0/66/bd6317bc5932accf351fc19f177ffba53712a202f9df10587da8df257c7e/greenlet-3.3.0-cp314-cp314t-macosx_11_0_universal2.whl", hash = "sha256:d6ed6f85fae6cdfdb9ce04c9bf7a08d666cfcfb914e7d006f44f840b46741931", size = 282638, upload-time = "2025-12-04T14:25:20.941Z" },
     { url = "https://files.pythonhosted.org/packages/30/cf/cc81cb030b40e738d6e69502ccbd0dd1bced0588e958f9e757945de24404/greenlet-3.3.0-cp314-cp314t-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d9125050fcf24554e69c4cacb086b87b3b55dc395a8b3ebe6487b045b2614388", size = 651145, upload-time = "2025-12-04T14:50:11.039Z" },
     { url = "https://files.pythonhosted.org/packages/9c/ea/1020037b5ecfe95ca7df8d8549959baceb8186031da83d5ecceff8b08cd2/greenlet-3.3.0-cp314-cp314t-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:87e63ccfa13c0a0f6234ed0add552af24cc67dd886731f2261e46e241608bee3", size = 654236, upload-time = "2025-12-04T14:57:47.007Z" },
-    { url = "https://files.pythonhosted.org/packages/69/cc/1e4bae2e45ca2fa55299f4e85854606a78ecc37fead20d69322f96000504/greenlet-3.3.0-cp314-cp314t-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2662433acbca297c9153a4023fe2161c8dcfdcc91f10433171cf7e7d94ba2221", size = 662506, upload-time = "2025-12-04T15:07:16.906Z" },
     { url = "https://files.pythonhosted.org/packages/57/b9/f8025d71a6085c441a7eaff0fd928bbb275a6633773667023d19179fe815/greenlet-3.3.0-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:3c6e9b9c1527a78520357de498b0e709fb9e2f49c3a513afd5a249007261911b", size = 653783, upload-time = "2025-12-04T14:26:06.225Z" },
     { url = "https://files.pythonhosted.org/packages/f6/c7/876a8c7a7485d5d6b5c6821201d542ef28be645aa024cfe1145b35c120c1/greenlet-3.3.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:286d093f95ec98fdd92fcb955003b8a3d054b4e2cab3e2707a5039e7b50520fd", size = 1614857, upload-time = "2025-12-04T15:04:28.484Z" },
     { url = "https://files.pythonhosted.org/packages/4f/dc/041be1dff9f23dac5f48a43323cd0789cb798342011c19a248d9c9335536/greenlet-3.3.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6c10513330af5b8ae16f023e8ddbfb486ab355d04467c4679c5cfe4659975dd9", size = 1676034, upload-time = "2025-12-04T14:27:33.531Z" },
@@ -614,7 +610,6 @@ wheels = [
 
 [[package]]
 name = "sqlalchemy-cloudflare-d1"
-version = "0.3.10"
 source = { editable = "../../" }
 dependencies = [
     { name = "httpx" },
@@ -629,13 +624,15 @@ requires-dist = [
     { name = "httpx", specifier = ">=0.24.0" },
     { name = "isort", marker = "extra == 'dev'", specifier = ">=5.12.0" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.0.0" },
+    { name = "pg8000", marker = "extra == 'hyperdrive'", specifier = ">=1.30.0" },
+    { name = "pymysql", marker = "extra == 'hyperdrive-mysql'", specifier = ">=1.1.0" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=7.0.0" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.21.0" },
     { name = "ruff", marker = "extra == 'dev'", specifier = "==0.12.4" },
     { name = "sqlalchemy", specifier = ">=2.0.0" },
     { name = "typing-extensions", specifier = ">=4.0.0" },
 ]
-provides-extras = ["async", "dev"]
+provides-extras = ["async", "dev", "hyperdrive", "hyperdrive-mysql"]
 
 [package.metadata.requires-dev]
 dev = [
@@ -643,6 +640,8 @@ dev = [
     { name = "greenlet", specifier = ">=3.2.3" },
     { name = "mypy", specifier = ">=1.17.0" },
     { name = "pandas", specifier = ">=2.0.0" },
+    { name = "pg8000", specifier = ">=1.31.5" },
+    { name = "pymysql", specifier = ">=1.2.3" },
     { name = "pytest", specifier = ">=8.4.1" },
     { name = "pytest-asyncio", specifier = ">=0.21.0" },
     { name = "pytest-socket", specifier = ">=0.7.0" },

sqlalchemy_cloudflare_d1-0.4.0/examples/workers-hyperdrive/README.md

@@ -0,0 +1,90 @@
+# SQLAlchemy over Hyperdrive — Python Worker example
+
+Uses SQLAlchemy Core against a PostgreSQL database through a
+[Hyperdrive](https://developers.cloudflare.com/hyperdrive/examples/python-workers/)
+binding, inside a Python Worker.
+
+Unlike the D1 example in `../workers`, no custom dialect is involved —
+Hyperdrive speaks the PostgreSQL wire protocol, so SQLAlchemy's own
+`postgresql+pg8000` dialect does the work. This package only supplies the
+binding-to-engine glue.
+
+## Requirements
+
+- `compatibility_date` of `2026-09-08` or later, plus the `python_workers` flag
+- A Hyperdrive config pointing at a reachable PostgreSQL database
+- A **synchronous** driver: `pg8000` for PostgreSQL (the supported path), or
+  `pymysql` for MySQL (best effort, no automated coverage). Of
+  the five drivers Cloudflare documents, these are the only two that can back a
+  SQLAlchemy engine — `psycopg` needs libpq (absent from the Workers Pyodide
+  build) and `asyncpg`/`aiomysql` are async-only, which SQLAlchemy cannot drive
+  without greenlet. `/drivers` re-checks this matrix against your own binding.
+
+## Setup
+
+1. Create a Hyperdrive config and put its ID in `wrangler.jsonc`:
+
+   ```bash
+   npx wrangler hyperdrive create sqlalchemy-example \
+     --connection-string="$POSTGRES_URL"
+   ```
+
+2. Sync dependencies, then copy the local package into `python_modules`:
+
+   ```bash
+   uv lock && uv sync
+   uv run pywrangler sync --force
+   mkdir -p python_modules/sqlalchemy_cloudflare_d1
+   cp ../../src/sqlalchemy_cloudflare_d1/*.py python_modules/sqlalchemy_cloudflare_d1/
+   ```
+
+   `sqlalchemy-cloudflare-d1` is deliberately absent from `pyproject.toml`.
+   pywrangler installs Worker dependencies with `--no-build`, so an editable
+   local path has no wheel to install and the sync fails outright.
+
+3. Create the table, either by running `db_init.sql` against the origin
+   database or by hitting `/setup` once the Worker is up.
+
+## Run
+
+Hyperdrive has **no local emulation**. `wrangler dev` always connects to the
+Postgres named by an environment variable, never to the real Hyperdrive config,
+and `"remote": true` is not valid on a hyperdrive binding. So local dev needs:
+
+```bash
+export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgresql://user:pass@host:5432/db?sslmode=require"
+uv run pywrangler dev --port 8788
+```
+
+The Worker still sees a normal Hyperdrive binding — wrangler proxies it through
+a local `*.hyperdrive.local` endpoint. Only a deployed Worker exercises the real
+config, including its pooling and caching.
+
+## Endpoints
+
+```bash
+curl http://localhost:8788/setup       # create table + seed rows (idempotent)
+curl http://localhost:8788/health      # open a connection, SELECT 1
+curl http://localhost:8788/driver      # report resolved dialect and pool
+curl http://localhost:8788/select      # SELECT via Table + select()
+curl http://localhost:8788/crud        # insert / update / delete round-trip
+curl http://localhost:8788/reflect     # reflect columns and primary key
+curl http://localhost:8788/concurrent  # overlapping queries, serialized
+curl http://localhost:8788/drivers     # which drivers connect from a Worker
+curl http://localhost:8788/teardown    # drop the table again
+```
+
+## Notes
+
+- **TLS must be explicitly disabled, and each driver spells it differently.**
+  pg8000 treats `ssl_context=None` as "attempt SSL" (only `False` disables it),
+  and pymysql needs `ssl_disabled=True`. Otherwise the handshake over the
+  Workers socket shim corrupts the connection — `KeyError: b'\x00'` for pg8000,
+  a `secureTransport` error for pymysql. `create_engine_from_hyperdrive()`
+  handles both. Hyperdrive terminates TLS itself, so the Worker hop needs no
+  encryption.
+- `create_engine_from_hyperdrive()` uses `NullPool`: a Worker cannot reuse
+  sockets across requests, and Hyperdrive maintains the real pool server-side.
+- Wrap database work in `hyperdrive_connection()` rather than calling
+  `engine.connect()` directly. It holds an isolate-wide `asyncio.Lock` so
+  synchronous driver I/O from overlapping requests is serialized.

sqlalchemy_cloudflare_d1-0.4.0/examples/workers-hyperdrive/db_init.sql

@@ -0,0 +1,31 @@
+-- Schema for the Hyperdrive example Worker.
+--
+-- The table is namespaced because a Hyperdrive config often points at a shared
+-- database. Nothing here drops or alters pre-existing objects.
+--
+-- Run against the PostgreSQL database that the Hyperdrive config points at:
+--   psql "$POSTGRES_URL" -f db_init.sql
+
+CREATE TABLE IF NOT EXISTS sqlalchemy_hyperdrive_example (
+    id SERIAL PRIMARY KEY,
+    name TEXT NOT NULL,
+    quantity INTEGER NOT NULL DEFAULT 0
+);
+
+INSERT INTO sqlalchemy_hyperdrive_example (name, quantity)
+SELECT 'widget', 10
+WHERE NOT EXISTS (
+    SELECT 1 FROM sqlalchemy_hyperdrive_example WHERE name = 'widget'
+);
+
+INSERT INTO sqlalchemy_hyperdrive_example (name, quantity)
+SELECT 'gadget', 5
+WHERE NOT EXISTS (
+    SELECT 1 FROM sqlalchemy_hyperdrive_example WHERE name = 'gadget'
+);
+
+INSERT INTO sqlalchemy_hyperdrive_example (name, quantity)
+SELECT 'sprocket', 0
+WHERE NOT EXISTS (
+    SELECT 1 FROM sqlalchemy_hyperdrive_example WHERE name = 'sprocket'
+);