Migrations de base de données

Le mode développeur enregistre le JSON du DocType. migrate lance les hooks, les patches, puis synchronise schéma, tâches, fixtures et traductions.

2 min de lectureMis à jour le 5 octobre 2026Source : docs.frappe.io

Commande

Les changements de schéma et les corrections de données passent par le système de migration. Après un changement dans l’application :

terminal

bench --site [sitename] migrate

Le détail de la commande est dans bench migrate. Les fichiers patches.txt sont aussi décrits dans Migrations.

Schéma

On édite le DocType pour ajouter, retirer ou changer des champs. À l’enregistrement, un JSON rejoint l’arbre de l’application. À l’installation, les tables naissent de ce JSON. Il faut le mode développeur.

migrate amène chaque application à sa version courante. D’abord le hook before_migrate, qui synchronise les droits. Puis les patches. Ensuite : schéma, tâches de fond, fixtures, tableaux de bord, icônes du bureau et pages web, traductions, index de recherche de toutes les routes. Enfin le hook after_migrate.

Pour chaque DocType, le hash MD5 du JSON est comparé à celui stocké. S’il diffère, le DocType est rechargé. Jusqu’à la v13, la synchro utilisait l’horodatage du JSON, méthode jugée fragile. Le passage au hash est celui de la pull request 14246.

Retirer ou renommer un champ ne supprime pas la colonne. Elle disparaît du formulaire, pour éviter une perte et pour qu’un patch puisse encore lire l’ancienne valeur. Frappe ne fait pas de migration de schéma inverse.

Patches

Un patch est un script Python avec une méthode execute, déclaré dans patches.txt. La convention est un paquet patches, par exemple frappe/patches/v12_0/my_awesome_patch.py, et la ligne frappe.patches.v12_0.my_awesome_patch.

Dans execute, la meta est encore celle de l’ancien JSON, pour écrire en supposant les anciens champs. Le nouveau schéma s’applique après le patch. Pour l’avoir pendant l’exécution : frappe.reload_doc(module_name, "doctype", doctype_name).

Depuis la v14 et la branche develop, patches.txt accepte des sections. [pre_model_sync] tourne avant la synchro des modèles. [post_model_sync] tourne après : inutile d’y recharger les DocTypes, ils le sont déjà.

Une ligne execute: lance une instruction isolée, par exemple execute:frappe.delete_doc('Page', 'applications', ignore_missing=True).

L’ordre est celui du fichier. Chaque ligne doit être unique. Un patch déjà passé ne repasse pas. Pour le relancer, un commentaire rend la ligne nouvelle, par exemple #2019-09-08.

Point d’attention

Une colonne retirée du formulaire est encore en base. Un patch qui a déjà une ligne identique dans patches.txt est ignoré.