klei-migrate

A database independent migration tool which support different migrations in different git branches

npm install klei-migrate
2 downloads in the last day
10 downloads in the last week
72 downloads in the last month

klei-migrate

Features

  • Database independent migrations
  • Can be used:
  • Handling different migration versions in different branches with:
    • automatic migration synchronization when used as a post-checkout hook for git
  • Environment dependent migration history
    • e.g. have a separate test database with its own migration history
  • Write migrations in coffee-script
    • N.B. klei-migrate does not depend on coffee-script itself, your project must have the module installed for it to work
  • Migration template (used when creating new migrations)
    • Can be set in a klei-migrate.json config file in cwd when running klei-migrate

Installation

To use from command line:

$ npm install -g klei-migrate

To use as a module from within your project:

$ npm install klei-migrate

And then:

var migrate = require('klei-migrate');

Configuration

klei-migrate looks for a klei-migrate.json configuration file in cwd (current working directory) when it is run.

The configuration options that can be set via the klei-migrate.json is:

  • template - Path to template to use when creating new migrations (a path relative to the config-file location)
  • timeout - Set default timeout for all migrations in seconds
  • env - Set default environment when running migrations
  • directory - Set directory where you have your migration files (and the .migrated.json status file)
  • coffee - Set default coffee-script mode

Example file:

{
  "directory": "migs",
  "template": ".migration.tpl.coffee",
  "coffee": true,
  "env": "stage",
  "timeout": 600
}

Commands

new or create - Create a new migration file

$ klei-migrate new [options] Your Migration Name

# or

$ klei-migrate create ...

Generates a migration file with name: <Unix Timestamp>_Your_Migration_Name.js in migrations/.

If no name is provided, like so:

$ klei-migrate new

The generated name will be: <Unix Timestamp>_migration.js.

Options:

  • --template - Can be used to set path to the template to use when creating the migration
  • --coffee - If set the migration file created will have .coffee extension instead of .js

dry or status - Show what is possible to migrate

Shows a list of possible migrations to run.

$ klei-migrate dry [options] [arguments]

Options:

  • --up or -u - If provided forces an up migration (default)
  • --down or -d - If provided forces an down migration
  • --limit or -l - Limits number of migrations to run to given number
  • --one - The same as --limit 1
  • --env or -e - Set environment name
  • --coffee - Activate coffee-script mode

Arguments:

  • name - Any given extra parameters is used to limit the migration list by name
    • If combined with --one the migration list is limited to only the provided name, even though it's not the next in line to be run

run - Run migrations

Runs all migrations, according to provided options, and stops when everything is done or when a migration has failed.

$ klei-migrate run [options] [arguments]

Options:

  • --up or -u - If provided forces an up migration (default)
  • --down or -d - If provided forces an down migration
  • --limit or -l - Limits number of migrations to run to given number
  • --one - The same as --limit 1
  • --timeout or -t - Limit migration execution timeout (per migration) to given number in seconds
  • --env or -e - Set environment name
  • --coffee - Makes klei-migrate look for migration files with .coffee extension instead of .js

Arguments:

  • name - Any given extra parameters is used to limit the migrations to run by name
    • If combined with --one only the migration with the given name is run, even though it's not the next in line

sync - Manual sync after switching branch

Reverts all migrations from provided branch that does not exist in current branch, and migrates all unmigrated migrations in current branch (used internally for post-checkout command, see below).

$ klei-migrate sync [arguments]

Options:

  • --timeout or -t - Limit migration execution timeout (per migration) to given number in seconds
  • --env or -e - Set environment name
  • --coffee - Run coffee-script migrations

Arguments:

  • fromBranch - The branch where klei-migrate should look for migrations to migrate down

post-checkout - Automatic sync after switching branch (if used as git hook)

How to use as a git checkout hook:

Create a file .git/hooks/post-checkout with the following contents:

If klei-migrate is installed globally:

#!/usr/bin/env sh
klei-migrate post-checkout "$@"

If installed as a local module:

#!/usr/bin/env sh
node_modules/.bin/klei-migrate post-checkout "$@"

Reverts all migrations from provided branch that does not exist in current branch, and migrates all unmigrated migrations in current branch (used internally for post-checkout command, see below).

$ klei-migrate post-checkout [arguments]

Options:

  • --timeout or -t - Limit migration execution timeout (per migration) to given number in seconds
  • --env or -e - Set environment name
  • --coffee - Run coffee-script migrations

Arguments:

  • fromRef - Set by git The git hash for the branch where klei-migrate should look for migrations to migrate down
  • toRef - Set by git The current branch git hash
  • flag - Set by git Is set to 1 for a branch checkout and 0 on a file checkout

Stored migration progress/history

Which migrations that has been run is stored in migrations/.migrated.json, so be sure to add it to your .gitignore.

The .migrated.json file takes the current environment name into account, so that you can have e.g. a separate test database with its own migration history.

npm loves you