From 87ab62f3960f86255345171a26251564a506888b Mon Sep 17 00:00:00 2001 From: Adam Coldrick Date: Mon, 9 Oct 2017 20:41:56 +0100 Subject: [PATCH] Add documentation on manually upgrading a StoryBoard instance Sometimes it is necessary to upgrade the database of a manually deployed StoryBoard instance, for example when updating a test server being used for development. This commit adds some documentation on how the `storyboard-db-manage` command-line tool can be used to upgrade and downgrade the database. Change-Id: I0ac21ddc3bacac7105efda7258e7ae52818f8f69 --- doc/source/index.rst | 13 ++++- doc/source/maintenance/upgrading.rst | 82 ++++++++++++++++++++++++++++ storyboard/db/migration/README | 26 --------- 3 files changed, 92 insertions(+), 29 deletions(-) create mode 100644 doc/source/maintenance/upgrading.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 79dedf2f..60e6bae8 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -38,13 +38,20 @@ Installation guides install/development -Migration guides ----------------- +Maintenance guides +------------------ +.. toctree:: + :maxdepth: 1 + + maintenance/upgrading + +Launchpad Migration guides +-------------------------- .. toctree:: :maxdepth 1 migration - + Developer docs -------------- diff --git a/doc/source/maintenance/upgrading.rst b/doc/source/maintenance/upgrading.rst new file mode 100644 index 00000000..e5088b7f --- /dev/null +++ b/doc/source/maintenance/upgrading.rst @@ -0,0 +1,82 @@ +==================================================== +Manually Upgrading/Downgrading a StoryBoard Instance +==================================================== + +If you have a manually deployed StoryBoard instance, for example a local +server for development, you may sometimes need to upgrade the database as +new changes are merged upstream. + +Similarly, you may wish to rollback a change to for testing purposes. This +guide will explain how you can use the ``storyboard-db-manage`` tool to +upgrade and downgrade your database schema. + +If using ``tox``, all commands in this guide should be run as :: + + $ tox -e venv -- $command + +You may find you need to prepend ``sudo`` to this command. + + +Checking the current version +============================ + +If you don't know what version your database is currently, you can check it +with:: + + $ storyboard-db-manage --config-file /path/to/storyboard.conf current + + +Upgrading the database +====================== + +If your existing database version is currently < 049, you are advised to +run the upgrade command using commit ``acce431b30a32497064ad6d1ab3872358e1e60dc`` +of the storyboard repository, since after that the migrations were consolidated +and will no longer work with existing databases older than version 049. + +You can upgrade to the latest database version in-place with the following +command:: + + $ storyboard-db-manage --config-file /path/to/storyboard.conf upgrade head + +Replacing ``head`` in this command allows you to specify a target version. For +example, this command will upgrade to version 055:: + + $ storyboard-db-manage --config-file /path/to/storyboard.conf upgrade 055 + +It is also possible to create an sql script to upgrade the database offline:: + + $ storyboard-db-manage --config-file /path/to/storyboard.conf upgrade head --sql + +Additionally, you can generate a script to upgrade between two versions with:: + + $ storyboard-db-manage --config-file /path/to/storyboard.conf \ + upgrade : --sql + +You can also upgrade the database incrementally, by specifying the number of +revisions to apply:: + + $ storyboard-db-manage --config-file /path/to/storyboard.conf \ + upgrade --delta <# of revs> + + +Downgrading the database +======================== + +If you need to downgrade to a version > 001 and < 049, you will need to first +downgrade to version 049, then use commit ``acce431b30a32497064ad6d1ab3872358e1e60dc`` +to downgrade further to the version you require. After this commit, the +migrations lower than 049 were consolidated and can no longer be used +individually. + +Downgrade the database by a certain number of revisions:: + + $ storyboard-db-manage --config-file /path/to/storyboard.conf \ + downgrade --delta <# of revs> + +You can also downgrade to a specific version:: + + $ storyboard-db-manage --config-file /path/to/storyboard.conf downgrade 055 + +Similar to upgrading, you can use the ``--sql`` flag to generate an sql script +to be applied later. diff --git a/storyboard/db/migration/README b/storyboard/db/migration/README index 0fa969ff..50d48263 100644 --- a/storyboard/db/migration/README +++ b/storyboard/db/migration/README @@ -20,32 +20,6 @@ can run sequentially to update the database. The scripts are executed by storyboard's migration wrapper which uses the Alembic library to manage the migration. -If your existing database version is currently < 049, you are advised to -run the upgrade command using commit `acce431b30a32497064ad6d1ab3872358e1e60dc` -of this repository, since after that the migrations were consolidated and -will no longer work with existing databases older than version 049. - -You can upgrade to the latest database version via: -$ storyboard-db-manage --config-file /path/to/storyboard.conf upgrade head - -To check the current database version: -$ storyboard-db-manage --config-file /path/to/storyboard.conf current - -To create a script to run the migration offline: -$ storyboard-db-manage --config-file /path/to/storyboard.conf upgrade head --sql - -To run the offline migration between specific migration versions: -$ storyboard-db-manage --config-file /path/to/storyboard.conf \ - upgrade : --sql - -Upgrade the database incrementally: -$ storyboard-db-manage --config-file /path/to/storyboard.conf \ - upgrade --delta <# of revs> - -Downgrade the database by a certain number of revisions: -$ storyboard-db-manage --config-file /path/to/storyboard.conf \ - downgrade --delta <# of revs> - This utility should be also used to load Project Groups and Projects form a .yaml file description. The description sample is provided in etc/projects.yaml. $ storyboard-db-manage --config-file /path/to/storyboard.conf \