Node Generic Migrations
A promise-based generic migration library for Node.js >= 6
.
Why?
After looking for a simple migration library for a while, all I found were very opinionated
libraries with no support for promises that either forced a storage system or a directory structure
on you. Instead, generic-migrations
gives you a public interface with which you can define how
you load and store state, how you set up and tear down your environment and all your migrations.
Whether you use separate files in a directory or not, store state in a file or in a database, or
any other detail is completely up to you.
Installation
$ npm install --save generic-migrations
Example
import migrations from 'generic-migrations'; const migr = migrations({ async setup (context) { /* connect to your DB, etc. */ context.db = await connectToDatabase(); }, async teardown (context) { /* close DB connection, etc */ await context.db.close(); }, async loadState (context) { /* load your state */ return await context.db.findOne(/* ... */); }, async saveState (context, state) { /* save your state */ await context.db.replaceOne(/* ... */); },}); /* For each version ... */migr.define(1, 'first-migration', { async upgrade (context) { /* Upgrade to version 1 */ }, async downgrade (context) { /* Downgrade from version 1 */ },}); /* Run the migrations */(async () => { migr.upgrade();});
API
createMigration(functions)
(default export)
Creates a new empty Migration
with the given lifecycle functions
.
functions
: Object with the following attributes:setup(context)
: (Optional) Function that sets up your environment, returns a Promise. Thecontext
attribute is an object that will be passed around for all user-defined functions; modify it at will.teardown(context)
: (Optional) Function that tears down your environment, returns a Promise. Thecontext
attribute is the same as the one given tosetup
.loadState(context)
: (Optional) Function that loads the state, returns a Promise to the state. The promise might resolve tonull
orundefined
if no state is available. Thecontext
attribute is the same as the one given tosetup
.saveState(context, state)
: (Optional) Function that saves the state, returns a Promise. Thecontext
attribute is the same as the one given tosetup
; thestate
argument should be stored unmodified in whatever storage system you want.
Migration#define(version, name, functions)
Defines a new version for your migration.
version
: Integer defining the version. Must be unique for this migration.name
: Migration name. Used only for logging and other human-oriented processes.functions
: Object with the following attributes:upgrade(context)
: Function that performs an upgrade to this version, returns a Promise. Thecontext
attribute is the same as the one given tosetup
.downgrade(context)
: Function that performs a downgrade from this version, returns a Promise. Thecontext
attribute is the same as the one given tosetup
.
Migration#upgrade(targetVersion = +Infinity)
Performs an upgrade to targetVersion
. Returns a promise that will resolve to the last version
that was upgraded to. See the section on error handling for more information.
-
targetVersion
: Target version for the upgrade. If not provided, upgrades to the latest defined version.Note that the saved state will remember only the last version up to the latest defined one. For example, if only versions
1
and5
are available and you callupgrade(10)
, the current version will be5
, and later adding versions3
and7
will trigger an upgrade for version7
but not3
.
Migration#downgrade(targetVersion = -Infinity)
Performs a downgrade to targetVersion
. Returns a promise that will resolve to one less than the last version that was downgraded from. See the section on error handling for more information.
-
targetVersion
: Target version for the downgrade. If not provided, downgrades to the earliest defined version.Note that the saved state will remember only the last version up to the earliest defined one. For example, if only versions
4
and6
are available and you calldowngrade(0)
, the current version will be3
, and later adding versions1
and5
will trigger an downgrade for version1
but not6
.
Error Handling
TODO