===============
solum-db-manage
===============

.. program:: solum-db-manage

SYNOPSIS
========
``solum-db-manage <action> [options]``

DESCRIPTION
===========
solum-db-manage helps manage solum specific database operations.

The migrations in the "alembic_migrations/versions/" directory contain
the changes needed to migrate from older Solum 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 Solum's migration wrapper
which uses the Alembic library to manage the migration.


OPTIONS
=======

The standard pattern for executing a solum-db-manage command is:

``solum-db-manage <command> [<args>]``

Run with -h to see a list of available commands:

``solum-db-manage -h``

Commands are:
 * version
 * upgrade
 * downgrade
 * stamp
 * revision

Detailed descriptions are below.


Upgrading/Downgrading
~~~~~~~~~~~~~~~~~~~~~

If you are a deployer or developer and want to migrate from Icehouse to Juno
or later you must first add version tracking to the database:

``solum-db-manage stamp icehouse``

You can then upgrade to the latest database version via:

``solum-db-manage upgrade head``

To check the current database version:

``solum-db-manage version``

Downgrade the database to a specific revision:

``solum-db-manage downgrade 594288b1585a``


Generating migration templates (developers only)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A database migration script is required when you submit a change to Solum
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 solum-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.

``solum-db-manage 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:

``solum-db-manage revision -m "description of revision"``

FILES
=====

The /etc/solum/solum.conf file contains global options which can be
used to configure some aspects of solum-db-manage, for example the DB
connection and logging.

BUGS
====

Solum issues are tracked in Launchpad so you can view or report bugs here:
  `OpenStack Solum Bugs <https://bugs.launchpad.net/solum>`__
