Migrations

MasterRecord migrations compare your entity definitions against a saved snapshot, generate the SQL to reconcile them, and apply it in order. You get version-controlled schema changes with up/down support across SQLite, MySQL, and PostgreSQL.

The workflow#

$ # 1. one-time: create the snapshot
$ masterrecord enable-migrations AppContext
$ 
$ # 2. generate a migration from current models
$ masterrecord add-migration InitialCreate AppContext
$ 
$ # 3. apply pending migrations
$ masterrecord update-database AppContext
$ 
$ # roll back the most recent migration
$ masterrecord update-database-down AppContext

Inside a Master app, use the friendlier wrapper:

$ master db enable
$ master db new InitialCreate
$ master db migrate
$ master db rollback

What a migration looks like#

Generated migrations are plain ESM with up() and down() methods built on the schema API. Review and edit them before applying:

import masterrecord from 'masterrecord';

class InitialCreate extends masterrecord.schema {
  constructor(context) { super(context); }

  async up(table) {
    await this.init(table);
    await this.createTable(table.User);
    await this.createTable(table.Post);
  }

  async down(table) {
    await this.init(table);
    await this.dropTable(table.Post);
    await this.dropTable(table.User);
  }
}

export default InitialCreate;

Evolving the schema#

Change a model — add a field, an index, or a relationship — then generate another migration. MasterRecord diffs against the snapshot and emits just the delta (add column, create index, etc.).

$ master db new AddViewsToPost
$ master db migrate

Migration tracking#

Applied migrations are recorded in a _masterrecord_migrations table, so update-databaseruns only what’s pending and is safe to re-run (idempotent).

CLI command reference#