Skip to content

Commit bdc425c

Browse files
jnsdlsclaude
andauthored
fix: support Nebula's dependency versions and SQLAlchemy on psycopg (#16)
Nebula is the first app on zero-server, and it couldn't install 0.0.1. Two problems. **Floors.** 0.0.1 asks for pydantic 2.14 and SQLAlchemy 2.1. Nebula is held at pydantic 2.12 because openrouter caps it below 2.13 (still true in 1.3.57, released today). Nebula is also pinned to SQLAlchemy 2.0, because its workspace scope gate reads private AsyncSession internals. The suite passes on pydantic 2.12.0, SQLAlchemy 2.0.40, asyncpg 0.30, psycopg 3.2.10 and starlette 1.6, so those are the new floors. A new `floors` job runs `uv sync --resolution lowest-direct` and then the suite, so CI tests every floor. **SQLAlchemy on psycopg.** Nebula runs SQLAlchemy over psycopg. On psycopg, `exec_driver_sql` passes `$1` to a driver that expects `%s`, so `SQLAlchemyDatabase` was asyncpg-only. Now it runs statements through psycopg's raw cursor on the same connection, inside the transaction SQLAlchemy opened. `sqlalchemy-psycopg` runs as a fourth adapter in the wire and SQL tiers. `sqlalchemy_transaction(connection)` wraps a connection that is already in a transaction, such as an AsyncSession's. Smaller changes: - `adapters/psycopg.py` imports `psycopg_pool` only under `TYPE_CHECKING`, so SQLAlchemy-on-psycopg works without psycopg-pool installed. - The `sqlalchemy` extra no longer installs asyncpg. The engine URL picks the driver, and the caller installs it. - Version bumped to 0.0.2. After merge, tag `v0.0.2` to publish. Local runs: 201 passed with 100% coverage at the locked versions, and 201 passed at the floors. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- codesmith:footer --> --- <a href="https://app.blacksmith.sh/agent-labs-dev/codesmith/zero-python/pr/16?autoLogin=true&ref=codesmith_pr_footer"><picture><source media="(prefers-color-scheme: dark)" srcset="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v3.svg"><source media="(prefers-color-scheme: light)" srcset="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-light-v3.svg"><img alt="View with [code]smith" src="https://pr-comments-assets.blacksmith.sh/codesmith/view-with-codesmith-dark-v3.svg"></picture></a> <a href="https://backend.blacksmith.sh/track/enable-autofix?expires=1794676459&installation_model_id=434381&pr_number=16&ref=codesmith_pr_footer&repository=agent-labs-dev%2Fzero-python&return_to=https%3A%2F%2Fgithub.com%2Fagent-labs-dev%2Fzero-python%2Fpull%2F16&signature=042396c0c2179772cffb1299c27f6deb4b55cb1a4bca1f9eb7438aca59eceba5"><picture><source media="(prefers-color-scheme: dark)" srcset="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-light.svg"><img alt="Autofix with [code]smith" src="https://pr-comments-assets.blacksmith.sh/codesmith/autofix-with-codesmith-dark.svg"></picture></a> <sup>Need help on this PR? Tag <code>@codesmith-bot</code> with what you need.</sup> <!-- codesmith:autofix:disabled --> <!-- /codesmith:footer --> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent cae5ad5 commit bdc425c

9 files changed

Lines changed: 106 additions & 32 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,35 @@ jobs:
4040
- run: uv run ty check
4141
- run: uv run pytest
4242

43+
# The suite again with every direct dependency at the lowest version pyproject.toml allows, so a floor
44+
# is never lower than what has been tested.
45+
floors:
46+
runs-on: ubuntu-latest
47+
services:
48+
postgres:
49+
image: postgres:17
50+
env:
51+
POSTGRES_PASSWORD: postgres
52+
ports: ["5432:5432"]
53+
options: >-
54+
--health-cmd pg_isready --health-interval 2s --health-timeout 5s --health-retries 30
55+
env:
56+
ZERO_SERVER_PG: postgresql://postgres:postgres@localhost:5432
57+
steps:
58+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
59+
with:
60+
persist-credentials: false
61+
- uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
62+
with:
63+
python-version: "3.12"
64+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
65+
with:
66+
node-version: "24"
67+
- run: npm ci
68+
working-directory: harness
69+
- run: uv sync --resolution lowest-direct
70+
- run: uv run --no-sync pytest --no-cov
71+
4372
# An unmodified Zero client syncing through zero-cache, once with the TypeScript reference app server
4473
# and once with the Python one. Fails on any difference in what the client ends up with.
4574
e2e:

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Compatibility is pinned to one Zero release at a time. This version is tested ag
99
## Usage
1010

