Skip to content

Commit bad6c85

Browse files
jnsdlsclaude
andcommitted
perf: send SQLAlchemy's BEGIN up front in a push session
SQLAlchemy's asyncpg dialect defers BEGIN to the first statement it runs itself, so each mutation's first statement took SQLAlchemy's execution path. In a push session the adapter now calls the dialect's private _start_transaction right after begin(), and every statement goes straight to asyncpg: a push of 100 puts went from 1.35x to 1.13x of TypeScript. If a release drops that method, the first statement begins the transaction as before; a test covers that fallback. The README and handle_mutate_request now say what sharing one connection per push means: mutators in a push share session state, and a handler that takes a second connection from the same pool can deadlock when the pool is smaller than the number of concurrent pushes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent a30c421 commit bad6c85

4 files changed

Lines changed: 29 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -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. The types to annotate those handlers (`QueryRequestHandler`, `TransactFn`, `MutateResponse`, `MutationResponse`, `ServerPushFailed` and the rest) import from `zero_server`, and `server_ast(query, schema)` returns the AST zero-cache receives for a query.
7878

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.
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`. A push's mutations run on one connection from the pool, taken at its first transaction and returned when the push ends. So mutators in one push share session state (a `SET` without `LOCAL`, session advisory locks, temp tables), and a handler that takes a second connection from the same pool while its push holds one can deadlock once the pool has fewer connections than there are concurrent pushes. 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

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

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99

1010
from sqlalchemy.exc import DBAPIError
1111
from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine
12+
from sqlalchemy.pool import PoolProxiedConnection
1213

1314
from zero_server.schema import Schema
1415
from zero_server.server.adapters._session import SessionConnection, session
@@ -23,7 +24,8 @@ class SQLAlchemyTransaction:
2324
same connection, inside the transaction SQLAlchemy opened. On asyncpg, SQLAlchemy defers `BEGIN` to
2425
the first statement it runs itself, so until the transaction is open a statement goes through
2526
`exec_driver_sql`, which hands the `$1` placeholders to asyncpg as they are. After that, statements
26-
go straight to the asyncpg connection, as the asyncpg adapter sends them.
27+
go straight to the asyncpg connection, as the asyncpg adapter sends them. In a push's session,
28+
`BEGIN` goes out before the callback runs, so every statement does.
2729
"""
2830

2931
def __init__(
@@ -93,9 +95,23 @@ async def _transaction[R](
9395
connection: AsyncConnection, fn: Callable[[DBTransaction[AsyncConnection]], Awaitable[R]]
9496
) -> R:
9597
async with connection.begin():
98+
if connection.dialect.driver == "asyncpg":
99+
await _send_begin(await connection.get_raw_connection())
96100
return await fn(await sqlalchemy_transaction(connection))
97101

98102

103+
async def _send_begin(pooled: PoolProxiedConnection) -> None:
104+
"""Have SQLAlchemy's asyncpg dialect send `BEGIN` now, so every statement can go straight to asyncpg.
105+
106+
The dialect defers `BEGIN` to the first statement it runs itself and has no public way to send it
107+
sooner; that first statement through SQLAlchemy cost a push of 100 puts about 20%.
108+
"""
109+
# Private: the asyncpg dialect's `_start_transaction`. A public way to begin, or its removal, retires this.
110+
start = getattr(pooled.dbapi_connection, "_start_transaction", None)
111+
if start is not None:
112+
await start()
113+
114+
99115
class SQLAlchemyDatabase(ZQLDatabase[AsyncConnection]):
100116
"""A `ZQLDatabase` on `engine`, whose URL names the asyncpg or the psycopg driver
101117
(`postgresql+asyncpg://` or `postgresql+psycopg://`)."""

‎src/zero_server/server/process_mutations.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -189,6 +189,10 @@ async def handle_mutate_request[T](
189189
A caller that needs push-level fields such as `timestamp` parses once with `PushBody.from_json` and
190190
passes the result. If that parse fails, pass the raw body instead and return the parse failure this
191191
produces.
192+
193+
With a database that opens sessions, as `ZQLDatabase` does, the push's mutations share one pooled
194+
connection: they see each other's session state, and a handler that takes another connection from
195+
the same pool can deadlock when the pool is smaller than the number of concurrent pushes.
192196
"""
193197
return await handle_mutate(db_provider, handler, query, body, user_id, report_user_id=True)
194198

‎tests/wire/test_adapters.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
"""Sessions: a push's transactions on one connection from the adapter's pool."""
22

33
import logging
4+
from types import SimpleNamespace
45
from typing import Any
56

67
import asyncpg
78
import pytest
89

910
from tests.wire.conftest import ADAPTERS, WireDB
1011
from zero_server.server.adapters.asyncpg import AsyncpgDatabase
12+
from zero_server.server.adapters.sqlalchemy import _send_begin
1113
from zero_server.server.zql_database import ZQLDatabase
1214

1315

@@ -77,3 +79,8 @@ async def transaction(self, fn: Any) -> Any:
7779
database = ZQLDatabase(Connection())
7880
async with database.session() as db:
7981
assert db is database
82+
83+
84+
async def test_sqlalchemy_begins_on_its_first_statement_without_start_transaction() -> None:
85+
# A SQLAlchemy without the dialect's private `_start_transaction` sends nothing early.
86+
await _send_begin(SimpleNamespace(dbapi_connection=object())) # ty: ignore[invalid-argument-type]

0 commit comments

Comments
 (0)