sqlalchemy-cloudflare-d1 0.3.8__tar.gz → 0.3.9__tar.gz

{sqlalchemy_cloudflare_d1-0.3.8 → sqlalchemy_cloudflare_d1-0.3.9}/CHANGELOG.md

@@ -13,6 +13,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 
+## [0.3.9]
+
+### Added
+
+- Configurable base API URL for local D1 proxy support ([#22](https://github.com/CollierKing/sqlalchemy-cloudflare-d1/issues/22))
+  - `Connection` and `AsyncConnection` now accept a `base_url` kwarg to override the Cloudflare endpoint
+  - Falls back to the `CF_D1_BASE_URL` environment variable, then the default Cloudflare URL
+  - Works with `create_engine(..., connect_args={"base_url": "http://localhost:8787"})` for the cleanest integration
+  - Enables local development against a `wrangler dev` D1 proxy without modifying source code
+
+
 ## [0.3.8]
 
 ### Added

{sqlalchemy_cloudflare_d1-0.3.8 → sqlalchemy_cloudflare_d1-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlalchemy-cloudflare-d1
-Version: 0.3.8
+Version: 0.3.9
 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

{sqlalchemy_cloudflare_d1-0.3.8 → sqlalchemy_cloudflare_d1-0.3.9}/examples/workers/src/entry.py

@@ -145,6 +145,11 @@ class Default(WorkerEntrypoint):
             return await self.test_time_nullable()
         elif path == "time-orm":
             return await self.test_time_orm()
+        # Parallel query tests (GitHub issue #20)
+        elif path == "parallel-queries-engine":
+            return await self.test_parallel_queries_engine()
+        elif path == "parallel-queries-async":
+            return await self.test_parallel_queries_async()
         else:
             return await self.index()
 
@@ -206,6 +211,8 @@ class Default(WorkerEntrypoint):
                 "/time-basic": "Test Time column insert/retrieve",
                 "/time-nullable": "Test nullable Time columns",
                 "/time-orm": "Test Time via ORM session",
+                "/parallel-queries-engine": "Timing: create_engine_from_binding() blocks per query (sequential)",
+                "/parallel-queries-async": "Timing: WorkerConnection async is truly concurrent",
             },
             "package": "sqlalchemy-cloudflare-d1",
             "connection_type": "WorkerConnection (D1 binding)",
@@ -3634,3 +3641,126 @@ class Default(WorkerEntrypoint):
                 },
                 status=500,
             )
