cerbos-sqlalchemy 0.3.1__tar.gz → 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. cerbos_sqlalchemy-0.5.0/PKG-INFO +722 -0
  2. cerbos_sqlalchemy-0.5.0/README.md +703 -0
  3. {cerbos-sqlalchemy-0.3.1 → cerbos_sqlalchemy-0.5.0}/pyproject.toml +40 -10
  4. cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/__init__.py +21 -0
  5. cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/_null_conventions.py +219 -0
  6. cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/_operators.py +1403 -0
  7. cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/_plan.py +296 -0
  8. cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/_regex.py +580 -0
  9. cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/_translator.py +1093 -0
  10. cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/collection_storage.py +681 -0
  11. cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/errors.py +16 -0
  12. cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/py.typed +0 -0
  13. cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/query.py +358 -0
  14. cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/relations.py +306 -0
  15. cerbos_sqlalchemy-0.5.0/tests/conftest.py +202 -0
  16. cerbos_sqlalchemy-0.5.0/tests/corpus.py +713 -0
  17. cerbos_sqlalchemy-0.5.0/tests/test_adversarial_conformance.py +442 -0
  18. cerbos_sqlalchemy-0.5.0/tests/test_query.py +1302 -0
  19. cerbos_sqlalchemy-0.5.0/tests/test_relations.py +85 -0
  20. cerbos_sqlalchemy-0.5.0/tests/test_translator.py +591 -0
  21. cerbos_sqlalchemy-0.5.0/tests/typing/check_types.py +66 -0
  22. cerbos-sqlalchemy-0.3.1/PKG-INFO +0 -149
  23. cerbos-sqlalchemy-0.3.1/README.md +0 -132
  24. cerbos-sqlalchemy-0.3.1/src/cerbos_sqlalchemy/__init__.py +0 -7
  25. cerbos-sqlalchemy-0.3.1/src/cerbos_sqlalchemy/query.py +0 -152
  26. cerbos-sqlalchemy-0.3.1/tests/conftest.py +0 -175
  27. cerbos-sqlalchemy-0.3.1/tests/test_query.py +0 -372
