diff --git a/specs/no-downward-sql-migration.rst b/specs/no-downward-sql-migration.rst new file mode 100644 index 0000000..84809c7 --- /dev/null +++ b/specs/no-downward-sql-migration.rst @@ -0,0 +1,92 @@ +======================================== + No More Downward SQL Schema Migrations +======================================== + +SQL Migrations are the accepted method for OpenStack projects to ensure +that a given schema is consistent across deployments. Often these +migrations include updating of the underlying data as well as +modifications to the schema. It is inadvisable to perform a downwards +migration in any environment. + + +Problem description +=================== + +Best practices state: when reverting post schema migration the +correct course is to restore to a known-good state of the database. + +Many migrations in OpenStack include data-manipulation to ensure the data +conforms to the new schema; often these data-migrations are difficult or +impossible to reverse without significant overhead. Performing a downgrade +of the schema with such data manipulation can lead to inconsistent or +broken state. The possibility of bad-states, relatively minimal testing, +and no demand for support renders a downgrade of the schema an unsafe +action. + +Proposed change +=============== + +The proposed change is as follows: + +* Eliminate the downgrade option(s) from the CLI tools utilized for + schema migrations. This is done by rejecting any attempt to migrate + that would result in a lower schema version number than current + +* Document best practices on restoring to a previous schema version + including the steps to take prior to migrating the schema + +* Stop support of migrations with downgrade functions across all + projects + +* Do not add future migrations with downgrade functions + + +Alternatives +------------ + +Downgrade paths can continue to be supported. + +Implementation +============== + +Assignee(s) +----------- + +Morgan Fainberg (irc: morganfainberg) +Matt Fischer (irc: mfisch) + +Work Items +---------- + +* Document best practices for restoring to a previous schema version + +* Update oslo.db to return appropriate errors when trying to perform + a schema downgrade + +* (all core teams) Do not accept new migrations that include downgrade + functions + +* (all core teams) Projects may drop downgrade functions in all + current migration scripts + +Dependencies +============ + +No external dependencies. + +References +========== + +1. `openstack-dev mailing list topic `_ + +2. `openstack-operators mailing list topic `_ + +3. `Current migration/rollback documentation `_ + +.. note:: + + This work is licensed under a Creative Commons Attribution 3.0 Unported License. + http://creativecommons.org/licenses/by/3.0/legalcode