> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-engage/upgrading/version-specific-upgrade-notes.md).

# Version specific Upgrade Notes

Version-specific documentation for upgrading to new major versions of Umbraco Engage.

This article provides specific upgrade instructions and breaking changes introduced when migrating to major version 18 of Umbraco Engage.

{% hint style="info" %}
When upgrading to a new minor or patch version, learn about the changes in the [Release Notes](/umbraco-engage/release-notes.md) article.
{% endhint %}

## Breaking changes

### 18.0.0 (Umbraco Engage v18 Launch)

Engage 18 adds support for Umbraco CMS 18. The main upgrade consideration is that the database schema alignment introduced in 17.2.0 is now **required** before you can upgrade.

#### Database Schema Alignment is now enforced

In 17.2.0, the schema alignment ran as an automatic on-boot migration (`AlignSchema`). It was followed by a **manual** script (`CompleteAlignSchema.sql`) to run during a maintenance window. Running the manual script was strongly recommended but not enforced — Engage continued to run with the schema left in the intermediate `Aligned` state.

Starting with Engage 18, completing this alignment is **mandatory**. This guarantees data integrity and performance going forward. The foreign keys, indexes, and constraints added by the alignment can no longer be treated as optional. A guard at the head of the v18 migrations reads the `Umbraco.Engage+DatabaseSchemaStatus` value in the `umbracoKeyValue` table. It **blocks the upgrade** unless the alignment has been completed. When the upgrade is blocked, Engage throws an error at startup and the migration does not proceed. The error message states which state the database is in and what to do next:

| `DatabaseSchemaStatus` | Result              | What to do                                                                                                                                                                           |
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Complete`             | Upgrade proceeds    | No action needed.                                                                                                                                                                    |
| *(no value)*           | Upgrade proceeds    | Fresh installs are unaffected.                                                                                                                                                       |
| `Aligned`              | **Upgrade blocked** | The automatic alignment ran, but `CompleteAlignSchema.sql` was never completed. Run it during a maintenance window, then retry the upgrade.                                          |
| `Pending`              | **Upgrade blocked** | A previous run of `CompleteAlignSchema.sql` started but did not finish. The script cannot be re-run from this state — the partial state must be investigated and recovered manually. |
| *(any other value)*    | **Upgrade blocked** | The schema is in an unexpected state. Expected `Complete` on existing installs, or no value on fresh installs.                                                                       |

{% hint style="warning" %}
If you upgraded through 17.2.x but never completed the manual schema alignment, your installation is most likely in the `Aligned` state. You must complete the schema alignment **before** upgrading to Engage 18, otherwise Engage will not start.
{% endhint %}

Follow the [Schema Alignment Guide](/umbraco-engage/upgrading/schema-alignment-guide.md) to complete the alignment. Once its steps are finished and the `DatabaseSchemaStatus` is `Complete`, the upgrade to Engage 18 proceeds normally.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umbraco.com/umbraco-engage/upgrading/version-specific-upgrade-notes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.