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.
- cerbos_sqlalchemy-0.5.0/PKG-INFO +722 -0
- cerbos_sqlalchemy-0.5.0/README.md +703 -0
- {cerbos-sqlalchemy-0.3.1 → cerbos_sqlalchemy-0.5.0}/pyproject.toml +40 -10
- cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/__init__.py +21 -0
- cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/_null_conventions.py +219 -0
- cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/_operators.py +1403 -0
- cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/_plan.py +296 -0
- cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/_regex.py +580 -0
- cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/_translator.py +1093 -0
- cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/collection_storage.py +681 -0
- cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/errors.py +16 -0
- cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/py.typed +0 -0
- cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/query.py +358 -0
- cerbos_sqlalchemy-0.5.0/src/cerbos_sqlalchemy/relations.py +306 -0
- cerbos_sqlalchemy-0.5.0/tests/conftest.py +202 -0
- cerbos_sqlalchemy-0.5.0/tests/corpus.py +713 -0
- cerbos_sqlalchemy-0.5.0/tests/test_adversarial_conformance.py +442 -0
- cerbos_sqlalchemy-0.5.0/tests/test_query.py +1302 -0
- cerbos_sqlalchemy-0.5.0/tests/test_relations.py +85 -0
- cerbos_sqlalchemy-0.5.0/tests/test_translator.py +591 -0
- cerbos_sqlalchemy-0.5.0/tests/typing/check_types.py +66 -0
- cerbos-sqlalchemy-0.3.1/PKG-INFO +0 -149
- cerbos-sqlalchemy-0.3.1/README.md +0 -132
- cerbos-sqlalchemy-0.3.1/src/cerbos_sqlalchemy/__init__.py +0 -7
- cerbos-sqlalchemy-0.3.1/src/cerbos_sqlalchemy/query.py +0 -152
- cerbos-sqlalchemy-0.3.1/tests/conftest.py +0 -175
- 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.
|