|
| 1 | +--- |
| 2 | +description: Discusses the possibility of downgrading to a previous version, along with the related topic of re-running the migrations that have occurred during an upgrade |
| 3 | +--- |
| 4 | + |
| 5 | +# Downgrade to a Previous Version |
| 6 | + |
| 7 | +## Downgrades are not strictly supported |
| 8 | + |
| 9 | +Downgrades are not a supported feature of the Umbraco product. |
| 10 | + |
| 11 | +The reason for this is the Umbraco migration scheme only supports upward migrations. |
| 12 | + |
| 13 | +When updating to a new version, often there are migrations to run that will make changes to Umbraco schema and data. This is done to bring the database to a state that will support the functionality of the version being upgraded to. |
| 14 | + |
| 15 | +There isn't an equivalent downward migration that will undo these changes. |
| 16 | + |
| 17 | +Given that, it can't be guaranteed that a database from a later version will work with an earlier one. |
| 18 | + |
| 19 | +For most cases therefore, if you wish to downgrade to an earlier version of Umbraco, it's best to also revert to a database backup from the version you are downgrading to. |
| 20 | + |
| 21 | +## Particular downgrades are possible and safe |
| 22 | + |
| 23 | +That said, between some versions, a downgrade may be possible and perfectly safe. There may be no migrations that run between them. Or, as is often the case, the migrations are backward compatible (e.g. adding a new, nullable field to a database table). |
| 24 | + |
| 25 | +You will need to determine this for yourself, likely via reviewing the changes and migrations between versions and testing. |
| 26 | + |
| 27 | +Once you have done that, this article will explain how to proceed with downgrading. |
| 28 | + |
| 29 | +## Downgrade process |
| 30 | + |
| 31 | +Downgrading the Umbraco application itself is straightforward. In the same way as when upgrading, you update the dependency on Umbraco in your project, you do the same when downgrading: |
| 32 | + |
| 33 | +`dotnet add package Umbraco.Cms --version <VERSION>` |
| 34 | + |
| 35 | +If you try to start Umbraco now though, it's quite likely you will find an exception thrown on boot indicating a problem with the migration state. This is because the version of Umbraco you are running now doesn't understand the state that has been stored in the database by the higher version you were running previously. |
| 36 | + |
| 37 | +To resolve this, you need to query the Umbraco database. |
| 38 | + |
| 39 | +There are two migration states stored for the CMS - for the core migrations and the pre-migrations (which run at different times on start-up). |
| 40 | + |
| 41 | +You can find the current state of these via: |
| 42 | + |
| 43 | +```sql |
| 44 | +select value from umbracoKeyValue where [key] = 'Umbraco.Core.Upgrader.State+Umbraco.Core.Premigrations' |
| 45 | +select value from umbracoKeyValue where [key] = 'Umbraco.Core.Upgrader.State+Umbraco.Core' |
| 46 | +``` |
| 47 | + |
| 48 | +You then need to find the latest state for the version of Umbraco you want to downgrade to. |
| 49 | + |
| 50 | +To find the earlier states you have to look in the source code, specifically [here for the pre-migrations](https://github.com/umbraco/Umbraco-CMS/blob/main/src/Umbraco.Infrastructure/Migrations/Upgrade/UmbracoPremigrationPlan.cs) and [here for the core ones](https://github.com/umbraco/Umbraco-CMS/blob/main/src/Umbraco.Infrastructure/Migrations/Upgrade/UmbracoPlan.cs). |
| 51 | + |
| 52 | +Each migration is commented with the version it was added, so you can read off the latest one for the version you wish to run. |
| 53 | + |
| 54 | +Having found the state you need, you set it via a query of the form: |
| 55 | + |
| 56 | +```sql |
| 57 | +update umbracoKeyValue |
| 58 | +set value = '{state value}' |
| 59 | +where [key] = 'Umbraco.Core.Upgrader.State+Umbraco.Core' |
| 60 | +``` |
| 61 | + |
| 62 | +Then restart Umbraco. |
| 63 | + |
| 64 | +## Re-running Migrations |
| 65 | + |
| 66 | +A related topic is if you want to re-run the migrations from a prior version to the version you are on. |
| 67 | + |
| 68 | +This isn't something that should be needed in normal usage of Umbraco. Umbraco handles running the necessary migrations on start-up and keeps track of it's state. However, if you are ever investigating an upgrade related issue, or testing an upgrade before running in production, it's useful to know how to do this. |
| 69 | + |
| 70 | +Again you need to manipulate the migration state stored in the database. |
| 71 | + |
| 72 | +You can update these values to an earlier state, and on start-up Umbraco will recognize that it's not at the latest and will re-run the migrations from the earlier state to the current one. |
| 73 | + |
| 74 | +For example if you were running 16.2, and wanted to re-run the core migrations for 15 and 16, you would set the core migration state to the latest one from 14, via: |
| 75 | + |
| 76 | +```sql |
| 77 | +update umbracoKeyValue |
| 78 | +set value = '{EEF792FC-318C-4921-9859-51EBF07A53A3}' |
| 79 | +where [key] = 'Umbraco.Core.Upgrader.State+Umbraco.Core' |
| 80 | +``` |
| 81 | + |
| 82 | +And then restart Umbraco. |
| 83 | + |
| 84 | +Migrations are written to be idempotent, so they can be run multiple times. If the change the migration is making is already detected to be there, it should skip without throwing an exception. |
0 commit comments