surreal-orm-lite 0.29.3__tar.gz → 0.30.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/CHANGELOG.md +133 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/PKG-INFO +339 -4
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/README.md +338 -3
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/__init__.py +30 -1
- surreal_orm_lite-0.30.0/src/surreal_orm_lite/define_parser.py +2466 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/functions.py +10 -2
- surreal_orm_lite-0.30.0/src/surreal_orm_lite/introspection.py +453 -0
- surreal_orm_lite-0.30.0/src/surreal_orm_lite/model_generator.py +1284 -0
- surreal_orm_lite-0.30.0/src/surreal_orm_lite/schema_state.py +441 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/.gitignore +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/LICENSE +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/Makefile +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/model_base.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/query_set.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/routing.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/subquery.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/src/surreal_orm_lite/types.py +0 -0
- {surreal_orm_lite-0.29.3 → surreal_orm_lite-0.30.0}/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.
|
|
3
|
+
Version: 0.30.0
|
|
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
|
|
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 | ✅ |
|