surreal-orm-lite 0.35.2__tar.gz → 0.35.4__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.2 → surreal_orm_lite-0.35.4}/CHANGELOG.md +77 -0
  2. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/PKG-INFO +31 -15
  3. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/README.md +30 -14
  4. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/cache.py +16 -1
  7. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/model_auth.py +17 -5
  8. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/model_base.py +85 -24
  9. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/schema.py +6 -4
  10. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/search.py +13 -0
  11. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/transaction.py +26 -0
  12. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/.gitignore +0 -0
  13. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/LICENSE +0 -0
  14. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/Makefile +0 -0
  15. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/_sdk.py +0 -0
  16. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/aggregations.py +0 -0
  17. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/auth.py +0 -0
  18. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/changefeed.py +0 -0
  19. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/concurrency.py +0 -0
  20. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/connection_config.py +0 -0
  21. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/connection_manager.py +0 -0
  22. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/constants.py +0 -0
  23. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/decoding.py +0 -0
  24. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/define_parser.py +0 -0
  25. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/edge.py +0 -0
  26. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/embedded.py +0 -0
  27. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/encoding.py +0 -0
  28. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/enum.py +0 -0
  29. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/exceptions.py +0 -0
  30. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/functions.py +0 -0
  31. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/geo.py +0 -0
  32. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/introspection.py +0 -0
  33. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/live.py +0 -0
  34. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/model_ddl.py +0 -0
  35. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/model_generator.py +0 -0
  36. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/py.typed +0 -0
  37. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/q.py +0 -0
  38. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/query_set.py +0 -0
  39. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/routing.py +0 -0
  40. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/schema_state.py +0 -0
  41. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/signals.py +0 -0
  42. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/subquery.py +0 -0
  43. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/surql_literal.py +0 -0
  44. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/testing/__init__.py +0 -0
  45. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/testing/database.py +0 -0
  46. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  47. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/time_travel.py +0 -0
  48. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/types.py +0 -0
  49. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.4}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,83 @@ 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.4] - 2026-10-23
