surreal-orm-lite 0.35.0__tar.gz → 0.35.3__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 (49) hide show
  1. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/CHANGELOG.md +91 -0
  2. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/PKG-INFO +51 -23
  3. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/README.md +50 -22
  4. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/cache.py +16 -1
  7. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/model_auth.py +50 -20
  8. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/model_base.py +55 -36
  9. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/schema.py +17 -11
  10. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/search.py +13 -0
  11. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/transaction.py +26 -0
  12. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/.gitignore +0 -0
  13. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/LICENSE +0 -0
  14. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/Makefile +0 -0
  15. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/_sdk.py +0 -0
  16. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/aggregations.py +0 -0
  17. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/auth.py +0 -0
  18. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/changefeed.py +0 -0
  19. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/concurrency.py +0 -0
  20. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/connection_config.py +0 -0
  21. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/connection_manager.py +0 -0
  22. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/constants.py +0 -0
  23. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/decoding.py +0 -0
  24. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/define_parser.py +0 -0
  25. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/edge.py +0 -0
  26. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/embedded.py +0 -0
  27. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/encoding.py +0 -0
  28. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/enum.py +0 -0
  29. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/exceptions.py +0 -0
  30. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/functions.py +0 -0
  31. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/geo.py +0 -0
  32. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/introspection.py +0 -0
  33. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/live.py +0 -0
  34. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/model_ddl.py +0 -0
  35. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/model_generator.py +0 -0
  36. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/py.typed +0 -0
  37. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/q.py +0 -0
  38. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/query_set.py +0 -0
  39. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/routing.py +0 -0
  40. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/schema_state.py +0 -0
  41. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/signals.py +0 -0
  42. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/subquery.py +0 -0
  43. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/surql_literal.py +0 -0
  44. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/testing/__init__.py +0 -0
  45. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/testing/database.py +0 -0
  46. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  47. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/time_travel.py +0 -0
  48. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/types.py +0 -0
  49. {surreal_orm_lite-0.35.0 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,97 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.35.3] - 2026-10-23
