Skip to content

Migration descriptor file

Introduction

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.

Example:

systemUnderAudit: Test_System

changesets:
  - name: 1.0.0
    changes:
      - migrate:
        dir-list: npl
      - npl-run:
        protocol: pkg/Factory
        action: create

  - name: 1.0.1
    changes:
      - migrate:
        dir-list: npl
        scripts: S0001_migration.kts

The Log

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

Properties

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

Change Sets

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.0
  changes:
  # list of changes

Properties

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

Changes

Unified migration (migrate)

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 change: 1.0.0 and dir-list: npl, the resulting source directory would be npl-1.0.0.

migrate is the recommended way of performing files upload, executing migration scripts or both.

Run NPL (npl-run)

Describes the loading and optional running of NPL code:

- npl-run:
  protocol: pkg/Factory
  action: create

It is possible to pass text (string) arguments for action as a comma separated list:

- npl-run:
  protocol: pkg/Factory
  action: create
  arguments: arg1, arg2, arg3

Properties

  • 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

Reset (reset)

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.

Properties

  • true|false - (required) - reset should always be set to true. Setting it to false is equivalent to omitting the change itself.

Run only (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.

Changes without run-only are always run.

If 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"

The npl-load change will only be executed when the ENGINE_NPL_MIGRATION_RUN_ONLY environment variable has the value DEV.