9
+
10
+ `update()`, `upsert()`, `authenticate()` and `refresh()` refuse an auth model whose signup field
11
+ is declared `Field(exclude=True)`, as the DDL methods, `signup()` and `signin()` do since v0.35.2
12
+ (#310): a record signed up elsewhere and loaded through such a model no longer loses its stored
13
+ password hash at its first `update()` or `upsert()`. No new public API.
14
+
15
+ ### Changed
16
+
17
+ - **`authenticate()`, `refresh()`, `update()` and `upsert()` raise the v0.35.2 `TypeError` for
18
+ an auth model with an excluded signup field** (#310). For a model built on
19
+ `AuthenticatedUserMixin` with a field SIGNUP writes that `Field(exclude=True)` keeps out of
20
+ `model_dump()` (`password: str = Field(exclude=True)`), `update()` and `upsert()` now raise it
21
+ before any request and any `pre_save`/`pre_update` signal, with or without `tx=` (nothing is
22
+ added to the transaction), and `authenticate()` and `refresh()` before any request (a refresh
23
+ token is not spent). The message, `schema.signup_excluded_refused()`, now names every refusing
24
+ call: `table_ddl()`, `define_table()`, `access_ddl()`, `define_access()`, `signup()`,
25
+ `signin()`, `authenticate()`, `refresh()`, `update()` and `upsert()`. Auth models without
26
+ `exclude=True`, and models that are not auth models, write and authenticate as before.
27
+
28
+ ### Fixed
29
+
30
+ - **A record signed up elsewhere no longer loses its password hash at `update()` or `upsert()`
31
+ of a model with an excluded signup field** (#310). v0.35.2 refused such a model in the DDL
32
+ methods, `signup()` and `signin()`, but not in the calls that drop the value: when the access
33
+ was defined by hand or by an earlier deploy and the account signed up through another client,
34
+ `SurrealDBConnectionManager.signup()` or a session opened before the upgrade, an instance
35
+ returned by `authenticate()` or loaded with `get()` wrote the record back without the hash at
36
+ its first `update()` or `upsert()`, with no error: the hash became `NONE` on a `SCHEMALESS`
37
+ table or an optional column, and every later signin failed. These calls are now refused first
38
+ (see Changed), and the stored record stays as it was. README section 19, "User models" and the
39
+ v0.35.2 row of "ORM behaviour: SurrealDB 2.x vs 3.x" describe it; the behaviour is the same on
40
+ both lines.
41
+
42
+ ## [0.35.3] - 2026-10-23
43
+
44
+ Follow-ups to the review of v0.35.0's full-text search (#304): the warning of `define_indexes()`
45
+ names every index it rebuilds, and `define_indexes(tx=…)` refuses to define an index in a
46
+ transaction that has already written records to the model's table, which SurrealDB servers would
47
+ leave out of the index. No new public API.
48
+
49
+ ### Changed
50
+
51
+ - **`define_indexes(tx=…)` raises `SurrealDbError` after an ORM write to the model's table**
52
+ (#304). SurrealDB servers do not index the records a transaction wrote before the index was
53
+ defined: they stay out of it after the commit, and a search misses them. When an index must be
54
+ defined or redefined and the block has already written records to the model's table with the
55
+ ORM (`save()`, `objects(tx=…).bulk_create()`, …), `define_indexes(tx=…)` now raises before any
56
+ DDL, naming the model and the table; the refusal does not fail the transaction. Definitions
57
+ (`define_table(tx=…)`, `define_relation(tx=…)`, `remove_index(tx=…)`, …), a write to another
58
+ table and a call with nothing to apply do not count; a raw `tx.add()` is not tracked. Call
59
+ `define_indexes()` without `tx=` first, then write in the transaction. Earlier releases accepted
60
+ the call and the records written before it were missing from the index on SurrealDB 2.x and 3.x.
61
+
62
+ ### Fixed
63
+
64
+ - **The analyzer warning of `define_indexes()` names the indexes the call redefines** (#304).
65
+ When one call redefined an analyzer and an index that uses it, the warning counted only the
66
+ indexes rebuilt with `REBUILD INDEX` (`Analyzer 'plain' redefined; 0 index(es) rebuilt:`,
67
+ naming none), although `DEFINE INDEX OVERWRITE` rebuilds the redefined index too. It now names
68
+ every index the call rebuilds, in the order applied.
69
+
70
+ ### Notes
71
+
72
+ - **Reported upstream**: a SurrealDB 3.x server leaving out of an index the records the same
73
+ transaction wrote before `DEFINE INDEX` is a server defect,
74
+ [surrealdb/surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618); 2.x behaves the
75
+ same, and the embedded engine indexes those records. README section 36 (Transactions), a row of
76
+ the "ORM behaviour: SurrealDB 2.x vs 3.x" table and one of the embedded engine's table describe
77
+ each engine's outcome, which tests pin.
78
+ - **A write after `define_indexes(tx=…)` on SurrealDB 2.x**: in the same block, a write to a table
79
+ that held records fails the commit with a retryable `SurrealDbConflictError` that a retry meets
80
+ again, a 2.x limitation; SurrealDB 3.x and the embedded engine commit and index it. Prefer
81
+ `define_indexes()` outside the block.
82
+ - Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
83
+ plus 3.1.5 for backward compatibility.
84
+
8
85
  ## [0.35.2] - 2026-10-22
9
86
 
10
87
  An auth model whose signup field is declared `Field(exclude=True)` is refused whatever its schema
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.35.2
3
+ Version: 0.35.4
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
@@ -1337,8 +1337,12 @@ gives such a model the same table, so the two can be called in any order.
1337
1337
  record with what `model_dump()` writes: a field declared `Field(exclude=True)` (`password: str = Field(exclude=True)`)
1338
1338
  would lose its stored value, the password hash, and every later signin would fail. Such a model raises `TypeError`,
1339
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"})`).
1340
+ the table), `table_ddl()`, `define_table()`, `signup()`, `signin()`, `authenticate()` and `refresh()` refuse it, and so
1341
+ do `update()` and `upsert()` (with or without `tx=`, before any signal), whoever wrote the record — another client, an
1342
+ access defined by hand, a session opened before the upgrade. Remove `exclude=True` and leave the field out where you
1343
+ serialise the model instead (`model_dump(exclude={"password"})`). **Changed in v0.35.4**: `authenticate()`, `refresh()`,
1344
+ `update()` and `upsert()` used to accept such a model, so a record loaded with `authenticate()` or `get()` lost its
1345
+ hash at its first `update()` or `upsert()`.
1342
1346
 
1343
1347
  #### Renewing a session (SurrealDB 3.x only)
1344
1348
 
@@ -5715,12 +5719,15 @@ print(*table, sep="\n")
5715
5719
  - An auth model with a field SIGNUP writes that `Field(exclude=True)` keeps out of `model_dump()`
5716
5720
  (`password: str = Field(exclude=True)`) raises `TypeError` too, naming the fields, before any request and whatever
5717
5721
  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,
5722
+ `signup()`, `signin()`, `authenticate()` and `refresh()` refuse it, and so do `update()` and `upsert()`, with or
5723
+ without `tx=` and before any signal. `update()` and `upsert()` replace the record with what `model_dump()` writes,
5719
5724
  so on any table (`SCHEMALESS`, or defined by hand with `with_table=False`) they would drop the password hash, failing
5720
5725
  every later signin, or be refused by a required column; a `SCHEMAFULL` table would not define the field either, so
5721
5726
  SurrealDB 3.x would refuse every signup and 2.x drop the hash. Remove `exclude=True` and leave the field out where
5722
5727
  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.
5728
+ table or with `with_table=False` used to be accepted, and its first `update()` or `upsert()` dropped the hash; until
5729
+ v0.35.4, `authenticate()`, `refresh()`, `update()` and `upsert()` still accepted it, so a record signed up elsewhere
5730
+ (another client, an access defined by hand) and loaded with `authenticate()` or `get()` lost its hash the same way.
5724
5731
  - Upgrading: a 0.33 `TableType.USER` model's table turns `SCHEMAFULL` at its next `define_access()`; records already
5725
5732
  there are checked at their next write.
5726
5733
 
@@ -6034,11 +6041,12 @@ SurrealDB keeps the tokens of the records an index holds when their analyzer cha
6034
6041
  misses them — the records written afterwards use the new analyzer — until the index is rebuilt. So when
6035
6042
  `define_indexes()`, or `SurrealDBConnectionManager.define_analyzer()`, redefines an analyzer, it rebuilds every index of
6036
6043
  the database that uses it (`REBUILD INDEX`, sorted by table then index; `define_indexes()` rebuilds the model's table's
6037
- last), and logs one warning naming them (logger `surreal_orm_lite.search`). A rebuild re-reads the table: seconds
6038
- per thousands of records on SurrealDB 2.x and the embedded engine. An analyzer belongs to the database, not to a table:
6039
- declare one `Analyzer` per name (a module constant) and reference it from every index that uses it — two definitions
6040
- under one name would redefine it in turn, each time rebuilding its indexes. An unchanged index is never redefined, so
6041
- start-up never rebuilds (and, on SurrealDB 2.x, never inflates its scores).
6044
+ last), and logs one warning naming them, an index it redefines at the same time included (logger
6045
+ `surreal_orm_lite.search`). A rebuild re-reads the table: seconds per thousands of records on SurrealDB 2.x and the
6046
+ embedded engine. An analyzer belongs to the database, not to a table: declare one `Analyzer` per name (a module
6047
+ constant) and reference it from every index that uses it — two definitions under one name would redefine it in turn,
6048
+ each time rebuilding its indexes. An unchanged index is never redefined, so start-up never rebuilds (and, on SurrealDB
6049
+ 2.x, never inflates its scores).
6042
6050
 
6043
6051
  ```python
6044
6052
  PLAIN = Analyzer("plain", ["blank"], ["ascii"])
@@ -6082,9 +6090,15 @@ print(await NoteV2.objects().search(text="physics").count())
6082
6090
  So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL when an analyzer must be defined or redefined, and
6083
6091
  `define_analyzer(tx=…)` when a redefinition has indexes to rebuild (a new analyzer, or a redefinition no index uses,
6084
6092
  joins the transaction): call `define_analyzer()` without `tx=` first.
6085
- - Prefer `define_indexes()` outside the block: in a transaction that also writes to the model's table, SurrealDB may
6086
- leave out of the index a record the block wrote before the index was defined, and may fail the block on a write
6087
- after it.
6093
+ - The block must not have written to the model's table yet: SurrealDB servers do not index the records a transaction
6094
+ wrote before the index was defined, which stay out of it after the commit. It is a server defect
6095
+ ([surrealdb/surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618) on 3.x, the same on 2.x); only the
6096
+ embedded engine indexes them. So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL, naming the model and
6097
+ the table, when an index must be defined or redefined and the block has already written records to the model's table
6098
+ with the ORM (`save()`, `objects(tx=…).bulk_create()`, …). The refusal does not fail the block. `define_table(tx=…)`,
6099
+ `define_relation(tx=…)` and a write to another table do not count; a raw `tx.add()` is not tracked.
6100
+ - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6101
+ in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again.
6088
6102
  - `remove_analyzer(tx=…)` reads committed state to find the indexes that use the analyzer: an index queued earlier in
6089
6103
  a buffered block is not seen.
6090
6104
  - A search in an interactive transaction sees the transaction's writes; in a buffered one, a read raises, as every
@@ -6267,7 +6281,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
6267
6281
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
6268
6282
  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
6269
6283
  otherwise. The full suite and every divergence below were re-verified on both new versions.
6270
- 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.
6284
+ 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.
6271
6285
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
6272
6286
 
6273
6287
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -6417,7 +6431,8 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6417
6431
  | 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 |
6418
6432
  | `search()` on a field without a full-text index | `SurrealDbError` naming the field | the same; 3.1 answers no record | v0.35.0 |
6419
6433
  | `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 |
6420
- | 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 |
6434
+ | 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 DDL methods, `signup()`, `signin()`, `authenticate()`, `refresh()`, `update()`, `upsert()` | same on both lines (a check of the model, no request) | v0.35.2 |
6435
+ | `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 |
6421
6436
  | 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 |
6422
6437
 
6423
6438
  > **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.
@@ -6455,6 +6470,7 @@ Capabilities not listed behave as on a 2.x server.
6455
6470
  | 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 |
6456
6471
  | 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 |
6457
6472
  | 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 |
6473
+ | `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 |
6458
6474
  | 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 |
6459
6475
 
6460
6476
  ---
@@ -1286,8 +1286,12 @@ gives such a model the same table, so the two can be called in any order.
1286
1286
  record with what `model_dump()` writes: a field declared `Field(exclude=True)` (`password: str = Field(exclude=True)`)
1287
1287
  would lose its stored value, the password hash, and every later signin would fail. Such a model raises `TypeError`,
1288
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"})`).
1289
+ the table), `table_ddl()`, `define_table()`, `signup()`, `signin()`, `authenticate()` and `refresh()` refuse it, and so
1290
+ do `update()` and `upsert()` (with or without `tx=`, before any signal), whoever wrote the record — another client, an
1291
+ access defined by hand, a session opened before the upgrade. Remove `exclude=True` and leave the field out where you
1292
+ serialise the model instead (`model_dump(exclude={"password"})`). **Changed in v0.35.4**: `authenticate()`, `refresh()`,
1293
+ `update()` and `upsert()` used to accept such a model, so a record loaded with `authenticate()` or `get()` lost its
1294
+ hash at its first `update()` or `upsert()`.
1291
1295
 
1292
1296
  #### Renewing a session (SurrealDB 3.x only)
1293
1297
 
@@ -5664,12 +5668,15 @@ print(*table, sep="\n")
5664
5668
  - An auth model with a field SIGNUP writes that `Field(exclude=True)` keeps out of `model_dump()`
5665
5669
  (`password: str = Field(exclude=True)`) raises `TypeError` too, naming the fields, before any request and whatever
5666
5670
  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,
5671
+ `signup()`, `signin()`, `authenticate()` and `refresh()` refuse it, and so do `update()` and `upsert()`, with or
5672
+ without `tx=` and before any signal. `update()` and `upsert()` replace the record with what `model_dump()` writes,
5668
5673
  so on any table (`SCHEMALESS`, or defined by hand with `with_table=False`) they would drop the password hash, failing
5669
5674
  every later signin, or be refused by a required column; a `SCHEMAFULL` table would not define the field either, so
5670
5675
  SurrealDB 3.x would refuse every signup and 2.x drop the hash. Remove `exclude=True` and leave the field out where
5671
5676
  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.
5677
+ table or with `with_table=False` used to be accepted, and its first `update()` or `upsert()` dropped the hash; until
5678
+ v0.35.4, `authenticate()`, `refresh()`, `update()` and `upsert()` still accepted it, so a record signed up elsewhere
5679
+ (another client, an access defined by hand) and loaded with `authenticate()` or `get()` lost its hash the same way.
5673
5680
  - Upgrading: a 0.33 `TableType.USER` model's table turns `SCHEMAFULL` at its next `define_access()`; records already
5674
5681
  there are checked at their next write.
5675
5682
 
@@ -5983,11 +5990,12 @@ SurrealDB keeps the tokens of the records an index holds when their analyzer cha
5983
5990
  misses them — the records written afterwards use the new analyzer — until the index is rebuilt. So when
5984
5991
  `define_indexes()`, or `SurrealDBConnectionManager.define_analyzer()`, redefines an analyzer, it rebuilds every index of
5985
5992
  the database that uses it (`REBUILD INDEX`, sorted by table then index; `define_indexes()` rebuilds the model's table's
5986
- last), and logs one warning naming them (logger `surreal_orm_lite.search`). A rebuild re-reads the table: seconds
5987
- per thousands of records on SurrealDB 2.x and the embedded engine. An analyzer belongs to the database, not to a table:
5988
- declare one `Analyzer` per name (a module constant) and reference it from every index that uses it — two definitions
5989
- under one name would redefine it in turn, each time rebuilding its indexes. An unchanged index is never redefined, so
5990
- start-up never rebuilds (and, on SurrealDB 2.x, never inflates its scores).
5993
+ last), and logs one warning naming them, an index it redefines at the same time included (logger
5994
+ `surreal_orm_lite.search`). A rebuild re-reads the table: seconds per thousands of records on SurrealDB 2.x and the
5995
+ embedded engine. An analyzer belongs to the database, not to a table: declare one `Analyzer` per name (a module
5996
+ constant) and reference it from every index that uses it — two definitions under one name would redefine it in turn,
5997
+ each time rebuilding its indexes. An unchanged index is never redefined, so start-up never rebuilds (and, on SurrealDB
5998
+ 2.x, never inflates its scores).
5991
5999
 
5992
6000
  ```python
5993
6001
  PLAIN = Analyzer("plain", ["blank"], ["ascii"])
@@ -6031,9 +6039,15 @@ print(await NoteV2.objects().search(text="physics").count())
6031
6039
  So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL when an analyzer must be defined or redefined, and
6032
6040
  `define_analyzer(tx=…)` when a redefinition has indexes to rebuild (a new analyzer, or a redefinition no index uses,
6033
6041
  joins the transaction): call `define_analyzer()` without `tx=` first.
6034
- - Prefer `define_indexes()` outside the block: in a transaction that also writes to the model's table, SurrealDB may
6035
- leave out of the index a record the block wrote before the index was defined, and may fail the block on a write
6036
- after it.
6042
+ - The block must not have written to the model's table yet: SurrealDB servers do not index the records a transaction
6043
+ wrote before the index was defined, which stay out of it after the commit. It is a server defect
6044
+ ([surrealdb/surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618) on 3.x, the same on 2.x); only the
6045
+ embedded engine indexes them. So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL, naming the model and
6046
+ the table, when an index must be defined or redefined and the block has already written records to the model's table
6047
+ with the ORM (`save()`, `objects(tx=…).bulk_create()`, …). The refusal does not fail the block. `define_table(tx=…)`,
6048
+ `define_relation(tx=…)` and a write to another table do not count; a raw `tx.add()` is not tracked.
6049
+ - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6050
+ in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again.
6037
6051
  - `remove_analyzer(tx=…)` reads committed state to find the indexes that use the analyzer: an index queued earlier in
6038
6052
  a buffered block is not seen.
6039
6053
  - A search in an interactive transaction sees the transaction's writes; in a buffered one, a read raises, as every
@@ -6216,7 +6230,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
6216
6230
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
6217
6231
  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
6218
6232
  otherwise. The full suite and every divergence below were re-verified on both new versions.
6219
- 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.
6233
+ 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.
6220
6234
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
6221
6235
 
6222
6236
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -6366,7 +6380,8 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6366
6380
  | 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 |
6367
6381
  | `search()` on a field without a full-text index | `SurrealDbError` naming the field | the same; 3.1 answers no record | v0.35.0 |
6368
6382
  | `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 |
6369
- | 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 |
6383
+ | 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 DDL methods, `signup()`, `signin()`, `authenticate()`, `refresh()`, `update()`, `upsert()` | same on both lines (a check of the model, no request) | v0.35.2 |
6384
+ | `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 |
6370
6385
  | 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 |
6371
6386
 
6372
6387
  > **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.
@@ -6404,6 +6419,7 @@ Capabilities not listed behave as on a 2.x server.
6404
6419
  | 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 |
6405
6420
  | 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 |
6406
6421
  | 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 |
6422
+ | `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 |
6407
6423
  | 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 |
6408
6424
 
6409
6425
  ---
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.35.2"
3
+ version = "0.35.4"
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.2"
1
+ __version__ = "0.35.4"
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
@@ -282,11 +282,14 @@ class AuthenticatedUserMixin:
282
282
 
283
283
  @classmethod
284
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
285
+ """SG1 (#296, #299, #310): refuse a model with a field SIGNUP writes that ``Field(exclude=True)`` keeps out of
286
286
  ``model_dump()`` (:meth:`_signup_fields_excluded`), whatever its schema mode. Pure:
287
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.
288
+ :meth:`define_access`, with or without the table), :meth:`_auth_variables` (behind :meth:`signup` and
289
+ :meth:`signin`), :meth:`authenticate`, :meth:`refresh`, and ``update()`` and ``upsert()`` (through
290
+ ``BaseSurrealModel._reject_signup_excluded()``, with or without ``tx``, before any signal) call it before any
291
+ request: whichever call loads the record — ``authenticate()``, a ``get()``, a signup by another client —,
292
+ ``update()`` and ``upsert()`` would drop the stored hash.
290
293
 
291
294
  Raises:
292
295
  TypeError: naming the model and those fields, in declaration order (``schema.signup_excluded_refused()``).
@@ -485,7 +488,7 @@ class AuthenticatedUserMixin:
485
488
  return statements
486
489
 
487
490
  @classmethod
488
- @_cache.invalidates("cls")
491
+ @_cache.invalidates("cls", records=False)
489
492
  async def define_access(
490
493
  cls,
491
494
  *,
@@ -954,7 +957,9 @@ class AuthenticatedUserMixin:
954
957
  TypeError: the model has a field SIGNUP writes that ``Field(exclude=True)`` keeps
955
958
  out of ``model_dump()`` (see :meth:`access_ddl`) — before any request, so an
956
959
  access defined by hand cannot leave a record that ``update()`` or ``upsert()``
957
- would strip of its password hash.
960
+ would strip of its password hash. :meth:`signin`, :meth:`authenticate`,
961
+ :meth:`refresh`, ``update()`` and ``upsert()`` refuse such a model the same way
962
+ (#310), whoever wrote the record.
958
963
  ValueError: for an unknown field or a missing required one — before any request.
959
964
  SurrealDbAuthenticationError: if the server refuses the signup, or returns no
960
965
  record for the new session (the message says how to grant the permission).
@@ -1004,11 +1009,14 @@ class AuthenticatedUserMixin:
1004
1009
  on the embedded engine too.
1005
1010
 
1006
1011
  Raises:
1012
+ TypeError: as in :meth:`signup` (#310) — before any request: the instance returned
1013
+ would be one ``update()`` and ``upsert()`` strip of its password hash.
1007
1014
  SurrealDbAuthenticationError: if the token is malformed, expired or revoked. A
1008
1015
  malformed one is rejected by the SDK's own schema check without ever reaching
1009
1016
  the server, and is normalised here like any other auth failure.
1010
1017
  SurrealDbError: on the embedded engine without ``bind=True``.
1011
1018
  """
1019
+ cls._refuse_signup_fields_excluded()
1012
1020
  # On a server, bind=True adopts the token on the shared connection once it resolved to an
1013
1021
  # instance; on the embedded engine the exchange runs on the shared session and adopts the
1014
1022
  # token itself — one SDK authenticate(), not a second one through the manager.
@@ -1031,6 +1039,9 @@ class AuthenticatedUserMixin:
1031
1039
  you.
1032
1040
 
1033
1041
  Raises:
1042
+ TypeError: as in :meth:`signup` (#310) — before any request, so the refresh token is
1043
+ not spent: the instance returned would be one ``update()`` and ``upsert()`` strip
1044
+ of its password hash.
1034
1045
  ValueError: if no connection is configured, or the model is not declared with
1035
1046
  ``with_refresh=True`` — both before any request.
1036
1047
  SurrealDbAuthenticationError: if the token is spent or expired, or the server does
@@ -1042,6 +1053,7 @@ class AuthenticatedUserMixin:
1042
1053
  it (:meth:`SurrealDBConnectionManager.get_refresh_token`) and the shared session
1043
1054
  is signed in as that record. The error says which.
1044
1055
  """
1056
+ cls._refuse_signup_fields_excluded()
1045
1057
  manager: type[SurrealDBConnectionManager] = cls._connection_manager() # type: ignore[attr-defined]
1046
1058
  manager.require_connection()
1047
1059
  if not cls._auth_setting("with_refresh", False):
@@ -79,6 +79,7 @@ from .search import (
79
79
  remove_index_statement,
80
80
  stored_indexes_using,
81
81
  transaction_analyzer_refused,
82
+ transaction_write_refused,
82
83
  warn_redefined,
83
84
  )
84
85
  from .signals import (
@@ -116,6 +117,7 @@ from .utils import (
116
117
 
117
118
  if TYPE_CHECKING:
118
119
  from .edge import BaseSurrealEdge
120
+ from .model_auth import AuthenticatedUserMixin
119
121
 
120
122
  logger = logging.getLogger(__name__)
121
123
 
@@ -158,6 +160,16 @@ _ANNOTATED: Any = typing.Annotated
158
160
  _PYDANTIC_DIR = os.path.dirname(os.path.abspath(pydantic.__file__))
159
161
 
160
162
 
163
+ @functools.cache
164
+ def _auth_mixin() -> "type[AuthenticatedUserMixin]":
165
+ """``model_auth.AuthenticatedUserMixin``, imported on first use — ``model_auth`` sits above this module — and kept,
166
+ so that the SG1 check of the full replaces ``update()`` and ``upsert()`` (#310) costs a call and an
167
+ ``issubclass()`` on every model."""
168
+ from .model_auth import AuthenticatedUserMixin
169
+
170
+ return AuthenticatedUserMixin
171
+
172
+
161
173
  def _legacy_table_name(cls: type) -> str | None:
162
174
  """Return the deprecated ``_table_name: ClassVar[str]`` of ``cls`` (or a base), else ``None``.
163
175
 
@@ -950,7 +962,7 @@ class BaseSurrealModel(BaseModel):
950
962
  return statements
951
963
 
952
964
  @classmethod
953
- @_cache.invalidates("cls")
965
+ @_cache.invalidates("cls", records=False)
954
966
  async def define_computed_fields(
955
967
  cls,
956
968
  overwrite: bool = True,
@@ -1238,7 +1250,8 @@ class BaseSurrealModel(BaseModel):
1238
1250
  index of the database that uses it: ``INFO FOR TABLE`` of every other table (one request each, only then), and
1239
1251
  ``REBUILD INDEX`` for each of their indexes using it (sorted by table then index) before the index definitions,
1240
1252
  then for each unchanged index of this table using it after them (the declared ones in declaration order, then
1241
- the others). One warning per redefined analyzer names the indexes rebuilt (logger
1253
+ the others). One warning per redefined analyzer names the indexes rebuilt, in the order applied — the indexes
1254
+ this call defines with it included, which their ``DEFINE INDEX OVERWRITE`` rebuilds (logger
1242
1255
  ``surreal_orm_lite.search``). A rebuild re-reads the table — seconds per thousands of records on SurrealDB 2.x
1243
1256
  and the embedded engine.
1244
1257
 
@@ -1258,11 +1271,19 @@ class BaseSurrealModel(BaseModel):
1258
1271
  Before any DDL (nothing sent but the reads): an index that names by ``str`` an analyzer neither the database
1259
1272
  nor the model's ``Analyzer`` objects define is refused; with *tx*, an analyzer to define or redefine is refused
1260
1273
  — SurrealDB builds an index with the analyzers committed before the transaction began: define it first,
1261
- outside the block. With *tx* and the analyzers in place, the index statements join the transaction — applied at
1262
- once in an interactive one (WebSocket, SurrealDB 3.x), at the commit in a buffered one (HTTP, SurrealDB 2.x,
1263
- the embedded engine), where a refusal comes back as the transaction's own error; a block that raises applies
1264
- nothing. In a buffered transaction an index queued earlier in the block is not seen by the reads, and is
1265
- queued again (the same statement). Every cached read is dropped.
1274
+ outside the block. With *tx*, an index to define or redefine is also refused when the transaction has already
1275
+ written records to the model's table — an ORM write (``save()``, ``objects(tx=…).bulk_create()``, …) or one
1276
+ noted on every table; a definition such as ``define_table(tx=…)`` does not count, nor does a raw ``tx.add()``,
1277
+ which the ORM does not track: SurrealDB servers do not index the records a transaction wrote before the index
1278
+ was defined, which stay out of it after the commit — a server defect (surrealdb/surrealdb#7618 on 3.x, the
1279
+ same on 2.x; the embedded engine indexes them). The refusal does not fail the transaction; call
1280
+ ``define_indexes()`` without *tx* first. With *tx* and the analyzers in place, the index statements join the
1281
+ transaction — applied at once in an interactive one (WebSocket, SurrealDB 3.x),
1282
+ at the commit in a buffered one (HTTP, SurrealDB 2.x, the embedded engine), where a refusal comes back as the
1283
+ transaction's own error; a block that raises applies nothing. On SurrealDB 2.x, a write to a table that held
1284
+ records, after its index in the same block, fails the commit with a retryable ``SurrealDbConflictError`` that a
1285
+ retry meets again. In a buffered transaction an index queued earlier in the block is not seen by the reads, and
1286
+ is queued again (the same statement). Every cached read is dropped.
1266
1287
 
1267
1288
  Names are written in backticks, filters re-rendered from a closed grammar, numbers from Python numbers,
1268
1289
  comments as string literals. A refusal names the analyzer or the index and its table, never the statement:
@@ -1279,9 +1300,10 @@ class BaseSurrealModel(BaseModel):
1279
1300
  Raises:
1280
1301
  TypeError: *overwrite* is not a ``bool`` — before any request.
1281
1302
  SurrealDbError: *tx* belongs to another connection — before any request; an analyzer named by ``str`` does
1282
- not exist, or *tx* is given and an analyzer must be defined or redefined — before any DDL; the server
1283
- refused a statement (``Can't apply analyzer definition: …``, ``Can't apply index definition: …``,
1284
- ``Can't apply index rebuild: …``).
1303
+ not exist, or *tx* is given and an analyzer must be defined or redefined, or an index must be defined
1304
+ or redefined after the transaction wrote records to the model's table (the message names the model and
1305
+ the table) — before any DDL; the server refused a statement (``Can't apply analyzer definition: …``,
1306
+ ``Can't apply index definition: …``, ``Can't apply index rebuild: …``).
1285
1307
  SurrealDbAuthenticationError: the session may not read the definitions or define the analyzers and
1286
1308
  indexes.
1287
1309
 
@@ -1332,9 +1354,17 @@ class BaseSurrealModel(BaseModel):
1332
1354
  keyword=keyword,
1333
1355
  redefined=redefined,
1334
1356
  )
1357
+ # Issue #304: SurrealDB servers do not index the records a transaction wrote before the index was defined.
1358
+ # Under tx the analyzers are in place (refused above otherwise), so the definitions are all that would join it.
1359
+ if tx is not None and definitions:
1360
+ written = tx._records_written() if isinstance(tx, Transaction) else frozenset()
1361
+ if written is None or table in written:
1362
+ raise SurrealDbError(transaction_write_refused(cls.__name__, table))
1335
1363
  # A redefined analyzer leaves every index using it with its old tokens: the table's declared indexes (above),
1336
1364
  # its other indexes (another model's, or defined by hand), and every other table's — one INFO FOR TABLE each.
1337
1365
  analyzer_of = {index.name: index.analyzer_name or "" for index in indexes}
1366
+ # Issue #304: an index this call redefines is rebuilt by its DEFINE INDEX OVERWRITE; the warning names it too.
1367
+ redefined_indexes = [(table, name, analyzer_of[name]) for name, _ in definitions if analyzer_of[name] in redefined]
1338
1368
  own_rebuilds = [(table, name, analyzer_of[name]) for name, _ in rebuilds]
1339
1369
  own_rebuilds += stored_indexes_using(table, stored_indexes, redefined, skip=analyzer_of)
1340
1370
  other_rebuilds: list[tuple[str, str, str]] = []
@@ -1352,11 +1382,11 @@ class BaseSurrealModel(BaseModel):
1352
1382
  subjects=[index_subject(name, table) for name, _ in definitions],
1353
1383
  )
1354
1384
  applied += await apply_rebuilds(client, tx, own_rebuilds)
1355
- warn_redefined(redefine, [*other_rebuilds, *own_rebuilds])
1385
+ warn_redefined(redefine, [*other_rebuilds, *redefined_indexes, *own_rebuilds])
1356
1386
  return applied
1357
1387
 
1358
1388
  @classmethod
1359
- @_cache.invalidates("cls")
1389
+ @_cache.invalidates("cls", records=False)
1360
1390
  async def remove_index(cls, name: str, *, missing_ok: bool = True, tx: Transaction | None = None) -> str:
1361
1391
  """Remove the index named *name* from this model's table (v0.35.0) and return the statement applied.
1362
1392
 
@@ -1443,6 +1473,23 @@ class BaseSurrealModel(BaseModel):
1443
1473
  if cls._is_view():
1444
1474
  raise TypeError(view_write_refused(cls.get_table_name(), f"{cls.__name__}.{call}"))
1445
1475
 
1476
+ @classmethod
1477
+ def _reject_signup_excluded(cls) -> None:
1478
+ """SG1 (#296, #299, #310) on an auth model (``AuthenticatedUserMixin``): refuse it when a field SIGNUP writes is
1479
+ one ``Field(exclude=True)`` keeps out of ``model_dump()`` (``_refuse_signup_fields_excluded()``); nothing on any
1480
+ other model. Pure.
1481
+
1482
+ Called by :meth:`_table_ddl`, after its other refusals, and by the full replaces :meth:`update` and
1483
+ :meth:`upsert`, right after the view and snapshot checks — before any signal, transaction use or request: they
1484
+ write what ``model_dump()`` writes, so they would drop the stored value of such a field (a password hash, and
1485
+ every later signin fails).
1486
+
1487
+ Raises:
1488
+ TypeError: the auth model and those fields, in declaration order (``schema.signup_excluded_refused()``).
1489
+ """
1490
+ if issubclass(cls, _auth_mixin()):
1491
+ cls._refuse_signup_fields_excluded()
1492
+
1446
1493
  @classmethod
1447
1494
  def _require_view(cls, method: str) -> str:
1448
1495
  """The model's view query (:meth:`get_view_query`), or V11 naming *method* (``"view_ddl()"``) (v0.32.0).
@@ -1494,7 +1541,7 @@ class BaseSurrealModel(BaseModel):
1494
1541
  return view_statement(cls.get_table_name(), query, overwrite, clauses=cls._declared_table_clauses())
1495
1542
 
1496
1543
  @classmethod
1497
- @_cache.invalidates("cls")
1544
+ @_cache.invalidates("cls", records=False)
1498
1545
  async def define_view(cls, *, overwrite: bool = True, tx: Transaction | None = None) -> str:
1499
1546
  """Apply this materialized view to the database (v0.32.0) and return the statement applied.
1500
1547
 
@@ -1594,7 +1641,7 @@ class BaseSurrealModel(BaseModel):
1594
1641
  return statement
1595
1642
 
1596
1643
  @classmethod
1597
- @_cache.invalidates("cls")
1644
+ @_cache.invalidates("cls", records=False)
1598
1645
  async def remove_view(cls, *, missing_ok: bool = True, tx: Transaction | None = None) -> str:
1599
1646
  """Remove this materialized view from the database (v0.32.0) and return the statement applied.
1600
1647
 
@@ -1773,15 +1820,11 @@ class BaseSurrealModel(BaseModel):
1773
1820
  raise TypeError(user_extra_refused(cls.__name__))
1774
1821
  schemafull = clauses.schema_mode == SchemaMode.SCHEMAFULL.value
1775
1822
  fields = [field_statement(table, column, overwrite=overwrite, schemafull=schemafull) for column in cls._table_columns()]
1776
- # Imported here: model_auth sits above this module.
1777
- from .model_auth import AuthenticatedUserMixin
1778
-
1779
- if issubclass(cls, AuthenticatedUserMixin):
1780
- # SG1 (#296, #299), after the other refusals, whatever the schema mode: SIGNUP writes a field model_dump()
1781
- # leaves out, which update() and upsert() would drop and a SCHEMAFULL table would refuse (3.x) or drop
1782
- # (2.x) — checked here, as UX1 is, so that table_ddl() and define_table() refuse the model access_ddl(),
1783
- # define_access(), signup() and signin() refuse.
1784
- cls._refuse_signup_fields_excluded()
1823
+ # SG1 (#296, #299, #310) on an auth model, after the other refusals, whatever the schema mode: SIGNUP writes a
1824
+ # field model_dump() leaves out, which update() and upsert() would drop and a SCHEMAFULL table would refuse
1825
+ # (3.x) or drop (2.x) — checked here, as UX1 is, so that table_ddl() and define_table() refuse the model
1826
+ # access_ddl(), define_access(), signup(), signin(), authenticate(), refresh(), update() and upsert() refuse.
1827
+ cls._reject_signup_excluded()
1785
1828
  return [statement, *fields]
1786
1829
 
1787
1830
  @classmethod
@@ -1923,7 +1966,7 @@ class BaseSurrealModel(BaseModel):
1923
1966
  return [table_statement, *field_statements]
1924
1967
 
1925
1968
  @classmethod
1926
- @_cache.invalidates("cls")
1969
+ @_cache.invalidates("cls", records=False)
1927
1970
  async def define_table(cls, *, overwrite: bool = True, tx: Transaction | None = None) -> str:
1928
1971
  """Apply this model's table and field definitions (v0.34.0; the full SurrealDB-ORM's method) and return the
1929
1972
  statements applied — or queued, with a buffered transaction — table first, joined with ``"\\n"`` (the full
@@ -3363,9 +3406,18 @@ class BaseSurrealModel(BaseModel):
3363
3406
  Emits the same signals as ``save()`` (``pre_save``/``around_save``/``post_save``);
3364
3407
  in a transaction ``around_save`` is skipped and ``post_save`` is deferred to a
3365
3408
  successful commit (consistent with ``save(tx=)``).
3409
+
3410
+ Raises:
3411
+ TypeError: the model is a materialized view (W1); or an auth model
3412
+ (``AuthenticatedUserMixin``) with a field SIGNUP writes that ``Field(exclude=True)``
3413
+ keeps out of ``model_dump()`` (SG1, #310): the replace would drop its stored value
3414
+ (a password hash) — before any signal, transaction use or request, with or
3415
+ without ``tx``.
3416
+ SurrealDbError: the instance is a snapshot read with ``as_of()``.
3366
3417
  """
3367
3418
  self._reject_view_write("upsert()")
3368
3419
  self._reject_snapshot_write("upsert()")
3420
+ self._reject_signup_excluded()
3369
3421
  return await self._save_with_signals(self._do_upsert, tx)
3370
3422
 
3371
3423
  @_cache.invalidates("self")
@@ -3412,9 +3464,18 @@ class BaseSurrealModel(BaseModel):
3412
3464
  Returns:
3413
3465
  The updated row as the SDK reads it (``[]`` for a record that does not exist), or
3414
3466
  ``None`` in a transaction.
3467
+
3468
+ Raises:
3469
+ TypeError: the model is a materialized view (W1); or an auth model
3470
+ (``AuthenticatedUserMixin``) with a field SIGNUP writes that ``Field(exclude=True)``
3471
+ keeps out of ``model_dump()`` (SG1, #310): the replace would drop its stored value
3472
+ (a password hash) — before any signal, transaction use or request, with or
3473
+ without ``tx``.
3474
+ SurrealDbError: the instance is a snapshot read with ``as_of()``, or it has no id.
3415
3475
  """
3416
3476
  self._reject_view_write("update()")
3417
3477
  self._reject_snapshot_write("update()")
3478
+ self._reject_signup_excluded()
3418
3479
  sender = self.__class__
3419
3480
  data = self._write_payload(replace=True)
3420
3481
  record_id = self._record_id()
@@ -88,7 +88,8 @@ refuses ``define_relation()`` of an edge model declared ``SCHEMAFULL`` with data
88
88
  ``user_extra_refused()`` gives the text of UX1, the refusal of a ``SCHEMAFULL`` table the model table DDL checks before
89
89
  any request, and ``signup_excluded_refused()`` that of SG1, an auth model with a field SIGNUP writes that
90
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).
91
+ access DDL, ``signup()`` and ``signin()`` (#299), ``authenticate()``, ``refresh()``, ``update()`` and ``upsert()``
92
+ (#310).
92
93
 
93
94
  The module sits low in the package: it imports neither ``model_base`` nor ``connection_manager``, so both can import
94
95
  it.
@@ -1955,8 +1956,9 @@ def signup_excluded_refused(model: str, fields: Sequence[str]) -> str:
1955
1956
  ``Field(exclude=True)`` keeps out of ``model_dump()`` (SG1): ``update()`` and ``upsert()`` replace the stored record
1956
1957
  with what ``model_dump()`` writes, whatever the table's schema mode, so they drop them or a required column refuses
1957
1958
  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."""
1959
+ ``define_table()``, ``access_ddl()``, ``define_access()``, ``signup()``, ``signin()``, ``authenticate()``,
1960
+ ``refresh()``, ``update()`` and ``upsert()`` raise it before any request — ``update()`` and ``upsert()`` before any
1961
+ signal too, with or without ``tx`` (#310), whoever wrote the record they replace. Pure."""
1960
1962
  names = ", ".join(repr(name) for name in fields)
1961
1963
  pronoun = "it" if len(fields) == 1 else "them"
1962
1964
  return (
@@ -1966,5 +1968,5 @@ def signup_excluded_refused(model: str, fields: Sequence[str]) -> str:
1966
1968
  f"SCHEMAFULL table defined from the model has no column for {pronoun} either (SurrealDB 3.x refuses the signup, "
1967
1969
  f"2.x drops {pronoun}). Remove exclude=True and leave {pronoun} out where you serialise the model instead "
1968
1970
  f"(model_dump(exclude={{{names}}})); until then table_ddl(), define_table(), access_ddl(), define_access(), "
1969
- f"signup() and signin() refuse {model}."
1971
+ f"signup(), signin(), authenticate(), refresh(), update() and upsert() refuse {model}."
1970
1972
  )
@@ -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: