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 cluster YAML configuration file.

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 cluster YAML configuration file.

Multi-tenant context

In a multi-tenant context, it is the Tenants cluster that triggers the call.

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 cluster YAML configuration file.

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 cluster YAML configuration file.

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.