Validate database migrations and model

Database migrations and the database model are managed independently in Nova. When a new database migration is added, changes are often needed to the database model and vice versa. However, there are no tests or checks that the database model matches the results of the database migrations leaving them to often drift apart.

Problem description

  • Database migrations affect the correctness of the database model.

  • No tests or checks exist to ensure the database model matches the results of the database migrations.

Use Cases

Providing a consistent database model to implement the online-schema-changes spec.

Helping operators determine when local changes to their running schema differs from the Nova model.

Project Priority

This is a dependency for another spec that fits under the ‘Live Upgrades’ kilo priorities.

Proposed change

A new unit test would be added that uses alembic to compare the result of the database migrations wit the database model defined in nova/db/sqlalchemy/

A new ‘db compare’ command to nova-manage would allow an operator to list the differences between their running database and the database model defined in nova.


Using the database model as a single source for all schema changes. This would avoid any drift between database migrations and the database model by generating DDL dynamically based on a comparison between the running schema and the model.

This option is the original goal, but it was decided that it would be best to split the spec into two parts: validating the schema against the model and then dynamically updating the schema to match the model. See the dependent spec online-schema-changes.

Data model impact

The existing model needs to be brought in line with changes migrations make. These are limited to a handful of cases:

  • PostgreSQL index name limitations

  • PostgreSQL Enum type naming

  • MySQL index length restrictions

  • Foreign key names

REST API impact


Security impact


Notifications impact


Other end user impact


Performance Impact

The new unit test is expected to add only a fraction of a second to the total time it takes to run tests.

Other deployer impact

The new ‘db compare’ command to nova-manage provides a means of viewing differences between the current running schema and Nova’s model.

Developer impact

Since the model will now be checked against the results of the database migrations, it is required to keep the model updated.



Primary assignee:


Other contributors:


Work Items

  • Bring model into line with existing migrations

  • Implement schema comparator

  • Implement new ‘db compare’ command to ‘nova-manage’


The schema synchronizer is implemented on top of alembic for its DDL generating functionality. This is already in the OpenStack global requirements list, but will be a new addition for Nova.


No extra tests beyond the added unit test.

Documentation Impact

Documentation will need to be updated to include the new ‘db compare’ command to ‘nova-manage’.