@hashicorp/dato-migration-gen

dato-migration-gen

This tool allows you to generate a Dato migration template & timestamped Dato migration file by providing a migrationSpec

It is a small Node-based CLI which wraps datocms-client to accomplish the above.

How to use

dato-migration-gen create [--name=<Name for Dato migration>] [--path=<Path to migrationSpec file>]

What does it do?

The create command will:

1. Generate a migration template file for use with Dato CLI
2. Run dato new migration with the migration name and generated template, thereby creating a timestamped Dato migration file.

Background

Our larger, more complex migrations need the following defined upfront in order to smooth the process:

• A target model - or multiple target models - these exist on Dato already and where you have records (data) to migrate
• A destination model (NEW ✨, created and iterated on within Dato admin UI)

Scripting Concepts

This scripts generated by the CLI set up a workflow to more easily leverage Dato's CLI and JS API client (datocms-client) for migrations.

What is a migrationSpec?

A migrationSpec is an object which you create in reference how the migration should proceed. This object should specify the following keys listed below to capture migration concepts in code and create a simpler workflow for migrations.

The goal is to create a workflow where developers should only need to create migrationSpecs and assume the generated script will update records or migrate records successfully where possible, as well as produce a sensible log of errors if any occur during a given dato migrate ... run.

targetModelApiKey

The current apiKey of this existing, "target" model. This is the model of the records being migrated.

It's worth noting that this model's apiKey (modelApiKey) value is consistent across Dato environments when forked, unlike the model's id.

destinationModelApiKey

The current apiKey of the destination model. This is the model to which records will be migrated.

This apiKey (modelApiKey) value is consistent across Dato environments when forked, unlike the model's id.

migrateAllRecords

An optional flag as to whether the script should migrate all records of the target model. This is helpful to use while verifying migration scripts. Set to true when running the final migration to migrate ALL records.

dataMigrations

An array of objects which document the migration of a record's data. A dataMigration object documents the following:

key	type	required	description
target	string	No	The field apiKey at which to get current data as it stands on the existing record, if not provided we assume usage of destination and transform will provide default values
destination	string	No	The field apiKey as it exists on the destination model - this must be camelCased since we're creating records. If destination is not provided, scripts should assume target is sufficient, a one-to-one migration of the data as the field apiKey for said data is assumed to be the same
transform	function	No	A function to run and transform current data to the desired format when targeting destination. This function will be passed the current value of the data at target on the record being migrated as well as the return value of your createContext function

createContext

You may optionally specify a createContext function for this model. This function can be async and is passed the Dato client as its only argument. The return value of createContext will be passed as the second argument to every transform function defined in dataMigrations for this migrationSpec