85 lines
3.9 KiB
Plaintext
85 lines
3.9 KiB
Plaintext
# 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
|