From 11768581cbe71a1eaf197204b6362d07da4d6c49 Mon Sep 17 00:00:00 2001 From: Daniel Schadt Date: Mon, 19 Dec 2022 21:36:05 +0100 Subject: use fietsupdate in documentation about backups This should be preferred over dealing with raw alembic now. --- doc/administration/backup.rst | 40 +++++++++++++++++++++++++++++++++++----- fietsboek/scripts/fietsctl.py | 28 ++++++++++++++++++++++++---- 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) -- cgit v1.2.3