---
upgrade:
  - |
    The database migration engine has changed from `sqlalchemy-migrate`__ to
    `alembic`__. For most deployments, this should have minimal to no impact
    and the switch should be mostly transparent. The main user-facing impact is
    the change in schema versioning. While sqlalchemy-migrate used a linear,
    integer-based versioning scheme, which required placeholder migrations to
    allow for potential migration backports, alembic uses a distributed version
    control-like schema where a migration's ancestor is encoded in the file and
    branches are possible. The alembic migration files therefore use a
    arbitrary UUID-like naming scheme and the ``keystone-manage db_version``
    command returns such a version.

    When the ``keystone-manage db_sync`` command is run without options or
    with the ``--expand`` or ``--contract`` options, all remaining
    sqlalchemy-migrate-based migrations will be automatically applied.

    Data migrations are now included in the expand phase and the ``--migrate``
    option is now a no-op. It may be removed in a future release.

    .. __: https://sqlalchemy-migrate.readthedocs.io/en/latest/
    .. __: https://alembic.sqlalchemy.org/en/latest/