+
+    # MARK: - Parallel Query Tests (GitHub issue #20)
+
+    async def test_parallel_queries_engine(self):
+        """Timing test showing create_engine_from_binding() queries run concurrently.
+
+        Although SyncWorkerConnection uses pyodide.ffi.run_sync() internally,
+        run_sync() drives the JS event loop rather than truly blocking it.
+        asyncio.gather() can therefore interleave multiple D1 round-trips.
+
+        Uses N unique parameterized queries (SELECT :n) so D1 cannot cache
+        results across runs. Sequential time = N * one_query_latency.
+        If concurrent, parallel time ≈ one_query_latency.
+        """
+        import asyncio
+        import time
+        from sqlalchemy import text
+
+        N_QUERIES = 10
+
+        try:
+            engine = self.get_engine()
+
+            async def single_query(i):
+                with engine.connect() as conn:
+                    result = conn.execute(text("SELECT :n as n"), {"n": i})
+                    return result.fetchone()[0]
+
+            seq_start = time.time()
+            for i in range(N_QUERIES):
+                await single_query(i)
+            sequential_time = time.time() - seq_start
+
+            par_start = time.time()
+            results = await asyncio.gather(*[single_query(i) for i in range(N_QUERIES)])
+            parallel_time = time.time() - par_start
+
+            results_correct = results == list(range(N_QUERIES))
+            # Expect genuine speedup — parallel < 80% of sequential
+            is_concurrent = parallel_time < sequential_time * 0.8
+
+            return Response.json(
+                {
+                    "test": "parallel_queries_engine",
+                    "success": results_correct and is_concurrent,
+                    "results_correct": results_correct,
+                    "is_concurrent": is_concurrent,
+                    "sequential_time_s": round(sequential_time, 3),
+                    "parallel_time_s": round(parallel_time, 3),
+                    "n_queries": N_QUERIES,
+                }
+            )
+        except Exception as e:
+            return Response.json(
+                {
+                    "test": "parallel_queries_engine",
+                    "success": False,
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                },
+                status=500,
+            )
+
+    async def test_parallel_queries_async(self):
+        """Timing test showing WorkerConnection async queries are truly concurrent.
+
+        Instead of a CPU-bound CTE (which D1 serializes server-side regardless),
+        we run many lightweight round-trips where network latency is the bottleneck.
+        N_QUERIES simple SELECTs are fired sequentially then concurrently via
+        asyncio.gather(). If WorkerConnection truly yields to the event loop,
+        the parallel run should be faster because multiple D1 round-trips overlap.
+        """
+        import asyncio
+        import time
+
+        N_QUERIES = 10
+
+        try:
+
+            async def single_query(i):
+                conn = self.get_connection()
+                cursor = conn.cursor()
+                await cursor.execute_async("SELECT ? as n", (i,))
+                row = cursor.fetchone()
+                conn.close()
+                return row[0]
+
+            # Sequential: N_QUERIES round-trips one after another
+            seq_start = time.time()
+            for i in range(N_QUERIES):
+                await single_query(i)
+            sequential_time = time.time() - seq_start
+
+            # Parallel: all N_QUERIES in flight at once
+            par_start = time.time()
+            results = await asyncio.gather(*[single_query(i) for i in range(N_QUERIES)])
+            parallel_time = time.time() - par_start
+
+            results_correct = results == list(range(N_QUERIES))
+            # Expect genuine speedup — parallel < 80% of sequential
+            is_concurrent = parallel_time < sequential_time * 0.8
+
+            return Response.json(
+                {
+                    "test": "parallel_queries_async",
+                    "success": results_correct and is_concurrent,
+                    "results_correct": results_correct,
+                    "is_concurrent": is_concurrent,
+                    "sequential_time_s": round(sequential_time, 3),
+                    "parallel_time_s": round(parallel_time, 3),
+                    "n_queries": N_QUERIES,
+                }
+            )
+        except Exception as e:
+            return Response.json(
+                {
+                    "test": "parallel_queries_async",
+                    "success": False,
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                },
+                status=500,
+            )

