Introduction: What Are Database Migrations in Frappe?
Database migrations in Frappe are the controlled process of updating a site’s database schema, data, and metadata to match the current state of installed apps and framework code.
In Frappe Framework v15, migrations ensure that changes such as new DocFields, modified DocTypes, patches, and fixtures are safely applied to existing sites without data loss.
Migrations are mandatory after:
- App updates
- Framework upgrades
- Installing or removing apps
- Pulling new code changes
Why Are Migrations Required?
Migrations keep the database and codebase in sync.
They ensure:
- New fields and DocTypes are created
- Schema changes are applied correctly
- Data patches run in the correct order
- Metadata is refreshed for Desk and backend usage
Without migrations, Frappe sites may break due to schema mismatches or missing data updates.
How Frappe Migration Works (High-Level Flow)
When a migration is triggered, Frappe performs the following steps internally:
- Loads installed apps for the site
- Applies schema changes for DocTypes
- Executes pending patches
- Syncs fixtures and customizations
Clears caches and rebuilds metadata
This entire process is orchestrated through the bench migrate command.
How to Run Database Migrations in Frappe v15
How to Run Migration for a Specific Site
Answer:
Use the bench migrate command.
bench migrate
This command applies all pending migrations for the current site configured in the bench.
How to Migrate a Specific Site Explicitly
bench --site sitename.local migrate
This is recommended in multi-site environments to avoid unintended migrations.
What Happens During bench migrate?
During migration, Frappe executes several internal processes in a strict order:
Schema Synchronization
DocType JSON definitions are compared with database tables, and missing or modified columns are created or updated.
Patch Execution
All unapplied patches listed in app patches.txt files are executed sequentially and recorded in the Patch Log.
Fixture Sync
Fixtures such as Custom Fields, Property Setters, and Custom Scripts are imported.
Metadata Reload
Desk metadata is refreshed to reflect schema and UI changes.
Understanding Patches in Frappe v15
What Is a Patch in Frappe?
A patch is a Python script that performs one-time data or logic changes during migration.
Patches are defined in:
app_name/patches.txt
Each patch runs only once per site and is tracked internally.
When Should You Use a Patch?
Use patches when:
- Updating existing data
- Migrating values between fields
- Fixing legacy inconsistencies
- Introducing non-schema changes
Schema changes should always be handled through DocType updates, not patches.
How Frappe Tracks Migration State
Frappe maintains migration state using internal DocTypes:
Patch Log – Tracks executed patches
Installed Applications – Tracks app versions
DocType Metadata – Tracks schema state
This ensures migrations are idempotent and safe to re-run.
Best Practices for Running Migrations
Always take a database backup
Before running migrations on production, ensure a full MariaDB backup exists.
Run migrations in staging first
Test migrations on a staging environment before applying to live systems.
Avoid editing database directly
All schema changes must go through DocType definitions or patches.
Do not interrupt migrations
Stopping migrations mid-process can corrupt schema or metadata.
Common Migration Issues and Troubleshooting
Migration fails due to patch error
- Check traceback output
- Fix patch logic
- Re-run bench migrate after correction
Column already exists error
- Indicates manual DB changes or inconsistent schema
- Compare DocType JSON with database table
Site stuck in partial migration
- Restore backup
- Re-run migration cleanly
Advanced Topics: Multi-App and Multi-Site Migrations
In environments with multiple apps:
- Migrations run app-by-app
- Patch order follows app installation order
- Each site maintains its own migration state
For multi-site benches, always specify the site explicitly.
Industry Relevance and Use Cases
Who benefits from understanding migrations?
- ERPNext implementers
- Frappe developers
- DevOps engineers
- System administrators managing upgrades
Migrations are critical during ERPNext version upgrades, hotfix deployments, and continuous delivery pipelines.
Technical Prerequisites
- Frappe Framework Version 15
- MariaDB configured and accessible
- Bench environment properly set up
- Background workers stopped during major upgrades (recommended)
Related Documentation
- App Installation in Frappe
- Bench Commands Reference
- Patches and Fixtures
- Custom Fields and Property Setters
(Refer only to official Frappe v15 documentation.)
Conclusion
Database migrations in Frappe Framework v15 are a core mechanism that ensures system stability, data integrity, and seamless upgrades. By understanding how migrations, patches, and schema sync work, developers and administrators can confidently manage production systems and avoid costly downtime.
For any serious ERPNext or Frappe deployment, mastering migrations is non-negotiable.
