Skip to main content

ADR 0011: Modular and Decentralized Migration System

Status​

Accepted

Context​

Framework M aims to support "Modular Monoliths" and high-scale distributed applications. Developers coming from Frappe expect a "Declarative/Sync" experience (where the database matches the code), while enterprise production environments require "Imperative/Migration" control (where patches are ordered and verified).

Previously, migrations were centralized in a single alembic/versions directory, which made it difficult to manage migrations for third-party or modular apps.

Decision​

We decided to implement a Dual-Track, Decentralized Migration System.

1. Dual-Track Strategy​

  • Sync Track (m migrate sync): A declarative auto-sync mechanism that compares current DocTypes with the database schema and applies changes directly. Supports before_sync and after_sync hooks in each app.
  • Migrate Track (m migrate run): An imperative version-based system using Alembic. Each app maintains its own alembic/versions directory.
  • Unified Command (m migrate all): A safe default that runs all pending migrations (run track) followed by the declarative sync.

2. Decentralized Version Locations​

Alembic is configured to scan multiple version_locations by merging paths from all INSTALLED_APPS. Each app's migrations/versions (or alembic/versions) folder is automatically included.

3. Smart App Discovery​

The system uses importlib.metadata entry points (group framework_m.apps) to discover modular apps. This eliminates the need for manual registration in a central configuration file.

Consequences​

  • Pros:
    • "It just works" experience for developers via m migrate sync.
    • Production safety via m migrate run for data patches.
    • True modularity: Apps are self-contained with their own migrations.
    • Zero-downtime deployment patterns are natively supported.
  • Cons:
    • Increased complexity in the env.py and MigrationManager orchestration.
    • Developers must understand the difference between a "sync" and a "run".

References​