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.
It is based on umzug by Sequelize.
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 |
npm i express-umzug
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
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
Add additional notes about how to deploy this on a live system
To be updated.
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.
We use SemVer for versioning. For the versions available, see the tags on this repository.
This project is licensed under the MIT License - see the LICENSE.md file for details