====================================================
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.