From 37eaf346b402c1b5bd005feaec587a3d77dedff3 Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Mon, 22 Sep 2025 09:39:31 +0200 Subject: [PATCH 1/9] Added support indication and how to for downgrades and re-running migrations --- 16/umbraco-cms/SUMMARY.md | 1 + .../fundamentals/setup/upgrading/README.md | 7 +- .../downgrades-and-rerunning-migrations.md | 84 +++++++++++++++++++ 3 files changed, 89 insertions(+), 3 deletions(-) create mode 100644 16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md diff --git a/16/umbraco-cms/SUMMARY.md b/16/umbraco-cms/SUMMARY.md index 611b8839ac9..0eeefac1146 100644 --- a/16/umbraco-cms/SUMMARY.md +++ b/16/umbraco-cms/SUMMARY.md @@ -34,6 +34,7 @@ * [Upgrade to Umbraco 7](fundamentals/setup/upgrading/version-specific/upgrade-to-umbraco-7.md) * [Minor upgrades for Umbraco 7](fundamentals/setup/upgrading/version-specific/minor-upgrades-for-umbraco-7.md) * [Upgrade Unattended](fundamentals/setup/upgrading/upgrade-unattended.md) + * [Downgrades and Re-running Migrations](fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md) * [Server setup](fundamentals/setup/server-setup/README.md) * [Running Umbraco On Azure Web Apps](fundamentals/setup/server-setup/azure-web-apps.md) * [Hosting Umbraco in IIS](fundamentals/setup/server-setup/iis.md) diff --git a/16/umbraco-cms/fundamentals/setup/upgrading/README.md b/16/umbraco-cms/fundamentals/setup/upgrading/README.md index 7a3dd19959e..203bc885c23 100644 --- a/16/umbraco-cms/fundamentals/setup/upgrading/README.md +++ b/16/umbraco-cms/fundamentals/setup/upgrading/README.md @@ -10,6 +10,7 @@ Before upgrading, it is recommended to **read the [upgrade introduction](./upgra ## Upgrade Guides -* [Upgrade details: Minor and Major upgrades](upgrade-details.md) -* [Upgrade Unattended](upgrade-unattended.md) -* [Version Specific upgrade notes](version-specific/README.md) +* [Upgrade Details](upgrade-details.md) - how to upgrade Umbraco across major, minor and patch version +* [Upgrade Unattended](upgrade-unattended.md) - configure Umbraco to upgrade in an unattended mode, avoiding the need to click through the installation wizard. +* [Version Specific Upgrades](version-specific/README.md) - details of changes to be aware of when upgrading to specific versions. +* [Downgrades and Re-running Migrations](downgrades-and-rerunning-migrations.md) - 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. diff --git a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md new file mode 100644 index 00000000000..a35147d3a0c --- /dev/null +++ b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md @@ -0,0 +1,84 @@ +--- +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 +--- + +# Downgrade to a Previous Version + +## Downgrades are not strictly supported + +Downgrades are not a supported feature of the Umbraco product. + +The reason for this is the Umbraco migration scheme only supports upward migrations. + +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. + +There isn't an equivalent downward migration that will undo these changes. + +Given that, it can't be guaranteed that a database from a later version will work with an earlier one. + +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. + +## Particular downgrades are possible and safe + +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). + +You will need to determine this for yourself, likely via reviewing the changes and migrations between versions and testing. + +Once you have done that, this article will explain how to proceed with downgrading. + +## Downgrade process + +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: + +`dotnet add package Umbraco.Cms --version ` + +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. + +To resolve this, you need to query the Umbraco database. + +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). + +You can find the current state of these via: + +```sql +select value from umbracoKeyValue where [key] = 'Umbraco.Core.Upgrader.State+Umbraco.Core.Premigrations' +select value from umbracoKeyValue where [key] = 'Umbraco.Core.Upgrader.State+Umbraco.Core' +``` + +You then need to find the latest state for the version of Umbraco you want to downgrade to. + +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). + +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. + +Having found the state you need, you set it via a query of the form: + +```sql +update umbracoKeyValue +set value = '{state value}' +where [key] = 'Umbraco.Core.Upgrader.State+Umbraco.Core' +``` + +Then restart Umbraco. + +## Re-running Migrations + +A related topic is if you want to re-run the migrations from a prior version to the version you are on. + +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. + +Again you need to manipulate the migration state stored in the database. + +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. + +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: + +```sql +update umbracoKeyValue +set value = '{EEF792FC-318C-4921-9859-51EBF07A53A3}' +where [key] = 'Umbraco.Core.Upgrader.State+Umbraco.Core' +``` + +And then restart Umbraco. + +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. From 68951b8e8ad72338813a83cf01034085b484b9e0 Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Mon, 22 Sep 2025 10:01:52 +0200 Subject: [PATCH 2/9] Linting --- .../upgrading/downgrades-and-rerunning-migrations.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md index a35147d3a0c..a13554a0f6f 100644 --- a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md +++ b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md @@ -16,7 +16,7 @@ There isn't an equivalent downward migration that will undo these changes. Given that, it can't be guaranteed that a database from a later version will work with an earlier one. -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. +If you wish to downgrade to an earlier version of Umbraco, it's best to also revert to a compatible database backup. You will need one from the version you are downgrading to. ## Particular downgrades are possible and safe @@ -32,7 +32,7 @@ Downgrading the Umbraco application itself is straightforward. In the same way a `dotnet add package Umbraco.Cms --version ` -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. +If you try to start Umbraco, 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 recognize the state stored by the higher version you were running previously. To resolve this, you need to query the Umbraco database. @@ -65,13 +65,13 @@ Then restart Umbraco. A related topic is if you want to re-run the migrations from a prior version to the version you are on. -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. +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 investigating an upgrade related issue, or testing an upgrade before running in production, it's useful to know how to do this. Again you need to manipulate the migration state stored in the database. -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. +You can update these values to an earlier state, and on start-up Umbraco will recognize that it's not at the latest. It will re-run the migrations from the earlier state to the current one. -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: +For example, let's say you are running 16.2, and want to re-run the core migrations for 15 and 16. Here you would set the core migration state to the latest one from 14, via: ```sql update umbracoKeyValue From 129d4630edd8924dd9b875d631d4d5a4310f5118 Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Mon, 22 Sep 2025 10:05:24 +0200 Subject: [PATCH 3/9] Linting --- .../setup/upgrading/downgrades-and-rerunning-migrations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md index a13554a0f6f..edd23771270 100644 --- a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md +++ b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md @@ -20,7 +20,7 @@ If you wish to downgrade to an earlier version of Umbraco, it's best to also rev ## Particular downgrades are possible and safe -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). +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 (for example adding a new, nullable field to a database table). You will need to determine this for yourself, likely via reviewing the changes and migrations between versions and testing. @@ -32,7 +32,7 @@ Downgrading the Umbraco application itself is straightforward. In the same way a `dotnet add package Umbraco.Cms --version ` -If you try to start Umbraco, 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 recognize the state stored by the higher version you were running previously. +If you try to start Umbraco, it's 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 recognize the state stored by the higher version you were running previously. To resolve this, you need to query the Umbraco database. From 06e4bd1e935129ea5e952feac259a442d8eb80fe Mon Sep 17 00:00:00 2001 From: Andy Butland Date: Mon, 22 Sep 2025 11:10:22 +0200 Subject: [PATCH 4/9] Added point about packages --- .../setup/upgrading/downgrades-and-rerunning-migrations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md index edd23771270..c0dc294dd80 100644 --- a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md +++ b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md @@ -8,7 +8,7 @@ description: Discusses the possibility of downgrading to a previous version, alo Downgrades are not a supported feature of the Umbraco product. -The reason for this is the Umbraco migration scheme only supports upward migrations. +The primary reason for this is the Umbraco migration scheme only supports upward migrations. 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. @@ -18,6 +18,8 @@ Given that, it can't be guaranteed that a database from a later version will wor If you wish to downgrade to an earlier version of Umbraco, it's best to also revert to a compatible database backup. You will need one from the version you are downgrading to. +Other factors that may preclude downgrading include packages you may be using. They may not be compatible with the lower version or support downgrades themselves. + ## Particular downgrades are possible and safe 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 (for example adding a new, nullable field to a database table). From bc092bc2a50fd8be471470fb8392631c27fa0f2f Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 22 Sep 2025 15:31:35 +0200 Subject: [PATCH 5/9] Update 16/umbraco-cms/fundamentals/setup/upgrading/README.md --- 16/umbraco-cms/fundamentals/setup/upgrading/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/fundamentals/setup/upgrading/README.md b/16/umbraco-cms/fundamentals/setup/upgrading/README.md index 203bc885c23..b1547f4377b 100644 --- a/16/umbraco-cms/fundamentals/setup/upgrading/README.md +++ b/16/umbraco-cms/fundamentals/setup/upgrading/README.md @@ -10,7 +10,7 @@ Before upgrading, it is recommended to **read the [upgrade introduction](./upgra ## Upgrade Guides -* [Upgrade Details](upgrade-details.md) - how to upgrade Umbraco across major, minor and patch version +* [Upgrade Details](upgrade-details.md) - how to upgrade Umbraco across major, minor, and patch versions. * [Upgrade Unattended](upgrade-unattended.md) - configure Umbraco to upgrade in an unattended mode, avoiding the need to click through the installation wizard. * [Version Specific Upgrades](version-specific/README.md) - details of changes to be aware of when upgrading to specific versions. * [Downgrades and Re-running Migrations](downgrades-and-rerunning-migrations.md) - 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. From 0b3a8574d4de49adcf58ca7236b910699942d6b7 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 22 Sep 2025 15:31:42 +0200 Subject: [PATCH 6/9] Update 16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md --- .../setup/upgrading/downgrades-and-rerunning-migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md index c0dc294dd80..4fc99fa2c12 100644 --- a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md +++ b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md @@ -8,7 +8,7 @@ description: Discusses the possibility of downgrading to a previous version, alo Downgrades are not a supported feature of the Umbraco product. -The primary reason for this is the Umbraco migration scheme only supports upward migrations. +The primary reason for this is that the Umbraco migration scheme only supports upward migrations. 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. From 2522b8d6c917c2a74c68e49b2215ebfb63447d29 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 22 Sep 2025 15:31:49 +0200 Subject: [PATCH 7/9] Update 16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md --- .../setup/upgrading/downgrades-and-rerunning-migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md index 4fc99fa2c12..7d62177e9ab 100644 --- a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md +++ b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md @@ -10,7 +10,7 @@ Downgrades are not a supported feature of the Umbraco product. The primary reason for this is that the Umbraco migration scheme only supports upward migrations. -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. +When updating to a new version, often there are migrations to run that will make changes to the Umbraco schema and data. This is being done to bring the database to a state that will support the functionality of the version being upgraded to. There isn't an equivalent downward migration that will undo these changes. From 228ca6a39c51045ec626259ee3c9c7ff338b4b60 Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 22 Sep 2025 15:31:55 +0200 Subject: [PATCH 8/9] Update 16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md --- .../setup/upgrading/downgrades-and-rerunning-migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md index 7d62177e9ab..326087f4cb6 100644 --- a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md +++ b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md @@ -22,7 +22,7 @@ Other factors that may preclude downgrading include packages you may be using. T ## Particular downgrades are possible and safe -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 (for example adding a new, nullable field to a database table). +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, migrations are backward compatible (for example, adding a new, nullable field to a database table). You will need to determine this for yourself, likely via reviewing the changes and migrations between versions and testing. From 35b64224d785feb4d323e37cc0953b4d40767afb Mon Sep 17 00:00:00 2001 From: Esha Noronha <82437098+eshanrnh@users.noreply.github.com> Date: Mon, 22 Sep 2025 15:32:01 +0200 Subject: [PATCH 9/9] Update 16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md --- .../setup/upgrading/downgrades-and-rerunning-migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md index 326087f4cb6..3138e77b184 100644 --- a/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md +++ b/16/umbraco-cms/fundamentals/setup/upgrading/downgrades-and-rerunning-migrations.md @@ -67,7 +67,7 @@ Then restart Umbraco. A related topic is if you want to re-run the migrations from a prior version to the version you are on. -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 investigating an upgrade related issue, or testing an upgrade before running in production, it's useful to know how to do this. +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 its state. However, if investigating an upgrade-related issue or testing an upgrade before running it in production, it's useful to know how to do this. Again you need to manipulate the migration state stored in the database.