# cultivator

> A mongodb migration tool.

Latest version **0.0.1** (published 2018-02-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install cultivator
pnpm add cultivator
yarn add cultivator
bun add cultivator
```

## Health

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

Positive: no vulnerabilities.

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

Negative: insecure dependencies; abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.1 |
| Published | 2018-02-23 |
| First published | 2018-02-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 32.6 KB |
| Known vulnerabilities | 0 (+10 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Stehpen Parker |
| Maintainers | hvhallmann |
| Keywords | migration, mongodb, rollback, automatic |

## Links

- npm: https://www.npmjs.com/package/cultivator
- Repository: https://github.com/agco/cultivator
- Homepage: https://github.com/agco/cultivator#readme
- Issues: https://github.com/agco/cultivator/issues
- npm.io page: https://npm.io/package/cultivator

## Dependencies (5)

- [lodash](https://npm.io/package/lodash.md) 4.17.4
- [mongodb](https://npm.io/package/mongodb.md) 2.2.22
- [bluebird](https://npm.io/package/bluebird.md) 3.4.7
- [require-directory](https://npm.io/package/require-directory.md) 2.1.1
- [mongodb-migrations](https://npm.io/package/mongodb-migrations.md) git+https://github.com/agco/agco-mongodb-migrations.git#61f9c520f77f6cd6af73df75de6921dd1192bd85

## Alternatives

- [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads
- [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads
- [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads
- [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads
- [@temporal-architect/claude-plugin](https://npm.io/package/@temporal-architect/claude-plugin.md) — 335 weekly downloads

## Recent versions

- 0.0.1 (latest) — 2018-02-23

## README

# cultivator

A tool for managing infrastructure migrations and, when errors occur, rollback changes. The current migration version
is stored in MongoDB and not in the local file-system, so it can be used with Heroku. It's also designed to be run from
Heroku's [release-phase](https://devcenter.heroku.com/articles/release-phase).

At a high level:

1. Scripts are created and stored in a migrations directory. (this directory is configurable, defaults to 
   `./migrations`)
2. Each script has `up` and `down` functions, that can do anything a script can do. Seed data, add indexes, provision
   new databases, etc..
3. Each script also contains an `id`, which is a `number` that represents the version of this script, used to help with
   ordering the execution of scripts.
3. Assuming your application version is at **123** A call to `Cultivator.run({ dbUrl: 'localhost/test', targetVersion:
   124 })` from your app, will *"migrate up"* to version **124**.
4. Similarly, assuming your application is now at version **124** a call to `Cultivator.run({ dbUrl: 'localhost/test',
   targetVersoin: 123})` from you app, will *"rollback"* to version **123*.


## Installation

Using `npm` from the CLI, download th module and add it to your `package.json` file.

```
$ npm i cultivator -S
```


## Usage

Cultivator can only be `required` as a `module` into an existing application. See the `example`
directory for example migration scripts. Or look over the `test` directory for additional usage.


### The programmatic usage


From within your application.

```
// require the package
const cultivator = require('cultivator')


// define some configuration options
const options = {
    dbUrl: 'mongodb://localhost/test',   // requried - full MongoDB URL
    targetVersion: 1,                    // requried - the version to migrate to
    collection: 'changelog',             // defaults to '_migrations'
    directory: './migratoins'            // defaults to './migrations'
}
    
// start a migration
cultivator.run(options)
    .then(result => {
        // success
        console.log(result.code, result.message)
    })
    .catch(error => {
        // migration failure, 
        console.log(error.error, error.message)
    })
```

The migration scripts must return a promise, where a resolved promise is a successful migration, and a rejected promise
is a failed migration. If a migration fails, it is the responsibility of the script to "undo" any partial migration.


## The configuration object

The run function takes a configuration object for additional customization. The keys are:

  * `dbUrl`  [`string`, required] full MongoDB connection URL
  * `targetVersion` [`number`, required] The **version** to migrate to, can be `up` or `down` from the current version.
  * `directory`  [`string`, optional, defaults to `./migrations`] The directory where the migration scripts are found. 
  * `collection`  [`string`, optional, defaults to `_migrations`] The MongoDB collection that stored the changelog of 
    scripts that have already been successfully executed.


## The Scripts

The scripts for migrating and rolling back are stored in the `migrations` folder (configured above). They are standard node.js
modules that export an object that contains two functions, `migrate` and `rollback`. These functions take no arguments and return
a promise, indicating success or failure.

```
module.exports = {
    id: 1,
    up: () => {
        ...
        return Promise.resolve('done')
    },
    down: () => {
        ...
        return Promise.resolve('done')
    }
}
```

These scripts run standard javascript, so the possibilities of what can be managed is virtually limitless. Good 
candidates are Seeding additional Data and managing indexes.

The script files can be names anything you like. The `id` key is used for ordering when a script should be run. If the
application is at version **42** the `up` script of version **43** would be run next. In the case of a rollback, the 
`down` script of version **43** would be run to return the application to version **42**.

Breaking large migrations into multiple scripts can make handling errors and rolling back a little easier.


## Testing

In order to run the tests, you need to have:

1. An instance of mongodb running at `localhost:27017`.

Tests can be run from `npm` like so:

```
$ npm test
```

These tests will add a database to MongoDB called `cultivator-test-db`.


## PRIOR ART

This module encapsulates
   * https://github.com/emirotin/mongodb-migrations

It was also inspired by:
   * https://github.com/flashstockinc/mongoose-data-migrate
   
which is a fork of
   * https://github.com/madhums/mongoose-migrate

which is a fork of
   * https://github.com/tj/node-migrate


## Road Map

This is quite functional in it's current form but could be made even better:

1. Add CLI support to run migrations and auto-generate stub migrations file.
2. Allow for pre and post scripts for a target version.

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