use fietsupdate in documentation about backups

This should be preferred over dealing with raw alembic now.

2 files changed, 59 insertions, 9 deletions

diff --git a/doc/administration/backup.rst b/doc/administration/backup.rst
index 3973298..fb379bc 100644
--- a/doc/administration/backup.rst
+++ b/doc/administration/backup.rst
@@ -34,20 +34,36 @@ In addition to the actual data, you should also note down the Fietsboek version
 and the database schema version, as backups can only be restored to the same
 version!
 
-To view the fietsboek version in case you are using ``git``, you can use the
+To view the Fietsboek version in case you are using ``git``, you can use the
 following command:
 
 .. code:: bash
 
     git rev-parse HEAD
 
+If you installed Fietsboek via ``pip`` or other means, you can use one of the
+following to see the version:
+
+.. code:: bash
+
+    .venv/bin/pip show fietsboek
+    .venv/bin/fietsctl version
+
+To view the data version, use ``fietsupdate``:
+
+.. code:: bash
+
+    .venv/bin/fietsupdate status -c development.ini
+
 To view the database schema version, use ``alembic``:
 
 .. code:: bash
 
     .venv/bin/alembic -c development.ini current
 
-Note those value in addition to your backup.
+Note those values (Fietsboek version, data version, database schema version) in
+addition to your backup, as you will need them when restoring data later or
+when troubleshooting the restoration process.
 
 Restore
 -------
@@ -55,17 +71,31 @@ Restore
 The restoration process works in four steps:
 
 First, we ensure that we are on the correct Fietsboek version. If you are using
-``git``, this can be done with ``git checkout``:
+``git``, this can be done with ``git checkout`` before installing it:
 
 .. code:: bash
 
     git checkout NOTED_GIT_VERSION_HERE
 
-Then, we get the database schema to the right version:
+If you have installed Fietsboek via ``pip``, you can use it to request a
+specific version:
 
 .. code:: bash
 
-    .venv/bin/alembic -c production.ini upgrade NOTED_ALEMBIC_VERSION_HERE
+    .venv/bin/pip install "fietsboek==vX.Y.Z"
+
+Next, we run the data migrations:
+
+.. code:: bash
+
+    .venv/bin/fietsupdate update -c development.ini VERSION_FROM_EARLIER
+
+We can verify that the database has the correct schema version by using the
+same command from earlier and comparing its output to the noted value:
+
+.. code:: bash
+
+    .venv/bin/alembic -c development.ini current
 
 Now, we can restore the data in the database. This step is dependent on the
 DBMS that you, therefore you should consult its documentation.
diff --git a/fietsboek/scripts/fietsctl.py b/fietsboek/scripts/fietsctl.py
index bd37987..efe22c2 100644
--- a/fietsboek/scripts/fietsctl.py
+++ b/fietsboek/scripts/fietsctl.py
@@ -7,7 +7,7 @@ import sys
 from pyramid.paster import bootstrap, setup_logging
 from sqlalchemy import select
 
-from .. import models
+from .. import models, __VERSION__
 
 
 EXIT_OKAY = 0
@@ -136,6 +136,12 @@ def cmd_passwd(env, args):
         return EXIT_OKAY
 
 
+def cmd_version():
+    """Show the installed fietsboek version."""
+    name = __name__.split(".")[0]
+    print(f"{name} {__VERSION__}")
+
+
 def parse_args(argv):
     """Parse the given args.
 
@@ -150,11 +156,17 @@ def parse_args(argv):
         "--config",
         dest="config_uri",
         help="configuration file, e.g., development.ini",
-        required=True,
     )
 
     subparsers = parser.add_subparsers(help="available subcommands", required=True)
 
+    p_version = subparsers.add_parser(
+        "version",
+        help="show the version",
+        description=cmd_version.__doc__,
+    )
+    p_version.set_defaults(func=cmd_version)
+
     p_useradd = subparsers.add_parser(
         "useradd",
         help="create a new user",
@@ -234,14 +246,22 @@ def parse_args(argv):
     )
     p_passwd.set_defaults(func=cmd_passwd)
 
-    return parser.parse_args(argv[1:])
+    return parser.parse_args(argv[1:]), parser
 
 
 def main(argv=None):
     """Main entry point."""
     if argv is None:
         argv = sys.argv
-    args = parse_args(argv)
+    args, parser = parse_args(argv)
+
+    if args.func == cmd_version:
+        cmd_version()
+        sys.exit(EXIT_OKAY)
+
+    if not args.config_uri:
+        parser.error("the following arguments are required: -c/--config")
+
     setup_logging(args.config_uri)
     env = bootstrap(args.config_uri)