Table of Contents

Database migration

When is the database migration launched?

Starting with version 1.12, the migration is launched exclusively by the backend.

Single-tenant context

In a single-tenant context, it is launched automatically at backend startup and it stops it by default in case of an error. You can disable the automatic execution:

  • By running the neos run command with the --automatic-migration false option.
  • By setting Migration:Automatic with the false value in the application configuration.

You can force the start of the backend even if the migration failed:

  • By running the neos run command with the --force-start option.
  • By setting Migration:ForceStart with the true value in the application configuration.

Multi-tenant context

In a multi-tenant context, migrations are triggered by the Tenants cluster:

  • Manually by an administrator
  • When a new tenant is created (more details)

Checking the database owner

Since version 2.2, a new check has been introduced to ensure that the database schema name matches the cluster name. On initial migration, the database schema name is stored in the $NeosObject system table with ObjectType = 'SchemaName'. If another cluster with a different name tries to migrate the database, an error will occur. This prevents untimely migrations when different clusters point to the same database.

Warning

If you rename a cluster, you should also remember to modify the value of the row ObjectType = 'SchemaName' in the $NeosObject system table.

How does the migration know what to update?

The migration starts by checking the schema version stored in the $NeosObject system table with ObjectType = 'SchemaVersion'. If the stored version is the same as the one in the current schema, the migration stops here and considers that the database is up to date.

Note

In a single-tenant context, it is possible to ignore this check during the automatic launch:

  • By running the neos run command with the --force-migration option.
  • By setting Migration:Force with the true value in the application configuration.

The commands to be run are then automatically determined by comparing the database schema with the expected schema.

Is the migration executed in a SQL transaction?

Starting with version 1.12, the migration is executed outside of any SQL transaction. This is necessary in order to limit locks and to obtain reasonable execution times. This also makes it easier to operate manually in the database in case of an error in the migration, leaving the database in the same state as the one that produced the error.

Warning

In production, it is strongly advised to make a backup of the database before any migration in order to allow a rollback in case of a major problem.

How to remove obsolete columns and tables?

By default, the migration does not delete the tables and columns that should no longer exist. To delete them permanently, you must launch the migration with the option AllowDataLoss = true.

To switch this option in single-tenant mode, there are several possibilities:

  • By running the neos run command with the --allow-data-loss option.
  • By setting Migration:AllowDataLoss with the value true in the application configuration.

How to obtain the queries issued to obtain the database schema during migration?

In order not to burden the logs, they are not visible by default. To enable them, you need to override the logger configuration so that it emits 'Information' level logs on the Sql commands executed by the migration. This can be done via an environment variable. Example below in PowerShell:

${env:Serilog__MinimumLevel__Override__Microsoft.EntityFrameworkCore.Database.Command} = "Information"

The environment variable must be set before the neos run command is executed.