neutron/doc/source/admin/migration-database.rst

Database

The upgrade of the Networking service database is implemented with Alembic migration chains. The migrations in the alembic/versions contain the changes needed to migrate from older Networking service releases to newer ones.

Since Liberty, Networking maintains two parallel Alembic migration branches.

The first branch is called expand and is used to store expansion-only migration rules. These rules are strictly additive and can be applied while the Neutron server is running.

The second branch is called contract and is used to store those migration rules that are not safe to apply while Neutron server is running.

The intent of separate branches is to allow invoking those safe migrations from the expand branch while the Neutron server is running and therefore reducing downtime needed to upgrade the service.

A database management command-line tool uses the Alembic library to manage the migration.

Database management command-line tool

The database management command-line tool is called neutron-db-manage. Pass the --help option to the tool for usage information.

The tool takes some options followed by some commands:

$ neutron-db-manage <options> <commands>

The tool needs to access the database connection string, which is provided in the neutron.conf configuration file in an installation. The tool automatically reads from /etc/neutron/neutron.conf if it is present. If the configuration is in a different location, use the following command:

$ neutron-db-manage --config-file /path/to/neutron.conf <commands>

Multiple --config-file options can be passed if needed.

Instead of reading the DB connection from the configuration file(s), you can use the --database-connection option:

$ neutron-db-manage --database-connection
  mysql+pymysql://root:secret@127.0.0.1/neutron?charset=utf8 <commands>

The branches, current, and history commands all accept a --verbose option, which, when passed, will instruct neutron-db-manage to display more verbose output for the specified command:

$ neutron-db-manage current --verbose

Note

The tool usage examples below do not show the options. It is assumed that you use the options that you need for your environment.

In new deployments, you start with an empty database and then upgrade to the latest database version using the following command:

$ neutron-db-manage upgrade heads

After installing a new version of the Neutron server, upgrade the database using the following command:

$ neutron-db-manage upgrade heads

In existing deployments, check the current database version using the following command:

$ neutron-db-manage current

To apply the expansion migration rules, use the following command:

$ neutron-db-manage upgrade --expand

To apply the non-expansive migration rules, use the following command:

$ neutron-db-manage upgrade --contract

To check if any contract migrations are pending and therefore if offline migration is required, use the following command:

$ neutron-db-manage has_offline_migrations

Note

Offline migration requires all Neutron server instances in the cluster to be shutdown before you apply any contract scripts.

To generate a script of the command instead of operating immediately on the database, use the following command:

$ neutron-db-manage upgrade heads --sql

.. note::

   The `--sql` option causes the command to generate a script.  The script
   can be run later (online or offline), perhaps after verifying and/or
   modifying it.

To migrate between specific migration versions, use the following command:

$ neutron-db-manage upgrade <start version>:<end version>

To upgrade the database incrementally, use the following command:

$ neutron-db-manage upgrade --delta <# of revs>

Note

Database downgrade is not supported.

To look for differences between the schema generated by the upgrade command and the schema defined by the models, use the revision --autogenerate command:

neutron-db-manage revision -m REVISION_DESCRIPTION --autogenerate

Note

This generates a prepopulated template with the changes needed to match the database state with the models.