A tool for executing DB migrations based on Sequelize and Umzug. Safely executes migrations among distributed, synchronously launched server instances, by acquiring a greedy lock on a migration table.

Downloads in past


500.0.4a year agoa year agoMinified + gzip package size for db-migrator-distributed in KB


A tool for executing DB migrations based on Umzug ( and Sequelize). Coming support for Firestore migrations...
The tool is safely executing migrations among distributed, synchronously launched server instances, by acquiring a greedy lock on a migration table.

Production tested

The tool has been tested and currently used in production env of one project.
It has been successfully tested with up to 6 simultaneously deployed instances.
Currently only tested with Postgres sequelize connection.
Getting started
  1. Install the package:

npm i db-migrator-distributed

  1. In the file where you want to execute the migrations (usually the starting point of your server), import the lib and
instantiate the migrator:
import DbMigrator from 'db-migrator-distributed';

const dbMigrator = new DbMigrator({ sequelizeConnection: mySequelizeConn });
try {
  await dbMigrator.run();
} catch (err) {
  process.exit(1); // migrations were unsuccessful

  1. Set up your migration files dir and structure. The most typical one would be to have the /migrations dir hold your
migrations and put it right under the root source files dir, eg: `myProject/src/migrations`. Otherwise, you can
specify the dir path in the init params of the DbMigrator constructor (see below for full list of possible params).

List possible init params

  • sequelizeConnection {Sequelize} (mandatory) The Sequelize connection instance that you use to connect to your DB

  • migrationsTable {string} (optional) The DB table where Umzug keeps track of the executed migrations so far.
Default: '_migrations'
  • migrationsLockTable {string} (optional) The DB table that is going to be used for acquiring the migrations
lock. Default: '_migrations_lock'
  • lockTimeoutSeconds {number} (optional) The time (in seconds) after which locks should expire.
Default: 60
  • migrationsDirPath {string} (optional) The dir path where you store your migrations files.
Default: 'dist/migrations'. If you don't use Typescript or a separate /dist dir for the compiled TS files, then dist won't make sense for you.
  • migrationFilesPattern {RegEx | string} (optional) The regex by which Umzug will determine whether a file in your
migrations dir is an actual migration file that is to be executed. Default: /^\d+[\w-_]+\.js$/ . This would match for example 20200330092617-create-users-table.js
  • extraMigrationFuncParams {any[]} (optional) Params, values, objects that you want to pass to your up()
and down() migrations execution functions. By default, the first two params will be the Sequelize queryInterface and the Sequelize instance.
  • loggger {any} (optional) A logger that you want to use that the migrator will also use to log events. The default
one is bunyan and it's set up to log to the console, so you don't have to provide anything, if you wish.
  • Finish support of Firestore migrations
  • Add support for rollback functionality
  • Test for other dialects, eg. MySQL