@@ -0,0 +1,722 @@
1
+ Metadata-Version: 2.1
2
+ Name: cerbos-sqlalchemy
3
+ Version: 0.5.0
4
+ Summary: SQLAlchemy adapter for generating queries with Cerbos: an open core, language-agnostic, scalable authorization solution
5
+ Author-Email: Cerbos Developers <sdk+sqlalchemy@cerbos.dev>
6
+ License: Apache-2.0
7
+ Classifier: Development Status :: 4 - Beta
8
+ Classifier: Intended Audience :: Developers
9
+ Classifier: Topic :: Security
10
+ Classifier: Topic :: Software Development :: Libraries
11
+ Project-URL: Homepage, https://cerbos.dev
12
+ Project-URL: Repository, https://github.com/cerbos/query-plan-adapters/tree/main/sqlalchemy
13
+ Requires-Python: >=3.10
14
+ Requires-Dist: sqlalchemy>=1.4
15
+ Requires-Dist: cerbos>=0.10.4
16
+ Provides-Extra: testcontainers
17
+ Requires-Dist: testcontainers>=3.5.3; extra == "testcontainers"
18
+ Description-Content-Type: text/markdown
19
+
20
+ # Cerbos + SQLAlchemy Adapter
21
+
22
+ Converts a [Cerbos](https://cerbos.dev) query plan ([PlanResources API](https://docs.cerbos.dev/cerbos/latest/api/index.html#resources-query-plan))
23
+ into a [SQLAlchemy](https://docs.sqlalchemy.org/) `Select`, for use with the
24
+ [Cerbos Python SDK](https://github.com/cerbos/cerbos-sdk-python).
25
+
26
+ ## Install
27
+
28
+ ```bash
29
+ pip install cerbos-sqlalchemy
30
+ ```
31
+
32
+ - Python >= 3.10
33
+ - SQLAlchemy >= 1.4 (1.4 and 2.x are both tested)
34
+ - Cerbos Python SDK (`cerbos`) >= 0.10.4; Cerbos PDP > v0.16
35
+ - Either SDK client: the HTTP `CerbosClient` or the gRPC client (see [Transports](#transports))
36
+
37
+ ## Quick start
38
+
39
+ ```python
40
+ from cerbos.sdk.client import CerbosClient
41
+ from cerbos.sdk.model import Principal, ResourceDesc
42
+ from sqlalchemy import Column, Integer, String, create_engine
43
+ from sqlalchemy.orm import Session, declarative_base
44
+
45
+ from cerbos_sqlalchemy import get_query
46
+
47
+ Base = declarative_base()
48
+
49
+
50
+ class LeaveRequest(Base):
51
+ __tablename__ = "leave_request"
52
+
53
+ id = Column(Integer, primary_key=True)
54
+ department = Column(String(225))
55
+ geography = Column(String(225))
56
+ priority = Column(Integer)
57
+
58
+
59
+ with CerbosClient(host="http://localhost:3592") as c:
60
+ principal = Principal(
61
+ "john",
62
+ roles={"employee"},
63
+ attr={"department": "marketing", "geography": "GB"},
64
+ )
65
+ plan = c.plan_resources("view", principal, ResourceDesc("leave_request"))
66
+
67
+ attr_map = {
68
+ "request.resource.attr.department": LeaveRequest.department,
69
+ "request.resource.attr.geography": LeaveRequest.geography,
70
+ "request.resource.attr.priority": LeaveRequest.priority,
71
+ }
72
+
73
+ # ALWAYS_ALLOWED -> select(LeaveRequest)
74
+ # ALWAYS_DENIED -> select(LeaveRequest).where(False)
75
+ # CONDITIONAL -> select(LeaveRequest).where(<translated condition>)
76
+ query = get_query(plan, LeaveRequest, attr_map)
77
+
78
+ # Compose with your own predicates; a denied plan stays denied.
79
+ query = query.where(LeaveRequest.priority < 5).limit(20)
80
+
81
+ with Session(create_engine("sqlite:///app.db")) as session:
82
+ rows = session.execute(query).scalars().all()
83
+ ```
84
+
85
+ `get_query` returns a `Select` for all three plan kinds, so you don't need to branch on the kind.
86
+ If you want to skip the round trip on a denial, check
87
+ `plan.filter.kind == PlanResourcesFilterKind.ALWAYS_DENIED` (from `cerbos.sdk.model`) first. Any
88
+ shape the adapter cannot translate raises instead of returning a broader query.
89
+
90
+ To debug, print the SQL: `print(query.compile(compile_kwargs={"literal_binds": True}))`.
91
+
92
+ ## Mapping attributes
93
+
94
+ `attr_map` maps each Cerbos attribute reference to a column. Values can be an ORM attribute
95
+ (`LeaveRequest.department`), a Core column (`LeaveRequest.__table__.c.department`), or any SQLAlchemy
96
+ column expression — for example a correlated scalar subquery for a value read through a to-one
97
+ relation.
98
+
99
+ ### Model styles
100
+
101
+ `table` accepts a Core `Table`, a legacy `declarative_base()` model, or a SQLAlchemy 2.0
102
+ `DeclarativeBase` subclass. An ORM model returns `Select[Tuple[Model]]`; a Core `Table` returns
103
+ `Select[Any]`.
104
+
105
+ ### Columns from more than one table
106
+
107
+ If `attr_map` references columns from other tables, pass `table_mapping` (4th positional
108
+ argument) — a list of `(table, join_condition)` pairs:
109
+
110
+ ```python
111
+ query = get_query(
112
+ plan,
113
+ Table1,
114
+ {
115
+ "request.resource.attr.foo": Table1.foo,
116
+ "request.resource.attr.bar": Table2.bar,
117
+ "request.resource.attr.bosh": Table3.bosh,
118
+ },
119
+ [
120
+ (Table2, Table1.table2_id == Table2.id),
121
+ (Table3, Table1.table3_id == Table3.id),
122
+ ],
123
+ )
124
+ ```
125
+
126
+ Tables may be models or Core `Table`s. A column expression that carries its own correlation (a
127
+ scalar subquery) needs no `table_mapping` entry.
128
+
129
+ If your models use `relationship()`, consider `query.with_only_columns(...)` to avoid implicit joins.
130
+
131
+ ### Collections and relations
132
+
133
+ - **A collection stored in one column** (JSON or PostgreSQL array) — declare it in
134
+ [`collection_columns`](#collection-storage) to get `size()` and constant indexing.
135
+ - **A collection in a related table** — map it to a [`Relation`](#collections-in-a-related-table)
136
+ and pass `relation_overrides()` as `operator_override_fns`. Read
137
+ [Mapping hazards](#mapping-hazards) before you do.
138
+ - **A collection the PDP already knows** (usually a principal attribute) — translated with no
139
+ configuration; see [Collection macros over known values](#collection-macros-over-known-values).
140
+
141
+ ## Options
142
+
143
+ | Option | Default | Use it when |
144
+ | --- | --- | --- |
145
+ | `table_mapping` | `None` | `attr_map` spans more than one table |
146
+ | `operator_override_fns` | `None` | you need a dialect-specific operator, or `relation_overrides()` for a collection in a related table |
147
+ | `null_attribute_representation` | `"omitted"` | your app sends explicit nulls for NULL columns (`"explicit"`) |
148
+ | `attribute_null_representation` | `None` | the NULL convention differs per attribute |
149
+ | `collection_columns` | `None` | a policy calls `size()`, indexes, or tests literal membership in a JSON / PostgreSQL array column |
150
+
151
+ ### NULL attribute representation
152
+
153
+ The planner emits the same `eq(x, null)` node however your application represents a NULL column in
154
+ the attributes it sends to `check()`, so you have to tell the adapter which convention you use.
155
+
156
+ | attributes you send for a NULL column | `check()` on that row | `IS NULL` filter |
157
+ | --- | --- | --- |
158
+ | `{"x": None}` — explicit null | allow | selects it — aligned |
159
+ | `{}` — attribute omitted | **deny** (CEL missing-attribute error) | selects it — **over-grants** |
160
+
161
+ The default is `"omitted"`, the convention that fails closed when the guess is wrong. If you send
162
+ NULL columns as explicit nulls, pass `"explicit"`, which translates `== null` to `IS NULL`:
163
+
164
+ ```python
165
+ get_query(plan, Resource, attr_map, null_attribute_representation="explicit")
166
+ ```
167
+
168
+ Under `"omitted"`, `x == null` and `x != null` answer exactly what CEL does: a NULL column is a
169
+ missing-attribute error, and a present one is never null. The adapter renders them as
170
+ `CASE WHEN x IS NOT NULL THEN FALSE END` (`TRUE` for `!=`), which is UNKNOWN for a NULL column and
171
+ stays UNKNOWN under any enclosing `not`, so the row is denied under both polarities. This needs `x`
172
+ mapped to a SQL expression (a column, or a correlated scalar subquery for a to-one relation) and no
173
+ override for that operator; otherwise the comparison raises. Every other null operand raises (a null
174
+ element of an `in` list, a null inside `hasIntersection`, ordering against null), and the refusal
175
+ fires before `operator_override_fns`. See [#302](https://github.com/cerbos/query-plan-adapters/issues/302)
176
+ and [#551](https://github.com/cerbos/query-plan-adapters/issues/551).
177
+
178
+ #### Declare the convention per attribute
179
+
180
+ One policy suite can mix both conventions (the same column mapped under two attribute names). Declare
181
+ it per attribute; the call-level option covers everything undeclared:
182
+
183
+ ```python
184
+ get_query(
185
+ plan,
186
+ Resource,
187
+ attr_map,
188
+ attribute_null_representation={
189
+ "request.resource.attr.owner": "explicit",
190
+ # department is omitted when NULL, so leave it undeclared
191
+ },
192
+ )
193
+ ```
194
+
195
+ Declaring `"explicit"` asserts that the column can be NULL **and** that a NULL reaches `check()` as
196
+ an explicit null. The equality family (`eq`, `ne`, `in`) over that attribute then renders so it is
197
+ never SQL UNKNOWN: CEL's `null != "x"` is TRUE, so the NULL row comes back. Ordering and string
198
+ operators are unchanged (CEL raises on a null receiver, which denies like UNKNOWN does). An
199
+ undeclared attribute follows the call-level option; if that is `"omitted"` and the caller in fact
200
+ sends an explicit null, `!=` against a constant under-grants the NULL rows, which fails closed.
201
+
202
+ **Declare both sides of a field-to-field comparison, or neither** — mixing conventions in one
203
+ comparison throws. See [#308](https://github.com/cerbos/query-plan-adapters/issues/308) and
204
+ [ADR 0004](../docs/adr/0004-the-null-convention-is-a-property-of-the-attribute.md).
205
+
206
+ > [!WARNING]
207
+ > **On Cerbos 0.56.0 and earlier, do not guard with `has()`: write `R.attr.x != null`.** An
208
+ > attribute the plan request omits is unknown to those planners, which assume the data layer
209
+ > supplies it, so they fold `has(R.attr.x)` to true: alone it plans as `ALWAYS_ALLOWED`, and
210
+ > `has(R.attr.x) && R.attr.y > 0` plans as `R.attr.y > 0`, which never excludes a row missing `x`.
211
+ > From 0.57.0 the planner keeps `has(R.attr.x)` in the plan, and the adapter translates it from
212
+ > `x`'s null convention or refuses it: under `omitted` a row has `x` when its value is not null, and
213
+ > under `explicit` every row has it. The planner still drops a `has(R.attr.x)` that only guards an
214
+ > access to `x`, as in `has(R.attr.x) && R.attr.x == "a"`, because that access already denies a row
215
+ > without `x`.
216
+
217
+ ### Collection storage
218
+
219
+ `size(R.attr.tags)` and `R.attr.tags[0]` need to know how the collection is stored. Declare it per
220
+ attribute:
221
+
222
+ ```python
223
+ from cerbos_sqlalchemy import CollectionColumn, get_query
224
+
225
+ get_query(
226
+ plan,
227
+ Resource,
228
+ attr_map,
229
+ collection_columns={
230
+ # PostgreSQL JSON/JSONB, a MySQL JSON column, or a SQLite JSON text column
231
+ "request.resource.attr.tags": CollectionColumn(Resource.tags, "json"),
232
+ # PostgreSQL array of text, varchar, boolean, integer or smallint
233
+ "request.resource.attr.labels": CollectionColumn(Resource.labels, "pgArray"),
234
+ },
235
+ )
236
+ ```
237
+
238
+ The storage names match the drizzle adapter's. The declaration is read in exactly three places. In
239
+ the first two it takes precedence over `attr_map` and any override:
240
+
241
+ - **`size()`** counts elements. Empty is `0`; an SQL NULL column or a non-array JSON value is
242
+ UNKNOWN, so `size(x) == 0` selects empty rows, never missing ones, and `size(x) >= 0` excludes them.
243
+ - **`x[i] == literal`** / **`x[i] != literal`** — string, number, boolean or `null` literal, constant
244
+ non-negative index, either operand order, under logical operators. JSON types are kept (`"1"` is not
245
+ `1`; `true` is not `1` even on SQLite); numbers compare as doubles. An absent element is UNKNOWN,
246
+ so it stays excluded under negation. A null *element* is a value: `[null][0] == null` is true.
247
+ PostgreSQL arrays are read through `to_jsonb`, so a non-1 lower bound still reads the element CEL does.
248
+
249
+ The third applies only to an attribute `attr_map` does **not** map, so a declaration added for
250
+ `size()` and indexing never changes how an existing relation answers membership:
251
+
252
+ - **`literal in x`** / **`hasIntersection(x, [literals])`**, either operand order, for string,
253
+ number, boolean and `null` literals. Each literal matches only an element of its own JSON type, as
254
+ CEL's heterogeneous equality does: `"2" in [2]` is false, and `hasIntersection(x, ["2", 3])`
255
+ matches on the `3` alone. An SQL NULL column or a non-array JSON value is UNKNOWN, so a negated
256
+ membership still excludes it. A column, an expression, or a list/map literal as the element raises.
257
+
258
+ Everything else over a declared element raises: a negative, fractional or dynamic index, ordering, a
259
+ projection like `x[0].name`, and comparison with a list or map literal. Elsewhere the attribute
260
+ still resolves through `attr_map`. The column must hold exactly the list you send to Cerbos, null
261
+ elements included.
262
+
263
+ The SQL is picked per dialect at compile time. SQLite (JSON1), PostgreSQL and MySQL 8.0.17+
264
+ (`"json"` only) are supported; any other dialect raises `CompileError`.
265
+
266
+ ### Operator overrides
267
+
268
+ `operator_override_fns` replaces the handler for an operator — for a more idiomatic SQL form, or to
269
+ translate a collection held in a related table:
270
+
271
+ ```python
272
+ from sqlalchemy.sql.expression import any_
273
+
274
+ query = get_query(
275
+ plan,
276
+ Table1,
277
+ attr_map={"request.resource.attr.foo": Table1.foo},
278
+ operator_override_fns={
279
+ "in": lambda c, v: c == any_(v), # PostgreSQL: = ANY instead of IN
280
+ },
281
+ )
282
+ ```
283
+
284
+ The type is `dict[str, Callable[[GenericColumn, Any], GenericExpression]]`, where `GenericColumn` is
285
+ `Column | InstrumentedAttribute` and `GenericExpression` is `BinaryExpression | ColumnOperators`.
286
+
287
+ - An entry whose value is `None` uses the default handler, including inside nested expressions.
288
+ - Without `operator_override_fns`, every `attr_map` entry is validated. With an explicit mapping
289
+ (even `{}` or only `None` entries), only attributes reached outside active overrides are
290
+ validated; an override owns the operands it translates.
291
+ - `matches()` never reaches the store's regex engine (none is RE2): the pattern is lowered to
292
+ exact string predicates, or refused (["Regular expressions"](#regular-expressions)). Override it
293
+ only if your database's engine is equivalent.
294
+ - An override's intermediate value reaching a default handler raises.
295
+
296
+ For a collection in a related table, use
297
+ [`relation_overrides()`](#collections-in-a-related-table) rather than writing the macros yourself.
298
+
299
+ ### Collection macros over known values
300
+
301
+ `exists`/`all` over a collection the PDP resolves at plan time — usually a principal attribute — is
302
+ translated with no override:
303
+
304
+ ```yaml
305
+ condition:
306
+ match:
307
+ expr: P.attr.teams.exists(t, R.attr.team == t)
308
+ ```
309
+
310
+ The planner unrolls this into an `or`/`and` chain at 10 elements or fewer, and sends a literal list
311
+ above that (cerbos/cerbos#2570, cerbos/cerbos#2817). The adapter applies the same fold with no cap,
312
+ so the SQL is equivalent either side of the threshold. A bare `t` becomes the element, `t.name`
313
+ drills into it, and each body goes through the normal pipeline (overrides and NULL handling apply).
314
+ An empty list: `exists` matches nothing, `all` matches everything. `exists_one` counts the bodies
315
+ that hold, `size(list.filter(t, ...))` counts them as a number, and `x in list.map(t, ...)` is an
316
+ `==` against each mapped body; CEL raises if any body raises, so each of these is UNKNOWN where
317
+ any body is. `except` over a literal list is still refused.
318
+
319
+ A list the plan builds from attributes (`[R.attr.a, R.attr.b].exists(s, s == "x")`) folds the same
320
+ way, with each element substituted into the body. Building the list evaluates every element, so an
321
+ element that raises in CEL (a missing attribute, or an expression over one) makes the whole macro
322
+ raise even beside a match: the folded filter is UNKNOWN for that row. `in` over a built list is an
323
+ `==` per element under the same guard, `x in (cond ? A : B)` is taken per branch, and `x in A + B`
324
+ is `x in A || x in B`.
325
+
326
+ `exists_one`, `filter`, `map` and `except` over a literal list raise, as does a `t.path` the element
327
+ doesn't carry, a map or list element, and a two-variable comprehension (`exists(i, v, ...)`), whose
328
+ index or map key has no SQL lowering. Macros over a related table (`R.attr.tags.exists(...)`) need
329
+ [`relation_overrides()`](#collections-in-a-related-table).
330
+
331
+ ### Collections in a related table
332
+
333
+ Map the collection attribute to a `Relation`, map each lambda variable's fields to the element
334
+ table's columns, and pass `relation_overrides()`:
335
+
336
+ ```python
337
+ from cerbos_sqlalchemy import Relation, get_query, relation_overrides
338
+
339
+ attr_map = {
340
+ "request.resource.attr.tags": Relation(
341
+ [Tag.resource_id == Resource.id],
342
+ correlate=[Resource],
343
+ ),
344
+ # The lambda variable in `R.attr.tags.exists(t, t.name == "public")`.
345
+ "t.name": Tag.name,
346
+ # A list of strings (`"public" in R.attr.tagNames`) needs the member column.
347
+ "request.resource.attr.tagNames": Relation(
348
+ [Tag.resource_id == Resource.id],
349
+ correlate=[Resource],
350
+ member=Tag.name,
351
+ ),
352
+ }
353
+
354
+ query = get_query(
355
+ plan, Resource, attr_map, operator_override_fns=relation_overrides()
356
+ )
357
+ ```
358
+
359
+ `Relation(correlation, correlate=(), *, member=None, hop_correlation=())`:
360
+
361
+ - `correlation` joins an element row to the row that owns the collection, through every hop.
362
+ - `correlate` lists the entities the subqueries correlate against: the queried table, plus every
363
+ enclosing lambda's table for a nested collection (`c.subCategories` inside `categories`).
364
+ SQLAlchemy auto-correlates only with the immediately enclosing `SELECT`.
365
+ - `member` is the element column `in` and `hasIntersection` compare.
366
+ - `hop_correlation` names the predicates that cross a to-one parent; see
367
+ [`require_hops`](#require_hops-the-one-hazard-with-a-library-helper).
368
+
369
+ `relation_overrides()` translates `exists`, `all`, `exists_one`, `size()`, `in`,
370
+ `hasIntersection`, `size(filter(...))`, `x in filter(...)`, `x in map(...)` and
371
+ `hasIntersection(map(...), [...])` over a `Relation`. Each is three-valued: an element whose body is
372
+ SQL NULL is a CEL error, which `exists` absorbs only beside a true element and `all` only beside a
373
+ false one, so `!tags.exists(t, t.name == "x")` excludes a row with a nameless tag, as the PDP does.
374
+ A plain `EXISTS (... WHERE body)` reads that tag as false and its negation selects the row. `in`,
375
+ `size()` and `hasIntersection` over anything that is not a `Relation` fall back to the default
376
+ handler. The dict is new on each call, so merge your own overrides into it.
377
+
378
+ The conformance harness runs exactly these overrides, so the corpus proves them.
379
+
380
+
381
+ ### Regular expressions
382
+
383
+ CEL's `matches()` is RE2, and no store's regex dialect is: MySQL's ICU engine lets `$` match before a
384
+ trailing newline, PostgreSQL's differs in classes and flags, and SQLite has none. So the pattern is
385
+ never handed to the store. The adapter parses it and lowers it only when what it matches can be said
386
+ with exact string predicates:
387
+
388
+ - a finite set of literals, under anchors or not: `^(ab|b)$` is `IN ('ab', 'b')`, `^h` and `\d` are
389
+ `startsWith`/`contains` over each literal, `(?i)` folds ASCII case (and `k`/`s` to KELVIN SIGN and
390
+ LONG S, as RE2 does);
391
+ - every character drawn from a set of at most 64, with a minimum count: `^[ab]+$`, `^\s*$`,
392
+ `^[[:alpha:]]+$`;
393
+ - a prefix and a suffix around one run of non-newline characters: `^a.*b$`, `^.{8,}$`.
394
+
395
+ A pattern RE2 rejects (a backreference, a lookahead, `a**`, a count above 1000) is an evaluation
396
+ error in CEL, so it is UNKNOWN for every row and denies under both polarities. Anything else (a
397
+ negated class, an anchor inside the pattern, a repetition over an unbounded group) raises
398
+ `UnsupportedPlanError`. A missing receiver, or one that is not a string, is UNKNOWN.
399
+
400
+ ### Transports
401
+
402
+ `get_query` accepts the HTTP client's `PlanResourcesResponse` or the gRPC client's protobuf one.
403
+ They behave identically except for a constant zero divisor (`x / -0.0`): only gRPC keeps the sign of
404
+ the zero, so only gRPC translates it; over HTTP, whose JSON renders `-0.0` as `-0` and decodes it to
405
+ the integer `0`, it raises `UnsupportedPlanError`.
406
+
407
+ ### Async
408
+
409
+ `get_query` does no I/O. Execute the `Select` however you already do, including `AsyncSession` or
410
+ `AsyncConnection`:
411
+
412
+ ```python
413
+ async with AsyncSession(async_engine) as session:
414
+ rows = (await session.execute(get_query(plan, Resource, attr_map))).scalars()
415
+ ```
416
+
417
+ Plan with the SDK's async client, or run the sync one off the event loop.
418
+
419
+ ## Correctness requirements
420
+
421
+ ### Database collation requirements
422
+
423
+ CEL string and hierarchy comparisons are byte-exact, and CEL orders strings by code point. The
424
+ adapter does not trust the column's collation for that:
425
+
426
+ - **MySQL:** every comparison, membership test and `LIKE` over a `String` column or a string
427
+ literal runs under `COLLATE utf8mb4_0900_bin`, which is byte-exact and NO PAD, so the default
428
+ `utf8mb4_0900_ai_ci` (on the column or on the connection) cannot make `One` match `one`. String
429
+ columns must use the `utf8mb4` character set, and a comparison over a column whose own collation
430
+ differs cannot use that column's index.
431
+ - **PostgreSQL:** equality is exact under any deterministic collation and is left alone. Every
432
+ ordering (`<`, `<=`, `>`, `>=`) over a string runs under `COLLATE "C"`, since a linguistic
433
+ collation such as `en_US.UTF-8` sorts `"One"` after `"a"`
434
+ ([#489](https://github.com/cerbos/query-plan-adapters/issues/489)). Avoid nondeterministic ICU
435
+ collations and `citext`.
436
+
437
+ The conformance MySQL leg runs under the server default, and the PostgreSQL leg under ICU's
438
+ `en-US`, so the corpus proves both on every run.
439
+
440
+ On SQLite a column collation does not help: SQLite's `LIKE` ignores it and folds ASCII case unless
441
+ the connection sets `PRAGMA case_sensitive_like = ON`. Without the pragma, `contains`, `startsWith`,
442
+ `endsWith` and hierarchy-prefix predicates **over-grant** (`R.attr.name.startsWith("o")` matches
443
+ `One`). The adapter does not own the connection, so set the pragma on every one it opens, as the
444
+ conformance harness does:
445
+
446
+ ```python
447
+ from sqlalchemy import create_engine, event
448
+
449
+ engine = create_engine("sqlite:///app.db")
450
+
451
+
452
+ @event.listens_for(engine, "connect")
453
+ def _case_sensitive_like(dbapi_connection, _connection_record):
454
+ cursor = dbapi_connection.cursor()
455
+ cursor.execute("PRAGMA case_sensitive_like = ON")
456
+ cursor.close()
457
+ ```
458
+
459
+ For an async engine, listen on `async_engine.sync_engine`.
460
+
461
+ ### Timestamps
462
+
463
+ Timestamp literals must be strict RFC 3339, within CEL's year 0001–9999 range, and exactly
464
+ representable at microsecond precision (discarded fractional digits must be zero); the mapped column
465
+ and database must preserve microseconds. A temporal attribute read outside `timestamp()` raises:
466
+ CEL sees the RFC 3339 string the application sent, which a stored timestamp no longer spells, and
467
+ has no overload comparing that string with a timestamp. Compare instants with `timestamp()` on both
468
+ operands.
469
+
470
+ `timestamp(R.attr.x) + duration("86400s")` (or `-`) compared with a timestamp literal is rewritten
471
+ to compare the column with the literal shifted the other way, guarded so a row whose sum leaves
472
+ CEL's range stays denied. Durations must be exact at microsecond precision. `timeSince()` raises:
473
+ the planner leaves it unevaluated, and the plan carries no instant to measure from.
474
+
475
+ ## Supported operators
476
+
477
+ | Shape | Default | Otherwise |
478
+ | --- | --- | --- |
479
+ | Comparisons, logical operators, value-first and field-to-field forms, ternaries | translated | — |
480
+ | `contains`, `startsWith`, `endsWith` | escaped `LIKE` | — |
481
+ | `+`, `-`, `*`, `/` by a constant | translated | — |
482
+ | `/` by a column | refused, unless the numerator is that column or a constant zero (a zero divisor then gives NaN, which has no sign) | an override |
483
+ | `%` | refused: CEL defines it only over integers, and attribute numbers are doubles | an override |
484
+ | `string()` over a text or boolean column | translated (a boolean through a `CASE` that spells `'true'`/`'false'`) | — |
485
+ | `string()` over a numeric column | refused: CEL prints Go's shortest `%g` form (`1e+06`, `-0`) | an override matching your database |
486
+ | `int()`, `double()` | refused | an override matching your database |
487
+ | `size()` over a string column | `LENGTH` (`CHAR_LENGTH` on MySQL, whose `LENGTH` counts bytes) | — |
488
+ | `upperAscii()` | a `REPLACE` per ASCII letter (`UPPER` also folds non-ASCII letters on PostgreSQL and MySQL); compared with a string literal, only the literal's own letters, which keeps SQLite before 3.46 inside its parser stack | — |
489
+ | `m["key"]` over a map attribute | read as `m.key` when `attr_map` maps that path | — |
490
+ | `{"k": v, ...}[R.attr.x] == literal`, `!=` (a map literal read at an attribute key) | the keys whose value answers it, UNKNOWN for a key outside the map | — |
491
+ | `timestamp(x) ± duration(...)` against a timestamp literal | the literal shifted instead | — |
492
+ | `timeSince()` | refused: the plan carries no evaluation instant | — |
493
+ | `size()` over a JSON or PostgreSQL array column | refused until declared | `collection_columns` |
494
+ | `x[i] == literal`, `x[i] != literal` over a JSON or PostgreSQL array column | refused until declared | `collection_columns` |
495
+ | `literal in x`, `hasIntersection(x, [literals])` over a JSON or PostgreSQL array column | refused until declared | `collection_columns`, for an attribute `attr_map` does not map |
496
+ | `exists`, `all` over a literal list (a principal attribute) or a list built from attributes | folded | — |
497
+ | `in` over a list built from attributes, a ternary of lists, or a concatenation `A + B` | translated per element, branch or operand | — |
498
+ | `exists`, `all`, `exists_one`, `filter`, `map`, `in`, `hasIntersection`, `size()` over a related table | — | `relation_overrides()` over a `Relation` |
499
+ | `index` over any other storage | refused | an `index` override |
500
+ | `exists_one` over a literal list, `size(filter(...))` and `in` over `map(...)` of one | folded, UNKNOWN where any body raises | — |
501
+ | `matches()` whose pattern is a finite set of literals under anchors, every character from a set, or a prefix and suffix around `.*` | translated as exact string predicates | — |
502
+ | `matches()` with any other pattern | refused | an override, only if your engine matches RE2 |
503
+ | `==`, `!=` between a string, number or boolean column and a list or map literal | false (true for `!=`) where the column is present | — |
504
+ | Timestamps, hierarchies | translated | — |
505
+
506
+ Numeric `size()` and string operations keep CEL's type errors rather than allowing SQL coercion.
507
+ Constant NaN ordering is false and its negation true (Cerbos 0.55; under 0.54 it was an evaluation
508
+ error and stayed denied under negation). A bare boolean column is accepted as a whole condition.
509
+
510
+ ## Conformance contract
511
+
512
+ The adapter is replayed against the shared [conformance corpus](../conformance/README.md): every
513
+ recorded plan from Cerbos PDP 0.57.0 and 0.56.0 is served by a stub PDP and fetched through the SDK's
514
+ HTTP `CerbosClient`, so it arrives as your application receives it, then translated with one mapping,
515
+ executed on SQLite (through a `Connection` and through an `AsyncSession`), PostgreSQL and MySQL
516
+ (`utf8mb4_0900_bin`), and the returned ids are compared with the decisions the PDP recorded. The
517
+ collections are stored as JSON on every store; the cases that read a collection declared in
518
+ `collection_columns` run once more on PostgreSQL with them stored as arrays (`pgArray`). The results
519
+ are the same on every store. For the current PDP, 0.57.0, where the total is every golden case
520
+ recorded in that tier:
521
+
522
+ | Tier | Passed / total |
523
+ | --- | --- |
524
+ | core | 32 / 32 |
525
+ | extended | 91 / 110 |
526
+ | adversarial | 409 / 546 |
527
+
528
+ Every case that does not pass is either refused with `UnsupportedPlanError` (81 cases) or is
529
+ skipped because its golden file records a planner divergence, which no adapter can pass and the
530
+ harness does not compare. Under 0.57.0 those are three extended cases and four adversarial cases:
531
+ `arithmetic/add/int-literal-plus-constant` and
532
+ `arithmetic/add/int-literal-negated` (the planner drops the int type of the literal in
533
+ `R.attr.x + 1`, while `check()` has no double + int overload and denies every row, so write `1.0`),
534
+ three
535
+ `composition/*` cases whose DENY condition reads `aNumber`, which j2 lacks: the plan's `not(...)` of
536
+ it denies j2, while `check()` receives `aNumber` as absent and treats the erroring DENY as not
537
+ matching ([#530](https://github.com/cerbos/query-plan-adapters/issues/530)), and
538
+ `type-mismatch/in/number-field-in-scalar-principal` and `type-mismatch/in/string-field-in-dyn-string`
539
+ (the planner rewrites `in` over a scalar container to `==`, which `check()` has no overload for;
540
+ [#596](https://github.com/cerbos/query-plan-adapters/issues/596)). On 0.56.0, `null/has/missing-attribute` and `null/has/composed-with-comparison` are skipped too:
541
+ that planner folds `has()` on an omitted attribute to true, while `check()` denies the row; 0.57.0
542
+ keeps `has()` in the plan.
543
+ [`conformance-ledger.json`](conformance-ledger.json) lists each refused case with the mechanism that
544
+ rules it out.
545
+
546
+ ### Refusals
547
+
548
+ A plan shape the adapter cannot express raises `cerbos_sqlalchemy.UnsupportedPlanError`, never a
549
+ best-effort filter. It subclasses `ValueError`, which these refusals raised before it existed; the
550
+ refusal for a relation-mapped attribute that no operator override consumes is also a `TypeError`, as
551
+ it was before. Invalid configuration (an unknown null representation, an unmapped attribute, a missing
552
+ `table_mapping`) keeps raising `ValueError`, `KeyError` or `TypeError`. An operator override that
553
+ cannot translate what it was handed should raise `UnsupportedPlanError` too.
554
+
555
+ ## Mapping hazards
556
+
557
+ The conformance contract proves the *plan* side. The other half is the *mapping*: **the rows a
558
+ subquery reads must be the rows the application put into the resource attributes.** The shared
559
+ corpus catalogues six ways that breaks, and every adapter records a position on each.
560
+
561
+ **A `Relation` is only the predicates you give it.** A collection-valued attribute reaches its rows
562
+ through the correlation you write, so every hazard below but the last is yours. Which ones apply
563
+ depends on how you write it:
564
+
565
+ - Through a mapped **`relationship()`** (`Model.rel.any(...)`, `Model.rel.has(...)`,
566
+ `select(...).join(Model.rel)`), SQLAlchemy applies the `primaryjoin` and, for a
567
+ single-table-inheritance target, the
568
+ [discriminator](https://docs.sqlalchemy.org/en/20/orm/queryguide/inheritance.html#single-inheritance-mappings).
569
+ - Through a **`Relation`**, or a hand-written correlated `select()` over columns (what the
570
+ conformance harness does), none of that applies.
571
+
572
+ Check both against the SQLAlchemy version you run.
573
+
574
+ | Hazard | Position | Mechanism to check |
575
+ |---|---|---|
576
+ | Filtered association | **Caller-owned** | `relationship(primaryjoin=…)` and `relationship(secondaryjoin=…)`. `.any()`/`.has()` apply them; a hand-written `select()` over the target's columns does not, and must repeat the predicate in its own `where()` |
577
+ | Default scope on the target model | **Caller-owned** | A soft-delete column (`deleted_at IS NULL`), a tenant column, a `published` flag, or a `with_loader_criteria` on the session. SQLAlchemy applies none of them to a subquery you build yourself |
578
+ | Subtype discrimination | **Caller-owned** | `polymorphic_identity` on a single-table-inheritance subclass. `select(Subclass)` carries the discriminator; `select(literal(1)).where(subclass_table.c.x == …)` over the shared table does not, and sees sibling subtypes |
579
+ | To-one relation used as a collection | **Caller-owned** | A `relationship(uselist=False)` whose foreign key has no unique constraint. Nothing makes the database enforce the single row the application saw — add the constraint |
580
+ | Composite association key | **Caller-owned** | A multi-column foreign key. An override is arbitrary SQLAlchemy, so a composite key *is* expressible — and nothing stops you writing half of it. Conjoin every column pair |
581
+ | Absent to-one parent | **Reproduced by `Relation(hop_correlation=…)`**, and proved by the corpus (`relation/all/to-one-chain`, `relation/bare-attribute/negated-one-hop-boolean` and siblings) | `hop_correlation`, which `relation_overrides()` passes to `cerbos_sqlalchemy.require_hops` — see below. Set it on every `Relation` that reaches a COLLECTION through an intermediate to-one hop. A SCALAR read through a to-one hop needs nothing: map it to a correlated scalar subquery and an absent hop is SQL NULL, excluded under both polarities. `attr_map` accepts any column expression for this, and it needs no `table_mapping` ([#375](https://github.com/cerbos/query-plan-adapters/issues/375)) |
582
+
583
+ ### `require_hops`: the one hazard with a library helper
584
+
585
+ Every intermediate segment of `a.b.c` is a to-one parent (CEL cannot dot through a list). When it is
586
+ absent, the application sends no attribute and CEL denies — but a subquery rooted at the resource
587
+ row can't tell an absent parent from a childless one, so `all` reads TRUE, `!exists` reads TRUE and
588
+ the count reads 0, each admitting denied rows ([#309](https://github.com/cerbos/query-plan-adapters/issues/309)).
589
+
590
+ ```python
591
+ # `mainCategory.subCategories`: the collection is reached THROUGH the category hop.
592
+ attr_map["request.resource.attr.mainCategory.subCategories"] = Relation(
593
+ [SubCategory.category_id == Category.id, Category.resource_id == Resource.id],
594
+ correlate=[Resource],
595
+ hop_correlation=[Category.resource_id == Resource.id],
596
+ )
597
+ ```
598
+
599
+ `relation_overrides()` routes every answer over a `Relation` through
600
+ `require_hops(expression, hop_correlation, correlate=())`, which wraps it in a `CASE` with **no
601
+ `ELSE`**: a missing hop yields NULL, which stays excluded under both polarities. With an empty
602
+ `hop_correlation` (a direct relation) it returns the expression unchanged, so `!tags.exists(...)`
603
+ over zero tags is still TRUE.
604
+
605
+ An override of your own over a chain must route **every** operator through it, not only the
606
+ macros: a bare `EXISTS` is FALSE for an absent parent and its negation TRUE, which is how
607
+ membership, `hasIntersection` ([#315](https://github.com/cerbos/query-plan-adapters/issues/315)) and
608
+ `!(size(chain) > 0)` ([#316](https://github.com/cerbos/query-plan-adapters/issues/316)) over-granted.
609
+ It must also keep a NULL body NULL, as `relation_overrides()` does; nothing checks either.
610
+
611
+ ## Behaviour changes
612
+
613
+ - Added ([#527](https://github.com/cerbos/query-plan-adapters/issues/527)): `Relation` and
614
+ `relation_overrides()`, the conformance harness's three-valued relation macros, now shipped. This
615
+ README used to show a hand-written `exists` override that put the body in `.where(body)`, which
616
+ reads a NULL body as false, so `!tags.exists(...)` selected rows the PDP denies. Replace overrides
617
+ copied from it with `relation_overrides()`. A widening.
618
+ - Fixed: a string, number or temporal column read where CEL needs a boolean (`not R.attr.aString`, `R.attr.aString && R.attr.aBool`) renders as `NULL`, CEL's type error, which `AND` and `OR` absorb as `&&` and `||` absorb it. PostgreSQL rejected the query, and SQLite and MySQL over-granted by reading the text as a number.
619
+ - **Breaking:** `null_attribute_representation` defaults to `"omitted"`, where it defaulted to
620
+ `"explicit"`. A caller that sends explicit nulls and set nothing now gets `x == null` matching no
621
+ row where it rendered `IS NULL`, and a refusal for the other null operands; pass
622
+ `null_attribute_representation="explicit"` to keep the old output
623
+ ([#499](https://github.com/cerbos/query-plan-adapters/issues/499),
624
+ [ADR 0011](../docs/adr/0011-denial-fails-closed-in-the-result.md)).
625
+ - [#500](https://github.com/cerbos/query-plan-adapters/issues/500), found by running the corpus on
626
+ PostgreSQL and MySQL:
627
+ - `+`, `-` and `*` read an integer or `Numeric` column as a double, as CEL reads every attribute
628
+ number. PostgreSQL used to multiply in exact `numeric`, so `R.attr.aNumber * 0.1 == 0.3` was true
629
+ for `3` (CEL: `0.30000000000000004`) — an over-grant.
630
+ - `size()` of a string counts characters on MySQL (`CHAR_LENGTH`), where `LENGTH` counted bytes.
631
+ - An ordering comparison between mismatched types inside a ternary no longer fails on PostgreSQL
632
+ with `CASE types text and boolean cannot be matched`.
633
+ - **Widening:** `collection_columns` storage `"json"` renders on MySQL 8.0.17+, where it used to
634
+ raise `CompileError`.
635
+ - [#545](https://github.com/cerbos/query-plan-adapters/issues/545): an ordering between a boolean
636
+ column and a boolean literal (`R.attr.aBool < true`) now translates, binding the literal as a
637
+ typed parameter, where SQLAlchemy used to raise `ArgumentError` at translation. CEL orders bools
638
+ `false < true`, as SQL's boolean does. A widening.
639
+ - **Breaking:** shapes that used to return a wrong filter now raise `UnsupportedPlanError`:
640
+ - `string()` over a numeric column. CEL prints an attribute double in Go's shortest `%g` form
641
+ (`1e+06`, `2`, `-0`), where `CAST` prints `1000000` or `2.0`, and SQL cannot keep the sign of a
642
+ zero, so `string(R.attr.aDouble) == "1e+06"` under-granted.
643
+ - `/` by a column, unless the numerator is that column or a constant zero. A zero divisor makes
644
+ CEL's quotient an infinity carrying the zero's sign, which SQL cannot read (`-0.0 = 0.0`, and
645
+ SQLite stores `-0.0` as `0.0`); the column used to be assumed `+0.0`, which over-granted.
646
+ - `%` over a column. CEL defines `%` only over integers and attribute numbers are doubles, so it is
647
+ a no-such-overload error; SQL's remainder made `!(R.attr.aNumber % 2 == 1)` true for most rows.
648
+ - A scalar column compared with a list or map literal (`R.attr.aString == ["same"]`), which used to
649
+ bind the list as a parameter and fail, or be coerced, at execution.
650
+ - Translation refusals now raise `cerbos_sqlalchemy.UnsupportedPlanError`, a `ValueError` subclass
651
+ (also a `TypeError` where the refusal raised one before), so existing handlers keep catching them.
652
+ Not breaking.
653
+ - **Breaking** ([#509](https://github.com/cerbos/query-plan-adapters/issues/509)): a collection macro
654
+ nested over the collection an enclosing macro iterates, whose body reads the enclosing element
655
+ (`tags.exists(t, tags.exists(u, u.name != t.name))`), now raises. `attr_map` binds a lambda
656
+ variable's fields by name and an override never sees the scope, so both subqueries range over the
657
+ one unaliased table and the body would compare each element with itself — under negation, an
658
+ over-grant — for any caller that mapped the inner variable.
659
+ - A literal list member the column's type cannot equal is dropped from `in` (`R.attr.aNumber in
660
+ ["5", 2]` compares `2` alone), as `==` already answered it, where it used to be bound into
661
+ `IN (...)` and converted by the store (`'5' = 5` is TRUE on SQLite) — an over-grant, since CEL's
662
+ `5 in ["5"]` is false. A list left with no comparable member is false for a present value.
663
+ - **Widening:** literal membership (`in`, `hasIntersection`) over a declared collection that
664
+ `attr_map` does not map now translates, where it used to raise `Attribute does not exist in the
665
+ attribute column map`. An attribute `attr_map` maps resolves membership exactly as before.
666
+ - **Breaking** ([#227](https://github.com/cerbos/query-plan-adapters/issues/227)): `size()` over a JSON
667
+ or array column not declared in `collection_columns` now raises; it used to return `LENGTH()` of the
668
+ column's text. `index` over undeclared storage raises a message naming the missing declaration
669
+ instead of `Unrecognised operator: index`.
670
+ - [#418](https://github.com/cerbos/query-plan-adapters/issues/418): `string()` over a boolean column now
671
+ translates (to a `CASE` spelling `'true'`/`'false'`, with NULL kept UNKNOWN) where it used to raise.
672
+ `CAST` would render `'1'` on SQLite and MySQL.
673
+ - **Breaking** ([#414](https://github.com/cerbos/query-plan-adapters/issues/414)): numeric `size()` and
674
+ string operations preserve CEL type errors instead of SQL coercion; NaN ordering is false and its
675
+ negation true (Cerbos 0.55); membership preserves the declared NULL convention inside lambda bodies
676
+ and against stored collections; bare temporal-attribute comparisons raise (use `timestamp()`).
677
+ - [#388](https://github.com/cerbos/query-plan-adapters/issues/388): a bare boolean column is accepted as
678
+ the whole condition (e.g. `R.attr.aBool`), where it used to be refused at the root. A widening.
679
+ - A numeric literal outside the int64 range (`R.attr.aDouble < -1e19`) is bound as a float; SQLite
680
+ used to raise `OverflowError` at execution. PostgreSQL is unchanged. A widening.
681
+ - [#387](https://github.com/cerbos/query-plan-adapters/issues/387):
682
+ - `hasIntersection` is order-insensitive like `eq`/`ne`/`in`, so a value-first spelling reaches an
683
+ override with the column first. A widening.
684
+ - **Breaking:** an override's intermediate value reaching a default handler raises; it used to
685
+ compare to a bare `False` and filter out every row.
686
+ - **Breaking:** the non-boolean check that refuses `filter()`/`map()` at the root also runs on every
687
+ `and`/`or`/`not` operand, raising the adapter's message instead of SQLAlchemy's WHERE-role error.
688
+
689
+ ## Example application
690
+
691
+ [`example/`](example/) installs the built wheel and runs the shared
692
+ [demo domain](../demo/README.md) against a live PDP, including pagination and the adapter's `Select`
693
+ composed with an application-owned `.where()` across all three plan kinds:
694
+
695
+ ```bash
696
+ # from the repository root
697
+ demo/scripts/run-example.sh sqlalchemy
698
+ ```
699
+
700
+ ## Development
701
+
702
+ | Suite | Checks | Needs |
703
+ | --- | --- | --- |
704
+ | `tests/test_translator.py` | caller options over recorded corpus plans: null representation, overrides, collection storage, transports, model styles | nothing — plans from `conformance/golden/` |
705
+ | `tests/test_query.py`, `tests/test_relations.py` | plans the planner cannot produce; options no policy can reach | nothing |
706
+ | `tests/test_adversarial_conformance.py` | returned rows match the recorded decisions, or the ledger's refusal is raised: every case on SQLite (sync and async), PostgreSQL and MySQL, and the cases that read a `collection_columns` declaration once more on PostgreSQL with the collections stored as native arrays. CI runs it under SQLAlchemy 1.4 and 2.x | SQLite, and Docker for PostgreSQL and MySQL, pinned in [`POSTGRES_IMAGE`](POSTGRES_IMAGE) and [`MYSQL_IMAGE`](MYSQL_IMAGE) |
707
+
708
+ ```bash
709
+ pdm install -G :all
710
+ pdm run test # all three
711
+ pdm run format # isort + ruff format
712
+ pdm run lint # ruff check --fix
713
+ ```
714
+
715
+ Without PDM installed, run the same commands through the [pyprojectx](https://pyprojectx.github.io/)
716
+ wrapper, `./pw` (`pw.bat` on Windows), which installs PDM, ruff and isort into `.pyprojectx/` on
717
+ first use: `./pw install`, `./pw test`, `./pw format`, `./pw lint`, or `./pw pdm <command>`. CI runs
718
+ `format` and `lint` on the SQLAlchemy 2.x leg and fails if they leave a diff.
719
+
720
+ CI links Ubuntu 24.04's SQLite (3.45), usually older than the one a developer's Python bundles, and
721
+ before 3.46 a deeply nested expression overflows SQLite's parser stack. `scripts/test-ci-sqlite.sh`
722
+ runs every suite that needs no Docker store against that SQLite, from `pdm.lock`, in a container.