surreal-orm-lite 0.29.3__tar.gz → 0.30.1__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 (46) hide show
  1. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/CHANGELOG.md +133 -0
  2. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/PKG-INFO +339 -4
  3. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/README.md +338 -3
  4. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/__init__.py +30 -1
  6. surreal_orm_lite-0.30.1/src/surreal_orm_lite/define_parser.py +2466 -0
  7. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/functions.py +10 -2
  8. surreal_orm_lite-0.30.1/src/surreal_orm_lite/introspection.py +453 -0
  9. surreal_orm_lite-0.30.1/src/surreal_orm_lite/model_generator.py +1284 -0
  10. surreal_orm_lite-0.30.1/src/surreal_orm_lite/schema_state.py +441 -0
  11. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/.gitignore +0 -0
  12. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/LICENSE +0 -0
  13. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/Makefile +0 -0
  14. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/_sdk.py +0 -0
  15. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/aggregations.py +0 -0
  16. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/auth.py +0 -0
  17. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/cache.py +0 -0
  18. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/changefeed.py +0 -0
  19. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/concurrency.py +0 -0
  20. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/connection_config.py +0 -0
  21. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/connection_manager.py +0 -0
  22. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/constants.py +0 -0
  23. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/decoding.py +0 -0
  24. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/edge.py +0 -0
  25. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/embedded.py +0 -0
  26. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/encoding.py +0 -0
  27. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/enum.py +0 -0
  28. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/exceptions.py +0 -0
  29. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/geo.py +0 -0
  30. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/live.py +0 -0
  31. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/model_auth.py +0 -0
  32. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/model_base.py +0 -0
  33. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/py.typed +0 -0
  34. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/q.py +0 -0
  35. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/query_set.py +0 -0
  36. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/routing.py +0 -0
  37. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/signals.py +0 -0
  38. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/subquery.py +0 -0
  39. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/surql_literal.py +0 -0
  40. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/testing/__init__.py +0 -0
  41. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/testing/database.py +0 -0
  42. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  43. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/time_travel.py +0 -0
  44. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/transaction.py +0 -0
  45. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/types.py +0 -0
  46. {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.1}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,139 @@ 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.30.0] - 2026-10-19
