# Copyright 2012 New Dream Network, LLC (DreamHost)
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.

The migrations in the alembic_migrations/versions contain the changes needed
to migrate from older storyboard releases to newer versions. A migration occurs
by executing a script that details the changes needed to upgrade/downgrade
the database. The migration scripts are ordered so that multiple scripts
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 \
    load_projects /path/to/projects.yaml


DEVELOPERS:
A database migration script is required when you submit a change to storyboard
that alters the database model definition.  The migration script is a special
python file that includes code to update/downgrade the database to match the
changes in the model definition. Alembic will execute these scripts in order to
provide a linear migration path between revision. The storyboard-db-manage
command can be used to generate migration template for you to complete.  The
operations in the template are those supported by the Alembic migration library.

$ storyboard-db-manage --config-file /path/to/storyboard.conf \
    revision -m "description of revision" --autogenerate

This generates a prepopulated template with the changes needed to match the
database state with the models.  You should inspect the autogenerated template
to ensure that the proper models have been altered.

In rare circumstances, you may want to start with an empty migration template
and manually author the changes necessary for an upgrade/downgrade.  You can
create a blank file via:

$ storyboard-db-manage --config-file /path/to/storyboard.conf \
    revision -m "description of revision"

The migration timeline should remain linear so that there is a clear path when
upgrading/downgrading.  To verify that the timeline does branch, you can run
this command:
$ storyboard-db-manage --config-file /path/to/storyboard.conf check_migration

If the migration path does branch, you can find the branch point via:
$ storyboard-db-manage --config-file /path/to/storyboard.conf history