How to revert a migration from master

Created by Robert Raposa
Last updated: May 23, 2019 by crice

This article describes how to handle what to do when you wish to revert a migration that has already made it to master.

It is important to understand that a migration that has made it to master could already have been run in many environments, including developer devstacks.  Although Production may be the first concern, you must follow-up with help for all other environments.

Step-by-step guide

Here's what you do to resolve removing a bad migration from master.

  1. Determine if the migration can be corrected with the addition of a new migration.  This is the simplest option when it is available.
    1. Use the following types of questions to help determine whether you can roll-forward (i.e. create a new migration rather than reverting the old migration).
      1. Can the new migration handle bad data that may have been created before the new migration appears?
      2. Will the new migration cause a problem in Production (e.g. altering a large table)?
  2. If you can resolve with a new migration, do so and then communicate about the need to get and run the new migration (see below).
  3. If you need to literally revert the migration from master,  do so and then communicate about how to revert the old migration (see below).
  4. Communicate about resolving the issue in the following places (Slack dev channel, email to edx-code@googlegroups.com):

    • A sample email might look like the following:

      The following migration was reverted from master during the last release (005_blahblah). 

      If you run into the following error on your devstack:

      (1054, "Unknown column 'commerce_commerceconfiguration.receipt_page' in 'field list'")

      You can fix it with the following:

      • git checkout 777964b9aae8a679fc4edef0d8186910777bd560
      • # revert to the earlier migration as follows...
      • ./manage.py lms --settings=devstack migrate commerce 0004
        • Answer "yes" when prompted.
      • git checkout master (or wherever you were)

      You may also need to run the following sql manually:

      • mysql -u root edxapp

      • ALTER TABLE ...;

    • If you know the error that developers are facing, include that in the Slack messages so it can be easily found.

  5. Use the stage_edxapp_Rollback_Migrations GoCD pipeline stage to revert the migration if it has made it to stage.