surreal-orm-lite 0.37.7__tar.gz → 0.38.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.37.7 → surreal_orm_lite-0.38.0}/CHANGELOG.md +85 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/PKG-INFO +351 -16
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/README.md +350 -15
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/__init__.py +15 -2
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/introspection.py +88 -7
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/__init__.py +82 -0
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/autodetect.py +148 -0
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/compare.py +435 -0
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/constants.py +9 -0
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/executor.py +1184 -0
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/generator.py +370 -0
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/introspector.py +217 -0
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/loader.py +224 -0
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/migration.py +217 -0
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/operations.py +1993 -0
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/render.py +709 -0
- surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/state.py +695 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/model_auth.py +52 -33
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/model_base.py +39 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/model_generator.py +14 -4
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/schema.py +83 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/schema_state.py +104 -12
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/.gitignore +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/LICENSE +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/Makefile +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/define_parser.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/hybrid.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/model_ddl.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/query_set.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/routing.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/search.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/subquery.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/types.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/utils.py +0 -0
- {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/vector.py +0 -0
|
@@ -5,6 +5,91 @@ 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.38.0] - 2026-10-28
|
|
9
|
+
|
|
10
|
+
Migration system: the ORM writes Django-style migration files from the models and applies them,
|
|
11
|
+
with the full SurrealDB-ORM's API (`makemigrations()`, `MigrationExecutor.migrate()`,
|
|
12
|
+
`rollback()`, `upgrade()`, the operations). Each migration is applied atomically, in one
|
|
13
|
+
SurrealDB transaction together with its record in the `_surreal_orm_migrations` tracking table,
|
|
14
|
+
on SurrealDB 3.x, 2.x and the embedded engine. The first minor of Tier 3's tooling phase.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- **`surreal_orm_lite.migrations`**: `Migration`, `Operation` and the operations `CreateTable`,
|
|
19
|
+
`AlterTable`, `DropTable`, `AddField`, `AlterField`, `DropField`, `CreateIndex`, `DropIndex`,
|
|
20
|
+
`RebuildIndex`, `DefineAnalyzer`, `RemoveAnalyzer`, `DefineEvent`, `RemoveEvent`,
|
|
21
|
+
`DefineAccess`, `RemoveAccess`, `DefineFunction`, `RemoveFunction`, `DataMigration` and
|
|
22
|
+
`RawSQL`, with `Operation.state_forwards()`/`state_backwards()`; `DefaultExpression` (an
|
|
23
|
+
addition: a SurrealQL default for the DDL only); `split_destructive()`; `MigrationGenerator` and
|
|
24
|
+
`generate_empty_migration()`; `MigrationExecutor` (`migrate()`, `rollback()`, `upgrade()`,
|
|
25
|
+
`get_migration_status()`, `show_sql()`, `migration_state()`) and `MigrationStatementError`;
|
|
26
|
+
`ModelIntrospector` and `introspect_models()`; `makemigrations()`; `MIGRATIONS_TABLE`; and,
|
|
27
|
+
re-exported as the full ORM's `migrations` package does, `DatabaseIntrospector` and
|
|
28
|
+
`ModelCodeGenerator`.
|
|
29
|
+
- **`makemigrations()`** reads the connected database by default and replays the migration files
|
|
30
|
+
not yet applied on top (the full ORM CLI's `--from-db`); `from_db=False` diffs against the files
|
|
31
|
+
alone, offline. `drop_missing=True` writes the removals of what the models no longer declare.
|
|
32
|
+
- **`schema_diff()`** (top level and `surreal_orm_lite.introspection`) lists the operations that
|
|
33
|
+
would bring the database to the models, `[]` when they agree; **`get_registered_models()`**
|
|
34
|
+
(top level) lists the model classes defined. The top level also exports `DefineAnalyzer`,
|
|
35
|
+
`DefineEvent`, `RebuildIndex` and `RemoveEvent`, as the full ORM's does.
|
|
36
|
+
- **`SchemaState.diff(target)`** and **`SchemaState.applied_migrations`** (the full ORM's 2nd
|
|
37
|
+
attribute, positional at its 2nd place); `FieldState.server`, `FieldState.undeclared` and
|
|
38
|
+
`TableState.undeclared` (keyword-only: the marks of a state built from models).
|
|
39
|
+
- README section 39, "Migrations (`makemigrations()`, `MigrationExecutor`, operations)" (write,
|
|
40
|
+
apply, change the models, data migrations, roll back, the operations, drift, server lines,
|
|
41
|
+
limits, a note for users of the full SurrealDB-ORM), seven rows of the "ORM behaviour:
|
|
42
|
+
SurrealDB 2.x vs 3.x" table and one of the embedded engine's, and the example notebook
|
|
43
|
+
`examples/v0.38.0_migration_system.ipynb`.
|
|
44
|
+
|
|
45
|
+
### Changed
|
|
46
|
+
|
|
47
|
+
- `generate_models_from_db()` skips the tracking table `_surreal_orm_migrations`, with a comment
|
|
48
|
+
line in the generated module's header.
|
|
49
|
+
- `DatabaseIntrospector.introspect()` reads the applied migrations' names into
|
|
50
|
+
`SchemaState.applied_migrations` when the database has the tracking table.
|
|
51
|
+
- The README sentences of sections 31 to 36 that promised the migrations "with v0.38.0" now point
|
|
52
|
+
to section 39; section 35 says how to remove a clause a model no longer declares.
|
|
53
|
+
|
|
54
|
+
### Notes
|
|
55
|
+
|
|
56
|
+
- **`migrate()` and `rollback()` read the database's schema before any change** (`INFO FOR DB`
|
|
57
|
+
and `INFO FOR TABLE`), replay the migrations over it and render every statement from it, so
|
|
58
|
+
that nothing is applied when one of them would be refused, and a table made by
|
|
59
|
+
`define_table()` before any migration can be altered by one. A session refused `INFO FOR DB`
|
|
60
|
+
gets `SurrealDbAuthenticationError` before anything is applied. `fake=True`, `upgrade()` and
|
|
61
|
+
`get_migration_status()` read no schema.
|
|
62
|
+
- **Server lines**: a full-text `CreateIndex` writes `FULLTEXT` on SurrealDB 3.x and `SEARCH` on
|
|
63
|
+
2.x and the embedded engine. On 2.x and the embedded engine an `any` column of a `SCHEMAFULL`
|
|
64
|
+
table is written `FLEXIBLE`, also in the redefinitions an `AlterTable` that makes a table
|
|
65
|
+
`SCHEMAFULL` writes in the same transaction, so their object values are kept (3.x keeps them
|
|
66
|
+
without it); `DefineEvent(async_mode=True)`, `DefineAccess(with_refresh=True)` and `COMPUTED`
|
|
67
|
+
fields raise `SurrealDbError` before any change. `AddField(reference=True)` is left to the
|
|
68
|
+
server (2.x refuses it unless `record_references` is enabled). A `RemoveAnalyzer` of an
|
|
69
|
+
analyzer an index still uses and a `DropTable` of a table a view reads raise `ValueError` before
|
|
70
|
+
any change on every line.
|
|
71
|
+
- **Deviations from the full ORM**: a migration that defines analyzers commits them first, in a
|
|
72
|
+
transaction of their own (SurrealDB builds an index with the committed analyzer only), and
|
|
73
|
+
restores the definition the database held if the rest fails; `MigrationStatementError` names
|
|
74
|
+
the migration, the operation and SurrealDB's reason, never the statement. The diff of a state
|
|
75
|
+
built from models carries what a model leaves to the database (an absent key never removes a
|
|
76
|
+
stored clause, as with `define_table()`): remove a clause with an `AlterTable`/`AlterField`
|
|
77
|
+
written by hand; a field the model no longer declares is removed by the `DropField` that
|
|
78
|
+
`makemigrations(drop_missing=True)` writes. A diff between two states read from databases or
|
|
79
|
+
migrations compares every clause.
|
|
80
|
+
- **Migration files are Python code**, executed when loaded: point `MigrationExecutor` and
|
|
81
|
+
`makemigrations()` at the application's own directory only. Expressions, rules, view queries,
|
|
82
|
+
event and function bodies, `RawSQL` and `DataMigration` SQL are trusted application code,
|
|
83
|
+
embedded as written: never build an operation from user input.
|
|
84
|
+
- **Deferred**: the CLI (`surreal-orm-lite makemigrations`, `migrate`, `rollback`…) to v0.39.0;
|
|
85
|
+
stored functions declared on models and their diff (the rest of #276); `DefineBearerAccess`,
|
|
86
|
+
`DefineApi` and the GraphQL config on SurrealDB 3.x; `CreateIndex(concurrently=True)`; squashing
|
|
87
|
+
migrations; a non-atomic mode; field `ASSERT`, `READONLY`, permissions and comment declared on
|
|
88
|
+
models; `define_table()` keeping a stored `DEFAULT ALWAYS`; a `schema_diff()` option listing the
|
|
89
|
+
clauses a model leaves to the database.
|
|
90
|
+
- Same code on SurrealDB 2.7.0, 3.3.4 and the embedded engine (3.1.5 retro), with no test skipped
|
|
91
|
+
on a supported line.
|
|
92
|
+
|
|
8
93
|
## [0.37.7] - 2026-10-28
|
|
9
94
|
|
|
10
95
|
Follow-up to the review of v0.37.0 (#320): a write the ORM refuses before it reaches the database
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.38.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
|
|
@@ -272,6 +272,7 @@ embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads
|
|
|
272
272
|
| Full-text search (`search()`, BM25 score and highlights) | ✅ |
|
|
273
273
|
| Vector search (`similar_to()`, KNN, HNSW indexes) | ✅ |
|
|
274
274
|
| Hybrid search (`hybrid_search()`, Reciprocal Rank Fusion) | ✅ |
|
|
275
|
+
| Migrations (makemigrations / migrate / rollback) | ✅ |
|
|
275
276
|
|
|
276
277
|
### Supported Filter Lookups
|
|
277
278
|
|
|
@@ -4521,8 +4522,9 @@ reads, stores, logs or writes them.
|
|
|
4521
4522
|
(`crypto::argon2::generate($value)`) stays in `FieldState.value` and the field is generated as a writable field.
|
|
4522
4523
|
- **APIs and the GraphQL config are not typed**: their definitions are in `SchemaState.other["apis"]` and
|
|
4523
4524
|
`SchemaState.other["configs"]`, as SurrealDB returns them (full ORM: `ApiState`, `GraphQLConfigState`).
|
|
4524
|
-
- **`SchemaState.diff()
|
|
4525
|
-
`
|
|
4525
|
+
- **`SchemaState.diff()`, `schema_diff()` and `applied_migrations`** come with the migrations ([section 39](#39-migrations-makemigrations-migrationexecutor-operations)):
|
|
4526
|
+
`applied_migrations` is filled from the tracking table when the database has one (full ORM: declared, never
|
|
4527
|
+
filled; it is the 2nd attribute, positional as in the full ORM); the `inspectdb` command comes with v0.39.0.
|
|
4526
4528
|
- **A refused or failed `INFO FOR DB` raises** `SurrealDbAuthenticationError` or `SurrealDbError`, and a
|
|
4527
4529
|
definition that cannot be read or parsed becomes a `SchemaIssue` in `schema.issues` and a logged warning (full
|
|
4528
4530
|
ORM: an empty state, and definitions dropped with a debug log).
|
|
@@ -4627,8 +4629,8 @@ except ServerError as exc: # the event refused the write: nothing changed
|
|
|
4627
4629
|
the statements it applied, which `event_ddl()` renders without a connection.
|
|
4628
4630
|
- `Account.remove_event("email_audit")` removes one event (`REMOVE EVENT IF EXISTS`; with `missing_ok=False` an
|
|
4629
4631
|
event that does not exist raises `SurrealDbNotFoundError`). An event the model no longer declares stays defined
|
|
4630
|
-
until it is removed: `define_events()` does not compare the database with the model
|
|
4631
|
-
|
|
4632
|
+
until it is removed: `define_events()` does not compare the database with the model; the migrations do, and
|
|
4633
|
+
`makemigrations(drop_missing=True)` writes its `RemoveEvent` ([section 39](#39-migrations-makemigrations-migrationexecutor-operations)).
|
|
4632
4634
|
- A subclass inherits `events` and defines them on its own table, unless it sets its own (`events=[]` for none).
|
|
4633
4635
|
Typed edges (`BaseSurrealEdge`) take events too: they fire on the edge table. Defining an event on a table that
|
|
4634
4636
|
does not exist creates the table, `SCHEMALESS`.
|
|
@@ -4804,8 +4806,8 @@ system user: run `define_events()` and `define_function()` at start-up or deploy
|
|
|
4804
4806
|
- **Names are quoted, and comments escaped with a backslash** (full ORM: names as written, and a quote doubled as
|
|
4805
4807
|
`''`, which SurrealDB refuses).
|
|
4806
4808
|
- **`define_function()` has no full-ORM equivalent**: the full ORM declares a function with `RawSQL`.
|
|
4807
|
-
- **The migration operations** (`DefineEvent`, `RemoveEvent`, `RawSQL`)
|
|
4808
|
-
longer declares
|
|
4809
|
+
- **The migration operations** (`DefineEvent`, `RemoveEvent`, `RawSQL`) are in `surreal_orm_lite.migrations`, and
|
|
4810
|
+
`makemigrations(drop_missing=True)` removes the events a model no longer declares ([section 39](#39-migrations-makemigrations-migrationexecutor-operations)).
|
|
4809
4811
|
|
|
4810
4812
|
### 33. Materialized views (`view_query`, `define_view()`)
|
|
4811
4813
|
|
|
@@ -5048,7 +5050,8 @@ record user's session.
|
|
|
5048
5050
|
- **`define_view()`/`remove_view()`/`view_ddl()`** apply, remove and render the view, where the full ORM applies one
|
|
5049
5051
|
through migrations (`CreateTable`/`AlterTable`) or `define_table()`. `define_table()` (since v0.34.0,
|
|
5050
5052
|
[section 35](#35-model-table-ddl-define_table-schema_mode-permissions)) accepts a view model and applies it through `define_view()`, so
|
|
5051
|
-
full-ORM code calling `define_table()` on a view works. Migrations
|
|
5053
|
+
full-ORM code calling `define_table()` on a view works. Migrations (`CreateTable`/`AlterTable` with `view_query`)
|
|
5054
|
+
are in [section 39](#39-migrations-makemigrations-migrationexecutor-operations).
|
|
5052
5055
|
- **`AS (…)` as in the full ORM, the table name quoted** (``DEFINE TABLE OVERWRITE `order_stats` AS (…)``).
|
|
5053
5056
|
- **Generated models write `view_query=`**, as the full ORM's do
|
|
5054
5057
|
([section 31](#31-schema-introspection-databaseintrospector-generate_models_from_db)).
|
|
@@ -5356,7 +5359,8 @@ session.
|
|
|
5356
5359
|
ORM's `class Likes(BaseSurrealModel)` form) raises `TypeError`; derive it from `BaseSurrealEdge`.
|
|
5357
5360
|
- **`relation_ddl()` and `define_relation()` on the edge model** render and apply the constraint, where the full ORM
|
|
5358
5361
|
applies the DDL through migrations or `define_table()`. `define_table()` (since v0.34.0) applies an edge model
|
|
5359
|
-
through the statement `define_relation()` carries, then its data fields; migrations
|
|
5362
|
+
through the statement `define_relation()` carries, then its data fields; migrations (`CreateTable`/`AlterTable`
|
|
5363
|
+
with the relation keys) are in [section 39](#39-migrations-makemigrations-migrationexecutor-operations).
|
|
5360
5364
|
- **The clauses the model declares (`schema_mode`, `permissions`, `changefeed`, `comment`, since v0.34.0) are
|
|
5361
5365
|
written, the others kept from the database** (the full ORM renders every clause from the model and resets the
|
|
5362
5366
|
others).
|
|
@@ -5629,8 +5633,10 @@ What the model declares wins; the rest is kept from the database:
|
|
|
5629
5633
|
|
|
5630
5634
|
- Nothing is removed: the table keeps its records, the fields, clauses, indexes and events the model does not declare,
|
|
5631
5635
|
the views that read it ([section 33](#33-materialized-views-view_query-define_view)), its live queries and its
|
|
5632
|
-
change feed's history. A key left out never removes a stored clause
|
|
5633
|
-
|
|
5636
|
+
change feed's history. A key left out never removes a stored clause, and the migrations' diff leaves it too
|
|
5637
|
+
([section 39](#39-migrations-makemigrations-migrationexecutor-operations)): to remove a clause the model no longer declares, write an `AlterTable` or
|
|
5638
|
+
`AlterField` migration by hand; a field the model no longer declares is removed by the `DropField` that
|
|
5639
|
+
`makemigrations(drop_missing=True)` writes. `schema_mode=SchemaMode.SCHEMALESS` turns a `SCHEMAFULL` table back,
|
|
5634
5640
|
and `permissions={}` writes `PERMISSIONS NONE`.
|
|
5635
5641
|
- Each call on a table with a change feed adds one `define_table` entry to it; `changes()` skips it, a raw
|
|
5636
5642
|
`SHOW CHANGES` shows it.
|
|
@@ -5854,7 +5860,8 @@ Applying needs a privileged session: run `define_table()` at start-up or deploym
|
|
|
5854
5860
|
- **One statement per call** (the full ORM sends one batch). A refused statement raises `SurrealDbError` naming the
|
|
5855
5861
|
table or the field, never the statement, as every lite DDL applier does; the statements before it stay applied
|
|
5856
5862
|
(`tx=` makes the whole call atomic). The full ORM raises `MigrationStatementError` (a `RuntimeError` from
|
|
5857
|
-
`surreal_orm.migrations`) with the SQL in its message
|
|
5863
|
+
`surreal_orm.migrations`) with the SQL in its message; this library's `MigrationStatementError`
|
|
5864
|
+
([section 39](#39-migrations-makemigrations-migrationexecutor-operations)) is raised by the migrations only, and `define_table()` keeps `SurrealDbError`.
|
|
5858
5865
|
- **`TYPE NORMAL` is written for `TableType.NORMAL` and for a model without `table_type`** (and for `USER`, `STREAM`
|
|
5859
5866
|
and `HASH`). The full ORM writes no `TYPE` there, and SurrealDB then stores `TYPE NORMAL` for a `SCHEMAFULL` table
|
|
5860
5867
|
(the full ORM's default) and `TYPE ANY` for a `SCHEMALESS` one. `TYPE NORMAL` refuses edges (`RELATE`) into the
|
|
@@ -6201,7 +6208,8 @@ print(await NoteV2.objects().search(text="physics").count())
|
|
|
6201
6208
|
|
|
6202
6209
|
- **Declared on the model**: `Analyzer` and `Index` take the argument names of the full ORM's `DefineAnalyzer` and
|
|
6203
6210
|
`CreateIndex`, a model lists its indexes in `SurrealConfigDict(indexes=[...])` and `define_indexes()` applies them;
|
|
6204
|
-
the full ORM declares analyzers and indexes in migrations, which this library
|
|
6211
|
+
the full ORM declares analyzers and indexes in migrations, which this library also has (`DefineAnalyzer`,
|
|
6212
|
+
`CreateIndex`, [section 39](#39-migrations-makemigrations-migrationexecutor-operations)).
|
|
6205
6213
|
- **`search()` applies wherever `filter()` applies**: `count()`, the aggregations, `values()` groups, `exists()`,
|
|
6206
6214
|
`bulk_update()`, `bulk_delete()`, `patch()` and a `Subquery`; the full ORM applies it to `exec()` only.
|
|
6207
6215
|
- **Refused where SurrealDB cannot honour it**: `search()` with `live()`/`watch()`, `as_of()` or `changes()` raises
|
|
@@ -6718,6 +6726,324 @@ except ValueError as error:
|
|
|
6718
6726
|
(0 to 10 000), `ef` and `dist`; the full ORM checks the field names only.
|
|
6719
6727
|
- **Reciprocal Rank Fusion only**: `search::linear()` (weights and score normalisation) is not offered yet.
|
|
6720
6728
|
|
|
6729
|
+
### 39. Migrations (`makemigrations()`, `MigrationExecutor`, operations)
|
|
6730
|
+
|
|
6731
|
+
Since v0.38.0 the ORM writes Django-style migration files from the models and applies them, with the full
|
|
6732
|
+
SurrealDB-ORM's API: `surreal_orm_lite.migrations` holds `Migration`, the operations (`CreateTable`, `AddField`,
|
|
6733
|
+
`CreateIndex` and the others), `MigrationGenerator`, `MigrationExecutor` and `makemigrations()`, and
|
|
6734
|
+
`surreal_orm_lite.schema_diff()` compares the models with a database. A migration is a Python file of a migrations
|
|
6735
|
+
directory; `MigrationExecutor.migrate()` applies each one atomically, in one SurrealDB transaction together with its
|
|
6736
|
+
record in the `_surreal_orm_migrations` table, and `rollback()` undoes them, on SurrealDB 3.x, 2.x and the embedded
|
|
6737
|
+
engine.
|
|
6738
|
+
|
|
6739
|
+
#### Write a migration
|
|
6740
|
+
|
|
6741
|
+
```python
|
|
6742
|
+
from surreal_orm_lite import BaseSurrealModel, SchemaMode, SurrealConfigDict
|
|
6743
|
+
from surreal_orm_lite.migrations import makemigrations
|
|
6744
|
+
|
|
6745
|
+
|
|
6746
|
+
class Person(BaseSurrealModel):
|
|
6747
|
+
model_config = SurrealConfigDict(table_name="person", schema_mode=SchemaMode.SCHEMAFULL)
|
|
6748
|
+
name: str
|
|
6749
|
+
age: int = 18
|
|
6750
|
+
|
|
6751
|
+
|
|
6752
|
+
class Post(BaseSurrealModel):
|
|
6753
|
+
model_config = SurrealConfigDict(table_name="post", schema_mode=SchemaMode.SCHEMAFULL)
|
|
6754
|
+
title: str
|
|
6755
|
+
body: str
|
|
6756
|
+
|
|
6757
|
+
|
|
6758
|
+
path = await makemigrations("initial", models=[Person, Post])
|
|
6759
|
+
print(path)
|
|
6760
|
+
# migrations/0001_initial.py
|
|
6761
|
+
```
|
|
6762
|
+
|
|
6763
|
+
`makemigrations()` compares the models with the current schema and writes the next file of the migrations directory
|
|
6764
|
+
(`migrations_dir=`, `"migrations"` by default): here a `CreateTable` and its `AddField` operations for each table. It
|
|
6765
|
+
returns `None` and writes nothing when there is no change. By default it reads the connected database and replays on
|
|
6766
|
+
top the migration files not yet applied (the full ORM CLI's `--from-db`), so it needs the connection; `from_db=False`
|
|
6767
|
+
diffs against the migration files alone, with no request (offline). Without `models=`, it takes every model class
|
|
6768
|
+
defined (`get_registered_models()`); `connection=` names the connection, whose models it keeps. A file is plain
|
|
6769
|
+
Python, to review before applying — this one was written by `makemigrations("add_email")` once `Person` declared an
|
|
6770
|
+
`email: str` field and `indexes=[Index("person_email", ["email"], unique=True)]`:
|
|
6771
|
+
|
|
6772
|
+
```python
|
|
6773
|
+
"""
|
|
6774
|
+
Migration: 0002_add_email
|
|
6775
|
+
Generated: 2026-10-27T12:00:00+00:00
|
|
6776
|
+
|
|
6777
|
+
Auto-generated migration file. Review before applying.
|
|
6778
|
+
"""
|
|
6779
|
+
|
|
6780
|
+
from surreal_orm_lite.migrations import Migration
|
|
6781
|
+
from surreal_orm_lite.migrations.operations import (
|
|
6782
|
+
AddField,
|
|
6783
|
+
CreateIndex,
|
|
6784
|
+
)
|
|
6785
|
+
|
|
6786
|
+
|
|
6787
|
+
migration = Migration(
|
|
6788
|
+
name="0002_add_email",
|
|
6789
|
+
dependencies=['0001_initial'],
|
|
6790
|
+
operations=[
|
|
6791
|
+
AddField(table='person', name='email', field_type='string'),
|
|
6792
|
+
CreateIndex(table='person', name='person_email', fields=['email'], unique=True),
|
|
6793
|
+
],
|
|
6794
|
+
)
|
|
6795
|
+
```
|
|
6796
|
+
|
|
6797
|
+
`generate_empty_migration("migrations", "backfill")` writes a file with no operation, to fill in by hand.
|
|
6798
|
+
|
|
6799
|
+
#### Apply it
|
|
6800
|
+
|
|
6801
|
+
```python
|
|
6802
|
+
from surreal_orm_lite.migrations import MigrationExecutor
|
|
6803
|
+
|
|
6804
|
+
executor = MigrationExecutor("migrations")
|
|
6805
|
+
print(await executor.migrate())
|
|
6806
|
+
# ['0001_initial', '0002_add_email']
|
|
6807
|
+
print((await executor.get_migration_status())["0002_add_email"])
|
|
6808
|
+
# {'applied': True, 'reversible': True, 'has_data': False, 'operations': 2}
|
|
6809
|
+
print(await executor.show_sql("0002_add_email"))
|
|
6810
|
+
# DEFINE FIELD `email` ON `person` TYPE string;
|
|
6811
|
+
#
|
|
6812
|
+
# DEFINE INDEX `person_email` ON `person` FIELDS `email` UNIQUE;
|
|
6813
|
+
```
|
|
6814
|
+
|
|
6815
|
+
`migrate()` first reads the database's schema (`INFO FOR DB` and `INFO FOR TABLE`, no change), replays the pending
|
|
6816
|
+
migrations over it and checks them, so that nothing is applied when one of them would be refused; then it applies
|
|
6817
|
+
each migration in one transaction with its record, so a migration is applied entirely or not at all. Because the
|
|
6818
|
+
statements are rendered from the database's schema, a table made by `define_table()` before any migration can be
|
|
6819
|
+
altered by one. A migration that defines analyzers commits them first, in a transaction of their own (SurrealDB builds
|
|
6820
|
+
an index with the committed analyzer only), and restores them to the definition the database held if the rest of the
|
|
6821
|
+
migration fails. Another process applying the same migration at the same time is safe: the tracking table's unique
|
|
6822
|
+
index lets one of them record it, and the other skips it with a warning. `migrate(target="0001_initial")` stops after
|
|
6823
|
+
that migration, and `show_sql(name)` prints a migration's statements without a request (`line=2` for SurrealDB 2.x and
|
|
6824
|
+
the embedded engine, `backwards=True` for its rollback). To adopt a database built before its migrations,
|
|
6825
|
+
`migrate(target="0001_initial", fake=True)` records the migrations up to that one without applying them, then
|
|
6826
|
+
`migrate()` applies the next ones. `executor = MigrationExecutor("migrations", connection="analytics")` uses a named
|
|
6827
|
+
connection. A refused statement raises `MigrationStatementError`, which names the migration, the operation and
|
|
6828
|
+
SurrealDB's reason, never the statement.
|
|
6829
|
+
|
|
6830
|
+
#### Change the models
|
|
6831
|
+
|
|
6832
|
+
```python
|
|
6833
|
+
await makemigrations("add_email", models=[Person, Post]) # 0002_add_email.py
|
|
6834
|
+
print(await makemigrations("add_email_again", models=[Person, Post]))
|
|
6835
|
+
# None
|
|
6836
|
+
```
|
|
6837
|
+
|
|
6838
|
+
A second `makemigrations()`, run before `migrate()`, writes nothing: the pending file is replayed over the database,
|
|
6839
|
+
so a new migration never repeats a pending one. The diff compares tables (schema mode, type, change feed, permissions,
|
|
6840
|
+
comment, view query, relation ends), fields, indexes, events, analyzers and the access of a user model; functions are
|
|
6841
|
+
not compared. It carries what a model leaves to the database: a clause the model does not declare stays as the
|
|
6842
|
+
database has it, as with `define_table()` — [section 35](#35-model-table-ddl-define_table-schema_mode-permissions)
|
|
6843
|
+
says how to remove one. Without `drop_missing=True`, removals (`DropTable`, `DropField`, `DropIndex`, `RemoveEvent`,
|
|
6844
|
+
`RemoveAnalyzer`, `RemoveAccess`), reversible or not, are left out and named in a warning: an event added by hand,
|
|
6845
|
+
which no model declares, is never removed by default. With `from_db=False` a removal is relative to the files: a model
|
|
6846
|
+
deleted since the last migration.
|
|
6847
|
+
|
|
6848
|
+
A removal of something neither the database nor an earlier migration holds is refused before any change, by
|
|
6849
|
+
`makemigrations()` and `migrate()` alike, since SurrealDB would refuse it; a `RawSQL` that defines something declares
|
|
6850
|
+
it in `state_operations=` (`RawSQL("DEFINE TABLE log SCHEMALESS;", state_operations=[CreateTable(name="log",
|
|
6851
|
+
schema_mode="SCHEMALESS")])`). The history of the database must match the files: a recorded migration whose dependency
|
|
6852
|
+
is not recorded is an error everywhere but in `get_migration_status()`, which warns; a recorded migration without its
|
|
6853
|
+
file is an error in `makemigrations()`, `upgrade()` and `rollback()`, and a warning in `migrate()` and
|
|
6854
|
+
`get_migration_status()`.
|
|
6855
|
+
|
|
6856
|
+
#### Data migrations
|
|
6857
|
+
|
|
6858
|
+
```python
|
|
6859
|
+
from surreal_orm_lite.migrations import AddField, DataMigration, Migration
|
|
6860
|
+
|
|
6861
|
+
migration = Migration(
|
|
6862
|
+
name="0003_person_slug",
|
|
6863
|
+
dependencies=["0002_add_email"],
|
|
6864
|
+
operations=[
|
|
6865
|
+
AddField(table="person", name="slug", field_type="option<string>"),
|
|
6866
|
+
DataMigration(
|
|
6867
|
+
forwards_sql="UPDATE person SET slug = string::lowercase(name);",
|
|
6868
|
+
backwards_sql="UPDATE person UNSET slug;",
|
|
6869
|
+
),
|
|
6870
|
+
],
|
|
6871
|
+
)
|
|
6872
|
+
```
|
|
6873
|
+
|
|
6874
|
+
`DataMigration` takes SurrealQL (`forwards_sql`, `backwards_sql`) or `async def` functions taking no argument
|
|
6875
|
+
(`forwards_func`, `backwards_func`). `migrate()` applies the schema only (`schema_only=True`, the default); `await
|
|
6876
|
+
executor.upgrade()` runs the data operations of the applied migrations, and `migrate(schema_only=False)` runs a
|
|
6877
|
+
migration's data operations right after its schema transaction. Data operations are not recorded: running `upgrade()`
|
|
6878
|
+
again runs them again, so write them idempotent.
|
|
6879
|
+
|
|
6880
|
+
#### Roll back
|
|
6881
|
+
|
|
6882
|
+
```python
|
|
6883
|
+
print(await executor.rollback("0001_initial"))
|
|
6884
|
+
# ['0002_add_email']
|
|
6885
|
+
await executor.rollback("") # undo every migration
|
|
6886
|
+
```
|
|
6887
|
+
|
|
6888
|
+
`rollback(target)` undoes the migrations applied after _target_, the last first, each in one transaction that also
|
|
6889
|
+
deletes its record; `""` undoes them all. Every migration to undo must be reversible, or nothing is undone. Creations
|
|
6890
|
+
are undone with `REMOVE … IF EXISTS`; redefinitions and the removals of indexes, analyzers, events, accesses and
|
|
6891
|
+
functions are reversible when they carry `previous=`, the definition they replace (the diff fills it in);
|
|
6892
|
+
`RebuildIndex` is reversible. `DropTable` and `DropField` are irreversible (the records' values are gone), as is a
|
|
6893
|
+
redefinition whose previous definition the ORM cannot write.
|
|
6894
|
+
|
|
6895
|
+
#### Operations
|
|
6896
|
+
|
|
6897
|
+
| Operation | Statement (SurrealDB 3.x) | Undone by | Reversible |
|
|
6898
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ---------------------------------------------- |
|
|
6899
|
+
| `CreateTable` | ``DEFINE TABLE `log` SCHEMAFULL;`` | ``REMOVE TABLE IF EXISTS `log`;`` | yes |
|
|
6900
|
+
| `AlterTable` | ``DEFINE TABLE OVERWRITE `person` SCHEMALESS;`` | ``DEFINE TABLE OVERWRITE `person` SCHEMAFULL;`` | with `previous_schema_mode` |
|
|
6901
|
+
| `DropTable` | ``REMOVE TABLE `log`;`` | — | no |
|
|
6902
|
+
| `AddField` | ``DEFINE FIELD `age` ON `person` TYPE int DEFAULT 18;`` | ``REMOVE FIELD IF EXISTS `age` ON `person`;`` | yes |
|
|
6903
|
+
| `AlterField` | ``DEFINE FIELD OVERWRITE `age` ON `person` TYPE int DEFAULT 21;`` | ``DEFINE FIELD OVERWRITE `age` ON `person` TYPE int DEFAULT 18;`` | with `previous_type` |
|
|
6904
|
+
| `DropField` | ``REMOVE FIELD `age` ON `person`;`` | — | no |
|
|
6905
|
+
| `CreateIndex` | ``DEFINE INDEX `person_email` ON `person` FIELDS `email` UNIQUE;`` | ``REMOVE INDEX IF EXISTS `person_email` ON `person`;`` | yes (`overwrite=True` without `previous=`: no) |
|
|
6906
|
+
| `DropIndex` | ``REMOVE INDEX `person_email` ON `person`;`` | the `previous=` definition | with `previous=` |
|
|
6907
|
+
| `RebuildIndex` | ``REBUILD INDEX `post_body` ON `post`;`` | the same statement | yes |
|
|
6908
|
+
| `DefineAnalyzer` | ``DEFINE ANALYZER OVERWRITE `english` TOKENIZERS class,blank FILTERS lowercase,snowball(english);`` | ``REMOVE ANALYZER IF EXISTS `english`;``, or `previous=` | yes |
|
|
6909
|
+
| `RemoveAnalyzer` | ``REMOVE ANALYZER `english`;`` | the `previous=` definition | with `previous=` |
|
|
6910
|
+
| `DefineEvent` | ``DEFINE EVENT `audit` ON `person` WHEN $event = 'CREATE' THEN { CREATE log SET who = $after.name };`` | ``REMOVE EVENT IF EXISTS `audit` ON `person`;``, or `previous=` | yes (`overwrite=True` without `previous=`: no) |
|
|
6911
|
+
| `RemoveEvent` | ``REMOVE EVENT `audit` ON `person`;`` | the `previous=` definition | with `previous=` |
|
|
6912
|
+
| `DefineAccess` | `DEFINE ACCESS account ON DATABASE TYPE RECORD SIGNUP ( … ) SIGNIN ( … ) DURATION …;` | ``REMOVE ACCESS IF EXISTS `account` ON DATABASE;``, or `previous=` | yes (`overwrite=True` without `previous=`: no) |
|
|
6913
|
+
| `RemoveAccess` | ``REMOVE ACCESS `account` ON DATABASE;`` | the `previous=` definition | with `previous=` |
|
|
6914
|
+
| `DefineFunction` | `DEFINE FUNCTION fn::greet($n: string) -> string { RETURN 'hi ' + $n; };` | `REMOVE FUNCTION IF EXISTS fn::greet;`, or `previous=` | yes (`overwrite=True` without `previous=`: no) |
|
|
6915
|
+
| `RemoveFunction` | `REMOVE FUNCTION fn::greet;` | the `previous=` definition | with `previous=` |
|
|
6916
|
+
| `DataMigration` | its `forwards_sql` or `forwards_func` | its `backwards_sql` or `backwards_func` | with one of them |
|
|
6917
|
+
| `RawSQL` | its `sql` | its `reverse_sql` | with `reverse_sql` |
|
|
6918
|
+
|
|
6919
|
+
Names are written in backticks, values as SurrealQL literals; expressions (`value`, `assertion`, `when`, `then`,
|
|
6920
|
+
permission rules), view queries, function bodies and the SurrealQL of `RawSQL` and `DataMigration` are application code
|
|
6921
|
+
written as is, after a check that each is one expression or whole statements: never build an operation from user
|
|
6922
|
+
input. Migration files are Python code, run when they are loaded: point the executor and `makemigrations()` at the
|
|
6923
|
+
application's own directory only.
|
|
6924
|
+
|
|
6925
|
+
#### Drift
|
|
6926
|
+
|
|
6927
|
+
```python
|
|
6928
|
+
from surreal_orm_lite import schema_diff
|
|
6929
|
+
|
|
6930
|
+
for operation in await schema_diff(models=[Person, Post]):
|
|
6931
|
+
print(operation.describe())
|
|
6932
|
+
```
|
|
6933
|
+
|
|
6934
|
+
`schema_diff()` lists the operations that would bring the database to the models — `[]` when they agree — and
|
|
6935
|
+
`makemigrations()` writes them against the database. The comparison normalises what SurrealDB renders differently
|
|
6936
|
+
from the ORM (whitespace in expressions, `1.5` and `1.5f`, `7d` and `1w`, permissions equal to SurrealDB's defaults,
|
|
6937
|
+
`FLEXIBLE` on an `any` column, index options left at their defaults), so the diff right after `migrate()` or
|
|
6938
|
+
`define_table()` is empty on every line. `SchemaState.diff()` between two states read from databases
|
|
6939
|
+
(`DatabaseIntrospector`), or migration states (`executor.migration_state()`), compares every clause: carrying what a
|
|
6940
|
+
model leaves to the database applies only to a state built from models.
|
|
6941
|
+
|
|
6942
|
+
#### Server lines
|
|
6943
|
+
|
|
6944
|
+
The same migration applies on SurrealDB 3.x, 2.x and the embedded engine: the statements that differ are chosen
|
|
6945
|
+
when they are applied. A full-text `CreateIndex` writes `FULLTEXT` on 3.x and `SEARCH` on 2.x and the embedded
|
|
6946
|
+
engine. On SurrealDB 2.x and the embedded engine, an `AddField` or `AlterField` of an `any` column of a `SCHEMAFULL`
|
|
6947
|
+
table writes `FLEXIBLE`, and an `AlterTable` that makes a table `SCHEMAFULL` also redefines its `any` columns,
|
|
6948
|
+
untyped lists and lists of sub-models `FLEXIBLE` in the same transaction, so their object values are kept (3.x keeps
|
|
6949
|
+
them without it). Those columns are the database's: `migrate()` and `rollback()` render from the database's schema
|
|
6950
|
+
with the migrations replayed, while `show_sql()` renders from the migration files alone, so on 2.x and the embedded
|
|
6951
|
+
engine `migrate()`'s batch may also redefine `FLEXIBLE` columns defined outside migrations that `show_sql(line=2)`
|
|
6952
|
+
does not show. When the database's definition of a table cannot be read entirely, and the `FLEXIBLE` clauses of such
|
|
6953
|
+
an `AlterTable`, or of a field holding `any` or a list of objects, would be chosen from that reading, `migrate()` and
|
|
6954
|
+
`rollback()` raise `SurrealDbError` on those lines before any change
|
|
6955
|
+
(`DatabaseIntrospector().introspect().issues` lists what could not be read). `DefineEvent(async_mode=True)`,
|
|
6956
|
+
`DefineAccess(with_refresh=True)` and `COMPUTED` fields need SurrealDB 3.x: on 2.x and the embedded engine they raise
|
|
6957
|
+
`SurrealDbError` before any change. `AddField(reference=True)` is left to the server: SurrealDB 2.x refuses it unless
|
|
6958
|
+
its `record_references` capability is enabled. A `RemoveAnalyzer` of an analyzer an index still uses and a `DropTable`
|
|
6959
|
+
of a table a view reads raise `ValueError` before any change on every line (SurrealDB 2.x would accept them, then
|
|
6960
|
+
refuse every write). The embedded engine behaves as a 2.x server and applies each migration atomically too
|
|
6961
|
+
([embedded table](#orm-behaviour-the-embedded-engine)); the [2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x) lists
|
|
6962
|
+
the differences.
|
|
6963
|
+
|
|
6964
|
+
#### Limits
|
|
6965
|
+
|
|
6966
|
+
- A migration's transaction that writes records, then defines an index on the same table: SurrealDB servers do not
|
|
6967
|
+
index those records (surrealdb/surrealdb#7618, as for `define_indexes(tx=…)`); define the index in an earlier
|
|
6968
|
+
migration, or run `RebuildIndex` after.
|
|
6969
|
+
- A migration holding `DefineAnalyzer` is atomic **except** its analyzer definitions, committed first (SurrealDB
|
|
6970
|
+
builds an index with the committed analyzer only): if the rest fails they are restored, and the error says whether
|
|
6971
|
+
that worked. Records other clients write in between are tokenised with the new analyzer (run `RebuildIndex`).
|
|
6972
|
+
- Analyzers are written with `OVERWRITE` first, so an analyzer of the same name made outside migrations is replaced,
|
|
6973
|
+
and when the rest of the migration fails the definition the database held is restored (or the analyzer removed when
|
|
6974
|
+
the database held none). A migration that redefines an analyzer whose current definition the ORM cannot read or
|
|
6975
|
+
write is refused before any change: redefine that analyzer in a form `Analyzer` accepts, by hand or with
|
|
6976
|
+
`define_indexes()`, then migrate again.
|
|
6977
|
+
- A redefined, removed or re-created access gets a new signing key from SurrealDB, so the tokens issued before are
|
|
6978
|
+
refused: sign in again (open WebSocket sessions keep working).
|
|
6979
|
+
- Live queries on a table a migration or a rollback removes are killed by SurrealDB: 3.x ends the subscription, 2.x
|
|
6980
|
+
goes silent. A redefinition keeps them.
|
|
6981
|
+
- Over HTTP the SDK gives up after 30 s, so a migration that builds a large index may be applied without an answer:
|
|
6982
|
+
the executor reads the tracking table, says so in a warning and does not run its data operations. Prefer WebSocket
|
|
6983
|
+
for long migrations.
|
|
6984
|
+
- An `AlterTable` writes the table's whole definition, and `DEFINE TABLE OVERWRITE` resets every clause it does not
|
|
6985
|
+
write, so with `from_db=False` the clauses set on the database outside migrations are replaced (with the default
|
|
6986
|
+
`from_db=True` they are read and kept).
|
|
6987
|
+
- `migrate()` and `rollback()` read the schema once, before their first change, so a definition another client
|
|
6988
|
+
changes meanwhile is not seen.
|
|
6989
|
+
- On SurrealDB 2.x and the embedded engine, `show_sql()` shows the statements rendered from the migration files, and
|
|
6990
|
+
`migrate()`'s batch may hold more `FLEXIBLE` redefinitions (see "Server lines").
|
|
6991
|
+
- Functions are not compared; there is no squashing and no command line yet (the CLI comes with v0.39.0).
|
|
6992
|
+
|
|
6993
|
+
#### Coming from the full SurrealDB-ORM
|
|
6994
|
+
|
|
6995
|
+
- **Import from `surreal_orm_lite.migrations`**: `from surreal_orm.migrations import …` becomes
|
|
6996
|
+
`from surreal_orm_lite.migrations import …`; a full-ORM migration file whose operations exist here loads after that
|
|
6997
|
+
change. `schema_diff`, `DefineAnalyzer`, `DefineEvent`, `RebuildIndex`, `RemoveEvent` and `get_registered_models`
|
|
6998
|
+
are also at the top level, as in the full ORM.
|
|
6999
|
+
- **`makemigrations()` is a coroutine**: the full ORM's `makemigrations` command, with the same default — it reads the
|
|
7000
|
+
database.
|
|
7001
|
+
- **One transaction per migration**, its record included: a failed migration leaves nothing applied (the full ORM
|
|
7002
|
+
sends the statements one after the other and leaves the first ones applied).
|
|
7003
|
+
- **The same tracking table**: `_surreal_orm_migrations`, with the same fields and unique index, so a database
|
|
7004
|
+
migrated by the full ORM keeps its history.
|
|
7005
|
+
- **Statements**: names in backticks, `TYPE NORMAL` where the full ORM writes no `TYPE`, `FLEXIBLE` after `TYPE`, and
|
|
7006
|
+
`THEN { … }` for an event, as `define_table()` and the other appliers write them.
|
|
7007
|
+
- **`previous=`** on the redefinitions and on the removals of indexes, analyzers, events, accesses and functions makes
|
|
7008
|
+
them reversible; the full ORM's removals are irreversible.
|
|
7009
|
+
- **`default=` is data**: a Python value written as a SurrealQL literal (a `str` is always a string); an expression is
|
|
7010
|
+
a `SurrealFunc`, and a default read from a database is a `DefaultExpression`.
|
|
7011
|
+
- **Not provided**: `DefineBearerAccess`, `DefineApi`/`RemoveApi`, `DefineGraphQLConfig`/`RemoveGraphQLConfig`,
|
|
7012
|
+
`encrypted=` and `CreateIndex(concurrently=True)`.
|
|
7013
|
+
- **`MigrationStatementError` is a `SurrealDbError`** and a `RuntimeError` (the full ORM's base): it names the
|
|
7014
|
+
migration, the operation and SurrealDB's reason, never the statement.
|
|
7015
|
+
- **What the diff carries**: a clause a model does not declare stays as the database has it, as with `define_table()`
|
|
7016
|
+
(the full ORM resets it).
|
|
7017
|
+
- **Creations are undone with `REMOVE … IF EXISTS`**, and removals that carry `previous=` are reversible.
|
|
7018
|
+
- **Operations are frozen**: `reversible` is a read-only property, and an operation is changed by building another.
|
|
7019
|
+
- **`SchemaState.applied_migrations` is filled** from the tracking table by `DatabaseIntrospector` and by
|
|
7020
|
+
`migration_state()` (the full ORM declares it and leaves it empty).
|
|
7021
|
+
- **`DefineFunction` and `RemoveFunction` are added**; `parse_define_*` are not exported.
|
|
7022
|
+
- **Porting a migration file's defaults**: in a full-ORM migration file, a string `default=` holding `::` or starting
|
|
7023
|
+
with `$` is an expression for the full ORM but a string literal here; rewrite it as `SurrealFunc('…')` (for example
|
|
7024
|
+
`default="time::now()"` becomes `default=SurrealFunc("time::now()")`).
|
|
7025
|
+
- **Data operations run after the schema**: `migrate(schema_only=False)` runs a migration's `DataMigration`s after its
|
|
7026
|
+
schema transaction, where the full ORM runs them in position; a data step that reads a field a later operation of the
|
|
7027
|
+
same migration removes goes in a migration of its own.
|
|
7028
|
+
- **Targets are names**: an unknown `migrate()` or `rollback()` target raises `ValueError`, where the full ORM compares
|
|
7029
|
+
names as strings (`n <= target`, `name > target`).
|
|
7030
|
+
- **`split_destructive()` partitions on removals**: a `RawSQL` without `reverse_sql` or a `RebuildIndex` stays in the
|
|
7031
|
+
first list, where the full ORM's partition on `reversible` puts it in the second.
|
|
7032
|
+
- **The current state**: `makemigrations()` reads the database and replays the migration files it has not applied on
|
|
7033
|
+
top, so a second run before `migrate()` writes nothing (the full ORM's `--from-db` writes the pending operations
|
|
7034
|
+
again); `from_db=False` diffs against the migration files, where the full ORM's `--no-from-db` diffs against an empty
|
|
7035
|
+
schema.
|
|
7036
|
+
- **The model registry**: `get_registered_models()` is provided (the model classes alive, read from the subclasses of
|
|
7037
|
+
`BaseSurrealModel`; a class whose name starts with `_` is left out but its subclasses are listed, as in the full
|
|
7038
|
+
ORM); they come depth first — each class's subclasses right after it, in definition order —, not in the full ORM's
|
|
7039
|
+
global definition order; `clear_model_registry()` is not provided, as there is no registry to clear.
|
|
7040
|
+
- **`migrate()` and `rollback()` read the schema first**: before any change they read the database's schema
|
|
7041
|
+
(`INFO FOR DB`, `INFO FOR TABLE`), replay the migrations over it and check them, so a removal SurrealDB would refuse,
|
|
7042
|
+
an analyzer still used by an index or a table a view reads (made outside migrations or not) is refused before
|
|
7043
|
+
anything is applied, and on SurrealDB 2.x the `FLEXIBLE` statements cover the columns the database holds; the full
|
|
7044
|
+
ORM sends each migration's statements as written. The session needs the right to read the schema, which every
|
|
7045
|
+
system user has.
|
|
7046
|
+
|
|
6721
7047
|
---
|
|
6722
7048
|
|
|
6723
7049
|
## Configuration Options
|
|
@@ -6840,7 +7166,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
6840
7166
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
6841
7167
|
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
|
|
6842
7168
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
6843
|
-
Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5. The row added in v0.35.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.36.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.36.2 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.37.0 were measured on 2.7.0, 3.3.4, 3.2.6 and the embedded engine, with 3.1.5 and 3.2.6 where they differ from 3.3.4. The row added in v0.37.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.37.4 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.37.5 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
|
|
7169
|
+
Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5. The row added in v0.35.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.36.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.36.2 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.37.0 were measured on 2.7.0, 3.3.4, 3.2.6 and the embedded engine, with 3.1.5 and 3.2.6 where they differ from 3.3.4. The row added in v0.37.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.37.4 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.37.5 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.38.0 were measured on 2.7.0, 3.3.4 and the embedded engine.
|
|
6844
7170
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
6845
7171
|
|
|
6846
7172
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -7007,6 +7333,13 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
7007
7333
|
| `hybrid_search()` on a field without a vector or full-text index | no vector index: the vector list is empty, so the full-text ranking alone is fused; no full-text index: `SurrealDbError` naming the field | the same; 3.1 and 3.2 put the first `vector_limit` records by id in the vector list, with no distance, and match no record for the text | v0.37.0 |
|
|
7008
7334
|
| An exact scan (`similar_to(dist=…)`, `hybrid_search(dist=…)`) with records at an equal distance at the last place | the ORM ranks the scan by distance, then id: the same records on every call, the tied ones by id (2.x's own scan picks among them in no fixed order) | the same records on every call, as with the HNSW index | v0.37.4 |
|
|
7009
7335
|
| `define_indexes(tx=)` then `remove_index(tx=)` in one block, the index not stored before the block | committed: the index absent after the commit, whatever the table holds | the commit fails with a retryable `SurrealDbConflictError`, whatever the table holds: nothing committed | v0.37.5 |
|
|
7336
|
+
| Migrations: full-text index in `CreateIndex` | `SEARCH` | `FULLTEXT` | v0.38.0 |
|
|
7337
|
+
| Migrations: `any` column of a `SCHEMAFULL` table, also when an `AlterTable` makes the table `SCHEMAFULL` | `FLEXIBLE` written; the `AlterTable` redefines the columns the database holds in its transaction, without which 2.x empties their object values at the next write | not written: 3.x keeps the values and refuses `FLEXIBLE` on `any` | v0.38.0 |
|
|
7338
|
+
| Migrations: `ASYNC` events, `WITH REFRESH` | refused before any DDL (`SurrealDbError`) | applied | v0.38.0 |
|
|
7339
|
+
| Migrations: `REFERENCE` | refused by the server unless `record_references` is enabled (`MigrationStatementError`) | applied | v0.38.0 |
|
|
7340
|
+
| Migrations: `COMPUTED` fields in `AddField`/`AlterField` | refused before any DDL (`SurrealDbError`) | applied | v0.38.0 |
|
|
7341
|
+
| Migrations: a live query on a table a migration removes | no further notification | the subscription ends | v0.38.0 |
|
|
7342
|
+
| Migrations: a migration's atomicity, concurrent `migrate()` | same on both lines: each migration and its record in one transaction; a concurrent run skips a migration the other recorded | same on both lines | v0.38.0 |
|
|
7010
7343
|
| 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 |
|
|
7011
7344
|
|
|
7012
7345
|
> **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.
|
|
@@ -7048,6 +7381,7 @@ Capabilities not listed behave as on a 2.x server.
|
|
|
7048
7381
|
| Vector search (v0.36.0) | as on a 2.x server: `MTREE` accepted, at most `ef` records returned (the ORM raises `ef` to `limit`), other conditions selected first in a `LET` (search annotations refused), writes made by the ids of the nearest, fewer records with a selective condition; an index without `TYPE` is `F64` (servers: `F32`), so the ORM always writes `TYPE` | 3.x refuses `MTREE`, applies the conditions during the index search and keeps search annotations | v0.36.0 |
|
|
7049
7382
|
| `remove_index(tx=)` then `define_indexes(tx=)` in one block | the index is defined again after its removal and committed, on a table holding records too | the same on 3.x; on 2.x, on a table holding records, the commit fails with a retryable conflict | v0.36.2 |
|
|
7050
7383
|
| Hybrid search (v0.37.0) | as on a 2.x server: the ORM fuses the two lists with `search::rrf()`'s formula, which the engine does not have, and the vector list selects the other conditions first (a `LET`); an exact scan (`dist=`) keeps the records at an equal distance at the `vector_limit`-th place by id (since v0.37.4), as `similar_to(dist=…)` does | 3.x fuses with `search::rrf()`, each list applying the conditions; its exact scan returns the same list | v0.37.0 |
|
|
7384
|
+
| Migrations (v0.38.0) | as on a 2.x server: `SEARCH` for a full-text `CreateIndex`, `FLEXIBLE` on `any` columns (also in the redefinitions of an `AlterTable` that makes a table `SCHEMAFULL`), `ASYNC` events, `WITH REFRESH` and `COMPUTED` fields refused before any DDL; each migration atomic, its analyzers committed first and compensated as on the servers | 3.x writes `FULLTEXT`, no `FLEXIBLE` on `any`, and applies `ASYNC`, `WITH REFRESH` and `COMPUTED` | v0.38.0 |
|
|
7051
7385
|
| 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 |
|
|
7052
7386
|
|
|
7053
7387
|
---
|
|
@@ -7100,7 +7434,8 @@ Contributions are welcome! Please:
|
|
|
7100
7434
|
| v0.35.0 | Tier 3 — Full-text search | ✅ Released |
|
|
7101
7435
|
| v0.36.0 | Tier 3 — Vector search | ✅ Released |
|
|
7102
7436
|
| v0.37.0 | Tier 3 — Hybrid search | ✅ Released |
|
|
7103
|
-
| v0.38.0
|
|
7437
|
+
| v0.38.0 | Tier 3 — Migration system | ✅ Released |
|
|
7438
|
+
| v0.39.0 – v0.40.0 | Tier 3 — Advanced (CLI, test factories) | 📋 Planned |
|
|
7104
7439
|
| v0.41.0 | Beta Phase (API freeze, hardening) | 📋 Planned |
|
|
7105
7440
|
| v2.0.0 | Production / GA (aligned with SDK 2.0) | 📋 Planned |
|
|
7106
7441
|
|
|
@@ -7162,7 +7497,7 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
|
|
|
7162
7497
|
| Full-Text Search | ✅ v0.35.0 (`search()`) | ✅ |
|
|
7163
7498
|
| Vector Search (KNN/HNSW) | ✅ v0.36.0 (`similar_to()`) | ✅ |
|
|
7164
7499
|
| Hybrid Search (RRF) | ✅ v0.37.0 (`hybrid_search()`) | ✅ |
|
|
7165
|
-
| Migrations & CLI | v0.38
|
|
7500
|
+
| Migrations & CLI | ✅ v0.38.0 (migrations), CLI v0.39.0 | ✅ |
|
|
7166
7501
|
| Test Fixtures & Factories | ✅ v0.25.0 SurrealFixture; factories v0.40.0 | ✅ |
|
|
7167
7502
|
| Retry, Logging, Metrics | v0.41.0 | ✅ |
|
|
7168
7503
|
| Connection Pool | post-GA (tentative) | ✅ |
|