A migration tool for node.js
JavaScript CoffeeScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
assets
bin
lib
tests
.gitattributes
.gitignore
.travis.yml
CHANGELOG.md
README.md
index.js
package.json

README.md

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.