Migration descriptor file
This document describes the migration configuration file (called migration descriptor) used to specify a sequence of migrations in a system. The migration descriptor file provides a way to describe the actions to be taken during the migrations in a declarative way.
The descriptor file must be named
migration.yml. It can be located in the top level of the specified directory or in
any of its subdirectories.
systemUnderAudit: Test_System changesets: - name: 1.0.0 changes: - migrate: dir-list: npl - npl-run: protocol: Factory action: create - name: 1.0.1 changes: - migrate: dir-list: npl scripts: S0001_migration.kts
The migration log describes an ordered list of change sets to be applied to an environment. A change set will be applied to that environment to 'bring it up to date' by only applying the changes that have not yet been applied.
systemUnderAudit: my_system changesets: - name: change_set_1 - name: change_set_2 - name: change_set_3
systemUnderAudit- Application name. This value will be used as prefix in naming the migration log protocol instance used to track changes that have been applied. Valid characters are alpha-numeric or an underscore(
- A list of change sets each having a name.
One migration is made up of a set of changes to be executed in a specified order. It is characterised by a name which
describes the change. The explicit order of change sets represents the order of execution. Valid characters are
alpha-numeric, an underscore(
_), or a period(
- name: release_alpha changes: # list of changes - name: release_foo changes: # list of changes - name: release_1.0 changes: # list of changes
name- The unique identifier used to name the change.
changes- list of changes in the change set. The order of changes represents the execution order.
Unified migration (
Allows you to load the sources and run the migration in one step or separately. It can be accomplished as follows:
- Upload NPL files:
- migrate: dir-list: npl
- Execute migration script:
- migrate: scripts: S0001_migrate.kts
- Upload NPL source files and execute migration script:
- migrate: dir-list: npl scripts: S0002_migrate.kts
Properties (requires one of the following)
scripts- Comma separated list of scripts executed as part of the change
dir-list- Comma separated list of source directory prefixes. Prefix will be prepended to the change name, separated by a "
-", to form the source directory name. The resulting directory must exist. For example, with a
dir-list: npl, the resulting source directory would be
migrate is the recommended way of performing files upload, executing migration scripts or both.
Run NPL (
Describes the loading and optional running of NPL code:
- npl-run: protocol: package-name/Factory action: create
If there is no package:
- npl-run: protocol: Factory action: create
It is possible to pass text (string) arguments for
action as a comma separated list:
- npl-run: protocol: Factory action: create arguments: arg1, arg2, arg3
protocol- (required) - prototype id of factory protocol to instantiate
action- (required) - action to execute. If no 'arguments' property is given, it must be an action with no parameters
Declare a changeset as a reset in the history of changes. This is necessary to support breaking changes in NPL that makes it impossible to re-run/compile old parts of the history.
- reset: true
This change has a very special characteristic:
- Any changeset in the migration descriptor file, e.g.
migration.yml, before a reset becomes ineffective and only useful as a record of the migration actions that have been applied to production. They will no longer be applied to empty ( dev/test) systems. They will no longer be considered as part of checksum validations.
- Executing a reset also closes the current migration log and opens a new one in the system being upgraded.
true|false- (required) - reset should always be set to
true. Setting it to
falseis equivalent to omitting the change itself.
Run only (
Optional property on a change level. Consists of a comma-separated list of environment identifiers used to decide if the change shall be executed or skipped.
run-only are always run.
run-only is non-empty, a change is executed only when the
ENGINE_NPL_MIGRATION_RUN_ONLY environment variable is
provided and matches one of the values in a
run-only change list property.
Given the migration descriptor:
changes: - npl-load: run-only: DEV dir-list: "npl/core"
npl-load change will only be executed when the
ENGINE_NPL_MIGRATION_RUN_ONLY environment variable has the value