Migration Process

General

For information

In PLANTA, migration means an adjustment of the database which is required in order to upgrade the system to a higher version. The migration procedure is based on migration packets written in Python and is integrated in PLANTA.
They carry out changes to the existing PLANTA installation, particularly to the database.
- In order to start the migration, the server must be started in migration mode (see the section below).
  - The server starts a new internal session with the PLANTA user named MIGRATION. As a result, all new records or changes that are created/made to the customizing in migration mode, have the MIGRATION change/creation user. See also the entry under Caution below.
- When the migration is started, all mandatory packets are run automatically. All further packets must be run manually. For more information, see migration process.

Caution

If the MIGRATION user and the persons assigned to it are deleted, they will automatically be created anew in the next update.

Notes

To improve performance under MSSQL, it is recommended to switch to the RECOVERY SIMPLE recovery model before migration: ALTER DATABASE <PLANTA_DB_USER> SET RECOVERY SIMPLE
After successful migration, the recovery model should be reset to the initial model. This is the standard model of the database.
Which migration packets are delivered with the required server or database release is specified in the release notes.
If there are problems in the sense that available Python modules cannot be loaded (e.g. in the 'FillMigrationRuleTable’ migration script), this can be resolved manually by running the CreateFolderPacket packet in the Cross-Release Packets module.

Update in the Container

For information

To update the customizing component in the container environment, proceed as follows:
- Include the following parameter in the environment variables in the manager container:
  CODE
```
- "UPDATE=1"
```
- Store the required version of the customizing image.
- Start the container and remove the parameter again after the update.

Migration Mode

For information

The server comes with a new mode for the implementation of the migration, the so called migration mode.
- In migration mode, the existing migration packets with parameters Upon system start = and Completed = are run.
- While the server is in migration mode, no client can connect to this server.
- After implementation of the migration, the server will be shut down automatically.
The migration is started by calling command: ["migration", "-c <name of the parameter file>"] in the manager container.

Notes

As an alternative to the migration mode, migration packets can also be run in the program (on the user interface) via the following modules.
- Overview of the previous runs
After carrying out the migration packets in the system, the server or the server service must be restarted and the migration results must be checked.

Technical Procedure

What happens if the server is started in migration mode?

The migration parameters must be contained in a parameter file.
- The parameter file should only be created and adjusted by experienced users.
- An example parameter file is located in the customizer container at config/migration/migration.par.
The migration command has a mandatory parameter: -c / --migration-config.
- This parameter must be the path to the migration parameter file (relative from the worker container).
- There must not be any blank spaces contained in this path!
To start the migration, the command: ["migration", "-c <name of the parameter file>"] command must be included in the docker-compose.yml in the manager container and the container must be started.
- The migration process should only be initiated by experienced users.
The server starts a new internal session with the Migration PLANTA user.
- As a result, all new records or changes that are created/made to the customizing in migration mode, have the Migration change/creation user.
- Please note that for this reason the Migration user must not be deleted.
It will be searched for new migration packets on the file system. The migration packets will then be executed and information on them will be saved in the database.
After the file system has been searched, the packets will be executed.

Migration Parameter

For information

The parameters required for the migration are specified in a parameter file.
Structure of the parameter file:

CODE

--migration-components
	Server
	Customizing-Hotfix
	Customizing
	Customer
	Before DB Import
	After DB Import

--abort-on-failure
--packets-to-exclude
--delete-demo-data
--change-license

--export-data
--export-schema
--container-update
--final-update

Section	Explanation
`migration-components`	Here, the components to be migrated are specified. The "traditional" migration with migration packets only starts when the `migration-compnents` parameter is set.
`abort-on-failure`	If this option is available, the migration will be aborted as soon as a migration packet fails.
`packets-to-exclude`	Here, the absolute Python path to a migration packet which is not to be run during migration can be stored per line. E.g.: `migration.server.S_39_5_21.WI19001_add_uuid_columns_to_kdb.AddUUIDColumnsToKDB`
`delete-demo-data`	If this parameter is included in the file, the demo data is deleted from the system. Caution: In the "clearing of demo data", no filter is set on the owner license or anything similar, instead all tables with project/user/etc. data is emptied (only user P20 and MIGRATION are retained). The function must be run at the beginning after a system has been set up and cannot be used to clear demo data in a system which has already been used productively!
`change-license`	If specified, the license records in the system are changed. If no license is specified in the parameter file, the license from the planta_server.conf is used. After license change, the migration is terminated and no migration packets are run afterwards.
`export-data`	Calls the database export with the transferred parameter file. Example: CODE `--export-data /mnt/transfer/config/export/master_data_export.par`
`export-schema`	Calls the schema export and writes the results in the transferred directory. Example: CODE `--export-schema /var/planta/export/schema`
`container-update`	Runs a migration in the container environment.
`final-update`	Carries out the final license exchange.

The possible components stem from the __init__.py of the respective migration directories.
The specified components determine the update type of the migration. It is therefore possibly to, e.g., only migrate the customizing or only the server component.
The parameter file does not only give the components to be migrated but also the sequence in which is migrated.
All packets that do not fall within the list of specified components receive the Not relevant status.

Customization Options

Information

Individual migration packets can be customized as well.