diff options
author | Daniel Schadt <kingdread@gmx.de> | 2022-10-20 21:49:47 +0200 |
---|---|---|
committer | Daniel Schadt <kingdread@gmx.de> | 2022-10-20 21:49:47 +0200 |
commit | 16216e721e0ecd981f9f30443b89d01033cdf63e (patch) | |
tree | ccae50772e87eb51d27ad3630cd9fded83181211 /doc/administration/upgrading.rst | |
parent | aa7ffe837fe5e0739c32a633d2d02544ca5d72ba (diff) | |
download | fietsboek-16216e721e0ecd981f9f30443b89d01033cdf63e.tar.gz fietsboek-16216e721e0ecd981f9f30443b89d01033cdf63e.tar.bz2 fietsboek-16216e721e0ecd981f9f30443b89d01033cdf63e.zip |
adjust docs for new updater script
Diffstat (limited to 'doc/administration/upgrading.rst')
-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! |