SeaQL / SeaQL/sea-orm

Entity first migration-generation

Open
#3,008 3 comments 8 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Area:entity-first
Dominant language
Rust
Stars
9.9k
Forks
734
Avg merge
6h 36m
Merged PRs (30d)
8

Description

Motivation

Get ready this is a big one. TL;DL generate migrations from entity-first approach

The entity-first workflow introduced in 2.0 provides schema-sync for development, but there is no clear path from entities to migration files for production use.

Currently, developers using entity-first must either:

  • Enable schema-sync at startup, which allows to perform live schema discovery, whic is not very suitable for production.
  • Manually write migration files that replicate what sync already knows how to compute
    Either way its pain.

The sync engine already diffs entity definitions against the live database and produces the usually correct DLLs. That diff output is exactly what a migration file should contain, but today it can only be applied immediately and not captured.

On the side note: this approach will make dropping during sync safe enough to be justifiable

Proposed Solution

(Main) CLI migration generation via entity crate binary

Add function similar to cli::run_cli(migration::Migrator).await; used by migration crates. It would:

  • Connects to a database (using env or cli args)
  • Collects entities
  • Runs the sync diff engine
  • Writes the resulting migration into a new migration file under the migration crate

This would work by adding an optional binary target to the entity crate (similar to how the migration crate already has main.rs).
-Generating migrations in sea-orm would be kinda hard so it will we raw sql wrapped in db.execute_raw

(Future) Offline diff without a live database and sea_orm migrations

First longer-term goal is about diffing against a reconstructed schema state from the migration file chain (like Django) or using an ephemeral database (like Atlas), removing the requirement for a live database during migration generation.

Second longterm goal is be to generate migration in seaORM syntax instead of raw SQL

Additional Information

  • I will implement main myself (future - unlikely to implement). I want to disscuss my proposal before starting.
  • This is partiall inspired by Django, with current codebase state in mind
  • Generated migrations are dialect-specific since they diff against a live database - this is a known limitation

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing migration crate main.rs and the cli::run_cli(migration::Migrator).await entry point, then trace the sync diff engine. The proposed result is an optional entity-crate binary that connects using environment or CLI arguments and writes the dialect-specific raw SQL diff, wrapped with db.execute_raw, into a migration file.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust, sql
Domain
cli, databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.