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 thefalse
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 thetrue
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 thetrue
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 valuetrue
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.