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.
Files changed (63) hide show
  1. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/CHANGELOG.md +85 -0
  2. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/PKG-INFO +351 -16
  3. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/README.md +350 -15
  4. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/__init__.py +15 -2
  6. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/introspection.py +88 -7
  7. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/__init__.py +82 -0
  8. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/autodetect.py +148 -0
  9. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/compare.py +435 -0
  10. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/constants.py +9 -0
  11. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/executor.py +1184 -0
  12. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/generator.py +370 -0
  13. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/introspector.py +217 -0
  14. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/loader.py +224 -0
  15. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/migration.py +217 -0
  16. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/operations.py +1993 -0
  17. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/render.py +709 -0
  18. surreal_orm_lite-0.38.0/src/surreal_orm_lite/migrations/state.py +695 -0
  19. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/model_auth.py +52 -33
  20. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/model_base.py +39 -0
  21. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/model_generator.py +14 -4
  22. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/schema.py +83 -0
  23. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/schema_state.py +104 -12
  24. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/.gitignore +0 -0
  25. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/LICENSE +0 -0
  26. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/Makefile +0 -0
  27. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/_sdk.py +0 -0
  28. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/aggregations.py +0 -0
  29. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/auth.py +0 -0
  30. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/cache.py +0 -0
  31. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/changefeed.py +0 -0
  32. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/concurrency.py +0 -0
  33. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/connection_config.py +0 -0
  34. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/connection_manager.py +0 -0
  35. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/constants.py +0 -0
  36. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/decoding.py +0 -0
  37. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/define_parser.py +0 -0
  38. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/edge.py +0 -0
  39. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/embedded.py +0 -0
  40. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/encoding.py +0 -0
  41. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/enum.py +0 -0
  42. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/exceptions.py +0 -0
  43. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/functions.py +0 -0
  44. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/geo.py +0 -0
  45. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/hybrid.py +0 -0
  46. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/live.py +0 -0
  47. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/model_ddl.py +0 -0
  48. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/py.typed +0 -0
  49. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/q.py +0 -0
  50. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/query_set.py +0 -0
  51. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/routing.py +0 -0
  52. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/search.py +0 -0
  53. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/signals.py +0 -0
  54. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/subquery.py +0 -0
  55. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/surql_literal.py +0 -0
  56. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
  57. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/testing/database.py +0 -0
  58. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  59. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/time_travel.py +0 -0
  60. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/transaction.py +0 -0
  61. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/types.py +0 -0
  62. {surreal_orm_lite-0.37.7 → surreal_orm_lite-0.38.0}/src/surreal_orm_lite/utils.py +0 -0
  63. {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.37.7
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()` and `schema_diff()` come with v0.38.0** (migrations), as does `applied_migrations`; the
4525
- `inspectdb` command comes with v0.39.0.
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 (that comes with migrations,
4631
- v0.38.0).
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`) and the removal of the events a model no
4808
- longer declares **come with migrations (v0.38.0)**.
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 come with v0.38.0.
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 come with v0.38.0.
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: remove a field, a change feed or a comment with
5633
- raw SurrealQL (migrations come with v0.38.0). `schema_mode=SchemaMode.SCHEMALESS` turns a `SCHEMAFULL` table back,
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 adds in v0.38.0.
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 – v0.40.0 | Tier 3 — Advanced (migrations, CLI) | 📋 Planned |
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 – v0.39 | ✅ |
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) | ✅ |