Dual-Track Migrations: Balancing Speed and Safety

In Framework M, we have finalized our Dual-Track Migration System, which provides two cooperative paths for evolving your database schema.

1. The Declarative Sync (m migrate sync)

The Sync Engine is designed for the 90% of development that involves additive changes like new fields, indices, or tables.

• Fast & Safe: It is physically incapable of executing DROP statements.
• State-Driven: It derives the schema directly from your Python classes and applies additive changes instantly.

2. The Imperative Patch (m migrate run)

For destructive operations or complex data transformations (column renames, table splits, or data cleanup), we use Alembic Patches.

• Versioned History: Provides a clear, immutable timeline of intentional schema evolution.
• Production Standard: Destructive actions are never automatic; they must be explicitly authored.

Deployment Strategies

Framework M adapts to your operational scale:

• Simple & Safe: Use m migrate all. It runs both tracks in a single, reliable sequence.
• Enterprise ZDM: Run m migrate run (History) followed by m migrate sync (State) independently. This "History leads State" order allows you to orchestrate complex data migrations and backfills before the final schema state is enforced, enabling true zero-downtime deployments at scale.
  • Lifecycle Hooks: Discovers and executes before_sync and after_sync Python hooks for custom schema preparation or data seeding.

Production Verification (m migrate verify)

For environments where you want to verify schema integrity without applying changes, we provide the m migrate verify command. It performs a read-only introspection and generates a risk-categorized report (Safe, Warning, Breaking), allowing you to detect unintended schema drift before the application starts.