Skip to main content

Expression Migrations

For each migration, the fromVersion: value must match the currently deployed version, and the toVersion: value must match the version currently being deployed.

Migrations will not be inferred between intermediate versions, for example it is not possible to supply a migration migration for versions 1 and 2 and versions 2 and 3 and for depot to automatically infer how to migrate between versions 1 and 3, instead a migration must be supplied for versions 1 and 3.

note

A migration from version 0 (i.e. no fromVersion) is only for initialising something that didn't exist before, the unset version is 1. That is, if a schema exists and has no version, is is version 1. If a schema doesn't exist at all it's version is effectively 0.

After the migration prepare step, a user-specified transform is applied against each migration target.

The transform is specified using a storage-independent DSL. At the top level, the document is an array of migration objects where:

  • target Required - name of the schema that will be modified
  • fromVersion Optional - source version of the schema, if unspecified this defaults to 0 (i.e. not present)
  • toVersion Required - target version of the schema
  • source Optional - if this is a newly created schema, the source schema from which records will be copied. If this is not a new schema, it is an error to specify anything other than the name of the target schema.
  • filter Optional - an expression that filters records from the source. If this is not a new schema, it is an error to specify anything other than true
  • properties Optional - a map of property name to expressions that will be used to populate newly added properties or transform existing properties, the expression is written in the scope of objects from the source schema as if it had not yet changed (i.e. with access to the old property names). It is only necessary to specify properties that need to be changed during the migration, other properties will be untouched if they existed previously or assume default values otherwise.

Example​

Given a schema as follows:

Person:
  type: object
  version: 1
  properties:
    name:
      type: string

And a change the schema as follows:

Person:
  type: object
  version: 2
  properties:
    firstName:
      type: string
    lastName:
      type: string

An example migration follows:

- target: Person
  fromVersion: 1
  toVersion: 2
  properties:
    firstName: name.split(" ")[0]
    lastName: name.split(" ")[1]

Use Cases​

The left sidebar lists various supported use cases for expression migrations.