Feat: Entity-first migrations by sinder38 · Pull Request #3015 · SeaQL/sea-orm

sinder38 · 2026-03-19T23:16:48Z

PR Info

Closes Entity first migration-generation #3008

Goal

Safe, production ready migration workflow.

PR Todo

CLI

Add entity crate generation to sea-orm-cli
--preview option for generate ( discovery without creating the migration)
fluff ✨
interactive (handle renames)
emit warning (destructive changes, assumptions)

Core

Implement generate_migration
Capture DDLs instead of applying them
Write output as raw SQL wrapped in db.execute_unprepared with timestamped filename
Allow dangerous change discovery
Migration summary
Warn on "obvious" data migration (some changes like adding a NOT NULL column obviously would require additional input from the developer)
Migrate down place holdert
Discover possible renames
Discover constraints ( would require a quick fix or sea-schema update)

Integration into the rest of codebae

Auto-update migration/src/lib.rs to register the new migration
Solve repetition issue (2 crates: entity, migration)
Solve migration tracker protection issue

Quality

Tests
Document the new workflow

Out of scope (probably)

Generate sea_orm statements instead of raw sql (I want this one myself, but it may take too long)
Generate proper down (not very useful)
Allow offline migration ( I need to check if dependencies for that already exist)
Generate data transition (hardest by far, definitely not doing that)

sinder38 · 2026-03-19T23:29:43Z

In terms of design:

I created a separate crate for entity-first migrations instead of extending the migrations crate directly, for easier reading. Currently it imports the migrations crate and builds on top, but I feel in the final version they should be merged into one.
Currently CLI functionality is not in sea-orm-cli again, to avoid the mess.
I changed how sync() works. Now it uses discover() for discovery and applies the changes. discover() itself is used by the entity-first migrator for detecting changes.
Also, discover() with dangerous turned on does not protect against deleting the migration tracker table. This is handled later down the line in "entity". I will change that, but I am not sure what the best approach is yet.

Other:

I think the migrations CLI output can be improved slightly in terms of clarity

NOT READY FOR MERGE THOUGH
Please review @Huliiiiii

tyt2y3 · 2026-03-20T00:04:36Z

oh wow, looks promising!

sinder38 · 2026-03-21T01:41:20Z

This is going to take longer than expected. I underestimated implementing proper change discovery phase

Huliiiiii · 2026-03-21T14:18:57Z

sea-orm-entity/src/cli.rs

+        #[arg(
+            long,
+            default_value = "true",
+            help = "Generate migration file based on Utc time",
+            conflicts_with = "local_time",
+            display_order = 1001
+        )]
+        universal_time: bool,
+
+        #[arg(
+            long,
+            help = "Generate migration file based on Local time",
+            conflicts_with = "universal_time",
+            display_order = 1002
+        )]
+        local_time: bool,


Could we merge this into a single option, like filename-timezone / migration-timezone?

Yes, I thought the same. just copied this part from original migrator.

Huliiiiii · 2026-03-21T14:26:04Z

sea-orm-entity/src/cli.rs

+    let url = cli
+        .database_url
+        .expect("Environment variable 'DATABASE_URL' not set");
+    let schema = cli.database_schema.unwrap_or_else(|| "public".to_owned());


Use clap's default_value.

Yes! again, just copied this part from original migrator.

Huliiiiii · 2026-03-21T14:27:23Z

sea-orm-entity/src/cli.rs

+            // Future: when --ephemeral is added, build an in-memory db here instead,
+            // apply existing migrations via the migrator, then pass it to generate_from_db.
+
+            if let Err(e) = generate_from_db(


Too many parameters. Use a struct instead.

Huliiiiii · 2026-03-21T14:33:10Z

sea-orm-entity/src/cli.rs

+                    .to_owned(),
+            )
+            .await
+            .expect("Failed to connect to database");


I think it would be better to expose the reason to the user.

Yes, same thoughts.
again, just copied this part from original migrator.

Huliiiiii · 2026-03-21T14:37:30Z

