General

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 by running the =CreateFolderPacket = packet in the Cross-Release Packets module manually.

Migration Mode

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 opening planta_migration.bat or ./planta_migration.sh in the server installation directory.
    • The migrate parameter will be ignored from here on.

Notes

  • As an alternative to the migration mode, migration packets can also be run in the program (on the surface) via the following modules.
  • 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?

  1. The Migrationsparameter 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 under config/migration/migration.par.
  2. The planta_migration script has a mandatory parameter: -c / --migration-config.
    • This parameter must be the path (relative from the server directory) to the migration parameter file.
    • There must not be any blank spaces contained in this path!
  3. To start the migration, the planta_migration script must be run in the server directory of the created parameter file: planta_migration -c "name of the parameter files”
    • The migration process should only be initiated by experienced users.
  4. 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.
  5. 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.
  6. After the file system has been searched, the packets will be executed.

Migration Parameter

Information

  • The parameters required for the migration are specified in a parameter file.
  • Structure of the parameter file:
--migration-components
	Server
	Customizing-Hotfix
	Customizing
	Customer
	Before DB Import
	After DB Import

--abort-on-failure
--packets-to-exclude
--delete-demo-data
--change-license
CODE
SectionExplanation
migration-componentsHere, the components to be migrated are specified. The "traditional" migration with migration packets only starts when the migration-compnents parameter is set.
abort-on-failureIf this option is available, the migration will be aborted as soon as a migration packet fails.
packets-to-excludeHere, 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 are 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.


  • 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 possible 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.

Caution

  • In the example parameter file under config/migration/migration.par, all components are listed that are theoretically possible. These components must necessarily be adjusted to the actual conditions and irrelevant components must be deleted before migration.

Customization Options

Information