Migration overview

Back up your data & files

The migration to Neos 9 is a major step. To ensure that no data is lost, back up your data & files beforehand. 

Clean up in Neos 8.3

To ensure a smooth migration, it is recommended to clean up the node data in Neos 8.3.

bash
./flow node:repair

If the repair process asks you to confirm certain steps, carefully read what it says. You might need to cancel it and first check why it f.e. wants to remove some nodes or properties, possibly due to incorrect constraints or other factors. If those operations are valid, please confirm them during the repair process and make sure you end up with the command returning no changes by running it a second time.

Remember you can run repair operations individually, should the process abort or you if you need to repeat certain steps. To find the identifier, use the help command and then run for example:

bash
./flow node:repair --only createMissingChildNodes

To make sure that the database is up-to-date for the big upgrade, run the migration command. 

none
./flow doctrine:migrate

Stricter Node Hierarchy in Neos 9

Neos 9 is more strict with Versions of Nodes in different dimensions. If a node has been moved to a different parent Node that does not exist in all dimensions, the migration will fail. There is a migration to change the identifiers in Neos 8.3, but this will lead to the Nodes no longer being connected after upgrading to Neos 9. The migration can be found in a separate package and has to be run in Neos 8.3. 

Different Node Types in different dimensions

If Nodes have the same identifier, but different Node Types in different dimensions, they cannot be migrated to Neos 9. There is a migration to change the identifiers in Neos 8.3, but this will lead to the Nodes no longer being connected after upgrading to Neos 9. The migration can be found in a separate package and has to be run in Neos 8.3.

Update your dependency constraints 

Version requirements

Please check the system requirements and update, if needed.

In your composer file, update the packages to versions that support Neos 9. You must also require a new package: The adapter for the Content Repository, that does the actual connection to the underlying database.

json
{
  	"name": "your/package",
  	"require": {
   		"neos/neos": "^9.0",
		"neos/neos-ui": "^9.0",
		"neos/contentgraph-doctrinedbaladapter": "^9.0"
  	}
}

Include the package for migrating the legacy data. You can remove the package after a successful data migration.

bash
composer require --no-update neos/contentrepository-legacynodemigration

Using composer, update your lock file and check if everything is really compatible. To be on the safe side, you can update using --dry-run. 

bash
composer update --dry-run

This will probably fail due to other packages in your project that need to be updated to work with Neos 9, so check those for newer versions.

When you are good to go, do the actual composer update:

bash
composer update

As an additional check you can run

bash
composer outdated

and see if any packages could be updated further. At this point, focus on the direct dependencies you can control.

Migrate your code

To get your code up-to-date, the first step is to run:

bash
./flow core:migrate

on all packages you maintain or want to create a PR for. This is still useful, as it will help bring your code to a state, that conforms to what Flow and Neos right before v9 expected.

The core:migrate command is supported by a new solution based on Rector, for the new migrations we ship for upgrading to Neos 9 (and beyond, as times goes by).

Run the rector migration

After you are done with the code adjustments, come back here and continue below.

Setting up the Content Repository

Run the commands to set up the new Content Repository. This will create a bunch of new tables in your database for the new Content Repository. 

bash
./flow doctrine:migrate
./flow cr:setup

Homepage must have Neos.Neos:Site as Super Type

Before exporting the data, ensure that your Homepage has Neos.Neos:Site as a super type, as described in the Fusion migration.

The next step is to export the data from Neos 8.3 to Neos 9.

bash
./flow site:exportLegacyData --path ./migratedContent

The package also allows further parameters to be passed, for example an alternative database connection or resource path. 

none
./flow site:exportLegacyData --path ./migratedContent --config '{"dbal": {"dbname": "neos80"}, "resourcesPath": "/path/to/neos-8.0/Data/Persistent/Resources"}'

Resources stored in cloud storage 

If the resources are stored in a cloud storage, set the source folder to "an empty string". It will extract metadata from the database but not fetch the file contents when exporting. Upon import no file content will be imported, it is expected to exist in whatever place it used to be! This can also be used to speed up migration with a lot of assets, in case they are in the right place in the fileystem already (it avoids copying all the data during export)

Then, import the export into the new Neos 9 database tables. 

bash
./flow site:importAll --path ./migratedContent

If all went well, the website should now be available as usual.