9
+
10
+ Schema introspection: the ORM reads the schema of a database as immutable typed objects and
11
+ generates `BaseSurrealModel` classes from it, with the full SurrealDB-ORM's names. It only reads
12
+ (`INFO FOR DB`, `INFO FOR TABLE`), and the same schema gives the same state and the same generated
13
+ types on SurrealDB 2.x, 3.x and the embedded engine. The first minor of Tier 3.
14
+
15
+ ### Added
16
+
17
+ - **`DatabaseIntrospector(connection=None, *, tables=None).introspect()`** returns a
18
+ `SchemaState`: the tables (`TableState`, with their `FieldState`, `IndexState` and `EventState`)
19
+ and the database's accesses (`AccessState`), analyzers (`AnalyzerState`), functions
20
+ (`FunctionState`, keyed `"fn::name"`) and params (`ParamState`). It sends `INFO FOR DB;`, then
21
+ one `INFO FOR TABLE` per table, outside any transaction: no record is read, nothing is defined or
22
+ written. A field is keyed by its path (`"address.city"`, `"tags.*"`), with `field_type` (its kind
23
+ without the optional wrapper), `nullable` (whether it may be `NONE`) and its expressions
24
+ (`default`, `value`, `computed`, `assertion`, permission rules) as SurrealQL text; every
25
+ definition keeps the server's statement in `raw`, and the sections the ORM does not model are in
26
+ `schema.other`. `connection=` is a connection name (else the current one: `using()`, then
27
+ `"default"`), and `tables=` reads those tables only.
28
+
29
+ ```python
30
+ from surreal_orm_lite import DatabaseIntrospector
31
+
32
+ schema = await DatabaseIntrospector().introspect()
33
+ person = schema.tables["person"]
34
+ person.fields["age"].field_type # 'int': option<int> on SurrealDB 2.x, none | int on 3.x
35
+ person.fields["age"].nullable # True
36
+ person.fields["age"].default # '18': SurrealQL text
37
+ person.indexes["person_name"].unique # True
38
+ ```
39
+
40
+ - **`ModelCodeGenerator().generate(state)`** and
41
+ **`generate_models_from_db(output_path=None, connection=None, *, tables=None, overwrite=True)`**
42
+ give deterministic source with one class per table: a `BaseSurrealModel`, or a `BaseSurrealEdge`
43
+ for a `TYPE RELATION` table. Fields use the lite's types (`Duration`, `Decimal`, `UUID`,
44
+ `RecordID`, `Range`, the geometry classes, `Literal`), sub-models for declared nested fields,
45
+ `computed()` for `COMPUTED` and for a `VALUE` that reads neither `$value` nor `$input`, aliases
46
+ for columns that cannot be attribute names, `extra="allow"` for `SCHEMALESS` tables, and
47
+ `connection=` for a schema read from a named connection. A constant `DEFAULT` becomes the Python
48
+ default (`DEFAULT 18` → `= 18`, `[]` → `Field(default_factory=list)`, `1h30m` →
49
+ `Duration.parse("1h30m")`, `u'…'` → `UUID("…")`); any other `DEFAULT` becomes a `server_fields`
50
+ entry. Names, comments and expressions read from the database reach the source only as escaped
51
+ string literals, single-line comments and generated identifiers.
52
+
53
+ ```python
54
+ from surreal_orm_lite import generate_models_from_db
55
+
56
+ source = await generate_models_from_db() # the source, as a string
57
+ await generate_models_from_db("app/models_generated.py") # also writes it, replacing the file
58
+ await generate_models_from_db("app/models_generated.py", overwrite=False) # FileExistsError
59
+ ```
60
+
61
+ - **`generate_models_from_db()` replaces an existing file atomically**, as the full ORM replaces
62
+ it: the source goes to a temporary file in the same directory, then `os.replace()` moves it over
63
+ the file, so a failure leaves the previous file. `overwrite=False` refuses an existing path with
64
+ `FileExistsError` before reading anything.
65
+ - **The state classes take the full SurrealDB-ORM's arguments**: `SchemaState`, `TableState`,
66
+ `FieldState`, `IndexState`, `EventState`, `AccessState` and `AnalyzerState` are built by
67
+ position or by keyword as in the full ORM, and the lite's own attributes (`raw`, `path`, `table`,
68
+ `comment`, …) are keyword-only. They are frozen dataclasses with read-only maps and tuples, and
69
+ `repr()` shows names and structure only, never a definition's text. `FunctionState`,
70
+ `ParamState`, `SchemaIssue` and `tables=` are lite additions. The 13 names are exported from
71
+ `surreal_orm_lite`.
72
+ - **Nothing is guessed**: a definition that cannot be parsed exactly, a section of an unexpected
73
+ shape or a failed `INFO FOR TABLE` becomes a `SchemaIssue` in `schema.issues` and a WARNING on
74
+ the `surreal_orm_lite.introspection` logger, whose message never quotes the definition.
75
+ `introspect()` raises `SurrealDbAuthenticationError` when the session may not run
76
+ `INFO FOR DB`, `SurrealDbError` when it fails otherwise, and `SurrealDbNotFoundError` for a
77
+ `tables=` name the database does not define.
78
+ - README section 31, "Schema introspection (`DatabaseIntrospector`, `generate_models_from_db()`)"
79
+ (reading the schema, generating models, how SurrealDB kinds become fields, what the generator
80
+ does not do, SurrealDB 2.x and 3.x, permissions, a note for users of the full SurrealDB-ORM), a
81
+ features row, rows in the 2.x/3.x and embedded-engine behaviour tables, the comparison and
82
+ roadmap rows, and the example notebook `examples/v0.30.0_schema_introspection.ipynb`.
83
+
84
+ ### Fixed
85
+
86
+ - **A stored function's parameter list is read in linear time** (`call_function()` with keyword
87
+ arguments, and now introspection): a long `DEFINE FUNCTION`, or one holding `` $` `` or `$⟨`
88
+ without a closing quote, no longer makes the reader copy or search the rest of the definition at
89
+ every `$`.
90
+
91
+ ### Notes
92
+
93
+ - **Kinds and field paths are normalised, expressions are kept as rendered**: `option<int>` (2.x)
94
+ and `none | int` (3.x) both give `field_type == "int"` and `nullable is True`, and `tags[*]`
95
+ (2.x) and `tags.*` (3.x) both give the field `"tags.*"`. Expressions (`default`, `value`, `raw`,
96
+ a generated `computed("…")`) are kept as each line renders them and may differ:
97
+ `VALUE IF b THEN 1 ELSE 2 END` on 2.x is `VALUE (IF b THEN 1 ELSE 2 END)` on 3.x.
98
+ - **Definitions only one line has** are read and typed on that line: on 3.x `COMPUTED`,
99
+ `REFERENCE`, `FULLTEXT` indexes, the `file` kind, `WITH REFRESH` and `BEARER` accesses, and
100
+ `DEFINE SEQUENCE` (kept raw in `schema.other`); on 2.x and the embedded engine `MTREE` and
101
+ `SEARCH ANALYZER` indexes and `geometry<feature>`.
102
+ - **The `users` section is never read.** On SurrealDB before 3.2.2 (every 2.x release, 3.x before
103
+ 3.2.2, and the embedded engine of SDK 2.0.0), `INFO FOR DB` shows user password hashes to every
104
+ role that may run `INFO`, per SurrealDB's `INFO` documentation; introspection never reads,
105
+ stores, logs or writes them. Introspection needs a system user (root, a namespace or a database
106
+ user): a record user or an anonymous session gets `SurrealDbAuthenticationError`, except on the
107
+ embedded engine, whose anonymous session owns the database.
108
+ - **Tables not generated**, listed in the module's header and still in `schema.tables`: a table
109
+ named like a SurrealQL keyword, in any case (`select`, `create`, `only`, …), and a table whose
110
+ name is not an identifier, which the ORM's statements cannot use as a table name.
111
+ - **`update()` and `READONLY` datetimes**: an instance holding a `READONLY` `datetime` field cannot
112
+ be changed with `update()`, after `get()` as after `save()`: Python keeps microseconds, SurrealDB
113
+ nanoseconds, and the server refuses the changed value. This predates v0.30.0; the generated class
114
+ says so: change such a record with `merge()`.
115
+ - **Sub-fields a `DEFAULT` fills**: a sub-field filled by a `DEFAULT` the model does not hold
116
+ (`prefs.at DEFAULT time::now()`, or any `DEFAULT` under a `dict[str, Any]` field) stays `None` on
117
+ the instance after `save()`, which reads back only `server_fields` and computed fields; a
118
+ following `update()` sends it as `NONE`: the server refuses it when the sub-field is required and
119
+ erases the value when it is optional. The generated class says so: call `refresh()` after
120
+ `save()` before an `update()`, or change the record with `merge()`.
121
+ - **Defaults are copied when the models are generated**: generate them again after changing a
122
+ `DEFAULT`. A value set on a `server_fields` field before `save()` is not written, as since
123
+ v0.18.0 and in the full ORM: set it with `merge()` once the record exists.
124
+ - `array<T, N>` becomes `list[T]`, leaving the length to the server (SurrealDB 2.x accepts at most
125
+ N items, 3.x exactly N); `null | T` becomes a required `T | None`, which the ORM sends as `NONE`
126
+ and `null | T` refuses: declare such a field `option<T>`. `ASSERT`, `PERMISSIONS` and field
127
+ comments are not generated, and `READONLY` is a comment. Never call `define_computed_fields()` on
128
+ a generated model.
129
+ - **Differences from the full SurrealDB-ORM**: the state is immutable, with tuples where the full
130
+ ORM has lists; permission values are `'FULL'`, `'NONE'` or `'WHERE <expr>'`; `default` is
131
+ SurrealQL text; `nullable` is false for `null | T`; accesses are database-level
132
+ (`schema.accesses`); a refused or failed `INFO FOR DB` raises and an unreadable definition
133
+ becomes a `SchemaIssue`; `connection=` is a name, and a client object raises `TypeError`;
134
+ generated models use comments for the `SurrealConfigDict` keys that arrive with v0.31.0–v0.33.0
135
+ (`table_type`, `permissions`, `changefeed`, `view_query`, `relation_in`, `relation_out`,
136
+ `enforced`); class names are not singularised. `schema_diff()` and `SchemaState.diff()` come with
137
+ v0.37.0 (migrations), the `inspectdb` command with v0.38.0 (CLI).
138
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
139
+ plus 3.1.5 for backward compatibility.
140
+
8
141
  ## [0.29.3] - 2026-10-18
9
142
 
10
143
  `get_or_create()` and `update_or_create()` bind the queryset's `variables()` in their lookup, as
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.29.3
3
+ Version: 0.30.1
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
@@ -264,6 +264,7 @@ embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads
264
264
  | Subqueries (`Subquery`, a QuerySet as a filter value) | ✅ |
265
265
  | Query cache (`cache()`, TTL, invalidated by ORM writes) | ✅ |
266
266
  | Multiple databases (named connections, `using()`) | ✅ |
267
+ | Schema introspection (`DatabaseIntrospector`, `generate_models_from_db()`) | ✅ |
267
268
 
268
269
  ### Supported Filter Lookups
269
270
 
@@ -4068,6 +4069,331 @@ views = await PageView.objects().count() # 2
4068
4069
  `?name=` query parameter: a request never chooses the connection (full ORM: `name` is visible and becomes a query
4069
4070
  parameter).
4070
4071
 
4072
+ ### 31. Schema introspection (`DatabaseIntrospector`, `generate_models_from_db()`)
4073
+
4074
+ Since v0.30.0 the ORM reads the schema of a database — its tables with their fields, indexes and events, and its
4075
+ accesses, analyzers, functions and params — as immutable typed objects, and generates `BaseSurrealModel` classes from
4076
+ it, as the full SurrealDB-ORM does. It only reads: it sends `INFO FOR DB` and `INFO FOR TABLE`, never a statement that
4077
+ reads a record or changes the schema, so it needs a session allowed to run `INFO`: a system user
4078
+ ([Permissions](#permissions)). Kinds, field paths and the generated types are the same on SurrealDB 2.x, 3.x and the
4079
+ embedded engine; expressions (`DEFAULT`, `VALUE`, `ASSERT` …) are kept as each line renders them
4080
+ ([SurrealDB 2.x and 3.x](#surrealdb-2x-and-3x)). The examples of this section run on the embedded engine (`mem://`),
4081
+ with nothing to start.
4082
+
4083
+ #### Reading the schema
4084
+
4085
+ ```python
4086
+ from surreal_orm_lite import DatabaseIntrospector, SurrealDBConnectionManager
4087
+
4088
+ SurrealDBConnectionManager.set_connection(url="mem://", namespace="shop", database="main")
4089
+ client = await SurrealDBConnectionManager.get_client()
4090
+ await client.query(
4091
+ "DEFINE TABLE person SCHEMAFULL;"
4092
+ "DEFINE FIELD name ON person TYPE string;"
4093
+ "DEFINE FIELD age ON person TYPE option<int> DEFAULT 18;"
4094
+ "DEFINE FIELD address ON person TYPE option<object>;"
4095
+ "DEFINE FIELD address.city ON person TYPE string;"
4096
+ "DEFINE INDEX person_name ON person FIELDS name UNIQUE;",
4097
+ {},
4098
+ )
4099
+
4100
+ schema = await DatabaseIntrospector().introspect()
4101
+ person = schema.tables["person"]
4102
+ person.schema_mode # 'SCHEMAFULL'
4103
+ person.fields["age"].field_type # 'int'
4104
+ person.fields["age"].nullable # True: option<int> on SurrealDB 2.x, none | int on 3.x
4105
+ person.fields["age"].default # '18': SurrealQL text
4106
+ person.fields["address.city"].path # ('address', 'city')
4107
+ person.indexes["person_name"].unique # True
4108
+ schema.issues # (): everything was read and parsed
4109
+ ```
4110
+
4111
+ - `introspect()` sends `INFO FOR DB;`, then one `INFO FOR TABLE` per table in codepoint order of the names (each
4112
+ escaped as an identifier), on the connection's client and outside any transaction. No record is read, nothing is
4113
+ defined or written.
4114
+ - `schema.tables` holds one `TableState` per table — mode, type (`"normal"`, `"relation"`, `"any"`), relation ends,
4115
+ view query, change feed, permissions and comment — with its `fields`, `indexes` and `events`. The database's own
4116
+ definitions are in `schema.accesses`, `schema.analyzers`, `schema.functions` (keyed `"fn::name"`) and
4117
+ `schema.params` (keyed without `$`). The sections the ORM does not model (`apis`, `configs`, `models`, and on
4118
+ SurrealDB 3.x `buckets`, `modules` and `sequences`) are kept in `schema.other` as SurrealDB returns them. The `users`
4119
+ section is never read.
4120
+ - A field is keyed by its path, with `*` for array items (`"address.city"`, `"tags.*"`), and `path` holds the
4121
+ segments, unescaped. `field_type` is its kind without the optional wrapper (`"any"` without `TYPE`), and `nullable`
4122
+ says whether it may be `NONE`.
4123
+ - Expressions are SurrealQL text, as the server renders them: `default`, `value`, `computed`, `assertion`, an event's
4124
+ `when` and `then`, a view's query, permission rules (`'FULL'`, `'NONE'` or `'WHERE <expr>'`). Every definition also
4125
+ keeps the server's statement in `raw`.
4126
+ - The state is immutable: frozen dataclasses, read-only maps that iterate in sorted key order, and tuples. Printing or
4127
+ logging a state shows names and structure only: definition texts stay in their attributes, out of `repr()` and
4128
+ `str()`.
4129
+ - Nothing is guessed. A definition that cannot be parsed exactly, a section of an unexpected shape or an
4130
+ `INFO FOR TABLE` that fails becomes a `SchemaIssue` in `schema.issues` (its `kind`, `name`, `table`, `message` and
4131
+ `statement`) and one WARNING on the `surreal_orm_lite.introspection` logger; `introspect()` does not raise for them.
4132
+ An issue's message never quotes the definition, which may hold a secret.
4133
+ - Errors: `SurrealDbAuthenticationError` when the session may not run `INFO FOR DB`, `SurrealDbError` when
4134
+ `INFO FOR DB` fails otherwise, and `SurrealDbNotFoundError` for a `tables=` name the database does not define.
4135
+
4136
+ ```python
4137
+ SurrealDBConnectionManager.add_connection("archive", url="mem://", namespace="shop", database="archive")
4138
+
4139
+ just_person = await DatabaseIntrospector(tables=["person"]).introspect() # INFO FOR TABLE `person` only
4140
+ no_table = await DatabaseIntrospector(tables=[]).introspect() # INFO FOR DB only: no_table.tables is empty
4141
+ archive = await DatabaseIntrospector("archive").introspect() # a named connection
4142
+ async with SurrealDBConnectionManager.using("archive"):
4143
+ archive = await DatabaseIntrospector().introspect() # the block's connection
4144
+ archive.connection # 'archive'
4145
+ ```
4146
+
4147
+ - `connection=` is the **name** of a connection, the one given to `add_connection()`, or `None` for the current one:
4148
+ the innermost `using()` block's, else `"default"`. It is resolved when `introspect()` runs, and `schema.connection`
4149
+ records it. A client object, such as `await SurrealDBConnectionManager.get_client()`, raises `TypeError`: it does
4150
+ not carry the connection's name, which routing and the generated models' `connection=` key need.
4151
+ - `tables=` reads those tables only: `None`, the default, reads every table, and an empty list reads none (the
4152
+ database-level sections are read all the same). A `str` raises `TypeError`: write `tables=["person"]`.
4153
+
4154
+ #### Generating models
4155
+
4156
+ ```python
4157
+ from surreal_orm_lite import ModelCodeGenerator, generate_models_from_db
4158
+
4159
+ source = ModelCodeGenerator().generate(schema) # the same text as: await generate_models_from_db()
4160
+ print(source)
4161
+ await generate_models_from_db("models_generated.py") # writes the file, replacing it if it exists (as the full ORM)
4162
+ try:
4163
+ await generate_models_from_db("models_generated.py", overwrite=False)
4164
+ except FileExistsError as exc:
4165
+ print(exc) # 'models_generated.py' already exists: overwrite=False refuses to replace it.
4166
+ ```
4167
+
4168
+ It prints:
4169
+
4170
+ ```python
4171
+ """Models generated by surreal_orm_lite.generate_models_from_db() from a SurrealDB schema.
4172
+
4173
+ Review them before use. They describe tables that already exist: do not call
4174
+ define_computed_fields() on them, it would replace the database's field definitions.
4175
+ """
4176
+
4177
+ from pydantic import BaseModel
4178
+ from surreal_orm_lite import BaseSurrealModel, SurrealConfigDict
4179
+
4180
+
4181
+ class PersonAddress(BaseModel):
4182
+ city: str
4183
+
4184
+
4185
+ class Person(BaseSurrealModel):
4186
+ # Indexes: person_name (UNIQUE)
4187
+ model_config = SurrealConfigDict(table_name="person")
4188
+
4189
+ id: str | None = None
4190
+ address: PersonAddress | None = None
4191
+ age: int | None = 18
4192
+ name: str
4193
+ ```
4194
+
4195
+ - `ModelCodeGenerator().generate(schema)` is pure: the same schema always gives the same source.
4196
+ `generate_models_from_db(output_path=None, connection=None, *, tables=None, overwrite=True)` reads the schema
4197
+ (`connection` and `tables` as for `DatabaseIntrospector`), generates the models and returns their source; with an
4198
+ `output_path` it also writes the file, UTF-8 with `\n` newlines, creating its parent directories.
4199
+ - An existing file is replaced, as the full ORM replaces it, and atomically: the source goes to a temporary file in
4200
+ the same directory, which `os.replace()` then moves over the file. A failure leaves the previous file and no
4201
+ temporary file, and a symbolic link is replaced by the file, its target never written. `overwrite=False` refuses an
4202
+ existing path with `FileExistsError` before reading anything, and creates the file exclusively.
4203
+ - One class per table: a `BaseSurrealModel`, or a `BaseSurrealEdge` for a `TYPE RELATION` table (which declares no
4204
+ `id`, `in_` or `out`: the base class provides them). Its `model_config` holds the `table_name`, `connection=` when
4205
+ the schema was read from another connection than `"default"`, then `server_fields` and `extra="allow"` (below). A
4206
+ model declares `id: str | None = None` first, then one line per field, in codepoint order of the columns.
4207
+ - A class is named after its table in PascalCase, without singularisation (`game_tables` → `GameTables`); a name
4208
+ that is taken — a Python keyword, a name the module imports, another table's class — gets `Model` appended (`range`
4209
+ → `RangeModel`). The table's comment, relation ends, view query, indexes and events are comments of its class, and
4210
+ the module's header lists every table or field left out, with the reason.
4211
+ - The source is safe to import: names, comments and expressions read from the database reach it only as escaped
4212
+ string literals, single-line ASCII comments and identifiers the generator builds, so a schema cannot inject code
4213
+ into it. It holds no timestamp, server address, namespace or database name, and no
4214
+ `from __future__ import annotations`.
4215
+
4216
+ #### How SurrealDB kinds become fields
4217
+
4218
+ | SurrealDB kind | Generated annotation |
4219
+ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
4220
+ | `any`, or no `TYPE` | `Any = None` |
4221
+ | `bool`, `int`, `float`, `string`, `bytes` | `bool`, `int`, `float`, `str`, `bytes` |
4222
+ | `number` | `int`, `float` or `Decimal`: their union, so each value keeps its type |
4223
+ | `decimal`, `datetime`, `uuid` | `Decimal`, `datetime`, `UUID` |
4224
+ | `duration` | `Duration`, nanosecond-exact ([section 24](#24-rich-field-types)) |
4225
+ | `range` | `Range` |
4226
+ | `record`, `record<…>` | `RecordID` |
4227
+ | `geometry<point>`, or another single geometry kind | `GeometryPoint` …; optional: `PointField = None` … ([section 25](#25-geospatial-fields)) |
4228
+ | `geometry`, `geometry<feature>` | `Geometry`; optional: `GeometryField = None` |
4229
+ | `geometry<…>` with several kinds | the union of their classes |
4230
+ | `object` with declared fields (`address.city`) | a sub-model (below) |
4231
+ | `object` without declared fields, an object literal (`{ a: int }`) | `dict[str, Any]` |
4232
+ | `array`, `array<T>`, `array<T, N>` | `list[Any]`, `list[T]` |
4233
+ | `set`, `set<T>`, `set<T, N>` | `set[T]` when `T` is hashable (`str`, `int`, `float`, `bool`, `bytes`, `Decimal`, `UUID`, `datetime`, `Duration`, a `Literal`), else `list[T]`; `set` alone: `list[Any]` |
4234
+ | `[A, B]` (a tuple) | `tuple[A, B]` |
4235
+ | string, integer and boolean literals (`'a'`, `1`, `true`) | `Literal[…]`, values in the kind's order |
4236
+ | float and decimal literals (`1.5f`, `1.5dec`) | `float`, `Decimal` |
4237
+ | `null` | `None` |
4238
+ | a union of kinds | the union of their annotations, `None` last; `Any` when one of them is `Any` |
4239
+ | `regex`, `function`, `file`, any other kind | `Any = None` |
4240
+
4241
+ - An optional kind, `option<T>` (rendered `none | T` by SurrealDB 3.x), gives `T | None = None`; a single geometry
4242
+ kind gives its field alias instead (`option<geometry<point>>` → `PointField = None`).
4243
+ - **Sub-models**: an `object` field with declared fields (`address` with `address.city`) becomes a `BaseModel` named
4244
+ after its class and column (`PersonAddress`), written before the class; an `array<object>` whose items have
4245
+ declared fields (`lines.*.sku`) becomes `list[<Class><Column>Item]`. The sub-model keeps undeclared keys
4246
+ (`extra="allow"`) when the object is `FLEXIBLE` or the table `SCHEMALESS`. A nested model writes its keys by
4247
+ attribute name, so when a nested column cannot be an attribute name as it is (`first-name`, `datetime`), its parent
4248
+ is a `dict[str, Any]` instead. A nested field whose parent is not defined makes that parent
4249
+ `dict[str, Any] | None = None`, noted in the header. Item definitions (`tags.*`) add no attribute: the array's kind
4250
+ carries the item type.
4251
+ - **`DEFAULT`**: a constant the model can hold exactly becomes the Python default, so the database stores the same
4252
+ value whether you set the field or not, and stores yours when you do — `DEFAULT 18` → `= 18`, `'active'` →
4253
+ `= "active"`, `true` → `= True`, `0.5f` on a `float` → `= 0.5`, `1.5dec` → `= Decimal("1.5")`, `NONE` → `= None`,
4254
+ `[]` → `= Field(default_factory=list)` (`set` for a set), `[1, 2]` → `= Field(default_factory=lambda: [1, 2])`,
4255
+ `{}` → `= Field(default_factory=dict)` or the sub-model's class, `1h30m` →
4256
+ `= Field(default_factory=lambda: Duration.parse("1h30m"))`, `d'2030-01-01T00:00:00Z'` →
4257
+ `= datetime.fromisoformat("2030-01-01T00:00:00Z")`, `u'…'` → `= UUID("…")`. The value is copied when the models are
4258
+ generated: generate them again after changing a `DEFAULT`. A `{}` whose sub-model needs a value makes the field
4259
+ required, because SurrealDB refuses a create that leaves it to that default. Any other default — an expression such
4260
+ as `time::now()`, a record id, `math::INF`, a non-empty object, a datetime with nanoseconds, a literal of another
4261
+ type — makes the field `T | None = None` and lists its attribute in `server_fields`
4262
+ ([section 20](#20-field-aliases-server_fields-and-mergerefreshfalse)): omitted on create, so that the server's
4263
+ default applies, and read back after `save()`. A value you set on such a field before `save()` is not written: set
4264
+ it with `merge()` once the record exists.
4265
+ - **`VALUE` and `COMPUTED`**: `COMPUTED e` (SurrealDB 3.x), and a `VALUE e` that reads neither `$value` nor
4266
+ `$input`, become `Computed[T] = computed("e")` ([section 16](#16-computed-fields-computed--define-field--value)):
4267
+ never written, read back after `save()`. When `computed()` refuses the expression (a `;`, even inside a string, or
4268
+ a block `{ … }`) or the column needs an alias, the field takes the server form instead: `T | None = None`, listed in
4269
+ `server_fields`. A `VALUE` that reads `$value` (`string::lowercase($value)`) is an ordinary field: you write the
4270
+ value and the server transforms it.
4271
+ - **`SCHEMALESS` tables** get `extra="allow"`: the fields the table does not declare are read into `model_extra` and
4272
+ written back.
4273
+ - **Aliases**: a column that cannot be an attribute name as it is gets one, with `Field(alias=<column>)`
4274
+ ([section 20](#20-field-aliases-server_fields-and-mergerefreshfalse)): `first-name` → `first_name`, `class` →
4275
+ `class_`, `_private` → `private`, `9lives` → `f_9lives`. So does a column named like a type or a name the module
4276
+ uses (`datetime`, `computed`, `list`, `str`, `Field`, `Any`), like a model attribute (`save`, `objects`, `json`), like
4277
+ a class of the module, or `l`, `O` or `I` (ambiguous names for linters): it gets a `_` suffix (`datetime_`, with
4278
+ `alias="datetime"`), since the attribute would otherwise shadow that name in the annotations after it.
4279
+ - **Skipped tables**, listed in the module's header: a table whose name is not an identifier (`order-items`:
4280
+ `table_name` refuses it), and a table named like a SurrealQL keyword, in any case, which the ORM's statements cannot
4281
+ use as a table name (`select`, `Select`, `create`, `only`, `none` …). They are in `schema.tables` all the same.
4282
+
4283
+ #### What the generator does not do
4284
+
4285
+ - It reads no record: a `SCHEMALESS` table's model holds the fields the table declares (with `extra="allow"`), and an
4286
+ object-literal kind (`{ a: int }`) stays a `dict[str, Any]`.
4287
+ - `ASSERT`, `PERMISSIONS`, `REFERENCE` (the field is a `RecordID`) and field comments are not generated: the database
4288
+ still applies them. `READONLY` is a trailing `# READONLY` comment: no field option exists for it.
4289
+ - `update()` fails on an instance holding a `READONLY` `datetime` field, after `get()` as after `save()`: Python keeps
4290
+ microseconds, SurrealDB nanoseconds, and the server refuses the changed value. The generated class says so: change
4291
+ such a record with `merge()`.
4292
+ - A sub-field filled by a `DEFAULT` the model does not hold (`prefs.at DEFAULT time::now()`, or any `DEFAULT` under a
4293
+ `dict[str, Any]` field) stays `None` on the instance after `save()`, which reads back only `server_fields` and
4294
+ computed fields. A following `update()` sends it as `NONE`: the server refuses it when the sub-field is required and
4295
+ erases it when it is optional. The generated class says so: call `refresh()` after `save()` before an `update()`, or
4296
+ change the record with `merge()`.
4297
+ - `array<T, N>` becomes `list[T]`: the length is left to the server, which checks it differently on each line
4298
+ (SurrealDB 2.x accepts at most N items, 3.x exactly N).
4299
+ - `null | T` becomes a required `T | None`, but the ORM sends `None` as `NONE`, which `null | T` refuses: give such a
4300
+ field a value, or declare it `option<T>`, which accepts `NONE`.
4301
+ - Never call `define_computed_fields()` on a generated model: it would replace the database's field definitions with
4302
+ `DEFINE FIELD OVERWRITE … VALUE …`, without their `TYPE`, `ASSERT` or `PERMISSIONS` (the module's docstring says so).
4303
+ - Long lines: the `model_config` line is wrapped the way `ruff format` keeps it — one keyword per line once it exceeds
4304
+ 128 columns, and the `server_fields` names one per line once their own line does. Other long lines — long names, a
4305
+ long `Literal` union — are left on one line for your formatter. When every line fits in 128 columns, the module
4306
+ passes `ruff check` and `ruff format --check` at that line length.
4307
+
4308
+ #### SurrealDB 2.x and 3.x
4309
+
4310
+ - Each line renders the same definition its own way. The reader normalises what the ORM types — kinds,
4311
+ nullability, field paths, flags and names — to one form, the 3.x one where both lines accept it: `option<int>`
4312
+ (2.x) and `none | int` (3.x) both give `field_type == "int"` and `nullable is True`; array items, `tags[*]` (2.x)
4313
+ and `tags.*` (3.x), both give the field `"tags.*"`; `FLEXIBLE TYPE object` (2.x) and `TYPE object FLEXIBLE` (3.x)
4314
+ both give `flexible is True`. The same schema gives the same state and the same generated types on every line.
4315
+ - Expressions are kept as each line renders them: `VALUE IF b THEN 1 ELSE 2 END` on 2.x is
4316
+ `VALUE (IF b THEN 1 ELSE 2 END)` on 3.x, a block `{ … }` is one line on 3.x and several on 2.x, and `math::INF`
4317
+ (2.x) is `math::INFINITY` (3.x). So `value`, `default`, `raw` … and a generated `computed("…")` may differ between
4318
+ the lines; the annotations do not.
4319
+ - A definition only one line has is read and typed on that line: on 3.x `COMPUTED` (`FieldState.computed`),
4320
+ `REFERENCE` (`reference`, `on_delete`), `FULLTEXT` indexes, the `file` kind, `WITH REFRESH` and `BEARER` accesses,
4321
+ and `DEFINE SEQUENCE` (kept raw in `schema.other["sequences"]`); on 2.x and the embedded engine `MTREE` indexes
4322
+ (`IndexState.mtree`), `SEARCH ANALYZER` indexes and `geometry<feature>`.
4323
+ - DDL that a `transaction()` block has not committed yet is invisible: introspection reads outside the transaction,
4324
+ so it sees the committed schema, inside the block too.
4325
+ - A database removed (`REMOVE DATABASE`) while the connection uses it: on 3.x introspection raises `SurrealDbError`
4326
+ (the database does not exist) until the database is defined again; 2.x answers an empty schema.
4327
+ - The embedded engine reads like a 2.x server
4328
+ ([ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine)).
4329
+
4330
+ #### Permissions
4331
+
4332
+ Introspection needs a system user: root, a namespace user or a database user, any role. A record user or an
4333
+ anonymous session gets `SurrealDbAuthenticationError` ("this session may not run INFO FOR DB"); on the embedded
4334
+ engine the anonymous session owns the database and may read it.
4335
+
4336
+ The `users` section is never read. On SurrealDB before 3.2.2 (every 2.x release, 3.x before 3.2.2, and the embedded
4337
+ engine of SDK 2.0.0), `INFO FOR DB` shows user password hashes to every role that may run `INFO`
4338
+ ([SurrealDB's `INFO` documentation](https://surrealdb.com/docs/surrealql/statements/info)); introspection never
4339
+ reads, stores, logs or writes them.
4340
+
4341
+ #### Coming from the full SurrealDB-ORM
4342
+
4343
+ - **Same names and call shapes**: `DatabaseIntrospector(connection).introspect()`,
4344
+ `ModelCodeGenerator().generate(state)`, `generate_models_from_db(output_path, connection)`, and the state classes
4345
+ `SchemaState`, `TableState`, `FieldState`, `IndexState`, `EventState`, `AccessState` and `AnalyzerState`, built by
4346
+ position or by keyword with the full ORM's arguments. Lite attributes (`raw`, `path`, `table`, `comment`, …) come
4347
+ after them and are keyword-only. `FunctionState`, `ParamState`, `SchemaIssue` and `tables=` are lite additions.
4348
+ - **State is immutable**: frozen dataclasses with read-only maps, and every definition keeps the server's statement
4349
+ in `raw` (full ORM: mutable dataclasses, no statement).
4350
+ - **Sequences are tuples**: compare `index.fields`, `analyzer.tokenizers`, `analyzer.filters`, `table.relation_in`
4351
+ and `table.relation_out` with tuples (`index.fields == ("email",)`); lists are accepted when constructing, and so
4352
+ is the full ORM's pipe-joined `relation_in="person | company"`. Relation ends are `()` where the full ORM has
4353
+ `None` (not a relation table, or any table).
4354
+ - **Permission values are `'FULL'`, `'NONE'` or `'WHERE <expr>'`** (full ORM: the bare condition).
4355
+ - **`default` is SurrealQL text**: `'18'`, `"'active'"`, `'time::now()'`, with `default_always` for
4356
+ `DEFAULT ALWAYS` (full ORM: a Python value, where `'active'` and `time::now()` both become strings). A
4357
+ `FieldState` built with a `default` that is not text raises `TypeError`.
4358
+ - **Typed defaults and `server_fields`**: a constant `DEFAULT` becomes a typed Python default
4359
+ (`Field(default_factory=list)`, `Duration.parse(…)`, `datetime.fromisoformat(…)`, `UUID(…)`), and any other
4360
+ `DEFAULT` becomes a `server_fields` entry (full ORM: `Field(default=…)` holding the SurrealQL text as a Python
4361
+ string, such as `'[]'` or `'time::now()'`, and no `server_fields`).
4362
+ - **`nullable` means "may be NONE"**: it is true for an optional kind (`option<T>`, rendered `none | T` by
4363
+ SurrealDB 3.x); `null | T` is not nullable, since it refuses NONE (full ORM: nullable). `field_type` is `"any"`
4364
+ for a field without `TYPE`, as in the full ORM.
4365
+ - **Accesses are database-level**: they are in `schema.accesses`, and `TableState` has no `access` attribute; find
4366
+ a table's with `[a for a in schema.accesses.values() if a.table == "user"]`. `table`, `signup_fields` and
4367
+ `signin_where` are read from `SIGNUP (CREATE <table> SET …)` (also `CREATE type::thing('<table>', …) SET …` and
4368
+ `CREATE type::record('<table>', …) SET …`, the forms `define_access()` uses for a `primary_key`) and
4369
+ `SIGNIN (SELECT … FROM <table> WHERE …)`. The full ORM reads the first form only, and another shape leaves them
4370
+ empty, with field names unescaped; durations are kept as rendered, `'NONE'` included.
4371
+ - **`encrypted` is not provided**: the lite has no `Encrypted` type, so a hashing `VALUE`
4372
+ (`crypto::argon2::generate($value)`) stays in `FieldState.value` and the field is generated as a writable field.
4373
+ - **APIs and the GraphQL config are not typed**: their definitions are in `SchemaState.other["apis"]` and
4374
+ `SchemaState.other["configs"]`, as SurrealDB returns them (full ORM: `ApiState`, `GraphQLConfigState`).
4375
+ - **`SchemaState.diff()` and `schema_diff()` come with v0.37.0** (migrations), as does `applied_migrations`; the
4376
+ `inspectdb` command comes with v0.38.0.
4377
+ - **A refused or failed `INFO FOR DB` raises** `SurrealDbAuthenticationError` or `SurrealDbError`, and a
4378
+ definition that cannot be read or parsed becomes a `SchemaIssue` in `schema.issues` and a logged warning (full
4379
+ ORM: an empty state, and definitions dropped with a debug log).
4380
+ - **`on_delete` keeps `'THEN <expr>'`** for `REFERENCE ON DELETE THEN …` (full ORM: `'THEN'` alone).
4381
+ - **`connection=` is a name**: the name a connection was added with (`add_connection()`), else the current one
4382
+ (`using()`, then `"default"`). A client object is refused with a `TypeError`, because a client does not carry the
4383
+ ORM's connection name, which routing, reconnects and the generated models' `connection=` key need (full ORM: an
4384
+ `HTTPConnection`).
4385
+ - **Generated models use comments** where the full ORM writes
4386
+ `SurrealConfigDict(table_type=…, permissions=…, changefeed=…, view_query=…, relation_in=…, relation_out=…, enforced=…)`:
4387
+ those keys arrive in the lite's `SurrealConfigDict` with v0.31.0–v0.33.0. `READONLY` is a comment too (full ORM:
4388
+ `Field(readonly=True)`).
4389
+ - **`RecordID` instead of `ForeignKey`/`ReferencesField`**; no `VectorField` or `Encrypted`; `computed()` instead
4390
+ of `Computed()`; `Duration`, `UUID`, `Decimal` and the geometry classes instead of `str`, `dict` and `float`;
4391
+ nested fields become sub-models (full ORM: dotted attribute lines).
4392
+ - **No singularisation**: `game_tables` becomes `GameTables` (full ORM: a trailing `s` is stripped, so `status`
4393
+ becomes `Statu`).
4394
+ - **`overwrite=False` added**: `generate_models_from_db(path)` replaces an existing file as the full ORM does, here
4395
+ atomically; `overwrite=False` refuses it with `FileExistsError`.
4396
+
4071
4397
  ---
4072
4398
 
4073
4399
  ## Configuration Options
@@ -4190,7 +4516,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
4190
4516
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
4191
4517
  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
4192
4518
  otherwise. The full suite and every divergence below were re-verified on both new versions.
4193
- 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.
4519
+ 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.
4194
4520
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
4195
4521
 
4196
4522
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -4301,6 +4627,13 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
4301
4627
  | `limit(n)` or `offset(n)` above `4294967295` (`2**32 - 1`) | the server refuses the read: `Found <n> but the LIMIT clause must evaluate to a positive integer` (`START` likewise) | read; above `2**63 - 1` the ORM raises `ValueError` when `limit()` or `offset()` is called, on both lines | pre-existing (documented in v0.28.1) |
4302
4628
  | Several connections in one process (`add_connection()`, `using()`) | each connection follows its own server: a 2.x connection's transactions are buffered, whatever the others are | each 3.x WebSocket connection gets interactive transactions, beside 2.x connections in the same process | v0.29.0 |
4303
4629
  | Text lookups (`startswith`, `endswith`, `like`, `ilike`, `match`, `regex`) | same on both lines: string functions guarded by `(field).is_string()` (`type::is::string` is 2.x-only); a `NONE`, `NULL`, non-string or array path value never matches | the same (`type::is_string` is 3.x-only; `a.b.is_string()` tests each element of an array path); until v0.29.1: operators SurrealQL lacks (`LIKE`…), a parse error on both lines | v0.29.2 |
4630
+ | Schema introspection (`DatabaseIntrospector`, `generate_models_from_db()`) | renders `option<T>`, array items as `tags[*]`, `FLEXIBLE` before `TYPE`, IF expressions bare: kinds and field paths are normalised to the 3.x forms | renders optional kinds with `none` first, items as `tags.*`, `FLEXIBLE` after `TYPE`, IF expressions in parentheses: same state and model types; expressions kept as rendered | v0.30.0 |
4631
+ | Definitions only one line has (schema introspection) | `MTREE` and `SEARCH ANALYZER` indexes, `geometry<feature>`: read and typed | `COMPUTED`, `REFERENCE`, `FULLTEXT`, kind `file`, `WITH REFRESH`, `BEARER`: read and typed; `DEFINE SEQUENCE`: kept raw | v0.30.0 |
4632
+ | `INFO` (schema introspection) by a record user or an anonymous session | refused: `SurrealDbAuthenticationError` (the SDK raises `InternalError`) | refused: `SurrealDbAuthenticationError` (the SDK raises `NotAllowedError`) | v0.30.0 |
4633
+ | `array<T, N>` read by schema introspection | at most N items; the generated `list[T]` leaves the check to the server | exactly N items; the generated `list[T]` leaves the check to the server | v0.30.0 |
4634
+ | Schema introspection of a database removed while the connection is open | empty schema | `SurrealDbError` (the database does not exist) until the database is defined again | v0.30.0 |
4635
+ | DDL not yet committed in a transaction, seen by schema introspection | invisible | invisible | v0.30.0 |
4636
+ | A regex with a backslash pair before a `/` (schema introspection) | `/a\\/b/` accepted (a backslash, then an escaped slash), `/\\/` refused: such a definition is a `SchemaIssue`, not read | `/\\/` accepted (an escaped backslash, then the closing slash), `/a\\/b/` refused: such a definition is a `SchemaIssue`, not read | v0.30.0 |
4304
4637
  | 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 |
4305
4638
 
4306
4639
  > **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.
@@ -4332,6 +4665,7 @@ Capabilities not listed behave as on a 2.x server.
4332
4665
  | Parse errors | bare `RuntimeError` (the DDL helpers raise `SurrealDbError`) | the SDK's error classes | v0.25.0 |
4333
4666
  | Time travel (`as_of()`) | `surrealkv+versioned://` only (`?versioned=true` is ignored by SDK 2.0.0); any other URL → `SurrealDbError` before any request; `fetch()` refused (2.x core) | versioned storage required (see the 2.x/3.x table) | v0.26.0 |
4334
4667
  | Several connections (`add_connection()`) | `mem://`: each name is a database of its own; an on-disk store (`surrealkv://`, `file://`) is open under one name at a time — a second name raises `SurrealDbConnectionError` | each name opens its own clients; two databases on one server are isolated | v0.29.0 |
4668
+ | Schema introspection (`DatabaseIntrospector`) | reads like a 2.x server (core 2.3.10): same state and same generated model types as on the servers; the anonymous owner session may run `INFO`; `COUNT` indexes cannot be defined | need a system user (root, namespace or database user) | v0.30.0 |
4335
4669
  | 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 |
4336
4670
 
4337
4671
  ---
@@ -4376,7 +4710,8 @@ Contributions are welcome! Please:
4376
4710
  | v0.27.0 | Subqueries | ✅ Released |
4377
4711
  | v0.28.0 | Query cache | ✅ Released |
4378
4712
  | v0.29.0 | Tier 2 — Multi-database | ✅ Released |
4379
- | v0.30.0 – v0.39.0 | Tier 3 — Advanced (search, DDL, migrations, CLI) | 📋 Planned |
4713
+ | v0.30.0 | Tier 3 — Schema introspection | ✅ Released |
4714
+ | v0.31.0 – v0.39.0 | Tier 3 — Advanced (search, DDL, migrations, CLI) | 📋 Planned |
4380
4715
  | v0.40.0 | Beta Phase (API freeze, hardening) | 📋 Planned |
4381
4716
  | v2.0.0 | Production / GA (aligned with SDK 2.0) | 📋 Planned |
4382
4717
 
@@ -4429,7 +4764,7 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
4429
4764
  | Subqueries | ✅ v0.27.0 (`Subquery`, a QuerySet in `filter()`) | ✅ |
4430
4765
  | Query Cache | ✅ v0.28.0 (`cache()`, `QueryCache`) | ✅ |
4431
4766
  | Multi-database | ✅ v0.29.0 (`add_connection()`, `using()`) | ✅ |
4432
- | Schema Introspection | v0.30.0 | ✅ |
4767
+ | Schema Introspection | ✅ v0.30.0 (`DatabaseIntrospector`, `generate_models_from_db()`) | ✅ |
4433
4768
  | DEFINE EVENT | v0.31.0 | ✅ |
4434
4769
  | Materialized views | v0.32.0 | ✅ |
4435
4770
  | Full-Text Search | v0.34.0 | ✅ |