A mongoose based migration framework for node with Typescript support
npm install migrate-mongoose-typescript#### Motivation
migrate-mongoose-typescript is a migration framework for projects which are already using mongoose and need typescript support
Most other migration frameworks:
- Use a local state file to keep track of which migrations have been run: This is a problem for PaS providers like heroku where the file system is wiped each time you deploy
- Not configurable enough: There are not a granular enough controls to manage which migrations get run
- Rely on a document-level migration: You have to change your application code to run a migration if it hasn't been run on a document you're working with
migrate-mongoose-typescript:
- Stores migration state in MongoDB
- Provides plenty of features such as
- Access to mongoose models in migrations
- Use of promises or standard callbacks
- custom config files or env variables for migration options
- ability to delete unused migrations
- Relies on a simple GLOBAL state of whether or not each migration has been called
- Can write your migrations in Typescript files
npm install migrate-mongoose-typescript
and then run
./node_modules/.bin/migrate [command] [options]
#### or
Install it globally
npm install -g migrate-mongoose-typescript
and then run
migrate [command] [options]
$3
Usage: migrate -d [[create|up|down]|list|prune] [optional options]Commands:
list Lists all migrations and their current state.
create Creates a new migration file.
up [migration-name] Migrates all the migration files that have not yet
been run in chronological order. Not including
[migration-name] will run UP on all migrations that
are in a DOWN state.
down Rolls back all migrations down to given name (if down
function was provided)
prune Allows you to delete extraneous migrations by
removing extraneous local migration files/database
migrations.
Options:
-d, --dbConnectionUri The URI of the database connection [string] [required]
--collection The mongo collection name to use for migrations [string] [default: "migrations"]
--es6 use es6 migration templates? [boolean]
--md, --migrations-dir The path to the migration files [string] [default: "./migrations"]
-t, --template-file The template file to use when creating a migration [string]
-c, --change-dir Change current working directory before running anything [string]
--autosync Automatically add any migrations on filesystem but not in db to db [boolean]
rather than asking interactively (use in scripts)
-h, --help Show help [boolean]
Examples:
node_modules/.bin/migrate list -d mongodb://localhost/migrations
node_modules/.bin/migrate create add_users -d mongodb://localhost/migrations
node_modules/.bin/migrate up add_user -d mongodb://localhost/migrations
node_modules/.bin/migrate down delete_names -d mongodb://localhost/migrations
node_modules/.bin/migrate prune -d mongodb://localhost/migrations
node_modules/.bin/migrate list --config settings.json
#### Setting Options Automatically
If you want to not provide the options such as
to the program every time you have 2 options.1. Set the option as an Environment Variable with the prefix MIGRATE_
Using a Javascript file:
`javascript
//index.js
export MIGRATE_dbConnectionUri=localhost/migrations
`
.env files are also supported:
bash
#.env
MIGRATE_dbConnectionUri=localhost/migrations
`
2. Provide a config file (defaults to migrate.json or migrate.js)
bash
If you have migrate.json in the directory, you don't need to do anything
migrate list
Otherwise you can provide a config file
migrate list --config somePath/myCustomConfigFile[.json]
`
$3
Command line args _beat_ Env vars _beats_ Config FileJust make sure you don't have aliases of the same option with 2 different values between env vars and config file
#### Migration Files
Here's how you can access your
models and handle errors in your migrationsES5 Example
`javascript
'use strict';var lib = require('myLibrary');
/**
* Make any changes you need to make to the database here
*/
exports.up = function up (done) {
return lib.doSomeWork().then(function() {
// Don't forget to call done() or the migration will never finish!
done();
})
.catch(function(error){
// If you get an error in your async operations you can call done like so
done(error);
});
// Throwing errors also works
throw new Error('It should never get here!');
};
/**
* Make any changes that UNDO the up function side effects here (if possible)
*/
exports.down = function down(done) {
lib.undoAboveWork().then(function() {
done();
})
.catch(function(error){
done(error);
});
};
`ES6 Example
javascript
/**
* Easy flow control
*/
// Notice no need for callback
export async function up() {
// Error handling is as easy as throwing an error
if (condition) {
throw new Error('This is an error. Could not complete migration');
}
// You can just run your updates and when function finishes the migration is assumed to be done!
await new Promise((resolve, reject) => {
setTimeout(()=> { resolve('ok'); }, 3000);
});
// ======== OR ===========
// just return the promise! It will succeed when it resolves or fail when rejected
return lib.getPromise();
}
`
Access to mongoose models
javascript
// Lets say you have a user model like this// models/User.js
const UserSchema = new Schema({
firstName: String,
lastName: String,
});
module.exports = mongoose.model('user', UserSchema);
// 1459287720919-my-migration.js
export async function up() {
// Then you can access it in the migration like so
await this('user').update({}, {
$rename: { firstName: 'first' }
}, { multi: true });
// Or something such as
const users = this('user').find();
/ Do something with users /
}
`
$3
Currently, the -d/dbConnectionUri must include the database to use for migrations in the uri.
example:
. If you don't want to pass it in every time feel free to use the
migrate.json` config file or an environment variable