Miracle Migrate

Migration suite for RethinkDB, made for MiracleTV.

To start, create a file in your project root directory, called miracle-migrate.json. It has the following schema:

interface MiracleMigrateConfig {
  migrationDir: string;
  connection?: {
    host: string;
    port: number;
    database?: string;
};

Defining migrations

After setting it up, you can use $ miracle-migrate create-migration <name> to create a migration file. It will have two functions, named up and down (similar to knew migrations), that correspond to each individual migration being set up and dismantled.

Each function is supplied with two arguments: db, which is rethinkdb Db istance that you can use to manipulate database, as well as connection option that you can use to actually commit changes to the database. Both up and down expect a promise in return, so if you need to apply multiple alterations in a migrations, either chain them using .then, or wrap them in Promise.all([...]) to return a resolvable promise.

CLI use

To apply all unapplied migrations, you can use $ miracle-migrate up and to dismantle all current migrations, you can use $ miracle-migrate down. Additionally, you can supplement a filename to each of the commands if you wish to rollback to a particular state. Refer to $ miracle-migrate help to see more.

Programmatic use

Additionally, you can import doUp and doDown functions from the package if you wish to use migrations from within your own code (i.e. when starting a server, or to share your project's configuration without duplicating it in the miracle-migrate.json).

Both functions have following signatures:

(
  dbName: string,
  connectionOptions: rdb.ConnectionOptions,
  filename: string = "end"
) => void

Where dbName is the name of your database, and connectionOptions is an object representing your connection to rethinkdb instance. filename is an optional argument that allows you to upgrade or downgrade to a specific migration file.

Database alterations

To keep track of applied migrations and their checksums (in order to help avoid downgrading using a migration file that was altered post-migration), this script creates an additional table within your specified database, called miracle-migrations. Please be aware of this as you model your database structure to avoid collisions.