Skip to main content

Migration Risk Engine

Framework M employs a risk-aware migration strategy designed to balance developer velocity with production stability. This is achieved through a core Migration Engine that sits between your declarative DocType definitions and the physical database.

The Problem: Opaque DDL​

In many frameworks, applying migrations is an "all or nothing" operation. If a developer unknowingly drops a column or changes a field type that truncates data, the first time they notice is usually when production data starts disappearing.

Framework M solves this by introspecting the live database and performing a dry-run comparison before any DDL is actually executed.

Core Concepts​

1. Introspection Adapters​

The engine is decoupled from specific database implementations through a Port/Adapter architecture.

  • Port (IntrospectionProtocol): Defines the contract for reading schema metadata (tables, columns, indexes).
  • Adapters: Concrete implementations that handle the low-level communication with the database. Framework M provides a default SQLAlchemy Adapter which is database-agnostic, but third-party packages (like MX-Mongo) can contribute their own engines.

This "Source of Truth" from the adapter is compared against your "Desired State" (the DocType blueprints in your code).

2. Risk Classification System​

Every detected difference is categorized into one of three risk levels:

🟢 SAFE (Non-Destructive)​

These changes can be applied without fear of data loss or service interruption.

  • Examples: Adding a new table, adding a nullable column, adding an index.
  • Action: Automatically applied in development; staged for review in production.

🟡 WARNING (Potentially Destructive)​

These changes might result in data truncation or require careful validation.

  • Examples: Shrinking a VARCHAR max length, changing a column to non-nullable without a default.
  • Action: Requires explicit confirmation in CLI and warns the user in the Studio UI.

🔴 BREAKING (Destructive)​

These changes will result in data loss or application crashes if not handled via Zero-Downtime Migration (ZDM) patterns.

  • Examples: Dropping a column, renaming a column, changing a data type (e.g., Integer to String).
  • Action: Blocked from automatic execution. Developers are directed to follow the ZDM Guide.

Visibility in the Stack​

This engine is exposed at multiple levels:

  • Studio Designer: Provides real-time feedback in the "Migration" tab as you modify fields.
  • CLI: The m migrate verify command allows developers to audit their changes before committing.
  • CI/CD: The risk engine can be used in PR checks to prevent dangerous migrations from reaching the main branch.