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
This commit is contained in:
Adam Coldrick 2017-10-09 20:41:56 +01:00
parent d0b595db25
commit 87ab62f396
3 changed files with 92 additions and 29 deletions

View File

@ -38,8 +38,15 @@ Installation guides
install/development
Migration guides
----------------
Maintenance guides
------------------
.. toctree::
:maxdepth: 1
maintenance/upgrading
Launchpad Migration guides
--------------------------
.. toctree::
:maxdepth 1

View File

@ -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 <start version>:<end version> --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.

View File

@ -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 <start version>:<end version> --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 \