diff options
| -rw-r--r-- | doc/administration/upgrading.rst | 75 |
1 files changed, 72 insertions, 3 deletions
diff --git a/doc/administration/upgrading.rst b/doc/administration/upgrading.rst index 4bdc656..9d19f90 100644 --- a/doc/administration/upgrading.rst +++ b/doc/administration/upgrading.rst @@ -53,15 +53,84 @@ Upgrading the Database is your last chance. Some updates might change the database schema. Those updates come with database -migrations that can adapt an existing database to the new schema. In order to -do so, use ``alembic``: +migrations that can adapt an existing database to the new schema. In addition +to database migrations, some updates also modify the on-disk data that +Fietsboek stores. + +Fietsboek comes with a handy tool that allows you to run the right database and +file migrations: ``fietsupdate``. + +You can use the following command to upgrade to the latest installed version: .. code:: bash - .venv/bin/alembic -c production.ini upgrade head + .venv/bin/fietsupdate update -c production.ini + +Or you can view the status of your installation: + +.. code:: bash + + .venv/bin/fietsupdate status -c production.ini + +.. note:: + + The ``fietsupdate`` tool is only there to run database migrations and other + update tasks. It does *not* retrieve or install the correct code, please + see the above sections to do that. Restarting Fietsboek -------------------- You can now run Fietsboek again. This step depends on the method that you use to deploy Fietsboek. + +Downgrading +=========== + +In some cases, it might be required that you uninstall an update to Fietsboek, +for example if it introduced a bug. Downgrading is possible and generally +consists of two steps: + +1) Restore the old data format (backwards migration) +2) Restore the old code + +.. warning:: + + As with updates, make sure you have backups of your important data ready! + +Restoring Data: Backups +----------------------- + +The preferred way to use the old data is by restoring a backup, see +:doc:`backup`. This method ensures that your data is original and prevents the +upgrade/downgrade process from inducing errors. + +Restoring Data: Downgrading +--------------------------- + +If you do not have old backups of your data, you can use ``fietsupdate`` to +convert your data from the new format to the old one. Please note that the +upgrade process can not always be undone: If an update deletes data, even the +downgrade cannot fix it. In such cases, the only way to restore the data is +through a backup. + +To use ``fietsupdate`` to downgrade your data, run the following command, +replacing ``VERSION`` with the version you want to downgrade to: + +.. code:: bash + + .venv/bin/fietsupdate downgrade -c production.ini VERSION + +Restoring Code +-------------- + +Now that the data has been restored to the old state, you need to restore the +Fietsboek code to the old version. This works similarly to the update, with the +difference that you should download and install the version of Fietsboek that +you downgraded your data to. + +If you use ``git``, you can check out old versions of the code by using ``git +checkout``. + +After obtaining the old code, don't forget to install it into your virtual +environment! |