Skip to content

feat: enhanced migration#5840

Draft
alexandru-uta wants to merge 7 commits intomasterfrom
alex/multimigration-v2
Draft

feat: enhanced migration#5840
alexandru-uta wants to merge 7 commits intomasterfrom
alex/multimigration-v2

Conversation

@alexandru-uta
Copy link
Contributor

@alexandru-uta alexandru-uta commented Feb 12, 2026

Resolves LANG-1126

Adds a new type of migration expression, where users specify a migrations folder via the compiler, e.g., moc --enhanced-migration migrations_folder --enhanced-orthogonal-persistence.

High-level Design Decisions

  • actors don't allow initializers on variables, e.g., declarations like let x : Nat = 5 are forbidden in actor bodies.
  • all actors have migration functions, even those deployed from scratch. All variables get initialized only in migration functions. Newly deployed actors will have to initialize their stable variables via an initializer function.
  • migrations can be a single function (which is migration from v(i) to v(i+1)), or a sequence of functions (which is migration from v(i), v(i+1), …, v(k)); all these functions should compose correctly, otherwise the compiler will reject the migration
  • all migration functions will be identified by the file in which they are defined — a single initializer per file; in production, these should be timestamps (datetime).
  • always, on every new deployment, ALL the migrations from the migrations folder will then be applied in lexicographic order.
  • the RTS will not allow to run the same migration twice as it will keep track of which migrations were already applied.

The restrictions for the multi-migration are the following:

  • Each migration file should be a module with a function called run() -- this will implement the migration logic.
  • The output of each migration must be compatible (subtype) with the input of the next one. The program fails to compile if not.
  • Each migration only needs to declare the fields it reads (input) and produces (output). Fields not mentioned by a migration are automatically carried through unchanged via a shared state type.
  • The output of the last migration must be compatible with the target actor's stable fields.
  • Fields are only removed from the state when the final actor no longer declares them.
  • The enhanced migration (--enhanced-migration) cannot be combined with the regular inline migration (with migration = ...).
migrations/                              actor {
├── 20240101_init.mo                       var b : Text;
│   run : {} → {a; b}                      var c : Bool;
│                                          var d : Nat;
├── 20240315_add_field.mo
│   run : {a; b} → {a; b; c}              public func check() : async () {
│                                            ...
├── 20240601_rename_a.mo                   };
│   run : {a; c} → {c; d}               }
│

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant