Migrations

A project often undergoes changes related to database schema during course of its life. It may also be required patch existing data. Frappe bundles tools to handle these scenarios.

When you pull updates from any Frappe app (including Frappe), you should run bench migrate to apply schema changes and data migrations if any.

Schema changes

You can edit a DocType to add, remove or change fields. On saving a DocType, a JSON file containing the DocType data is added to source tree of your app. When you add an app to a site, the DocTypes are installed using this JSON file. For making schema changes, it's required to set developer_mode in the configuration.

On running a sync (bench migrate), doctypes in the system are synced to their latest version from the JSON files in the app.

Note: Fields are soft deleted ie. the columns are not removed from the database table and however, they will not be visible in the documents. This is done to avoid any potential data loss situations and to allow you write related data migrations which might need values from deleted fields.

Note: Frappe doesn't support reverse schema migrations.

Data Migrations

On introducing data related changes, you might want to run one off scripts to change existing data to match expectations as per new code.

To add a data migration to your code, you will have to write an execute function to a python module and add it to patches.txt of your app. Alternatively, you can create a new patch interactively by using following command:

$ bench create-patch
Select app for new patch (frappe, hrms, ecommerce_integrations, erpnext): frappe
Provide DocType name on which this patch will apply: User
Describe what this patch does: Improve Indexing
Provide filename for this patch [improve_indexing.py]:
Patch folder '/home/ankush/benches/develop/apps/frappe/frappe/core/doctype/user/patches' doesn't exist, create it? [Y/n]: y
Created /home/ankush/benches/develop/apps/frappe/frappe/core/doctype/user/patches/improve_indexing.py and updated patches.txt

It is recommended to make a file with a patch number and name in its path and add it to a patches package (directory) in your app. You can then add a line with dotted path to the patch module to patches.txt.

The directory structure followed in Frappe is as below

frappe
└── patches
    └── 4_0
        └── my_awesome_patch.py

The patch can be added to patches.txt by adding a line like

frappe.patches.4_0.my_awesome_patch

The metadata ie. DocType available in the execute function will be the latest as per JSON files in the apps. However, you will not be able to access metadata of any previous states of the system.

One off Python statements

You can also add one off python statements in patches.txt using the syntax, execute:{python statement}

For example, execute:frappe.get_doc("User", "Guest").save()

Note: All lines in patches.txt have to be unique. If you want to run a line twice, you can make it unique by adding a distinct comment.

For Example,

execute:frappe.installer.make_site_dirs() #2014-02-19