Express Umzug

This middleware creates a series of endpoints to help you monitor and manage your database migrations when it's pushed to production. It's useful when you run your application on Cloud Native Platforms such as Cloudfoundry, ElasticBeanstalk, AWS ECS, Nomad, Kubernetes, Openshift, Heroku etc. and you are in need of endpoints for administering schema migrations.

Getting Started

It is based on umzug by Sequelize.

Endpoints

| Endpoint ID | Description | | ---- | ---- | | GET migrations/all | Getting all migrations (Combining output of executed and pending) | | GET migrations/pending | Getting all pending migrations | | GET migrations/executed | Getting all executed migrations | | POST migrations/up| Executing pending migrations | | POST migrations/up/:id | Executing pending migrations upto specific migration id | | POST migrations/up/step/:count | Executing pending migrations up till pecific steps | | POST migrations/down | Reverting executed migration | | POST migrations/down/:id | Reverting executed migrations down to specific migration id | | POST migrations/down/step/:count | Reverting executed migrations down till specific steps |

Download Postman Collection

Installing

npm i express-umzug

Usage

Using express-umzug is really simple. You'd import it just as other packages, invoke the instance, and apply it as a middleware to your Express app instance. For example:

const express = require("express");
const { expressUmzug, SequelizeStorage } = require("express-umzug");
const sequelize = require("./path/to/your/sequelize/instance"); // usually "./models/"
const { Sequelize } = require("sequelize");
const app = express();

app.use(expressUmzug({
  secretKey: "<your_secret_key>" // make sure not to share this key
  umzugOptions: {
    context: sequelize.getQueryInterface(), // required for express-umzug to work
    storage: new SequelizeStorage({ sequelize }), // your migration storage mechanism (you can check the source code to look at the available storage types)
    basePath: "/development", // you can change this to a custom base path of your choice (by default - an empty string i.e. no base path),
    migrations: {
      // change according to your migration path
      glob: "/migrations/*.js",
      // you'd need to pass down a function to `resolve` field which hijacks
      // the migrations and passes down the correct sequelize instance and the
      // Sequelize class. Expect it to break if you don't pass the function
      resolve: ({ name, path, context }) => {
        const migration = require(path);
        return {
          name,
          up: async () => migration.up(context, Sequelize),
          down: async () => migration.down(context, Sequelize),
        };
      }
    },
    logger: console // you can optionally pass a logger too
  },
}));

// rest of the code...

For express-umzug to work, the options argument requires a secretKey string to be passed in. You'd then add the same secret key in x-secret-key header of you request. This secret key is not supposed to be committed in the code. Keep it somewhere hidden. options also requires umzugOptions to be passed in. This is the options object that is intrinsically passed into umzug constructor.

Currently, only the sequelize ORM is supported.

Once set up, you can use any HTTP client (e.g. cURL, Postman, Insomnia, etc.) to access the endpoints to manage you migrations. Refer to Endpoints for all the available endpoints and their use cases. For example, hitting migrations/all endpoint will give you all the executed and pending migrations.

curl -H "x-secret-key: <your_secret_key>" https://example.com/migrations/all

Running the tests

You can run the tests using npm test command:

npm test

To check the test coverage, execute:

jest --coverage

If you have jest globally installed on your system

OR

npx jest --coverage

If you don't have jest globally installed on your system

Deployment

Add additional notes about how to deploy this on a live system

Built With

To be updated.

Contributing

We currently don't allow other developers to contribute to this project. Once the project becomes more mature, we'll open the doors for contributions. Keep checking this space.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Dishant Pandya - Initial work - Openxcell
• Dhwanik Panchal - Initial work - Email

License

This project is licensed under the MIT License - see the LICENSE.md file for details