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

The descriptor file must be named migration.yml, and it should be located in the root of the specified directory.

Example:

$schema: https://documentation.noumenadigital.com/schemas/migration-schema-v2.yml

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

  - name: 1.0.1
    changes:
      - migrate:
         sources:
         - npl
         migrations:
          - kotlin-script/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.

$schema: https://documentation.noumenadigital.com/schemas/migration-schema-v2.yml

changesets:
  - name: change_set_1
  - name: change_set_2
  - name: change_set_3

Validation

The migration descriptor now follows the JSON Schema convention, which allows you to specify the version of the schema being used. When used in a supported editor, this enables inline validation, error highlighting, keyword suggestions, autocompletion, and detailed documentation for each key. To specify the schema version, use the $schema key with the URL of the desired schema version. To reference the latest version (v2)

Field reference

changesets

An ordered list of change sets to apply. Each entry is a changeset.

changeset

Field	Type	Required	Description
name	string / number	Yes	Unique identifier for the change set. Allowed characters: letters, digits, ., _, -.
changes	array	Yes	List of changes to execute in order. Must contain at least one entry.

change

Each entry in changes must be exactly one of:

Type	Description
migrate	Loads NPL sources, applies rules or transformations. See migrate.
npl-run	Executes a protocol permission. See npl-run.

migrate

Executes a migration composed of one or more actions. At least one of sources, rules, or migrations must be provided.

Field	Type	Required	Description
sources	array of string	No	Paths to NPL source directories, relative to migration.yml.
migrations	array of string	No	Paths to Kotlin script state transformation files (.kts), relative to migration.yml.
rules	string	No	Path to a party automation rule descriptor file, relative to migration.yml.
contrib-libraries	array of string	No	Paths to zip files containing contribution libraries, relative to migration.yml.
run-only	array of string	No	Environment filter. See run-only.

npl-run

Executes a permission on a protocol.

Field	Type	Required	Description
protocol	string	Yes	Fully qualified or package-relative name of the protocol (e.g. pkg/Factory).
action	string	Yes	Name of the permission to execute.
arguments	array of string	No	Positional arguments passed to the permission, in order.
run-only	array of string	No	Environment filter. See run-only.

run-only

An optional list of environment labels that controls whether a change is executed. If the list is empty or absent, the change always runs. If one or more labels are listed, the change runs only when the migration is invoked with a matching label. This allows a single migration.yml to cover multiple environments (for example DEV, PROD).

Samples

Loading sources

$schema: https://documentation.noumenadigital.com/schemas/migration-schema-v2.yml

changesets:
- name: 1.0.0
  changes:
    - migrate:
        sources:
        - npl-1.0.0

Loading sources with applying rules

$schema: https://documentation.noumenadigital.com/schemas/migration-schema-v2.yml

changesets:
  - name: 1.0.0
    changes:
    - migrate:
        sources:
        - npl-1.0.0
        rules: rules/rules.yml

Loading sources, and applying transformation

$schema: https://documentation.noumenadigital.com/schemas/migration-schema-v2.yml

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

  - name: 1.0.1
    changes:
      - migrate:
          sources:
          - npl
          migrations:
          - kotlin-script/S0001_migration.kts

Migration using run-only

$schema: https://documentation.noumenadigital.com/schemas/migration-schema-v2.yml

changesets:
  - name: 1.0.0
    changes:
    - migrate:
        sources:
        - npl-1.0.0
    - npl-run:
        protocol: pkg/Factory
        action: create
        run-only:
        - DEV

  - name: 1.0.1
    changes:
      - migrate:
          sources:
          - npl
          migrations:
          - kotlin-script/S0001_migration.kts

Passing arguments to a permission

$schema: https://documentation.noumenadigital.com/schemas/migration-schema-v2.yml

changesets:
  - name: 1.0.0
    changes:
      - migrate:
          sources:
          - npl-1.0.0
      - npl-run:
          protocol: pkg/Factory
          action: createWithConfig
          arguments:
          - "production"
          - "42"

Loading contribution libraries

$schema: https://documentation.noumenadigital.com/schemas/migration-schema-v2.yml

changesets:
  - name: 1.0.0
    changes:
      - migrate:
          sources:
          - npl-1.0.0
          contrib-libraries:
          - libs/my-contrib.zip