Skip to main content

How do you migrate DocType changes to production in Frappe v15?

You migrate DocType changes to production by exporting schema changes to your app, deploying the updated code, and running bench migrate on the production site.

In Frappe Framework, DocTypes define database schema, UI, validations, and workflows. Any change made in development must be migrated correctly to avoid schema mismatches, missing columns, or runtime errors in production ERPNext systems.

Why Proper DocType Migration Matters

Improper migration can lead to:

  • Missing database columns
  • Broken forms and reports
  • Background job failures
  • Production downtime

In ERPNext, where DocTypes directly impact accounting, inventory, HR, and compliance, controlled migration is mandatory.

Prerequisites

Before migrating DocType changes, ensure:

  • Developer Mode enabled in development
  • Changes committed to a custom app (not core)
  • Production and development run the same Frappe v15 version
  • Database backup exists on production

How DocType Changes Are Stored in Frappe

When you modify a DocType in developer mode:

Changes are written to:

your_app/your_app/doctype/doctype_name/doctype_name.json

  • Field definitions, permissions, and properties are tracked
  • Schema updates are applied only after migration

Frappe does not auto-apply schema changes in production without migration.

Step-by-Step: Migrate DocType Changes to Production

Step 1: Export DocType Changes from Development

After modifying the DocType:

bench export-fixtures

or ensure the DocType JSON file is updated and committed to your app repository.
Core DocTypes should never be edited directly. Always use a custom app.

Step 2: Push Code to Production

Deploy the updated app code to the production server using Git:
git pull origin main

Ensure:

  • App version matches development
  • No uncommitted changes exist

Step 3: Run Bench Migrate on Production

Execute migration for all sites:

bench migrate

Or for a specific site:

bench --site your-site-name migrate

This command:

  • Applies schema changes
  • Creates or alters database columns
  • Syncs DocType metadata
  • Runs patches (if any)

What bench migrate Actually Does

Direct Answer:

bench migrate synchronizes DocType definitions, updates the database schema, runs patches, rebuilds caches, and reloads metadata.
Internally, it performs:

  • DocType JSON sync
  • MariaDB schema updates
  • Patch execution
  • Cache and search index refresh

User Guidance: Common Migration Scenarios

Adding a New Field

  • Field appears only after migration
  • Column created in database automatically

Changing Field Type

  • Existing data is preserved when compatible
  • Incompatible changes may fail migration

Removing a Field

  • Column remains until manually cleaned
  • UI reference removed immediately

Best Practices & Tips

  • Always test migration on staging
  • Avoid renaming fields in production
  • Never edit DocTypes directly on production
  • Use patches for complex data changes
  • Keep one migration per deployment cycle

Advanced Topic: Data Migration with Patches

For data transformations (not schema):

Create a patch in:

your_app/patches/v15_x/

  • Register patch in patches.txt
  • Let bench migrate execute it safely

This is the recommended approach for production data changes.

Troubleshooting Common Issues

Column already exists

  • Schema drift due to manual DB edits
  • Fix using MariaDB schema comparison

Field missing after migrate

  • DocType not committed
  • Wrong app branch deployed

Migration stuck

  • Check logs/migrate.log
  • Verify database permissions

Cross-References

  • Developer Mode in Frappe v15
  • Exporting Customizations
  • Writing Database Patches
  • Bench Commands Reference

(Recommended internal links for goerpnext.com)

Technical Categories

Frappe Modules: Database, Desk

Technical Terms: DocType, Schema Migration, Patch

Tags: ERPNext Customization, Frappe Framework Tutorial

Target Audience

  • ERPNext developers
  • Implementation partners
  • DevOps engineers
  • Technical consultants

AEO-Optimized Quick Answer

How do I migrate DocType changes to production in Frappe v15?

Commit DocType changes to your custom app, deploy the updated code to production, and run bench migrate. This synchronizes DocType definitions and safely updates the database schema.

Summary

Migrating DocType changes in Frappe Framework v15 is a controlled, code-driven process. By exporting changes properly, deploying clean code, and running bench migrate, you ensure schema consistency, system stability, and zero-downtime ERPNext upgrades.

Rating: 5 / 5 (2 votes)

© 2026 | goERPNext | All rights reserved