sea-orm-entity/src/cli.rs

+    let builder = entity_set.register(schema.builder());
+
+    println!("Discovering schema changes...");
+    let raw = builder.discover(&db, dangerous).await?;


raw…what?

The idea, was that it was unprocessed changes, will change

Huliiiiii · 2026-03-21T14:58:36Z

src/schema/builder.rs

+    {
+        let _existing = Self::discover_existing_schema(db).await?;
+
+        #[allow(unreachable_code)]


Why so many #[allow(unreachable_code)]?

copied from original. I just decided not to think about it. I the new discover() I removed them.

Huliiiiii · 2026-03-21T15:02:34Z

src/schema/builder.rs

+                let in_entities = self
+                    .entities
+                    .iter()
+                    .any(|e| get_table_name(e.table.get_table_name()) == existing_name);


Rename get_table_name to something more semantic.

Okay, but I don't see a problem.

Huliiiiii · 2026-03-21T15:03:48Z

src/schema/builder.rs

+        // and generate drop statements for them.
+        #[allow(unreachable_code)]
+        if allow_dangerous {
+            for existing_table in &_existing.tables {


How will this handle multiple schemas?

I did't cover multiple schemas. as most of the sea architecture doesn't support them as well

Okay, leave a TODO comment here so we don't forget to handle this during future refactoring.

Don't worry I am doing rewrite of discover() since yesterday.

Huliiiiii · 2026-03-21T15:07:34Z

src/schema/builder.rs

+    fn discover_changes(
        &self,
-        db: &C,
+        db_backend: DbBackend,
        existing: &DiscoveredSchema,
        created_enums: &mut Vec<Statement>,
-    ) -> Result<(), DbErr> {
-        let db_backend = db.get_database_backend();
-
+        changes: &mut Vec<Statement>,
+        allow_dangerous: bool,


Too many params.

Huliiiiii · 2026-03-21T15:08:44Z

src/schema/builder.rs

+                                            .table(
+                                                self.table
+                                                    .get_table_name()
+                                                    .expect("Checked above")


Indents too deep.

okay, will change

sinder38 · 2026-03-21T15:41:01Z

Thanks for feedback! I didn't have experience developing CLI in rust before.
The most important question is about the multiple schemas. Am I mandated to support them at this point?
Also on the note of CLI QoL and formatting. I am currently inheriting some of the bad in my opinion formatting from migrator, it it fine to change some parts of it?

I just wanted to say that I mostly wanted to discuss (#3015 (comment)) the integration with existing code and not get exact code review, as this first draft for a reason

@Huliiiiii

Huliiiiii · 2026-03-21T17:20:31Z

Oh, I got confused. I thought you wanted me to review the code above.

As for the refactor, I think we can merge it back into the CLI crate first, and then see how it goes. For the more significantly changed parts, feel free to refactor them, since that should make the diff clearer.

For the rest of the architecture, I agree with calling discover inside sync.

I think a better approach is to update the migration crate so that discover either accepts options (or add another method that does) or returns a structured change plan instead of Vec<Statement> to avoid manually inspecting the SQL string.

Ideally, both should be implemented.

sinder38 added 4 commits March 19, 2026 17:36

Add separate functions for discovery to schema builder

208c137

update sync to use discover() instead

8251d3a

add .zed to gitignore

ac82ef1

Add first draft implementation of entity-first migrator

1813316

Appease Clippy and Taplo

f905ad2

Huliiiiii requested changes Mar 21, 2026

View reviewed changes

Uh oh!

Conversation

sinder38 commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Info

Goal

PR Todo

CLI

Core

Integration into the rest of codebae

Quality

Out of scope (probably)

Uh oh!

sinder38 commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tyt2y3 commented Mar 20, 2026

Uh oh!

sinder38 commented Mar 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sinder38 commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Huliiiiii commented Mar 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sinder38 commented Mar 19, 2026 •

edited

Loading

sinder38 commented Mar 19, 2026 •

edited

Loading

sinder38 commented Mar 21, 2026 •

edited

Loading