1111
```sh
12-
pip install "zero-server[sqlalchemy,starlette]" # or [asyncpg], or [psycopg]
12+
pip install "zero-server[sqlalchemy,asyncpg,starlette]" # or [asyncpg], or [psycopg]
1313
```
1414

1515
The schema stays in your TypeScript `schema.ts`, because the client needs it. Emit it as JSON, and generate Python types from it:
@@ -76,7 +76,7 @@ app = Starlette(
7676

7777
Point `ZERO_QUERY_URL` and `ZERO_MUTATE_URL` at `/query` and `/mutate`. With FastAPI, `app.router.routes.extend(zero_routes(...))`. With another framework, call `handle_query_request` and `handle_mutate_request` yourself; `zero_server/integrations/starlette.py` is short enough to copy.
7878

79-
- **Databases.** `SQLAlchemyDatabase` (SQLAlchemy's asyncio engine on asyncpg), `AsyncpgDatabase` (an asyncpg pool) and `PsycopgDatabase` (a psycopg 3 async pool), under `zero_server.server.adapters`. Another driver plugs into `ZQLDatabase` as a `DBConnection` whose `query` takes `$1` placeholders.
79+
- **Databases.** `SQLAlchemyDatabase` (SQLAlchemy's asyncio engine on asyncpg or psycopg; the `sqlalchemy` extra installs neither driver), `AsyncpgDatabase` (an asyncpg pool) and `PsycopgDatabase` (a psycopg 3 async pool), under `zero_server.server.adapters`. Another driver plugs into `ZQLDatabase` as a `DBConnection` whose `query` takes `$1` placeholders.
8080
- **Validation.** `@define_query(Model)` and `@define_mutator(Model)` parse args with a Pydantic model or `TypeAdapter` first; a failure reaches the client as upstream's validation error.
8181
- **Strict building.** `create_builder(schema, strict=True)` refuses an unknown column when the query is built. Upstream only refuses it when the endpoint maps the query, failing the whole batch, so this is for your tests.
8282

‎pyproject.toml‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "zero-server"
3-
version = "0.0.1"
3+
version = "0.0.2"
44
description = "Community Python server SDK for Rocicorp Zero. Not affiliated with Rocicorp."
55
readme = "README.md"
66
license = "Apache-2.0"
@@ -15,7 +15,8 @@ classifiers = [
1515
"Programming Language :: Python :: 3.13",
1616
"Typing :: Typed",
1717
]
18-
dependencies = ["pydantic>=2.14", "typing-extensions>=4.12"]
18+
# Floors are the lowest versions the suite passes on, and CI's `floors` job runs it at exactly these.
19+
dependencies = ["pydantic>=2.12", "typing-extensions>=4.12"]
1920

2021
[project.urls]
2122
Homepage = "https://github.com/agent-labs-dev/zero-python"
@@ -27,17 +28,18 @@ Changelog = "https://github.com/agent-labs-dev/zero-python/releases"
2728
zero-server = "zero_server.codegen:main"
2829

2930
[project.optional-dependencies]
30-
sqlalchemy = ["sqlalchemy[asyncio]>=2.1", "asyncpg>=0.32"]
31-
asyncpg = ["asyncpg>=0.32"]
32-
psycopg = ["psycopg>=3.3", "psycopg-pool>=3.3"]
33-
starlette = ["starlette>=1.8"]
31+
# The engine's driver is the caller's: add `asyncpg`, or install psycopg yourself.
32+
sqlalchemy = ["sqlalchemy[asyncio]>=2.0.40"]
33+
asyncpg = ["asyncpg>=0.30"]
34+
psycopg = ["psycopg>=3.2.10", "psycopg-pool>=3.2.6"]
35+
starlette = ["starlette>=1.6"]
3436

3537
[dependency-groups]
3638
dev = [
3739
"zero-server[sqlalchemy,asyncpg,psycopg,starlette]",
3840
"httpx2>=2.13",
3941
# psycopg's prebuilt libpq, so the tests need no system libpq.
40-
"psycopg[binary]>=3.3",
42+
"psycopg[binary]>=3.2.10",
4143
"hypothesis>=6.169",
4244
"pytest>=9.1",
4345
"pytest-asyncio>=1.4",
@@ -47,7 +49,7 @@ dev = [
4749
]
4850

4951
# The Python app server of the end-to-end tier.
50-
e2e = ["starlette>=1.8", "uvicorn>=0.54"]
52+
e2e = ["starlette>=1.6", "uvicorn>=0.54"]
5153

5254
[build-system]
5355
requires = ["uv_build>=0.11,<0.14"]

‎src/zero_server/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
from zero_server.server.process_queries import handle_query_request
1414
from zero_server.server.push_processor import PushProcessor
1515

16-
__version__ = "0.0.1"
16+
__version__ = "0.0.2"
1717

1818
__all__ = [
1919
"ApplicationError",

‎src/zero_server/server/adapters/psycopg.py‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,15 @@
55
"""
66

77
from collections.abc import Awaitable, Callable, Sequence
8-
from typing import Any
8+
from typing import TYPE_CHECKING, Any
99

1010
import psycopg
1111
from psycopg.rows import dict_row
12-
from psycopg_pool import AsyncConnectionPool
12+
13+
if TYPE_CHECKING:
14+
# Only `PsycopgDatabase` takes a pool. The SQLAlchemy adapter reuses `PsycopgTransaction` on
15+
# SQLAlchemy's own connection, and must not need psycopg-pool installed for it.
16+
from psycopg_pool import AsyncConnectionPool
1317

1418
from zero_server.schema import Schema
1519
from zero_server.server.transaction import DBTransaction, Row
@@ -40,7 +44,7 @@ async def query(self, sql: str, params: Sequence[Any] = ()) -> list[Row]:
4044

4145

4246
class PsycopgConnection:
43-
def __init__(self, pool: AsyncConnectionPool) -> None:
47+
def __init__(self, pool: "AsyncConnectionPool") -> None:
4448
self.pool = pool
4549

4650
async def transaction[R](self, fn: Callable[[DBTransaction[psycopg.AsyncConnection[Any]]], Awaitable[R]]) -> R:
@@ -51,5 +55,5 @@ async def transaction[R](self, fn: Callable[[DBTransaction[psycopg.AsyncConnecti
5155
class PsycopgDatabase(ZQLDatabase[psycopg.AsyncConnection[Any]]):
5256
"""A `ZQLDatabase` on a psycopg pool (`AsyncConnectionPool(conninfo, open=False)`, then `await pool.open()`)."""
5357

54-
def __init__(self, pool: AsyncConnectionPool, schema: Schema | None = None) -> None:
58+
def __init__(self, pool: "AsyncConnectionPool", schema: Schema | None = None) -> None:
5559
super().__init__(PsycopgConnection(pool), schema)

‎src/zero_server/server/adapters/sqlalchemy.py‎

Lines changed: 31 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
"""SQLAlchemy's asyncio engine, with the asyncpg driver.
1+
"""SQLAlchemy's asyncio engine, with the asyncpg or the psycopg driver.
22
3-
Needs the `zero-server[sqlalchemy]` extra.
3+
Needs the `zero-server[sqlalchemy]` extra, and the driver the engine's URL names.
44
"""
55

66
from collections.abc import Awaitable, Callable, Sequence
@@ -15,14 +15,24 @@
1515

1616

1717
class SQLAlchemyTransaction:
18-
def __init__(self, connection: AsyncConnection) -> None:
18+
"""One transaction of an `AsyncConnection`.
19+
20+
On asyncpg a statement goes through `exec_driver_sql`, which hands the `$1` placeholders to asyncpg
21+
as they are. psycopg's paramstyle is `%s`, so on psycopg it goes through psycopg's raw cursor on the
22+
same connection, inside the transaction SQLAlchemy opened.
23+
"""
24+
25+
def __init__(self, connection: AsyncConnection, driver_transaction: DBTransaction[Any] | None = None) -> None:
1926
self._connection = connection
27+
self._driver_transaction = driver_transaction
2028

2129
@property
2230
def wrapped_transaction(self) -> AsyncConnection:
2331
return self._connection
2432

2533
async def query(self, sql: str, params: Sequence[Any] = ()) -> list[Row]:
34+
if self._driver_transaction is not None:
35+
return await self._driver_transaction.query(sql, params)
2636
try:
2737
result = await self._connection.exec_driver_sql(sql, tuple(params))
2838
except DBAPIError as error:
@@ -33,17 +43,33 @@ async def query(self, sql: str, params: Sequence[Any] = ()) -> list[Row]:
3343
return [dict(row) for row in result.mappings()] if result.returns_rows else []
3444

3545

46+
async def sqlalchemy_transaction(connection: AsyncConnection) -> SQLAlchemyTransaction:
47+
"""Wrap a connection that is already in a transaction, such as one an `AsyncSession` holds."""
48+
driver = connection.dialect.driver
49+
if driver == "asyncpg":
50+
return SQLAlchemyTransaction(connection)
51+
if driver == "psycopg":
52+
from zero_server.server.adapters.psycopg import PsycopgTransaction
53+
54+
driver_connection = (await connection.get_raw_connection()).driver_connection
55+
# `None` only once SQLAlchemy has invalidated the connection, which it never does mid-transaction.
56+
assert driver_connection is not None
57+
return SQLAlchemyTransaction(connection, PsycopgTransaction(driver_connection))
58+
raise ValueError(f"SQLAlchemy driver {driver!r} is not supported; use asyncpg or psycopg")
59+
60+
3661
class SQLAlchemyConnection:
3762
def __init__(self, engine: AsyncEngine) -> None:
3863
self.engine = engine
3964

4065
async def transaction[R](self, fn: Callable[[DBTransaction[AsyncConnection]], Awaitable[R]]) -> R:
4166
async with self.engine.begin() as connection:
42-
return await fn(SQLAlchemyTransaction(connection))
67+
return await fn(await sqlalchemy_transaction(connection))
4368

4469

4570
class SQLAlchemyDatabase(ZQLDatabase[AsyncConnection]):
46-
"""A `ZQLDatabase` on `engine`, which must use the asyncpg driver (`postgresql+asyncpg://`)."""
71+
"""A `ZQLDatabase` on `engine`, whose URL names the asyncpg or the psycopg driver
72+
(`postgresql+asyncpg://` or `postgresql+psycopg://`)."""
4773

4874
def __init__(self, engine: AsyncEngine, schema: Schema | None = None) -> None:
4975
super().__init__(SQLAlchemyConnection(engine), schema)

‎tests/unit/test_api.py‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
must_get_query,
1919
)
2020
from zero_server.schema import load_schema, server_to_client
21+
from zero_server.server.adapters.sqlalchemy import sqlalchemy_transaction
2122
from zero_server.server.process_queries import handle_query_request
2223
from zero_server.server.server_schema import get_server_schema
2324
from zero_server.server.transaction import ServerTransaction
@@ -172,3 +173,14 @@ def test_mutate_by_attribute() -> None:
172173
assert isinstance(mutate.issue, TableCRUD)
173174
with pytest.raises(AttributeError):
174175
_ = mutate.nope
176+
177+
178+
async def test_sqlalchemy_refuses_an_unsupported_driver() -> None:
179+
class Dialect:
180+
driver = "pg8000"
181+
182+
class Connection:
183+
dialect = Dialect()
184+
185+
with pytest.raises(ValueError, match="'pg8000' is not supported"):
186+
await sqlalchemy_transaction(Connection()) # ty: ignore[invalid-argument-type]

‎tests/wire/conftest.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@
5050
"CREATE TABLE pair (a TEXT, b INTEGER, note TEXT, PRIMARY KEY (a, b))",
5151
]
5252

53-
ADAPTERS = ["sqlalchemy", "asyncpg", "psycopg"]
53+
ADAPTERS = ["sqlalchemy", "sqlalchemy-psycopg", "asyncpg", "psycopg"]
5454
"""Every Python adapter runs the same wire and SQL tiers."""
5555

5656
type Databases = dict[str, Callable[[Schema | None], ZQLDatabase[Any]]]
@@ -64,13 +64,16 @@ async def open_adapters(url: str, engine: AsyncEngine) -> tuple[Databases, Calla
6464
pool = await asyncpg.create_pool(url, min_size=1, max_size=4)
6565
psycopg_pool = AsyncConnectionPool(url, min_size=1, max_size=4, open=False)
6666
await psycopg_pool.open()
67+
psycopg_engine = create_async_engine(f"postgresql+psycopg://{url.split('://', 1)[1]}")
6768

6869
async def close() -> None:
6970
await pool.close()
7071
await psycopg_pool.close()
72+
await psycopg_engine.dispose()
7173

7274
return {
7375
"sqlalchemy": lambda schema: SQLAlchemyDatabase(engine, schema),
76+
"sqlalchemy-psycopg": lambda schema: SQLAlchemyDatabase(psycopg_engine, schema),
7477
"asyncpg": lambda schema: AsyncpgDatabase(pool, schema),
7578
"psycopg": lambda schema: PsycopgDatabase(psycopg_pool, schema),
7679
}, close

‎uv.lock‎

Lines changed: 9 additions & 11 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)