Upgrade Instructions 9.1 → 9.2

The upgrade to Neos 9.2 requires an extensive migration on the content repository data

If you upgrade an existing Neos 9.x installation with production data to Neos 9.2 please read carefully the guide #Required CR upgrades and replay

For further information on what changed, please take a look at the changelogs (Neos, Flow)

#Update Instructions

Before making substantial changes, make sure you create a backup of the database and files!

cd /installation-root/
# Update the core package dependencies
composer require --no-update "neos/neos:~9.2.0"
composer require --no-update "neos/neos-ui:~9.2.0"

# Update optional package dependencies (if installed)
composer require --no-update "neos/demo:~9.2.0"

If you have development packages in your composer manifest, update them to match as well:

# Update development packages (if installed)
composer require --no-update --dev "neos/buildessentials:~9.2.0"

Make sure to update every required Neos package to ~9.2.0! Otherwise there can be an error during updating, because of version conflicts.

After completing these steps, your package should be upgraded to the latest version of the Neos UI and ready to use. Thank you for using Neos!

#New System Requirements for Neos 9.2

Please note that Neos 9.2 and Flow 9.2 raise the minimum PHP version from PHP 8.2 to PHP 8.4.
PHP 8.2 will be dead with security support ending in December 2026 and Neos 9.2 and 9.3 will be maintained well beyond that. PHP 8.4 was released in November 2024.

compatible PHP version	compatible MariaDB version	compatible MySql version
PHP 8.4 - 8.5	>= 10.7	>= 8.0.14, < 8.4.0

#Required CR upgrades and replay

#New CR Upgrades

Neos 9.2 fixes all known race conditions of the content repository - even the theoretical ones ;)

Because of that stricter validation we can now ensure that illegal event sequences will not exist - and the projections will not need to handle these.

If you have events from a previous Neos 9 release they might contain illegal sequences that were not guarded then but will now fail to replay.

Neos 9.2 features a new concept of such CR Upgrades that allow the detection and automatic fix of these:

./flow crupgrade:eventsstatus

That CLI command will report any known fixable inconsistencies. The suggested command in the output can then be used to apply the upgrades. Please note that all upgrades are destructive and you might want to make a dry run first via --dry-run. Also each suggested CLI command provides extensive documentation via --help.

#Dangling content streams

With Neos 9.2 we ensure that a sequence of events is committed atomically. We cannot fail to miss a cleanup event. In previous versions due to various circumstances it could still happen that certain content streams existed but without belonging to a workspace thus effectively obsolete.

These dangling content streams bloat up the projected content graph and should be cleaned up. Please check if your Neos can be cleaned up a little:

./flow contentstream:status

If it reports "Okay. No dangling streams found" you are all set. If there are content streams please look into cleaning those up via ./flow contentStream:removeDangling.

Note that this process is fully optional and can also be done after Neos 9.2 is deployed.

#Replay of the content graph

Required extensive migration on the content repository data

If Neos 9.2 is deployed but the database not prepared and storing the nodes as with your previous Neos 9 version, everything will crash as the new tables don't exist.

Neos 9.2 introduces a new overhauled database schema for the MySQL / MariaDB content graph projection. In traditional state management like with Neos 8 we could not allow ourselves such refactoring.

The new graph will create copies for nodes in workspaces only on demand and thus greatly reduce storage and make workspace operations faster. We cannot migrate to this schema from your current projections state as the new projection requires information that is only available in the past events.

To upgrade to Neos 9.2, which brings the new optimised content graph - you need to build up the content graph projection fully from scratch. Thats where we apply event by event to reach effectively same state just optimised stored.

Please continue in the guide below how to replay safely on production without downtime or mistakes:

How to replay the content graph in production

#Optional upgrade to correct UTC dates in events

An optional migration of the above mentioned #new CR Upgrades is to correct the dates of events and nodes. By storing recordedAt as datetime field we lost its original timezone information. While strictly not required this migration corrects the events to avoid any offset timestamps if you rely on those. Do note that this is the same migration we already provided via patch to Neos 9.0.13 and 9.1.6.

./flow crupgrade:eventsrecordedattoutc --dry-run

Note that the effects on the content graph will only show after a replay. For further information see the documentation in ./flow crupgrade:eventsrecordedattoutc --help

#Adjustments

Neos Ui

Workspace Selector

The workspace selector was moved from inside the publish dropdown to the main primary toolbar. Its shows what base workspace you are publishing into. Workspace labels can be adjusted in the workspace module and the the default label of the live workspace can be set via CLI:

./flow workspace:settitle live "Live Workspace"

Plugins

In the last upgrade instructions we documented deprecations for Neos Ui plugin authors and new APIs. With Neos 9.2 we have published a new experimental package @neos-project/neos-ui-contentrepository-model. It provides the same typescript types to plugins we use in the core and thus should help creating a plugin and navigating the code a bit.

Translations

Note that we finally got to clean up the translations from Neos.Neos into the proper place in the Ui. Custom overrides need to account that in the unlikely case. See change.

Deprecation:

No API deprecations with this release.

#Finish the update

# Update the packages
composer update

# Flush the caches
./flow flow:cache:flush --force
./flow flow:session:destroyAll

# Run code migrations, as needed for any packages that need to be
# migrated. Rule of thumb:
#
# - any 3rd party packages that still install fine at least claim
#   to work, and should be updated by their maintainer(s).
# - your own packages should always be treated with a migration,
#   at least it marks that as done.
#
./flow flow:core:migrate <Vendor.PackageName>

# Run database migrations
./flow doctrine:migrate

# Publish resources
./flow resource:publish