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)

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