You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 9e95bb1
Browse filesBrowse the repository at this point in the historyBrowse files
## Summary
Pins `@rocicorp/zero` **1.11.3** (from 1.10.0) and ports what changed in
the server SDK between them.
```diff
query builder
- AST as built, normalized only when zero-cache hashes it
+ AST normalized at every step: related sorted by alias, where flattened + sorted
+ values ordered null < bool < number < string < array; static params comparable
+ empty and/or kept (always true / always false)
z2s
+ LIKE patterns bound as text (non-string patterns match as their string)
+ char(n) compared as ::bpchar; bare `character` column named bpchar
- $n::text::text -> $n::text
mutate
+ mutator return value -> result.data, written to zero_0.mutations
+ tx.retry_on(predicate): re-run in a fresh tx, at most 5 runs per push
+ tx unusable once its transaction has ended
+ adapters take isolation_level=
ZQLDatabase.run
+ bare statement when the connection supports it, no BEGIN/COMMIT
query endpoint
+ transform requests parsed in strip mode (unknown fields ignored)
compat proof
+ valita 0.5.5 (`dist/index.js`), scope remapped to 1.11.3 line numbers
```
Not ported: upstream's `LogSink` (Python logs through stdlib `logging`),
and query interning, which only saves work.
Upstream now interns built queries, and a few type-violating inputs
share a key: a `flip` of `'yes'` with `true`, and any `orderBy`
direction other than `'asc'` with `'desc'`. That made upstream's output
depend on earlier programs. The harness now builds each program from a
fresh schema, and `docs/compat.md` records it as a known difference.
## Evidence
- **Before** (pin bumped, port unchanged): `pytest`: 53 failed, 661
passed (AST normalization, query bodies, SQL tier).
**After:** `pytest`: 782 passed, `zero_server` at 100%; `python -m
tests.compat`: 54 upstream modules and every port module fully exercised
differentially.
- New differential tests:
- **Mutate:** return values, every `retry_on` outcome, using a `tx`
after it ended, isolation level per adapter, `run` with and without a
bare connection.
- **SQL tier:** `char(3)` and `bpchar` columns, compared and matched
with LIKE.
- **Pinned builder programs:** each new sort rule.
- **Not run locally:** e2e (port 55432 was held by an unrelated
container). CI runs it.
- **Wall-clock bench, Python side vs `main`:**
| Case | `main` | This PR | Change |
| --- | --- | --- | --- |
| `build.simple` | 3.6 µs | 4.0 µs | about 13% slower |
| `build.complex` | 20.1 µs | 23.3 µs | about 16% slower |
| `query` cases | | | 7–16% slower |
| `z2s` | | | unchanged |
The cost is the per-step normalization upstream added. TS got faster at
rebuilding the same query thanks to interning, so expect CodSpeed to
flag `build`/`query`. Porting interning is the follow-up that wins this
back.
## Merge Danger
**Door:** two-way
**Blast Radius:** wire
Every query AST sent to zero-cache changes shape: key order, sorted
conditions and relationships, and empty and/or now kept. This now
matches what a 1.11.3 TypeScript server sends. A deployment still on
zero-cache 1.10 would see different query hashes, which re-runs its
queries.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- codesmith:footer -->
---
<a
href="https://app.blacksmith.sh/agent-labs-dev/codesmith/zero-python/pr/39?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-3x.png"
width="162" height="28"></picture></a> <a
href="https://backend.blacksmith.sh/track/enable-autofix?expires=1795812024&installation_model_id=434381&pr_number=39&ref=codesmith_pr_footer&repository=agent-labs-dev%2Fzero-python&return_to=https%3A%2F%2Fgithub.com%2Fagent-labs-dev%2Fzero-python%2Fpull%2F39&signature=1bb4b63b27217ea29779703a36fdaf667c13d82e31972f8fbc67b0adb8c81db9"><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-3x.png"
width="190" height="28"></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>
Copy file name to clipboardExpand all lines: README.md
+4-1Lines changed: 4 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ A community Python server SDK for [Zero](https://zero.rocicorp.dev/). It is not
4
4
5
5
It ports what `@rocicorp/zero/server` gives a TypeScript backend: the query endpoint (`ZERO_QUERY_URL`), the mutate endpoint (`ZERO_MUTATE_URL`), the ZQL query builder, `defineQueries` and `defineMutators`, and `tx.mutate` and `tx.run` on Postgres. The client and `zero-cache` stay in TypeScript, and a Python backend serves the same TypeScript client a TypeScript backend would.
6
6
7
-
Compatibility is pinned to one Zero release at a time. This version is tested against `@rocicorp/zero`**1.10.0** (see `ZERO_VERSION`).
7
+
Compatibility is pinned to one Zero release at a time. This version is tested against `@rocicorp/zero`**1.11.3** (see `ZERO_VERSION`).
8
8
9
9
## Usage
10
10
@@ -77,6 +77,9 @@ app = Starlette(
77
77
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.
78
78
79
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.
80
+
-**Mutator results.** What a mutator returns, if not `None`, reaches the client as the mutation's result data, and is also written to zero-cache's `mutations` table so it survives a lost response. Python has one `None`, so a mutator cannot return JSON `null` as data the way a TypeScript mutator can.
81
+
-**Re-running a mutator.**`tx.retry_on(predicate)` asks `predicate(error, attempt)`, sync or async, whether to run the mutator again in a fresh transaction when the run fails, including at `COMMIT`. Only `True` means yes. A mutator runs at most 5 times per push, and `tx` is unusable once its transaction has ended, inside the predicate too.
82
+
-**Isolation level.** Each adapter takes `isolation_level="read committed" | "repeatable read" | "serializable"` for the transactions mutations run in. Unset, the database's default applies.
80
83
-**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.
81
84
-**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.
0 commit comments