From d170f41d3b1c47d6807c87d50f37e37f713fa4d7 Mon Sep 17 00:00:00 2001 From: Baptiste Jonglez Date: Thu, 23 Apr 2020 23:34:30 +0200 Subject: [PATCH] Improve documentation regarding database migrations --- docs/contributing.rst | 25 ++++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index c88d0c35..27f890b3 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -48,21 +48,36 @@ In case you want to update to newer versions (from Git), you can just run the "u Create database migrations -------------------------- -In case you need to modify the database schema, first update the models in -``ihatemoney/models.py``. Then run the following command to create a new -database revision file:: +In case you need to modify the database schema, first make sure that you have +an up-to-date database by running the dev server at least once (the quick way +or the hard way, see above). The dev server applies all existing migrations +when starting up. + +You can now update the models in ``ihatemoney/models.py``. Then run the following +command to create a new database revision file:: make create-database-revision If your changes are simple enough, the generated script will be populated with -the necessary migrations steps. You can edit the generated script. e.g: To add -data migrations. +the necessary migrations steps. You can view and edit the generated script, which +is useful to review that the expected model changes have been properly detected. +Usually the auto-detection works well in most cases, but you can of course edit the +script to fix small issues. You could also edit the script to add data migrations. + +When you are done with your changes, don't forget to add the migration script to +your final git commit! + +If the migration script looks completely wrong, remove the script and start again +with an empty database. The simplest way is to remove or rename the dev database +located at ``/tmp/ihatemoney.db``, and run the dev server at least once. For complex migrations, it is recommended to start from an empty revision file which can be created with the following command:: make create-empty-database-revision +You then need to write the migration steps yourself. + Useful settings ----------------