9
+
10
+ Follow-ups to the review of v0.35.0's full-text search (#304): the warning of `define_indexes()`
11
+ names every index it rebuilds, and `define_indexes(tx=…)` refuses to define an index in a
12
+ transaction that has already written records to the model's table, which SurrealDB servers would
13
+ leave out of the index. No new public API.
14
+
15
+ ### Changed
16
+
17
+ - **`define_indexes(tx=…)` raises `SurrealDbError` after an ORM write to the model's table**
18
+ (#304). SurrealDB servers do not index the records a transaction wrote before the index was
19
+ defined: they stay out of it after the commit, and a search misses them. When an index must be
20
+ defined or redefined and the block has already written records to the model's table with the
21
+ ORM (`save()`, `objects(tx=…).bulk_create()`, …), `define_indexes(tx=…)` now raises before any
22
+ DDL, naming the model and the table; the refusal does not fail the transaction. Definitions
23
+ (`define_table(tx=…)`, `define_relation(tx=…)`, `remove_index(tx=…)`, …), a write to another
24
+ table and a call with nothing to apply do not count; a raw `tx.add()` is not tracked. Call
25
+ `define_indexes()` without `tx=` first, then write in the transaction. Earlier releases accepted
26
+ the call and the records written before it were missing from the index on SurrealDB 2.x and 3.x.
27
+
28
+ ### Fixed
29
+
30
+ - **The analyzer warning of `define_indexes()` names the indexes the call redefines** (#304).
31
+ When one call redefined an analyzer and an index that uses it, the warning counted only the
32
+ indexes rebuilt with `REBUILD INDEX` (`Analyzer 'plain' redefined; 0 index(es) rebuilt:`,
33
+ naming none), although `DEFINE INDEX OVERWRITE` rebuilds the redefined index too. It now names
34
+ every index the call rebuilds, in the order applied.
35
+
36
+ ### Notes
37
+
38
+ - **Reported upstream**: a SurrealDB 3.x server leaving out of an index the records the same
39
+ transaction wrote before `DEFINE INDEX` is a server defect,
40
+ [surrealdb/surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618); 2.x behaves the
41
+ same, and the embedded engine indexes those records. README section 36 (Transactions), a row of
42
+ the "ORM behaviour: SurrealDB 2.x vs 3.x" table and one of the embedded engine's table describe
43
+ each engine's outcome, which tests pin.
44
+ - **A write after `define_indexes(tx=…)` on SurrealDB 2.x**: in the same block, a write to a table
45
+ that held records fails the commit with a retryable `SurrealDbConflictError` that a retry meets
46
+ again, a 2.x limitation; SurrealDB 3.x and the embedded engine commit and index it. Prefer
47
+ `define_indexes()` outside the block.
48
+ - Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
49
+ plus 3.1.5 for backward compatibility.
50
+
51
+ ## [0.35.2] - 2026-10-22
52
+
53
+ An auth model whose signup field is declared `Field(exclude=True)` is refused whatever its schema
54
+ mode (#299): v0.34.1 refused it only for a `SCHEMAFULL` table, and on any other table its
55
+ `update()` or `upsert()` dropped the stored password hash. No new public API.
56
+
57
+ ### Changed
58
+
59
+ - **An auth model with an excluded signup field raises `TypeError` whatever its schema mode and
60
+ `with_table`** (#299). For a model built on `AuthenticatedUserMixin` with a field SIGNUP writes
61
+ that `Field(exclude=True)` keeps out of `model_dump()` (`password: str = Field(exclude=True)`),
62
+ `table_ddl()`, `define_table()`, `access_ddl()` and `define_access()` (with or without the
63
+ table) now raise `TypeError` before any request on a `SCHEMALESS` table, with no declared schema
64
+ mode and with `with_table=False`, as v0.34.1 did for a `SCHEMAFULL` table. `signup()` and
65
+ `signin()` raise the same error before any request, so an access defined by hand cannot leave
66
+ such a record either. The message names the model and the fields in declaration order and keeps
67
+ the advice: remove `exclude=True` and leave the field out where you serialise the model instead
68
+ (`model_dump(exclude={"password"})`). A model that relied on `exclude=True` now fails at
69
+ start-up instead of losing data later. Auth models without `exclude=True`, and models that are
70
+ not auth models, render and apply as before.
71
+
72
+ ### Fixed
73
+
74
+ - **An auth model no longer loses its stored password hash at `update()` or `upsert()`** (#299).
75
+ Both replace the record with what `model_dump()` writes, so an auth model whose signup field was
76
+ declared `Field(exclude=True)` lost the stored value at its first `update()` or `upsert()`, with
77
+ no error, on a `SCHEMALESS` table (a model with neither `table_type` nor `schema_mode`) or with
78
+ `define_access(with_table=False)` over an optional column defined by hand
79
+ (`TYPE option<string>`): the hash became `NONE` and every later signin failed. With a required
80
+ column (`TYPE string`), the write was refused instead. Such a model is now refused before it
81
+ writes a record (see Changed). README section 19, "User models" and a row of "ORM behaviour:
82
+ SurrealDB 2.x vs 3.x" describe it; the behaviour is the same on both lines.
83
+
84
+ ### Notes
85
+
86
+ - **Undeclared keys in list items on SurrealDB 3.x** (#301): the 0.34.1 entry below says 3.x
87
+ keeps a key a `SCHEMAFULL` table does not define "in the items of any list of objects,
88
+ `FLEXIBLE` or not". It keeps it only in the items of a list whose items define a field, such as
89
+ a list of sub-models `define_table()` writes, and in an object inside them that defines one. It
90
+ refuses it in the items of a list that defines no item field (an `array<object>` defined by hand
91
+ without `v.*.n`), at the top level and in a sub-model outside such a list. SurrealDB's
92
+ documentation of `FLEXIBLE` says every object of a `SCHEMAFULL` table, list items included,
93
+ accepts only the keys defined for it, so do not rely on 3.x keeping such a key. README section
94
+ 35, the v0.7.0 and v0.34.0 rows of "ORM behaviour: SurrealDB 2.x vs 3.x" and the embedded
95
+ engine's "Model table DDL (v0.34.0)" row now state the exception. No ORM behaviour changes.
96
+ - Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
97
+ plus 3.1.5 for backward compatibility.
98
+
8
99
  ## [0.35.0] - 2026-10-22
9
100
 
10
101
  Full-text search: a queryset searches text with the full SurrealDB-ORM's `search()`, and scores and
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.35.0
3
+ Version: 0.35.3
4
4
  Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
5
5
  Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
6
6
  Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
@@ -1333,6 +1333,13 @@ gives such a model the same table, so the two can be called in any order.
1333
1333
  > **The password field holds the hash.** SurrealDB returns the stored record, so
1334
1334
  > `result.user.password` is `$argon2id$v=19$…`, never the plaintext you submitted.
1335
1335
 
1336
+ **Keep the password field in `model_dump()`.** SIGNUP writes every field, while `update()` and `upsert()` replace the
1337
+ record with what `model_dump()` writes: a field declared `Field(exclude=True)` (`password: str = Field(exclude=True)`)
1338
+ would lose its stored value, the password hash, and every later signin would fail. Such a model raises `TypeError`,
1339
+ naming the fields, before any request and whatever its schema mode: `access_ddl()`, `define_access()` (with or without
1340
+ the table), `table_ddl()`, `define_table()`, `signup()` and `signin()` refuse it. Remove `exclude=True` and leave the
1341
+ field out where you serialise the model instead (`model_dump(exclude={"password"})`).
1342
+
1336
1343
  #### Renewing a session (SurrealDB 3.x only)
1337
1344
 
1338
1345
  ```python
@@ -5705,13 +5712,15 @@ print(*table, sep="\n")
5705
5712
  declares its own.
5706
5713
  - A `TableType.USER` model with `extra="allow"` raises `TypeError` there (with `with_table=True`), since its table is
5707
5714
  `SCHEMAFULL`; a `server_fields` column without a constant default needs a database `DEFAULT` ("Field types" above).
5708
- - A field SIGNUP writes that `Field(exclude=True)` keeps out of `model_dump()` (`password: str = Field(exclude=True)`)
5709
- raises `TypeError` too, naming the field, before any request (with a `SCHEMAFULL` schema mode): `define_access()`
5710
- with `with_table=True` and `define_table()` both refuse it, since the table would not define it, so SurrealDB 3.x
5711
- would refuse every signup and 2.x drop the password hash, failing every signin. Remove `exclude=True` and leave the
5712
- field out where you serialise the model instead (`model_dump(exclude={"password"})`): `update()` and `upsert()`
5713
- replace the record with what `model_dump()` writes, so even over a table defined by hand (`with_table=False`) they
5714
- would be refused (a required column) or drop the hash (an optional one), failing every later signin.
5715
+ - An auth model with a field SIGNUP writes that `Field(exclude=True)` keeps out of `model_dump()`
5716
+ (`password: str = Field(exclude=True)`) raises `TypeError` too, naming the fields, before any request and whatever
5717
+ its schema mode: `table_ddl()`, `define_table()`, `access_ddl()` and `define_access()` (with or without the table),
5718
+ `signup()` and `signin()` refuse it. `update()` and `upsert()` replace the record with what `model_dump()` writes,
5719
+ so on any table (`SCHEMALESS`, or defined by hand with `with_table=False`) they would drop the password hash, failing
5720
+ every later signin, or be refused by a required column; a `SCHEMAFULL` table would not define the field either, so
5721
+ SurrealDB 3.x would refuse every signup and 2.x drop the hash. Remove `exclude=True` and leave the field out where
5722
+ you serialise the model instead (`model_dump(exclude={"password"})`). **Changed**: such a model on a `SCHEMALESS`
5723
+ table or with `with_table=False` used to be accepted, and its first `update()` or `upsert()` dropped the hash.
5715
5724
  - Upgrading: a 0.33 `TableType.USER` model's table turns `SCHEMAFULL` at its next `define_access()`; records already
5716
5725
  there are checked at their next write.
5717
5726
 
@@ -5743,12 +5752,21 @@ print(*table, sep="\n")
5743
5752
  `define_table()` writes such a list `FLEXIBLE` before 3.x; the item's typed fields are still checked. 3.x keeps those
5744
5753
  values without it. On 2.x and the embedded engine, the items of such a list then also keep a key the model does not
5745
5754
  declare, written raw or by another client (the ORM never sends one), which they drop from a list that is not
5746
- `FLEXIBLE`: a 2.x limitation, since `FLEXIBLE` there covers the whole item. 3.x keeps such a key in the items of any
5747
- list of objects, `FLEXIBLE` or not, and refuses it at the top level or in a sub-model.
5755
+ `FLEXIBLE`: a 2.x limitation, since `FLEXIBLE` there covers the whole item. 3.x keeps such a key, `FLEXIBLE` or not,
5756
+ in the items of a list of objects whose items define a field (every list of sub-models `define_table()` writes) and
5757
+ in an object inside them that defines one; it refuses it at the top level, in a sub-model outside such a list, and in
5758
+ the items of a list that defines no item field (an `array<object>` defined by hand without `v.*.n`). SurrealDB's
5759
+ [documentation of
5760
+ `FLEXIBLE`](https://surrealdb.com/docs/reference/query-language/statements/define/field#flexible-data-types) says
5761
+ every object of a `SCHEMAFULL` table, an item of a list included, accepts only the keys defined for it unless its
5762
+ field is `FLEXIBLE`: 3.x departs from it in a list whose items define a field, so a later 3.x may refuse such a key
5763
+ there too: do not rely on it.
5748
5764
  - On SurrealDB 3.x a required untyped array refuses an object item unless its items are defined
5749
5765
  (`no such field exists`): `define_table()` writes the item definition `TYPE any` (`bag.*`) on every line.
5750
5766
  - A write naming a field a `SCHEMAFULL` table does not define is refused on 3.x and dropped on 2.x and the embedded
5751
- engine ("What SurrealDB checks" above).
5767
+ engine ("What SurrealDB checks" above), except in the items of a list of objects: on 3.x of a list whose items define
5768
+ a field (every list of sub-models `define_table()` writes), on 2.x and the embedded engine of a list `define_table()`
5769
+ writes `FLEXIBLE`.
5752
5770
  - `COMPUTED` fields are SurrealDB 3.x's: `define_table()` keeps a stored one `COMPUTED`, and writes a new computed
5753
5771
  field `VALUE` on both lines.
5754
5772
  - The [2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x) and the
@@ -6016,11 +6034,12 @@ SurrealDB keeps the tokens of the records an index holds when their analyzer cha
6016
6034
  misses them — the records written afterwards use the new analyzer — until the index is rebuilt. So when
6017
6035
  `define_indexes()`, or `SurrealDBConnectionManager.define_analyzer()`, redefines an analyzer, it rebuilds every index of
6018
6036
  the database that uses it (`REBUILD INDEX`, sorted by table then index; `define_indexes()` rebuilds the model's table's
6019
- last), and logs one warning naming them (logger `surreal_orm_lite.search`). A rebuild re-reads the table: seconds
6020
- per thousands of records on SurrealDB 2.x and the embedded engine. An analyzer belongs to the database, not to a table:
6021
- declare one `Analyzer` per name (a module constant) and reference it from every index that uses it — two definitions
6022
- under one name would redefine it in turn, each time rebuilding its indexes. An unchanged index is never redefined, so
6023
- start-up never rebuilds (and, on SurrealDB 2.x, never inflates its scores).
6037
+ last), and logs one warning naming them, an index it redefines at the same time included (logger
6038
+ `surreal_orm_lite.search`). A rebuild re-reads the table: seconds per thousands of records on SurrealDB 2.x and the
6039
+ embedded engine. An analyzer belongs to the database, not to a table: declare one `Analyzer` per name (a module
6040
+ constant) and reference it from every index that uses it — two definitions under one name would redefine it in turn,
6041
+ each time rebuilding its indexes. An unchanged index is never redefined, so start-up never rebuilds (and, on SurrealDB
6042
+ 2.x, never inflates its scores).
6024
6043
 
6025
6044
  ```python
6026
6045
  PLAIN = Analyzer("plain", ["blank"], ["ascii"])
@@ -6064,9 +6083,15 @@ print(await NoteV2.objects().search(text="physics").count())
6064
6083
  So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL when an analyzer must be defined or redefined, and
6065
6084
  `define_analyzer(tx=…)` when a redefinition has indexes to rebuild (a new analyzer, or a redefinition no index uses,
6066
6085
  joins the transaction): call `define_analyzer()` without `tx=` first.
6067
- - Prefer `define_indexes()` outside the block: in a transaction that also writes to the model's table, SurrealDB may
6068
- leave out of the index a record the block wrote before the index was defined, and may fail the block on a write
6069
- after it.
6086
+ - The block must not have written to the model's table yet: SurrealDB servers do not index the records a transaction
6087
+ wrote before the index was defined, which stay out of it after the commit. It is a server defect
6088
+ ([surrealdb/surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618) on 3.x, the same on 2.x); only the
6089
+ embedded engine indexes them. So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL, naming the model and
6090
+ the table, when an index must be defined or redefined and the block has already written records to the model's table
6091
+ with the ORM (`save()`, `objects(tx=…).bulk_create()`, …). The refusal does not fail the block. `define_table(tx=…)`,
6092
+ `define_relation(tx=…)` and a write to another table do not count; a raw `tx.add()` is not tracked.
6093
+ - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6094
+ in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again.
6070
6095
  - `remove_analyzer(tx=…)` reads committed state to find the indexes that use the analyzer: an index queued earlier in
6071
6096
  a buffered block is not seen.
6072
6097
  - A search in an interactive transaction sees the transaction's writes; in a buffered one, a read raises, as every
@@ -6249,7 +6274,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
6249
6274
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
6250
6275
  on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
6251
6276
  otherwise. The full suite and every divergence below were re-verified on both new versions.
6252
- Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs.
6277
+ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5. The row added in v0.35.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
6253
6278
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
6254
6279
 
6255
6280
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -6263,7 +6288,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6263
6288
  | Cleanup on a missing target (`delete_table`) | native no-op | ORM makes it a silent no-op | v0.7.0 |
6264
6289
  | Aggregation over an empty set (`NaN` / `±inf`) | returns `0.0` / `None` | ORM normalises to `0.0` / `None` | v0.7.0 |
6265
6290
  | Namespace/db selection (`use()` ordering) | lenient (auto-creates) | strict — ORM signs in before `use()` | v0.7.0 |
6266
- | Writing a field a `SCHEMAFULL` table does not define (`CREATE`, `INSERT`, `INSERT RELATION`) | silently dropped: the record is stored without it | rejected ("Found field …, but no such field exists"): nothing is stored | v0.7.0 |
6291
+ | Writing a field a `SCHEMAFULL` table does not define (`CREATE`, `INSERT`, `INSERT RELATION`) | silently dropped: the record is stored without it; kept in the items of a list `define_table()` writes `FLEXIBLE` (a 2.x limitation) | rejected ("Found field …, but no such field exists"): nothing is stored, except in the items of a list whose items define a field (every list of sub-models), which keep it | v0.7.0 |
6267
6292
  | `upsert()` / `update_or_create()` / `get_or_create()` | same on both lines | same on both lines | v0.10.0 |
6268
6293
  | `patch()` / `atomic_append` / `atomic_set_add` / `atomic_remove` / `atomic_increment` | same on both lines (portable `array::*` fns chosen over divergent `+=`/`-=`) | same on both lines | v0.11.0 |
6269
6294
  | `retry_on_conflict` / `SurrealDbConflictError` (retryable conflict) | same type + decorator; conflicts rarer (engine serialises more), except on `CHANGEFEED` tables (section 22) | same type + decorator; conflicts are the normal optimistic-MVCC failure | v0.12.0 |
@@ -6391,7 +6416,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6391
6416
  | Model table DDL (`define_table()`: `DEFINE TABLE` + `DEFINE FIELD`) | same on both lines: one `DEFINE TABLE OVERWRITE` and one `DEFINE FIELD OVERWRITE` per column, keeping what the model does not declare | the same | v0.34.0 |
6392
6417
  | An `Any` or untyped `list`/`set` field of a `SCHEMAFULL` model | `define_table()` adds `FLEXIBLE` (read from `client.version()`): without it these engines empty such values, optional or not; the item definitions as on 3.x | kept without `FLEXIBLE` (refused there); an untyped `list` gets an item definition `TYPE any`, without which 3.x refuses an object item of a required one (`no such field exists`) | v0.34.0 |
6393
6418
  | A `list` of sub-models (`list[M]`, at any depth) holding a `dict`, an `Any` or an untyped `list`, in a `SCHEMAFULL` model | `define_table()` also writes the `list` `FLEXIBLE`: without it these engines drop such a value from every item, then refuse the record's next write (`Found NONE for field`) | kept without `FLEXIBLE` on the `list`, which `define_table()` does not write there | v0.34.0 |
6394
- | A write naming a field a `SCHEMAFULL` table does not define (an undeclared `merge()` key, a raw query, records predating `SCHEMAFULL`) | the field is dropped, silently; kept in the items of a list `define_table()` writes `FLEXIBLE` (a 2.x limitation) | the write is refused (`no such field exists`), except in the items of a list of objects, which keep it | v0.34.0 |
6419
+ | A write naming a field a `SCHEMAFULL` table does not define (an undeclared `merge()` key, a raw query, records predating `SCHEMAFULL`) | the field is dropped, silently; kept in the items of a list `define_table()` writes `FLEXIBLE` (a 2.x limitation) | the write is refused (`no such field exists`), except in the items of a list whose items define a field (every list of sub-models `define_table()` writes), which keep it | v0.34.0 |
6395
6420
  | Full-text index (`define_indexes()`, `index_ddl(line=)`) | `SEARCH ANALYZER` (`FULLTEXT` is a parse error), read from `client.version()`; several fields accepted, the ORM writes one | `FULLTEXT ANALYZER` (`SEARCH` is a parse error); one field per index | v0.35.0 |
6396
6421
  | Removing an analyzer an index uses (`remove_analyzer()`) | the server would accept it, then refuse every write to the table: the ORM refuses it first, with 3.x's message | refused by the server | v0.35.0 |
6397
6422
  | BM25 score of a term in more than half the documents (`SearchScore`) | below zero: a text holding such a term scores lower than without it, and ranks differently than on 3.x | `0.0`: the term adds nothing to the score | v0.35.0 |
@@ -6399,6 +6424,8 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6399
6424
  | Two `search()` fields AND-ed | only the records matching every field, each field scored as if searched alone | the same on 3.3; 3.1 can also return records that match only one of the fields, scored `0.0` on the other | v0.35.0 |
6400
6425
  | `search()` on a field without a full-text index | `SurrealDbError` naming the field | the same; 3.1 answers no record | v0.35.0 |
6401
6426
  | `live()` with a `Subquery` that searches a field without a full-text index | `SurrealDbError` naming the field, before the live query starts | the same (the live query would never notify); 3.1 starts it | v0.35.0 |
6427
+ | An auth model with a `Field(exclude=True)` field SIGNUP writes (`password: str = Field(exclude=True)`) | `TypeError` before any request, whatever the schema mode and `with_table`: the four DDL methods, `signup()` and `signin()` | same on both lines (a check of the model, no request) | v0.35.2 |
6428
+ | `define_indexes(tx=)` in a block that writes to the model's table (an ORM write before the index, a write after it) | a write before it: refused (left out of the index); a write after it, to a table holding records, fails the commit with a retryable `SurrealDbConflictError`, again on retry | a write before it: refused (left out of the index, [surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618)); a write after it is committed and indexed | v0.35.3 |
6402
6429
  | Full suite and every divergence in this table, re-run on SurrealDB 2.7.0 and 3.3.0 | 2.7.0 identical to 2.6.5 (same passes, same 3.x-only skips) | 3.3.0 identical to 3.2.4, except the system-user signin row | v0.19.1 |
6403
6430
 
6404
6431
  > **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
@@ -6434,8 +6461,9 @@ Capabilities not listed behave as on a 2.x server.
6434
6461
  | Server-side events and stored functions (v0.31.0) | as on a 2.x server: `$input` is `NONE`; `Event(async_mode=True)` raises `SurrealDbError` before any DDL | `ASYNC` events on 3.x | v0.31.0 |
6435
6462
  | Materialized views (v0.32.0) | as on a 2.x server: `int` sums and `Decimal` means; in a grouped view, `math::stddev()`/`math::variance()`, an expression around an aggregate, a field outside `GROUP BY` and a `GROUP BY` on an alias raise `SurrealDbError` before any DDL; writes to a view refused by the ORM (the engine would accept them); no live queries | `float` sums and means on 3.x | v0.32.0 |
6436
6463
  | TYPE RELATION constraints (v0.33.0) | as on a 2.x server: a raw `ALTER TABLE … TYPE` of a table already written to is not enforced (`define_relation()` sends `DEFINE TABLE OVERWRITE`); an endpoint outside `IN`/`OUT` whose record does not exist raises `SurrealDbNotFoundError` | `SurrealDbError` for that endpoint on 3.x | v0.33.0 |
6437
- | Model table DDL (v0.34.0) | as on a 2.x server: `define_table()` adds `FLEXIBLE` to the `Any` and untyped columns of a `SCHEMAFULL` table and to its lists of sub-models holding a `FLEXIBLE` column; a write naming a field the table does not define drops that field | 3.x keeps those values without `FLEXIBLE` and refuses that write | v0.34.0 |
6464
+ | Model table DDL (v0.34.0) | as on a 2.x server: `define_table()` adds `FLEXIBLE` to the `Any` and untyped columns of a `SCHEMAFULL` table and to its lists of sub-models holding a `FLEXIBLE` column; a write naming a field the table does not define drops that field, except in the items of a list `define_table()` writes `FLEXIBLE`, which keep it | 3.x keeps those values without `FLEXIBLE` and refuses that write, except in list items that define a field | v0.34.0 |
6438
6465
  | Full-text search (v0.35.0) | as on a 2.x server: `SEARCH ANALYZER`, a term in more than half the documents scores below zero, BM25 statistics grow with each rebuild and keep deleted records, `remove_analyzer()` refuses an analyzer an index uses; an index defined in the transaction that defines its analyzer sees it, which `define_indexes(tx=…)` refuses all the same | 3.x writes `FULLTEXT ANALYZER`, scores such a term `0.0`, keeps BM25 statistics exact and refuses that removal | v0.35.0 |
6466
+ | `define_indexes(tx=)` in a block that writes to the model's table | an ORM write before it: refused all the same, although this engine indexes its records; a write after it is committed and indexed | refused (left out of the index); on 2.x a write after it, to a table holding records, fails the commit | v0.35.3 |
6439
6467
  | Everything else | CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields, upsert/patch, server values, computed fields, stored functions, signals: the same as on a 2.x server | unchanged | v0.25.0 |
6440
6468
 
6441
6469
  ---
@@ -1282,6 +1282,13 @@ gives such a model the same table, so the two can be called in any order.
1282
1282
  > **The password field holds the hash.** SurrealDB returns the stored record, so
1283
1283
  > `result.user.password` is `$argon2id$v=19$…`, never the plaintext you submitted.
1284
1284
 
1285
+ **Keep the password field in `model_dump()`.** SIGNUP writes every field, while `update()` and `upsert()` replace the
1286
+ record with what `model_dump()` writes: a field declared `Field(exclude=True)` (`password: str = Field(exclude=True)`)
1287
+ would lose its stored value, the password hash, and every later signin would fail. Such a model raises `TypeError`,
1288
+ naming the fields, before any request and whatever its schema mode: `access_ddl()`, `define_access()` (with or without
1289
+ the table), `table_ddl()`, `define_table()`, `signup()` and `signin()` refuse it. Remove `exclude=True` and leave the
1290
+ field out where you serialise the model instead (`model_dump(exclude={"password"})`).
1291
+
1285
1292
  #### Renewing a session (SurrealDB 3.x only)
1286
1293
 
1287
1294
  ```python
@@ -5654,13 +5661,15 @@ print(*table, sep="\n")
5654
5661
  declares its own.
5655
5662
  - A `TableType.USER` model with `extra="allow"` raises `TypeError` there (with `with_table=True`), since its table is
5656
5663
  `SCHEMAFULL`; a `server_fields` column without a constant default needs a database `DEFAULT` ("Field types" above).
5657
- - A field SIGNUP writes that `Field(exclude=True)` keeps out of `model_dump()` (`password: str = Field(exclude=True)`)
5658
- raises `TypeError` too, naming the field, before any request (with a `SCHEMAFULL` schema mode): `define_access()`
5659
- with `with_table=True` and `define_table()` both refuse it, since the table would not define it, so SurrealDB 3.x
5660
- would refuse every signup and 2.x drop the password hash, failing every signin. Remove `exclude=True` and leave the
5661
- field out where you serialise the model instead (`model_dump(exclude={"password"})`): `update()` and `upsert()`
5662
- replace the record with what `model_dump()` writes, so even over a table defined by hand (`with_table=False`) they
5663
- would be refused (a required column) or drop the hash (an optional one), failing every later signin.
5664
+ - An auth model with a field SIGNUP writes that `Field(exclude=True)` keeps out of `model_dump()`
5665
+ (`password: str = Field(exclude=True)`) raises `TypeError` too, naming the fields, before any request and whatever
5666
+ its schema mode: `table_ddl()`, `define_table()`, `access_ddl()` and `define_access()` (with or without the table),
5667
+ `signup()` and `signin()` refuse it. `update()` and `upsert()` replace the record with what `model_dump()` writes,
5668
+ so on any table (`SCHEMALESS`, or defined by hand with `with_table=False`) they would drop the password hash, failing
5669
+ every later signin, or be refused by a required column; a `SCHEMAFULL` table would not define the field either, so
5670
+ SurrealDB 3.x would refuse every signup and 2.x drop the hash. Remove `exclude=True` and leave the field out where
5671
+ you serialise the model instead (`model_dump(exclude={"password"})`). **Changed**: such a model on a `SCHEMALESS`
5672
+ table or with `with_table=False` used to be accepted, and its first `update()` or `upsert()` dropped the hash.
5664
5673
  - Upgrading: a 0.33 `TableType.USER` model's table turns `SCHEMAFULL` at its next `define_access()`; records already
5665
5674
  there are checked at their next write.
5666
5675
 
@@ -5692,12 +5701,21 @@ print(*table, sep="\n")
5692
5701
  `define_table()` writes such a list `FLEXIBLE` before 3.x; the item's typed fields are still checked. 3.x keeps those
5693
5702
  values without it. On 2.x and the embedded engine, the items of such a list then also keep a key the model does not
5694
5703
  declare, written raw or by another client (the ORM never sends one), which they drop from a list that is not
5695
- `FLEXIBLE`: a 2.x limitation, since `FLEXIBLE` there covers the whole item. 3.x keeps such a key in the items of any
5696
- list of objects, `FLEXIBLE` or not, and refuses it at the top level or in a sub-model.
5704
+ `FLEXIBLE`: a 2.x limitation, since `FLEXIBLE` there covers the whole item. 3.x keeps such a key, `FLEXIBLE` or not,
5705
+ in the items of a list of objects whose items define a field (every list of sub-models `define_table()` writes) and
5706
+ in an object inside them that defines one; it refuses it at the top level, in a sub-model outside such a list, and in
5707
+ the items of a list that defines no item field (an `array<object>` defined by hand without `v.*.n`). SurrealDB's
5708
+ [documentation of
5709
+ `FLEXIBLE`](https://surrealdb.com/docs/reference/query-language/statements/define/field#flexible-data-types) says
5710
+ every object of a `SCHEMAFULL` table, an item of a list included, accepts only the keys defined for it unless its
5711
+ field is `FLEXIBLE`: 3.x departs from it in a list whose items define a field, so a later 3.x may refuse such a key
5712
+ there too: do not rely on it.
5697
5713
  - On SurrealDB 3.x a required untyped array refuses an object item unless its items are defined
5698
5714
  (`no such field exists`): `define_table()` writes the item definition `TYPE any` (`bag.*`) on every line.
5699
5715
  - A write naming a field a `SCHEMAFULL` table does not define is refused on 3.x and dropped on 2.x and the embedded
5700
- engine ("What SurrealDB checks" above).
5716
+ engine ("What SurrealDB checks" above), except in the items of a list of objects: on 3.x of a list whose items define
5717
+ a field (every list of sub-models `define_table()` writes), on 2.x and the embedded engine of a list `define_table()`
5718
+ writes `FLEXIBLE`.
5701
5719
  - `COMPUTED` fields are SurrealDB 3.x's: `define_table()` keeps a stored one `COMPUTED`, and writes a new computed
5702
5720
  field `VALUE` on both lines.
5703
5721
  - The [2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x) and the
@@ -5965,11 +5983,12 @@ SurrealDB keeps the tokens of the records an index holds when their analyzer cha
5965
5983
  misses them — the records written afterwards use the new analyzer — until the index is rebuilt. So when
5966
5984
  `define_indexes()`, or `SurrealDBConnectionManager.define_analyzer()`, redefines an analyzer, it rebuilds every index of
5967
5985
  the database that uses it (`REBUILD INDEX`, sorted by table then index; `define_indexes()` rebuilds the model's table's
5968
- last), and logs one warning naming them (logger `surreal_orm_lite.search`). A rebuild re-reads the table: seconds
5969
- per thousands of records on SurrealDB 2.x and the embedded engine. An analyzer belongs to the database, not to a table:
5970
- declare one `Analyzer` per name (a module constant) and reference it from every index that uses it — two definitions
5971
- under one name would redefine it in turn, each time rebuilding its indexes. An unchanged index is never redefined, so
5972
- start-up never rebuilds (and, on SurrealDB 2.x, never inflates its scores).
5986
+ last), and logs one warning naming them, an index it redefines at the same time included (logger
5987
+ `surreal_orm_lite.search`). A rebuild re-reads the table: seconds per thousands of records on SurrealDB 2.x and the
5988
+ embedded engine. An analyzer belongs to the database, not to a table: declare one `Analyzer` per name (a module
5989
+ constant) and reference it from every index that uses it — two definitions under one name would redefine it in turn,
5990
+ each time rebuilding its indexes. An unchanged index is never redefined, so start-up never rebuilds (and, on SurrealDB
5991
+ 2.x, never inflates its scores).
5973
5992
 
5974
5993
  ```python
5975
5994
  PLAIN = Analyzer("plain", ["blank"], ["ascii"])
@@ -6013,9 +6032,15 @@ print(await NoteV2.objects().search(text="physics").count())
6013
6032
  So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL when an analyzer must be defined or redefined, and
6014
6033
  `define_analyzer(tx=…)` when a redefinition has indexes to rebuild (a new analyzer, or a redefinition no index uses,
6015
6034
  joins the transaction): call `define_analyzer()` without `tx=` first.
6016
- - Prefer `define_indexes()` outside the block: in a transaction that also writes to the model's table, SurrealDB may
6017
- leave out of the index a record the block wrote before the index was defined, and may fail the block on a write
6018
- after it.
6035
+ - The block must not have written to the model's table yet: SurrealDB servers do not index the records a transaction
6036
+ wrote before the index was defined, which stay out of it after the commit. It is a server defect
6037
+ ([surrealdb/surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618) on 3.x, the same on 2.x); only the
6038
+ embedded engine indexes them. So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL, naming the model and
6039
+ the table, when an index must be defined or redefined and the block has already written records to the model's table
6040
+ with the ORM (`save()`, `objects(tx=…).bulk_create()`, …). The refusal does not fail the block. `define_table(tx=…)`,
6041
+ `define_relation(tx=…)` and a write to another table do not count; a raw `tx.add()` is not tracked.
6042
+ - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6043
+ in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again.
6019
6044
  - `remove_analyzer(tx=…)` reads committed state to find the indexes that use the analyzer: an index queued earlier in
6020
6045
  a buffered block is not seen.
6021
6046
  - A search in an interactive transaction sees the transaction's writes; in a buffered one, a read raises, as every
@@ -6198,7 +6223,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
6198
6223
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
6199
6224
  on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
6200
6225
  otherwise. The full suite and every divergence below were re-verified on both new versions.
6201
- Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs.
6226
+ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5. The row added in v0.35.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
6202
6227
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
6203
6228
 
6204
6229
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -6212,7 +6237,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6212
6237
  | Cleanup on a missing target (`delete_table`) | native no-op | ORM makes it a silent no-op | v0.7.0 |
6213
6238
  | Aggregation over an empty set (`NaN` / `±inf`) | returns `0.0` / `None` | ORM normalises to `0.0` / `None` | v0.7.0 |
6214
6239
  | Namespace/db selection (`use()` ordering) | lenient (auto-creates) | strict — ORM signs in before `use()` | v0.7.0 |
6215
- | Writing a field a `SCHEMAFULL` table does not define (`CREATE`, `INSERT`, `INSERT RELATION`) | silently dropped: the record is stored without it | rejected ("Found field …, but no such field exists"): nothing is stored | v0.7.0 |
6240
+ | Writing a field a `SCHEMAFULL` table does not define (`CREATE`, `INSERT`, `INSERT RELATION`) | silently dropped: the record is stored without it; kept in the items of a list `define_table()` writes `FLEXIBLE` (a 2.x limitation) | rejected ("Found field …, but no such field exists"): nothing is stored, except in the items of a list whose items define a field (every list of sub-models), which keep it | v0.7.0 |
6216
6241
  | `upsert()` / `update_or_create()` / `get_or_create()` | same on both lines | same on both lines | v0.10.0 |
6217
6242
  | `patch()` / `atomic_append` / `atomic_set_add` / `atomic_remove` / `atomic_increment` | same on both lines (portable `array::*` fns chosen over divergent `+=`/`-=`) | same on both lines | v0.11.0 |
6218
6243
  | `retry_on_conflict` / `SurrealDbConflictError` (retryable conflict) | same type + decorator; conflicts rarer (engine serialises more), except on `CHANGEFEED` tables (section 22) | same type + decorator; conflicts are the normal optimistic-MVCC failure | v0.12.0 |
@@ -6340,7 +6365,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6340
6365
  | Model table DDL (`define_table()`: `DEFINE TABLE` + `DEFINE FIELD`) | same on both lines: one `DEFINE TABLE OVERWRITE` and one `DEFINE FIELD OVERWRITE` per column, keeping what the model does not declare | the same | v0.34.0 |
6341
6366
  | An `Any` or untyped `list`/`set` field of a `SCHEMAFULL` model | `define_table()` adds `FLEXIBLE` (read from `client.version()`): without it these engines empty such values, optional or not; the item definitions as on 3.x | kept without `FLEXIBLE` (refused there); an untyped `list` gets an item definition `TYPE any`, without which 3.x refuses an object item of a required one (`no such field exists`) | v0.34.0 |
6342
6367
  | A `list` of sub-models (`list[M]`, at any depth) holding a `dict`, an `Any` or an untyped `list`, in a `SCHEMAFULL` model | `define_table()` also writes the `list` `FLEXIBLE`: without it these engines drop such a value from every item, then refuse the record's next write (`Found NONE for field`) | kept without `FLEXIBLE` on the `list`, which `define_table()` does not write there | v0.34.0 |
6343
- | A write naming a field a `SCHEMAFULL` table does not define (an undeclared `merge()` key, a raw query, records predating `SCHEMAFULL`) | the field is dropped, silently; kept in the items of a list `define_table()` writes `FLEXIBLE` (a 2.x limitation) | the write is refused (`no such field exists`), except in the items of a list of objects, which keep it | v0.34.0 |
6368
+ | A write naming a field a `SCHEMAFULL` table does not define (an undeclared `merge()` key, a raw query, records predating `SCHEMAFULL`) | the field is dropped, silently; kept in the items of a list `define_table()` writes `FLEXIBLE` (a 2.x limitation) | the write is refused (`no such field exists`), except in the items of a list whose items define a field (every list of sub-models `define_table()` writes), which keep it | v0.34.0 |
6344
6369
  | Full-text index (`define_indexes()`, `index_ddl(line=)`) | `SEARCH ANALYZER` (`FULLTEXT` is a parse error), read from `client.version()`; several fields accepted, the ORM writes one | `FULLTEXT ANALYZER` (`SEARCH` is a parse error); one field per index | v0.35.0 |
6345
6370
  | Removing an analyzer an index uses (`remove_analyzer()`) | the server would accept it, then refuse every write to the table: the ORM refuses it first, with 3.x's message | refused by the server | v0.35.0 |
6346
6371
  | BM25 score of a term in more than half the documents (`SearchScore`) | below zero: a text holding such a term scores lower than without it, and ranks differently than on 3.x | `0.0`: the term adds nothing to the score | v0.35.0 |
@@ -6348,6 +6373,8 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6348
6373
  | Two `search()` fields AND-ed | only the records matching every field, each field scored as if searched alone | the same on 3.3; 3.1 can also return records that match only one of the fields, scored `0.0` on the other | v0.35.0 |
6349
6374
  | `search()` on a field without a full-text index | `SurrealDbError` naming the field | the same; 3.1 answers no record | v0.35.0 |
6350
6375
  | `live()` with a `Subquery` that searches a field without a full-text index | `SurrealDbError` naming the field, before the live query starts | the same (the live query would never notify); 3.1 starts it | v0.35.0 |
6376
+ | An auth model with a `Field(exclude=True)` field SIGNUP writes (`password: str = Field(exclude=True)`) | `TypeError` before any request, whatever the schema mode and `with_table`: the four DDL methods, `signup()` and `signin()` | same on both lines (a check of the model, no request) | v0.35.2 |
6377
+ | `define_indexes(tx=)` in a block that writes to the model's table (an ORM write before the index, a write after it) | a write before it: refused (left out of the index); a write after it, to a table holding records, fails the commit with a retryable `SurrealDbConflictError`, again on retry | a write before it: refused (left out of the index, [surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618)); a write after it is committed and indexed | v0.35.3 |
6351
6378
  | Full suite and every divergence in this table, re-run on SurrealDB 2.7.0 and 3.3.0 | 2.7.0 identical to 2.6.5 (same passes, same 3.x-only skips) | 3.3.0 identical to 3.2.4, except the system-user signin row | v0.19.1 |
6352
6379
 
6353
6380
  > **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
@@ -6383,8 +6410,9 @@ Capabilities not listed behave as on a 2.x server.
6383
6410
  | Server-side events and stored functions (v0.31.0) | as on a 2.x server: `$input` is `NONE`; `Event(async_mode=True)` raises `SurrealDbError` before any DDL | `ASYNC` events on 3.x | v0.31.0 |
6384
6411
  | Materialized views (v0.32.0) | as on a 2.x server: `int` sums and `Decimal` means; in a grouped view, `math::stddev()`/`math::variance()`, an expression around an aggregate, a field outside `GROUP BY` and a `GROUP BY` on an alias raise `SurrealDbError` before any DDL; writes to a view refused by the ORM (the engine would accept them); no live queries | `float` sums and means on 3.x | v0.32.0 |
6385
6412
  | TYPE RELATION constraints (v0.33.0) | as on a 2.x server: a raw `ALTER TABLE … TYPE` of a table already written to is not enforced (`define_relation()` sends `DEFINE TABLE OVERWRITE`); an endpoint outside `IN`/`OUT` whose record does not exist raises `SurrealDbNotFoundError` | `SurrealDbError` for that endpoint on 3.x | v0.33.0 |
6386
- | Model table DDL (v0.34.0) | as on a 2.x server: `define_table()` adds `FLEXIBLE` to the `Any` and untyped columns of a `SCHEMAFULL` table and to its lists of sub-models holding a `FLEXIBLE` column; a write naming a field the table does not define drops that field | 3.x keeps those values without `FLEXIBLE` and refuses that write | v0.34.0 |
6413
+ | Model table DDL (v0.34.0) | as on a 2.x server: `define_table()` adds `FLEXIBLE` to the `Any` and untyped columns of a `SCHEMAFULL` table and to its lists of sub-models holding a `FLEXIBLE` column; a write naming a field the table does not define drops that field, except in the items of a list `define_table()` writes `FLEXIBLE`, which keep it | 3.x keeps those values without `FLEXIBLE` and refuses that write, except in list items that define a field | v0.34.0 |
6387
6414
  | Full-text search (v0.35.0) | as on a 2.x server: `SEARCH ANALYZER`, a term in more than half the documents scores below zero, BM25 statistics grow with each rebuild and keep deleted records, `remove_analyzer()` refuses an analyzer an index uses; an index defined in the transaction that defines its analyzer sees it, which `define_indexes(tx=…)` refuses all the same | 3.x writes `FULLTEXT ANALYZER`, scores such a term `0.0`, keeps BM25 statistics exact and refuses that removal | v0.35.0 |
6415
+ | `define_indexes(tx=)` in a block that writes to the model's table | an ORM write before it: refused all the same, although this engine indexes its records; a write after it is committed and indexed | refused (left out of the index); on 2.x a write after it, to a table holding records, fails the commit | v0.35.3 |
6388
6416
  | Everything else | CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields, upsert/patch, server values, computed fields, stored functions, signals: the same as on a 2.x server | unchanged | v0.25.0 |
6389
6417
 
6390
6418
  ---
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.35.0"
3
+ version = "0.35.3"
4
4
  description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -1,4 +1,4 @@
1
- __version__ = "0.35.0"
1
+ __version__ = "0.35.3"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -783,7 +783,14 @@ def _resolve(
783
783
  return None, tx
784
784
 
785
785
 
786
- def invalidates(of: _Of, *, deletes: bool = False) -> Callable[[F], F]:
786
+ def _note_records(tables: frozenset[str] | None, tx: Any) -> None:
787
+ """Note *tables* (``None``: every table) as written with records on *tx* (issue #304), when its class has
788
+ ``_note_record_write`` — recognised by its class, as :func:`writing` recognises a transaction."""
789
+ if callable(getattr(type(tx), "_note_record_write", None)):
790
+ tx._note_record_write(tables)
791
+
792
+
793
+ def invalidates(of: _Of, *, deletes: bool = False, records: bool = True) -> Callable[[F], F]:
787
794
  """Decorate an ORM write method so that it invalidates the cached reads it can change.
788
795
 
789
796
  ``of`` says which tables the call writes, from its first argument: ``"self"`` (the instance's model table),
@@ -794,6 +801,11 @@ def invalidates(of: _Of, *, deletes: bool = False) -> Callable[[F], F]:
794
801
  ``@classmethod``, this is the inner decorator. The wrapper keeps the signature, the docstring and
795
802
  ``__wrapped__``, sends nothing, and carries ``__surreal_cache_writes__``.
796
803
 
804
+ With a transaction, the tables are also noted on it as written with records (issue #304:
805
+ ``Transaction._note_record_write``, which ``define_indexes(tx=…)`` reads) — unless ``records=False``, which marks
806
+ a method that applies definitions (``define_table()``, ``remove_index()``…) and writes no record: its tables are
807
+ noted for the query cache only. The wrapper carries the flag as ``__surreal_record_writes__``.
808
+
797
809
  The one error of its own (v0.29.0): with ``"self"``, ``"edge"`` or ``"cls"``, a ``tx`` of another connection than
798
810
  the model's raises ``SurrealDbError`` (``routing.check_transaction()``) before the write is put in flight or noted
799
811
  on the transaction, so a refused write invalidates nothing. The transaction is read statically, never asked. A
@@ -818,10 +830,13 @@ def invalidates(of: _Of, *, deletes: bool = False) -> Callable[[F], F]:
818
830
  arg0 = bound.arguments[first]
819
831
  model = arg0 if isinstance(arg0, type) else type(arg0)
820
832
  _routing.check_transaction(model, tx, f"{model.__name__}.{func.__name__}()")
833
+ if records and tx is not None:
834
+ _note_records(tables, tx)
821
835
  async with writing(tables, tx):
822
836
  return await func(*args, **kwargs)
823
837
 
824
838
  wrapper.__surreal_cache_writes__ = True # type: ignore[attr-defined]
839
+ wrapper.__surreal_record_writes__ = records # type: ignore[attr-defined]
825
840
  return cast(F, wrapper)
826
841
 
827
842
  return decorate
@@ -38,7 +38,7 @@ from .auth import AuthTokens, build_auth_payload, wrap_auth_error
38
38
  from .connection_manager import SurrealDBConnectionManager
39
39
  from .embedded import model_auth_unsupported
40
40
  from .exceptions import SurrealDbAuthenticationError, SurrealDbError
41
- from .schema import TableClauses, declared_clauses
41
+ from .schema import TableClauses, declared_clauses, signup_excluded_refused
42
42
  from .transaction import Transaction
43
43
  from .types import SchemaMode
44
44
  from .utils import apply_ddl_statements, validate_alias_name, validate_field_name
@@ -268,17 +268,33 @@ class AuthenticatedUserMixin:
268
268
  @classmethod
269
269
  def _signup_fields_excluded(cls) -> list[str]:
270
270
  """The fields SIGNUP writes that ``Field(exclude=True)`` keeps out of ``model_dump()``, in declaration order
271
- (#296).
272
-
273
- The model table DDL defines the columns ``model_dump()`` writes (``model_ddl.model_columns()`` skips the same
274
- fields), while SIGNUP writes every field of :meth:`_signup_fields` — so on a ``SCHEMAFULL`` table these have no
275
- column: SurrealDB 3.x refuses the signup, 2.x drops their values (a password hash, and every signin fails).
276
- ``BaseSurrealModel._table_ddl()`` refuses such a table (SG1), behind ``table_ddl()``, ``define_table()``,
277
- :meth:`access_ddl` and :meth:`define_access`.
271
+ (#296, #299).
272
+
273
+ SIGNUP writes every field of :meth:`_signup_fields`, while ``update()`` and ``upsert()`` replace the stored
274
+ record with what ``model_dump()`` writes, whatever the table's schema mode — so they drop these values (a
275
+ password hash, and every later signin fails), or a required column refuses them —, and the model table DDL
276
+ defines the columns ``model_dump()`` writes (``model_ddl.model_columns()`` skips the same fields), so on a
277
+ ``SCHEMAFULL`` table these have no column: SurrealDB 3.x refuses the signup, 2.x drops their values.
278
+ :meth:`_refuse_signup_fields_excluded` refuses such a model (SG1).
278
279
  """
279
280
  fields = getattr(cls, "model_fields", {}) or {}
280
281
  return [name for name in cls._signup_fields() if fields[name].exclude is True]
281
282
 
283
+ @classmethod
284
+ def _refuse_signup_fields_excluded(cls) -> None:
285
+ """SG1 (#296, #299): refuse a model with a field SIGNUP writes that ``Field(exclude=True)`` keeps out of
286
+ ``model_dump()`` (:meth:`_signup_fields_excluded`), whatever its schema mode. Pure:
287
+ ``BaseSurrealModel._table_ddl()`` (behind ``table_ddl()`` and ``define_table()``), :meth:`access_ddl` (behind
288
+ :meth:`define_access`, with or without the table) and :meth:`_auth_variables` (behind :meth:`signup` and
289
+ :meth:`signin`) call it before any request.
290
+
291
+ Raises:
292
+ TypeError: naming the model and those fields, in declaration order (``schema.signup_excluded_refused()``).
293
+ """
294
+ excluded = cls._signup_fields_excluded()
295
+ if excluded:
296
+ raise TypeError(signup_excluded_refused(cls.__name__, excluded))
297
+
282
298
  @classmethod
283
299
  def _signup_primary_key(cls) -> str | None:
284
300
  """The primary key SIGNUP builds the record id from, or ``None`` for a server id.
@@ -383,15 +399,17 @@ class AuthenticatedUserMixin:
383
399
  TypeError: with ``with_table=True``, a ``TableType.USER`` model with
384
400
  ``extra="allow"`` (its ``SCHEMAFULL`` table refuses or drops the fields the
385
401
  model does not declare), or, for a model whose schema mode is ``SCHEMAFULL``,
386
- an *overwrite* that is not a ``bool``, or a field SIGNUP writes that
387
- ``Field(exclude=True)`` keeps out of ``model_dump()`` and so out of the table
388
- (SurrealDB 3.x would refuse every signup, 2.x drop the value — a password hash,
389
- failing every signin); the message names the model and the fields, in
390
- declaration order. ``table_ddl()`` and ``define_table()`` refuse that model too.
402
+ an *overwrite* that is not a ``bool``; then, whatever the schema mode and
403
+ *with_table*, a field SIGNUP writes that ``Field(exclude=True)`` keeps out of
404
+ ``model_dump()``: ``update()`` and ``upsert()`` replace the record with what
405
+ ``model_dump()`` writes, so on any table (``SCHEMALESS``, or defined by hand)
406
+ they would drop the value — a password hash, failing every later signin — or
407
+ be refused by a required column, and a ``SCHEMAFULL`` table would not define
408
+ the field (SurrealDB 3.x would refuse every signup, 2.x drop the value). The
409
+ message names the model and the fields, in declaration order; ``table_ddl()``,
410
+ ``define_table()``, :meth:`signup` and :meth:`signin` refuse that model too.
391
411
  Remove ``exclude=True`` and pass ``exclude=`` to ``model_dump()`` where you
392
- serialise the model: ``update()`` and ``upsert()`` replace the record with what
393
- ``model_dump()`` writes, so a table defined by hand would refuse them or drop the
394
- value.
412
+ serialise the model.
395
413
  ValueError: an auth key naming no field of the model, an unknown hashing family or
396
414
  duration, a primary key SIGNUP cannot bind; with ``with_table=True`` and a
397
415
  ``SCHEMAFULL`` schema mode, a ``FLEXIBLE`` request on a kind without an object
@@ -416,11 +434,13 @@ class AuthenticatedUserMixin:
416
434
 
417
435
  statements: list[str] = []
418
436
  if with_table and cls._schemafull_access():
419
- # The model table DDL's refusals, SG1 (#296) included: a column SIGNUP writes that the table would not define.
437
+ # The model table DDL's refusals, UX1 then SG1 included.
420
438
  table_ddl: list[str] = cls._table_ddl(overwrite, cls._access_table_clauses()) # type: ignore[attr-defined]
421
439
  statements.extend(table_ddl)
422
440
  elif with_table:
423
441
  statements.append(cls._access_table_statement(table, clause))
442
+ # SG1 whatever the schema mode and with_table (#299): update() and upsert() would drop what SIGNUP wrote.
443
+ cls._refuse_signup_fields_excluded()
424
444
 
425
445
  # The record id follows the model's primary key, because the rest of the ORM does: a
426
446
  # random id here would leave User.objects().get(email=…) addressing a record the
@@ -465,7 +485,7 @@ class AuthenticatedUserMixin:
465
485
  return statements
466
486
 
467
487
  @classmethod
468
- @_cache.invalidates("cls")
488
+ @_cache.invalidates("cls", records=False)
469
489
  async def define_access(
470
490
  cls,
471
491
  *,
@@ -516,8 +536,8 @@ class AuthenticatedUserMixin:
516
536
 
517
537
  Raises:
518
538
  TypeError: see :meth:`access_ddl` — before any request, a field SIGNUP writes that
519
- ``Field(exclude=True)`` keeps out of a ``SCHEMAFULL`` table included, which
520
- ``define_table()`` refuses too.
539
+ ``Field(exclude=True)`` keeps out of ``model_dump()`` included, whatever the
540
+ schema mode and *with_table*.
521
541
  ValueError: see :meth:`access_ddl` — before any request.
522
542
  SurrealDbError: if the server rejects a statement. The most likely cause on
523
543
  **SurrealDB 2.6.x** is ``with_refresh=True``: that line cannot parse
@@ -574,7 +594,12 @@ class AuthenticatedUserMixin:
574
594
  Every field named in the SIGNUP clause must be bound, or the server has no value for a
575
595
  ``$variable`` it references — so absent optional fields are sent as ``None`` explicitly
576
596
  rather than omitted.
597
+
598
+ First of all, SG1 (#299): a model with a field SIGNUP writes that ``Field(exclude=True)``
599
+ keeps out of ``model_dump()`` is refused, so an access defined by hand cannot leave a
600
+ stored record that ``update()`` or ``upsert()`` would strip of its hash.
577
601
  """
602
+ cls._refuse_signup_fields_excluded()
578
603
  known = set(cls._signup_fields())
579
604
  unknown = sorted(set(values) - known)
580
605
  if unknown:
@@ -926,6 +951,10 @@ class AuthenticatedUserMixin:
926
951
  instance's password field holds the **hash**, since that is what the server stores.
927
952
 
928
953
  Raises:
954
+ TypeError: the model has a field SIGNUP writes that ``Field(exclude=True)`` keeps
955
+ out of ``model_dump()`` (see :meth:`access_ddl`) — before any request, so an
956
+ access defined by hand cannot leave a record that ``update()`` or ``upsert()``
957
+ would strip of its password hash.
929
958
  ValueError: for an unknown field or a missing required one — before any request.
930
959
  SurrealDbAuthenticationError: if the server refuses the signup, or returns no
931
960
  record for the new session (the message says how to grant the permission).
@@ -948,6 +977,7 @@ class AuthenticatedUserMixin:
948
977
  Isolation and ``bind=`` behave exactly as in :meth:`signup`, on the embedded engine too.
949
978
 
950
979
  Raises:
980
+ TypeError: as in :meth:`signup` — before any request.
951
981
  ValueError: for an unknown or missing field — before any request.
952
982
  SurrealDbAuthenticationError: if the credentials are refused. Both DB lines are
953
983
  normalised here: the same wrong password surfaces as ``NotFoundError`` on 3.x
@@ -47,7 +47,6 @@ from .schema import (
47
47
  read_table_fields,
48
48
  remove_event_statement,
49
49
  remove_view_statement,
50
- signup_excluded_refused,
51
50
  table_holds_records,
52
51
  table_kind,
53
52
  table_permissions_text,
@@ -80,6 +79,7 @@ from .search import (
80
79
  remove_index_statement,
81
80
  stored_indexes_using,
82
81
  transaction_analyzer_refused,
82
+ transaction_write_refused,
83
83
  warn_redefined,
84
84
  )
85
85
  from .signals import (
@@ -951,7 +951,7 @@ class BaseSurrealModel(BaseModel):
951
951
  return statements
952
952
 
953
953
  @classmethod
954
- @_cache.invalidates("cls")
954
+ @_cache.invalidates("cls", records=False)
955
955
  async def define_computed_fields(
956
956
  cls,
957
957
  overwrite: bool = True,
@@ -1239,7 +1239,8 @@ class BaseSurrealModel(BaseModel):
1239
1239
  index of the database that uses it: ``INFO FOR TABLE`` of every other table (one request each, only then), and
1240
1240
  ``REBUILD INDEX`` for each of their indexes using it (sorted by table then index) before the index definitions,
1241
1241
  then for each unchanged index of this table using it after them (the declared ones in declaration order, then
1242
- the others). One warning per redefined analyzer names the indexes rebuilt (logger
1242
+ the others). One warning per redefined analyzer names the indexes rebuilt, in the order applied — the indexes
1243
+ this call defines with it included, which their ``DEFINE INDEX OVERWRITE`` rebuilds (logger
1243
1244
  ``surreal_orm_lite.search``). A rebuild re-reads the table — seconds per thousands of records on SurrealDB 2.x
1244
1245
  and the embedded engine.
1245
1246
 
@@ -1259,11 +1260,19 @@ class BaseSurrealModel(BaseModel):
1259
1260
  Before any DDL (nothing sent but the reads): an index that names by ``str`` an analyzer neither the database
1260
1261
  nor the model's ``Analyzer`` objects define is refused; with *tx*, an analyzer to define or redefine is refused
1261
1262
  — SurrealDB builds an index with the analyzers committed before the transaction began: define it first,
1262
- outside the block. With *tx* and the analyzers in place, the index statements join the transaction — applied at
1263
- once in an interactive one (WebSocket, SurrealDB 3.x), at the commit in a buffered one (HTTP, SurrealDB 2.x,
1264
- the embedded engine), where a refusal comes back as the transaction's own error; a block that raises applies
1265
- nothing. In a buffered transaction an index queued earlier in the block is not seen by the reads, and is
1266
- queued again (the same statement). Every cached read is dropped.
1263
+ outside the block. With *tx*, an index to define or redefine is also refused when the transaction has already
1264
+ written records to the model's table — an ORM write (``save()``, ``objects(tx=…).bulk_create()``, …) or one
1265
+ noted on every table; a definition such as ``define_table(tx=…)`` does not count, nor does a raw ``tx.add()``,
1266
+ which the ORM does not track: SurrealDB servers do not index the records a transaction wrote before the index
1267
+ was defined, which stay out of it after the commit — a server defect (surrealdb/surrealdb#7618 on 3.x, the
1268
+ same on 2.x; the embedded engine indexes them). The refusal does not fail the transaction; call
1269
+ ``define_indexes()`` without *tx* first. With *tx* and the analyzers in place, the index statements join the
1270
+ transaction — applied at once in an interactive one (WebSocket, SurrealDB 3.x),
1271
+ at the commit in a buffered one (HTTP, SurrealDB 2.x, the embedded engine), where a refusal comes back as the
1272
+ transaction's own error; a block that raises applies nothing. On SurrealDB 2.x, a write to a table that held
1273
+ records, after its index in the same block, fails the commit with a retryable ``SurrealDbConflictError`` that a
1274
+ retry meets again. In a buffered transaction an index queued earlier in the block is not seen by the reads, and
1275
+ is queued again (the same statement). Every cached read is dropped.
1267
1276
 
1268
1277
  Names are written in backticks, filters re-rendered from a closed grammar, numbers from Python numbers,
1269
1278
  comments as string literals. A refusal names the analyzer or the index and its table, never the statement:
@@ -1280,9 +1289,10 @@ class BaseSurrealModel(BaseModel):
1280
1289
  Raises:
1281
1290
  TypeError: *overwrite* is not a ``bool`` — before any request.
1282
1291
  SurrealDbError: *tx* belongs to another connection — before any request; an analyzer named by ``str`` does
1283
- not exist, or *tx* is given and an analyzer must be defined or redefined — before any DDL; the server
1284
- refused a statement (``Can't apply analyzer definition: …``, ``Can't apply index definition: …``,
1285
- ``Can't apply index rebuild: …``).
1292
+ not exist, or *tx* is given and an analyzer must be defined or redefined, or an index must be defined
1293
+ or redefined after the transaction wrote records to the model's table (the message names the model and
1294
+ the table) — before any DDL; the server refused a statement (``Can't apply analyzer definition: …``,
1295
+ ``Can't apply index definition: …``, ``Can't apply index rebuild: …``).
1286
1296
  SurrealDbAuthenticationError: the session may not read the definitions or define the analyzers and
1287
1297
  indexes.
1288
1298
 
@@ -1333,9 +1343,17 @@ class BaseSurrealModel(BaseModel):
1333
1343
  keyword=keyword,
1334
1344
  redefined=redefined,
1335
1345
  )
1346
+ # Issue #304: SurrealDB servers do not index the records a transaction wrote before the index was defined.
1347
+ # Under tx the analyzers are in place (refused above otherwise), so the definitions are all that would join it.
1348
+ if tx is not None and definitions:
1349
+ written = tx._records_written() if isinstance(tx, Transaction) else frozenset()
1350
+ if written is None or table in written:
1351
+ raise SurrealDbError(transaction_write_refused(cls.__name__, table))
1336
1352
  # A redefined analyzer leaves every index using it with its old tokens: the table's declared indexes (above),
1337
1353
  # its other indexes (another model's, or defined by hand), and every other table's — one INFO FOR TABLE each.
1338
1354
  analyzer_of = {index.name: index.analyzer_name or "" for index in indexes}
1355
+ # Issue #304: an index this call redefines is rebuilt by its DEFINE INDEX OVERWRITE; the warning names it too.
1356
+ redefined_indexes = [(table, name, analyzer_of[name]) for name, _ in definitions if analyzer_of[name] in redefined]
1339
1357
  own_rebuilds = [(table, name, analyzer_of[name]) for name, _ in rebuilds]
1340
1358
  own_rebuilds += stored_indexes_using(table, stored_indexes, redefined, skip=analyzer_of)
1341
1359
  other_rebuilds: list[tuple[str, str, str]] = []
@@ -1353,11 +1371,11 @@ class BaseSurrealModel(BaseModel):
1353
1371
  subjects=[index_subject(name, table) for name, _ in definitions],
1354
1372
  )
1355
1373
  applied += await apply_rebuilds(client, tx, own_rebuilds)
1356
- warn_redefined(redefine, [*other_rebuilds, *own_rebuilds])
1374
+ warn_redefined(redefine, [*other_rebuilds, *redefined_indexes, *own_rebuilds])
1357
1375
  return applied
1358
1376
 
1359
1377
  @classmethod
1360
- @_cache.invalidates("cls")
1378
+ @_cache.invalidates("cls", records=False)
1361
1379
  async def remove_index(cls, name: str, *, missing_ok: bool = True, tx: Transaction | None = None) -> str:
1362
1380
  """Remove the index named *name* from this model's table (v0.35.0) and return the statement applied.
1363
1381
 
@@ -1495,7 +1513,7 @@ class BaseSurrealModel(BaseModel):
1495
1513
  return view_statement(cls.get_table_name(), query, overwrite, clauses=cls._declared_table_clauses())
1496
1514
 
1497
1515
  @classmethod
1498
- @_cache.invalidates("cls")
1516
+ @_cache.invalidates("cls", records=False)
1499
1517
  async def define_view(cls, *, overwrite: bool = True, tx: Transaction | None = None) -> str:
1500
1518
  """Apply this materialized view to the database (v0.32.0) and return the statement applied.
1501
1519
 
@@ -1595,7 +1613,7 @@ class BaseSurrealModel(BaseModel):
1595
1613
  return statement
1596
1614
 
1597
1615
  @classmethod
1598
- @_cache.invalidates("cls")
1616
+ @_cache.invalidates("cls", records=False)
1599
1617
  async def remove_view(cls, *, missing_ok: bool = True, tx: Transaction | None = None) -> str:
1600
1618
  """Remove this materialized view from the database (v0.32.0) and return the statement applied.
1601
1619
 
@@ -1761,9 +1779,9 @@ class BaseSurrealModel(BaseModel):
1761
1779
  ``FLEXIBLE`` following *clauses*' schema mode. Pure.
1762
1780
 
1763
1781
  Raises:
1764
- TypeError: *overwrite* is not a ``bool``; a ``TableType.USER`` model with ``extra="allow"`` (UX1); then, when
1765
- *clauses* are ``SCHEMAFULL``, an auth model (``AuthenticatedUserMixin``) with a field SIGNUP writes that
1766
- ``Field(exclude=True)`` keeps out of the columns (SG1, #296).
1782
+ TypeError: *overwrite* is not a ``bool``; a ``TableType.USER`` model with ``extra="allow"`` (UX1); then,
1783
+ whatever *clauses*' schema mode, an auth model (``AuthenticatedUserMixin``) with a field SIGNUP writes
1784
+ that ``Field(exclude=True)`` keeps out of ``model_dump()`` (SG1, #296, #299).
1767
1785
  ValueError: see :meth:`_table_columns`.
1768
1786
  """
1769
1787
  if cls._is_view():
@@ -1774,16 +1792,15 @@ class BaseSurrealModel(BaseModel):
1774
1792
  raise TypeError(user_extra_refused(cls.__name__))
1775
1793
  schemafull = clauses.schema_mode == SchemaMode.SCHEMAFULL.value
1776
1794
  fields = [field_statement(table, column, overwrite=overwrite, schemafull=schemafull) for column in cls._table_columns()]
1777
- if schemafull:
1778
- # Imported here, only for a SCHEMAFULL table: model_auth sits above this module.
1779
- from .model_auth import AuthenticatedUserMixin
1780
-
1781
- # SG1 (#296), after the other refusals: SIGNUP writes a field the columns leave out, which the SCHEMAFULL
1782
- # table would refuse (3.x) or drop (2.x) — checked here, as UX1 is, so that table_ddl(), define_table(),
1783
- # access_ddl() and define_access() refuse the same model.
1784
- excluded: list[str] = cls._signup_fields_excluded() if issubclass(cls, AuthenticatedUserMixin) else []
1785
- if excluded:
1786
- raise TypeError(signup_excluded_refused(cls.__name__, excluded))
1795
+ # Imported here: model_auth sits above this module.
1796
+ from .model_auth import AuthenticatedUserMixin
1797
+
1798
+ if issubclass(cls, AuthenticatedUserMixin):
1799
+ # SG1 (#296, #299), after the other refusals, whatever the schema mode: SIGNUP writes a field model_dump()
1800
+ # leaves out, which update() and upsert() would drop and a SCHEMAFULL table would refuse (3.x) or drop
1801
+ # (2.x) — checked here, as UX1 is, so that table_ddl() and define_table() refuse the model access_ddl(),
1802
+ # define_access(), signup() and signin() refuse.
1803
+ cls._refuse_signup_fields_excluded()
1787
1804
  return [statement, *fields]
1788
1805
 
1789
1806
  @classmethod
@@ -1827,11 +1844,13 @@ class BaseSurrealModel(BaseModel):
1827
1844
  Raises:
1828
1845
  TypeError: *overwrite* is not a ``bool``; a ``TableType.USER`` model with ``extra="allow"`` (its table is
1829
1846
  ``SCHEMAFULL``, which refuses or drops the fields the model does not declare); an auth model
1830
- (``AuthenticatedUserMixin``) whose declared schema mode is ``SCHEMAFULL`` with a field SIGNUP writes
1831
- that ``Field(exclude=True)`` keeps out of the columns (``password: str = Field(exclude=True)``), which
1832
- the table would refuse or drop, failing every signup or signin — ``define_access()`` refuses it too;
1833
- remove ``exclude=True`` (a table defined by hand would not help: ``update()`` and ``upsert()`` replace
1834
- the record with what ``model_dump()`` writes).
1847
+ (``AuthenticatedUserMixin``), whatever its schema mode, with a field SIGNUP writes that
1848
+ ``Field(exclude=True)`` keeps out of ``model_dump()`` (``password: str = Field(exclude=True)``):
1849
+ ``update()`` and ``upsert()`` replace the record with what ``model_dump()`` writes, so they would drop
1850
+ the password hash, failing every later signin, or be refused by a required column, and a
1851
+ ``SCHEMAFULL`` table would not define the field — ``access_ddl()``, ``define_access()``, ``signup()``
1852
+ and ``signin()`` refuse the model too; remove ``exclude=True`` and pass ``exclude=`` to
1853
+ ``model_dump()`` where you serialise the model.
1835
1854
  ValueError: a ``FLEXIBLE`` request on a kind without an object; a computed field's expression that is not
1836
1855
  SurrealQL the ORM can embed.
1837
1856
 
@@ -1923,7 +1942,7 @@ class BaseSurrealModel(BaseModel):
1923
1942
  return [table_statement, *field_statements]
1924
1943
 
1925
1944
  @classmethod
1926
- @_cache.invalidates("cls")
1945
+ @_cache.invalidates("cls", records=False)
1927
1946
  async def define_table(cls, *, overwrite: bool = True, tx: Transaction | None = None) -> str:
1928
1947
  """Apply this model's table and field definitions (v0.34.0; the full SurrealDB-ORM's method) and return the
1929
1948
  statements applied — or queued, with a buffered transaction — table first, joined with ``"\\n"`` (the full
@@ -2008,8 +2027,8 @@ class BaseSurrealModel(BaseModel):
2008
2027
 
2009
2028
  Raises:
2010
2029
  TypeError: *overwrite* is not a ``bool``; a ``TableType.USER`` model with ``extra="allow"``; an auth model
2011
- whose declared schema mode is ``SCHEMAFULL`` with a field SIGNUP writes that ``Field(exclude=True)``
2012
- keeps out of the columns (see :meth:`table_ddl`) — before any request.
2030
+ with a field SIGNUP writes that ``Field(exclude=True)`` keeps out of ``model_dump()``, whatever its
2031
+ schema mode (see :meth:`table_ddl`) — before any request.
2013
2032
  ValueError: a ``FLEXIBLE`` request on a kind without an object; a computed field's expression that is not
2014
2033
  SurrealQL the ORM can embed — before any request.
2015
2034
  SurrealDbError: *tx* belongs to another connection — before any request; the table is a materialized view
@@ -85,8 +85,10 @@ table's field definitions with one ``INFO FOR TABLE``, keyed by path whichever r
85
85
  definition the parser cannot read. ``table_refused()`` gives the texts of the node models' table guard (TG1–TG4),
86
86
  ``relation_table_refused()`` names ``define_table()`` when it is the caller, and ``relation_schemafull_refused()``
87
87
  refuses ``define_relation()`` of an edge model declared ``SCHEMAFULL`` with data fields, which it would not define.
88
- ``user_extra_refused()`` and ``signup_excluded_refused()`` give the texts of UX1 and SG1, the refusals of a
89
- ``SCHEMAFULL`` table the model table DDL checks before any request.
88
+ ``user_extra_refused()`` gives the text of UX1, the refusal of a ``SCHEMAFULL`` table the model table DDL checks before
89
+ any request, and ``signup_excluded_refused()`` that of SG1, an auth model with a field SIGNUP writes that
90
+ ``Field(exclude=True)`` keeps out of ``model_dump()``, refused whatever its schema mode by the model table DDL, the
91
+ access DDL, ``signup()`` and ``signin()`` (#299).
90
92
 
91
93
  The module sits low in the package: it imports neither ``model_base`` nor ``connection_manager``, so both can import
92
94
  it.
@@ -1949,16 +1951,20 @@ def user_extra_refused(model: str) -> str:
1949
1951
 
1950
1952
 
1951
1953
  def signup_excluded_refused(model: str, fields: Sequence[str]) -> str:
1952
- """The refusal of an auth model whose ``SCHEMAFULL`` table would leave out *fields* (SG1, #296): SIGNUP writes
1953
- them, ``Field(exclude=True)`` keeps them out of ``model_dump()`` and so out of the columns the model table DDL
1954
- defines — in ``table_ddl()``, ``define_table()`` and ``define_access()`` alike. Pure."""
1954
+ """The refusal of an auth model with *fields* (in declaration order) that SIGNUP writes and
1955
+ ``Field(exclude=True)`` keeps out of ``model_dump()`` (SG1): ``update()`` and ``upsert()`` replace the stored record
1956
+ with what ``model_dump()`` writes, whatever the table's schema mode, so they drop them or a required column refuses
1957
+ them (#299), and a ``SCHEMAFULL`` table defined from the model has no column for them (#296). ``table_ddl()``,
1958
+ ``define_table()``, ``access_ddl()``, ``define_access()``, ``signup()`` and ``signin()`` raise it before any
1959
+ request. Pure."""
1955
1960
  names = ", ".join(repr(name) for name in fields)
1956
1961
  pronoun = "it" if len(fields) == 1 else "them"
1957
1962
  return (
1958
- f"{model}: SIGNUP writes {names}, but Field(exclude=True) keeps {pronoun} out of model_dump() and so out of the "
1959
- f"SCHEMAFULL table that table_ddl(), define_table() and define_access() define for the model; that table would "
1960
- f"refuse {pronoun} (SurrealDB 3.x) or drop {pronoun} (2.x), so no signup or signin would work. Remove "
1961
- f"exclude=True and leave {pronoun} out where you serialise the model instead (model_dump(exclude={{{names}}})): "
1962
- f"update() and upsert() replace the record with what model_dump() writes, so even over a table defined by "
1963
- f"hand they would be refused or drop {pronoun}."
1963
+ f"{model}: SIGNUP writes {names}, but Field(exclude=True) keeps {pronoun} out of model_dump(), and update() and "
1964
+ f"upsert() replace the stored record with what model_dump() writes, whatever the table's schema mode: they "
1965
+ f"would drop {pronoun} (a password hash: every later signin fails) or be refused by a required column. A "
1966
+ f"SCHEMAFULL table defined from the model has no column for {pronoun} either (SurrealDB 3.x refuses the signup, "
1967
+ f"2.x drops {pronoun}). Remove exclude=True and leave {pronoun} out where you serialise the model instead "
1968
+ f"(model_dump(exclude={{{names}}})); until then table_ddl(), define_table(), access_ddl(), define_access(), "
1969
+ f"signup() and signin() refuse {model}."
1964
1970
  )
@@ -1063,6 +1063,16 @@ def transaction_analyzer_refused(model: str, name: str) -> str:
1063
1063
  )
1064
1064
 
1065
1065
 
1066
+ def transaction_write_refused(model: str, table: str) -> str:
1067
+ """The refusal of ``define_indexes(tx=…)`` when the transaction has already written records to *table*, the
1068
+ model's (issue #304): SurrealDB servers leave those records out of the index."""
1069
+ return (
1070
+ f"{model}.define_indexes(tx=…) cannot define an index on table {table!r} in a transaction that has already "
1071
+ "written to that table: SurrealDB servers do not index the records a transaction wrote before the index was "
1072
+ f"defined. Call {model}.define_indexes() without tx= first, then write in the transaction."
1073
+ )
1074
+
1075
+
1066
1076
  def plan_indexes(
1067
1077
  indexes: Iterable[Index],
1068
1078
  table: str,
@@ -1140,6 +1150,9 @@ def warn_redefined(redefine: Iterable[Analyzer], rebuilt: Sequence[IndexUse]) ->
1140
1150
  """Log one warning per analyzer of *redefine*, naming the indexes of *rebuilt* (``(table, index, analyzer)``) that
1141
1151
  use it, in order: ``Analyzer 'english' redefined; 2 index(es) rebuilt: page.page_title, post.post_title``.
1142
1152
 
1153
+ *rebuilt* is every index the caller rebuilt, in the order applied: a ``REBUILD INDEX``, and an index it redefined
1154
+ (``DEFINE INDEX OVERWRITE`` rebuilds it — issue #304).
1155
+
1143
1156
  An analyzer belongs to the database: two models declaring two definitions of one name redefine it in turn, and
1144
1157
  rebuild every index using it each time — the warning makes that visible.
1145
1158
  """
@@ -25,6 +25,11 @@ Query cache (v0.28.0): an ORM write that joins a transaction notes the tables it
25
25
  it returns or raises (a failed commit's state is unknown). ``cancel()`` forgets them: nothing
26
26
  became visible.
27
27
 
28
+ Records written (issue #304): an ORM write of records that joins a transaction also notes the tables it writes
29
+ (``_note_record_write``), apart from the query cache's — a definition such as ``define_table(tx=…)`` notes its table
30
+ for the cache only. ``define_indexes(tx=…)`` reads them (``_records_written``): SurrealDB servers do not index the
31
+ records a transaction wrote before the index was defined. A raw ``tx.add()`` is not noted.
32
+
28
33
  Errors (issue #278): the errors a failed transaction raises give the server's reason and the failed statement's
29
34
  position, without the server's excerpt of the statement; the server's own text stays reachable as their suppressed
30
35
  ``__context__``. A query the server or the embedded engine refuses at a buffered commit raises ``SurrealDbError`` on
@@ -223,6 +228,10 @@ class Transaction(ABC):
223
228
  # Query cache: the tables written in this transaction, invalidated at commit.
224
229
  self._cache_tables: set[str] = set()
225
230
  self._cache_all = False
231
+ # Issue #304: the tables an ORM write of records changed in this transaction (definitions excluded), kept
232
+ # until the transaction ends.
233
+ self._record_tables: set[str] = set()
234
+ self._record_all = False
226
235
  # Issue #268: the errors of the statements that failed in this transaction (interactive strategy).
227
236
  self._failures: list[BaseException] = []
228
237
 
@@ -264,6 +273,23 @@ class Transaction(ABC):
264
273
  self._cache_tables.clear()
265
274
  self._cache_all = False
266
275
 
276
+ def _note_record_write(self, tables: Iterable[str] | None) -> None:
277
+ """Note the tables an ORM write of records in this transaction changes (``None``: every table) — issue #304.
278
+
279
+ ``cache.invalidates()`` calls it for each write method of records that joins the transaction, before the write
280
+ is sent or queued — never for a definition (``define_table()``, ``remove_index()``…), whose table is noted for
281
+ the query cache only. Unlike the query cache's tables, the commit and the cancel keep them.
282
+ """
283
+ if tables is None:
284
+ self._record_all = True
285
+ else:
286
+ self._record_tables |= set(tables)
287
+
288
+ def _records_written(self) -> frozenset[str] | None:
289
+ """The tables an ORM write of records changed so far in this transaction (issue #304): ``None`` when one noted
290
+ every table. ``define_indexes(tx=…)`` reads it; a raw ``tx.add()`` is not counted."""
291
+ return None if self._record_all else frozenset(self._record_tables)
292
+
267
293
  @property
268
294
  @abstractmethod
269
295
  def is_interactive(self) -> bool: