node-migrate state storage for MongoDB
This is a state storage implementation for the node-migrate
framework. It will store your migation state in a MongoDB collection called migrations
which contains a single document.
In case you’re using node-migrate
for migrating your MongoDB, it makes sense to keep the state within the database itself, instead of a separate file which is used by node-migrate
per default.
Installation
$ yarn add @nodepit/migrate-state-store-mongodb
Usage
Either create a wrapper script such as run-migrations.ts
which calls the migration API like so:
import * as migrate from 'migrate';
import { MongoStateStore } from '@nodepit/migrate-state-store-mongodb';
migrate.load({
stateStore: new MongoStateStore(MONGODB_HOST),
// further configuration …
}, (err, set) => {
// your code …
});
Per default, the migrations are stored in a collection called migrations
. If you want to customize the collection name, instantiate the MongoStateStore
with an object instead:
new MongoStateStore({ uri: MONGODB_HOST, collectionName: 'custom-migrations-collection' });
Synchronization
If you’re running in a clustered environments with more than one node, there will likely be concurrency issues when more than one node tries to run a migration (also see here). The plugin provides a locking mechanism which ensures that only one node can run migrations at a given time (and other ones will just wait until the migration has finished). For this, initialize MongoStateStore
with a lockCollectionName
:
new MongoStateStore({
uri: MONGODB_HOST,
collectionName: 'migrations',
lockCollectionName: 'migrationlock'
});
… then use the synchronizedUp
function instead of calling migrate.load
and set.up
directly to ensure that the migration is only run on one instance at a time:
import { MongoStateStore, synchronizedUp } from '@nodepit/migrate-state-store-mongodb';
await synchronizedUp({ stateStore: mongoStateStore });
CLI Usage
Alternatively, you can also pass the store on the migrate
CLI using the --store
flag. For that, create a a file which has as default export a configured subclass with a zero-arg constructor of the MongoStateStore
. See here for details. You can then call migrate up --store=./my-store.js
. Locking is not available in this case.
Development
Install NPM dependencies with yarn
.
To execute the tests, run the test
task.
For the best development experience, make sure that your editor supports ESLint and EditorConfig.
Releasing to NPM
Commit all changes and run the following:
$ npm login
$ npm version <update_type>
$ npm publish --access public
… where <update_type>
is one of patch
, minor
, or major
. This will update the package.json
, and create a tagged Git commit with the version number.
Contributing
Pull requests are very welcome. Feel free to discuss bugs or new features by opening a new issue.
Copyright nodepit.com, 2018 – 2023.