# klei-migrate

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

Latest version **0.6.2** (published 2014-02-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install klei-migrate
pnpm add klei-migrate
yarn add klei-migrate
bun add klei-migrate
```

Provides the command `klei-migrate`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.6.2 |
| Published | 2014-02-12 |
| First published | 2013-09-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 39 |
| Author | Joakim Bengtson |
| Maintainers | joakimbeng |
| Keywords | migrate, migration, branching, git, coffee-script |

## Links

- npm: https://www.npmjs.com/package/klei-migrate
- Repository: http://github.com/klei/migrate
- Homepage: https://github.com/klei/migrate
- Issues: https://github.com/klei/migrate/issues
- npm.io page: https://npm.io/package/klei-migrate

## Dependencies (3)

- [nopt](https://npm.io/package/nopt.md) ~2.1.2
- [colors](https://npm.io/package/colors.md) ~0.6.2
- [klei-fs](https://npm.io/package/klei-fs.md) ~0.4.2

## Recent versions

- 0.6.2 (latest) — 2014-02-12
- 0.6.1 — 2013-12-06
- 0.6.0 — 2013-11-23
- 0.5.0 — 2013-11-23
- 0.4.2 — 2013-10-09
- 0.4.1 — 2013-09-17
- 0.4.0 — 2013-09-10
- 0.3.2 — 2013-09-09
- 0.3.1 — 2013-09-09
- 0.2.0 — 2013-09-08
- 0.1.1 — 2013-09-04
- 0.1.0 — 2013-09-04

## README

klei-migrate
==================

## Features

* Database independent migrations
* Can be used:
   * programatically as a local node module
   * from command line
   * as a gruntplugin with [grunt-klei-migrate](https://github.com/klei/grunt-klei-migrate) for [Grunt](http://gruntjs.com/)
* 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:

```bash
$ npm install -g klei-migrate
```

To use as a module from within your project:

```bash
$ npm install klei-migrate
```

And then:

```javascript
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**:

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

## Commands

### `new` or `create` - Create a new migration file

```bash
$ 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:

```bash
$ 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.

```bash
$ 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.

```bash
$ 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)*.

```bash
$ 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:

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

If installed as a local module:

```bash
#!/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)*.

```bash
$ 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.

---
_Source: https://npm.io/package/klei-migrate · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._