{sqlalchemy_cloudflare_d1-0.3.8 → sqlalchemy_cloudflare_d1-0.3.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlalchemy-cloudflare-d1"
-version = "0.3.8"
+version = "0.3.9"
 description = "A SQLAlchemy dialect for Cloudflare's D1 Serverless SQLite Database"
 readme = "README.md"
 authors = [

{sqlalchemy_cloudflare_d1-0.3.8 → sqlalchemy_cloudflare_d1-0.3.9}/src/sqlalchemy_cloudflare_d1/connection.py

@@ -6,6 +6,7 @@ Supports two connection modes:
 2. Worker Binding - for use inside Cloudflare Python Workers (d1_binding)
 """
 
+import os
 from typing import Any, Dict, List, Optional, Sequence, Union
 
 try:
@@ -475,8 +476,14 @@ class Connection:
         self.database_id = database_id
         self.api_token = api_token
 
-        # Build the D1 REST API URL
-        self.base_url = f"https://api.cloudflare.com/client/v4/accounts/{account_id}/d1/database/{database_id}"
+        # Build the D1 REST API URL, allowing override via kwarg or CF_D1_BASE_URL env var
+        _default_base = (
+            f"https://api.cloudflare.com/client/v4/accounts/{account_id}"
+            f"/d1/database/{database_id}"
+        )
+        self.base_url = kwargs.get(
+            "base_url", os.environ.get("CF_D1_BASE_URL", _default_base)
+        )
 
         # HTTP client
         self.client = httpx.Client(
@@ -826,11 +833,14 @@ class AsyncConnection:
         self.database_id = database_id
         self.api_token = api_token
 
-        # Build the D1 REST API URL
-        self.base_url = (
+        # Build the D1 REST API URL, allowing override via kwarg or CF_D1_BASE_URL env var
+        _default_base = (
             f"https://api.cloudflare.com/client/v4/accounts/{account_id}"
             f"/d1/database/{database_id}"
         )
+        self.base_url = kwargs.get(
+            "base_url", os.environ.get("CF_D1_BASE_URL", _default_base)
+        )
 
         # Async HTTP client
         self.client = httpx.AsyncClient(

sqlalchemy_cloudflare_d1-0.3.9/tests/integration/test_base_url_integration.py

@@ -0,0 +1,175 @@
+"""Integration tests for the configurable base URL feature (Issue #22).
+
+These tests verify that CF_D1_BASE_URL and the base_url kwarg correctly
+redirect HTTP requests away from the hard-coded Cloudflare endpoint.
+
+A minimal local HTTP server mimics the D1 /raw response format so that
+no real Cloudflare credentials are required to run these tests.
+"""
+
+import json
+import os
+import threading
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from unittest.mock import patch
+
+import pytest
+from sqlalchemy import create_engine, text
+
+from sqlalchemy_cloudflare_d1.connection import Connection
+
+
+# MARK: - Local D1 Proxy Fixture
+
+
+@pytest.fixture()
+def local_d1_server():
+    """Start a local HTTP server that mimics the D1 REST API /raw endpoint.
+
+    Modelled after the local D1 proxy described in Issue #22. Responds with
+    the Cloudflare /raw response envelope so the Connection can parse it.
+    """
+
+    received_requests: list[str] = []
+
+    class _D1Handler(BaseHTTPRequestHandler):
+        def do_POST(self):
+            received_requests.append(self.path)
+            body_bytes = self.rfile.read(int(self.headers["Content-Length"]))
+            json.loads(body_bytes)  # parse but ignore — any SQL is fine
+
+            response = {
+                "success": True,
+                "result": [
+                    {
+                        "results": {
+                            "columns": ["value"],
+                            "rows": [[42]],
+                        },
+                        "meta": {},
+                        "success": True,
+                    }
+                ],
+                "errors": [],
+                "messages": [],
+            }
+            payload = json.dumps(response).encode()
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(payload)))
+            self.end_headers()
+            self.wfile.write(payload)
+
+        def log_message(self, format, *args):  # noqa: A002
+            pass  # suppress server log noise in test output
+
+    server = HTTPServer(("127.0.0.1", 0), _D1Handler)
+    port = server.server_address[1]
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    yield f"http://127.0.0.1:{port}", received_requests
+
+    server.shutdown()
+
+
+# MARK: - Base URL Override Tests
+
+
+class TestBaseUrlOverride:
+    """Verify that base_url kwarg and CF_D1_BASE_URL env var route requests
+    to a custom endpoint instead of the default Cloudflare API URL.
+    """
+
+    def test_base_url_kwarg_redirects_requests(self, local_d1_server):
+        """Connection uses base_url kwarg instead of the Cloudflare endpoint."""
+        base_url, received = local_d1_server
+        conn = Connection(
+            account_id="fake_account",
+            database_id="fake_db",
+            api_token="fake_token",
+            base_url=base_url,
+        )
+        try:
+            cur = conn.cursor()
+            cur.execute("SELECT 1 AS value")
+            row = cur.fetchone()
+            assert row == (42,)
+            assert any("/raw" in path for path in received)
+        finally:
+            conn.close()
+
+    def test_cf_d1_base_url_env_var_redirects_requests(self, local_d1_server):
+        """Connection reads CF_D1_BASE_URL from the environment and routes there."""
+        base_url, received = local_d1_server
+        with patch.dict(os.environ, {"CF_D1_BASE_URL": base_url}):
+            conn = Connection(
+                account_id="fake_account",
+                database_id="fake_db",
+                api_token="fake_token",
+            )
+            try:
+                cur = conn.cursor()
+                cur.execute("SELECT 1 AS value")
+                row = cur.fetchone()
+                assert row == (42,)
+                assert any("/raw" in path for path in received)
+            finally:
+                conn.close()
+
+    def test_sqlalchemy_engine_with_connect_args(self, local_d1_server):
+        """Engine built with connect_args={'base_url': ...} routes to the local server."""
+        base_url, received = local_d1_server
+        engine = create_engine(
+            "cloudflare_d1://fake_account:fake_token@fake_db",
+            connect_args={"base_url": base_url},
+        )
+        try:
+            with engine.connect() as conn:
+                result = conn.execute(text("SELECT 1 AS value"))
+                row = result.fetchone()
+            assert row == (42,)
+            assert any("/raw" in path for path in received)
+        finally:
+            engine.dispose()
+
+    def test_sqlalchemy_engine_with_base_url_query_param(self, local_d1_server):
+        """Engine built from a URL with ?base_url= routes requests to the local server."""
+        base_url, received = local_d1_server
+        encoded = urllib.parse.quote(base_url, safe="")
+        engine = create_engine(
+            f"cloudflare_d1://fake_account:fake_token@fake_db?base_url={encoded}"
+        )
+        try:
+            with engine.connect() as conn:
+                result = conn.execute(text("SELECT 1 AS value"))
+                row = result.fetchone()
+            assert row == (42,)
+            assert any("/raw" in path for path in received)
+        finally:
+            engine.dispose()
+
+    def test_base_url_kwarg_takes_precedence_over_env_var(self, local_d1_server):
+        """When both base_url kwarg and CF_D1_BASE_URL are set, kwarg wins."""
+        base_url, received = local_d1_server
+        with patch.dict(
+            os.environ, {"CF_D1_BASE_URL": "http://should-not-be-used:9999"}
+        ):
+            conn = Connection(
+                account_id="fake_account",
+                database_id="fake_db",
+                api_token="fake_token",
+                base_url=base_url,
+            )
+            try:
+                cur = conn.cursor()
+                cur.execute("SELECT 1 AS value")
+                row = cur.fetchone()
+                assert row == (42,)
+            finally:
+                conn.close()
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v", "-s"])

{sqlalchemy_cloudflare_d1-0.3.8 → sqlalchemy_cloudflare_d1-0.3.9}/tests/integration/test_worker_integration.py

@@ -959,4 +959,64 @@ class TestWorkerTimeColumn:
         assert data["test"] == "time_orm"
         assert data["success"] is True, f"time_orm failed: error={data.get('error')}"
         assert data["entry_title"] == "Time Test Entry"
-        assert data["start_time_is_time"] is True
+
+
+# MARK: - Parallel Query Tests (GitHub issue #20)
+
+
+class TestParallelQueries:
+    """Concurrency tests proving both connection types are non-blocking.
+
+    Despite using pyodide.ffi.run_sync() internally, SyncWorkerConnection
+    drives the JS event loop rather than truly blocking it. Both connection
+    types show genuine speedup when queries are run via asyncio.gather().
+    """
+
+    def test_engine_queries_are_concurrent(self, dev_server):
+        """create_engine_from_binding() is concurrent — gather gives real speedup.
+
+        Both queries run a CPU-heavy recursive CTE (SUM of 1..500000).
+        Parallel time should be < 80% of sequential time, confirming that
+        run_sync() drives the JS event loop and does not block it.
+        """
+        port = dev_server
+        response = requests.get(f"http://localhost:{port}/parallel-queries-engine")
+
+        assert response.status_code == 200, (
+            f"parallel_queries_engine failed: {response.json()}"
+        )
+        data = response.json()
+
+        assert data["test"] == "parallel_queries_engine", data
+        assert data["results_correct"] is True, f"query results wrong: {data}"
+        assert data["is_concurrent"] is True, (
+            f"expected concurrent behaviour but got no speedup: "
+            f"sequential={data['sequential_time_s']}s, "
+            f"parallel={data['parallel_time_s']}s "
+            f"({data['n_queries']} queries)"
+        )
+
+    def test_worker_connection_queries_are_concurrent(self, dev_server):
+        """WorkerConnection async is truly concurrent — gather gives real speedup.
+
+        Both queries run the same CPU-heavy recursive CTE.
+        Parallel time should be < 80% of sequential time, confirming that
+        await cursor.execute_async() yields to the event loop and allows
+        both D1 calls to overlap.
+        """
+        port = dev_server
+        response = requests.get(f"http://localhost:{port}/parallel-queries-async")
+
+        assert response.status_code == 200, (
+            f"parallel_queries_async failed: {response.json()}"
+        )
+        data = response.json()
+
+        assert data["test"] == "parallel_queries_async", data
+        assert data["results_correct"] is True, f"query results wrong: {data}"
+        assert data["is_concurrent"] is True, (
+            f"expected concurrent behaviour but got no speedup: "
+            f"sequential={data['sequential_time_s']}s, "
+            f"parallel={data['parallel_time_s']}s "
+            f"({data['n_queries']} queries)"
+        )

{sqlalchemy_cloudflare_d1-0.3.8 → sqlalchemy_cloudflare_d1-0.3.9}/tests/unit/test_dialect.py

@@ -234,5 +234,65 @@ def test_async_dbapi_module():
     assert hasattr(AsyncAdapt_d1_dbapi, "connect")
 
 
+def test_connection_base_url_kwarg():
+    """Test that Connection accepts a custom base_url kwarg."""
+    from unittest.mock import patch
+
+    from sqlalchemy_cloudflare_d1.connection import Connection
+
+    with patch("sqlalchemy_cloudflare_d1.connection.httpx") as mock_httpx:
+        mock_httpx.Client.return_value = None
+        conn = Connection(
+            account_id="acct",
+            database_id="db",
+            api_token="token",
+            base_url="http://localhost:8787",
+        )
+        assert conn.base_url == "http://localhost:8787"
+
+
+def test_connection_base_url_env_var():
+    """Test that Connection reads CF_D1_BASE_URL from the environment."""
+    import os
+    from unittest.mock import patch
+
+    from sqlalchemy_cloudflare_d1.connection import Connection
+
+    with patch.dict(os.environ, {"CF_D1_BASE_URL": "http://localhost:9999"}):
+        with patch("sqlalchemy_cloudflare_d1.connection.httpx") as mock_httpx:
+            mock_httpx.Client.return_value = None
+            conn = Connection(account_id="acct", database_id="db", api_token="token")
+            assert conn.base_url == "http://localhost:9999"
+
+
+def test_connection_base_url_default():
+    """Test that Connection falls back to the Cloudflare URL when no override is set."""
+    import os
+    from unittest.mock import patch
+
+    from sqlalchemy_cloudflare_d1.connection import Connection
+
+    env = {k: v for k, v in os.environ.items() if k != "CF_D1_BASE_URL"}
+    with patch.dict(os.environ, env, clear=True):
+        with patch("sqlalchemy_cloudflare_d1.connection.httpx") as mock_httpx:
+            mock_httpx.Client.return_value = None
+            conn = Connection(account_id="acct", database_id="db", api_token="token")
+            assert conn.base_url == (
+                "https://api.cloudflare.com/client/v4/accounts/acct/d1/database/db"
+            )
+
+
+def test_base_url_passthrough_via_url_query():
+    """Test that base_url can be passed via the connection string query params."""
+    from sqlalchemy.engine.url import make_url
+
+    dialect = CloudflareD1Dialect()
+    url = make_url(
+        "cloudflare_d1://acct:token@db?base_url=http%3A%2F%2Flocalhost%3A8787"
+    )
+    _, kwargs = dialect.create_connect_args(url)
+    assert kwargs["base_url"] == "http://localhost:8787"
+
+
 if __name__ == "__main__":
     pytest.main([__file__])

{sqlalchemy_cloudflare_d1-0.3.8 → sqlalchemy_cloudflare_d1-0.3.9}/uv.lock

@@ -922,7 +922,7 @@ wheels = [
 
 [[package]]
 name = "sqlalchemy-cloudflare-d1"
-version = "0.3.8"
+version = "0.3.9"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },