A node based migration framework for ESM for mongoose
migrate-mongoose is a migration framework for projects which are already using mongoose.
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:
- 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
You can install it locally in your project
npm install @eventonehq/migrate-mongoose
and then run
npx migrate [command] [options]
Install it globally
npm install -g @eventonehq/migrate-mongoose
and then run
migrate [command] [options]
Usage: migrate -d <mongo-uri> [[create|up|down<migration-name>]|list|prune] [optional options]
Commands:
list Lists all migrations and their current state.
create <migration-name> 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 <migration-name> 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"]
--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:
migrate list -d mongodb://localhost/migrations
migrate create add_users -d mongodb://localhost/migrations
migrate up add_user -d mongodb://localhost/migrations
migrate down delete_names -d mongodb://localhost/migrations
migrate prune -d mongodb://localhost/migrations
migrate list --config settings.json
If you want to not provide the options such as --dbConnectionUri to the program every time you have 2 options.
export MIGRATE_dbConnectionUri=localhost/migrations
.env files are also supported. All variables will be read from the .env file and set by migrate-mongoose.
#.env
MIGRATE_dbConnectionUri=mongodb://localhost:27017/mydb# 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.jsonCommand line args beat Env vars beats Config File
Just make sure you don't have aliases of the same option with 2 different values between env vars and config file
By default, migrate-mongoose assumes your migration folder exists.
Here's an example of a migration created using migrate create some-migration-name . This example demonstrates how you can access your mongoose models and handle errors in your migrations
/**
* 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()
}Just go about your business as usual, importing your models and making changes to your database.
migrate-mongoose makes an independent connection to MongoDB to fetch and write migration states and makes no assumptions about your database configurations or even prevent you from making changes to multiple or even non-mongo databases in your migrations. As long as you can import the references to your models you can use them in migrations.
Below is an example of a typical setup in a mongoose project
import { Schema, model } = from 'mongoose'
const UserSchema = new Schema({
firstName: String,
lastName: String
})
export const UserModel = model('user', UserSchema)import { connect } = from 'mongoose'
import { UserModel } from './user.model.js'
connect('mongodb://localhost:27017/mydb')
export { UserModel }import { UserModel } from '../models/index.js'
export async function up() {
// Then you can use it in the migration like so
await UserModel.create({ firstName: 'Ada', lastName: 'Lovelace' })
// OR do something such as
const users = await UserModel.find()
/* Do something with users */
}If you're using the package programmatically. You can access your models using the connection you constructed the Migrator with through the this context.
export async function up() {
// "this('user')" is the same as calling "connection.model('user')" using the connection you passed to the Migrator constructor.
//
await this('user').create({ firstName: 'Ada', lastName: 'Lovelace' })
}Currently, the -d/dbConnectionUri must include the database to use for migrations in the uri.
example: -d mongodb://localhost:27017/development .
If you don't want to pass it in every time feel free to use the migrate.json config file or an environment variable
Feel Free to check out the examples in the project to get a better idea of usage
- Start an issue. We will discuss the best approach
- Make a pull request. I'll review it and comment until we are both confident about it
- I'll merge your PR and bump the version of the package