blormig v1.0.2
Blormig
A Migration tools for nodejs and Blorm ORM
blormig is a framework-agnostic migration tool for Node. It provides a clean API for running and rolling back tasks.
Highlights
- Written in TypeScript - you have built-in typings and auto-completion right in your IDE
- Programmatic API for migrations
- Database agnostic
- Supports logging of migration process
- Supports multiple storages for migration data
Documentation
Minimal Example
The following example uses a Sqlite database through blorm and persists the migration data in the database itself through the blorm storage.
index.js
:
const { Blorm } = require('blorm');
const { Blormig } = require('blormig');
const blorm = new Blorm({ dialect: 'sqlite', storage: './db.sqlite' });
const blormig = new Blormig({
migrations: {
path: './migrations',
params: [
blorm.getQueryInterface()
]
},
storage: 'blorm',
storageOptions: { blorm }
});
(async () => {
// Checks migrations and run them if they are not already applied. To keep
// track of the executed migrations, a table (and blorm model) called BlormMeta
// will be automatically created (if it doesn't exist already) and parsed.
await blormig.up();
})();
migrations/00_initial.js
:
const { Blorm } = require('blorm');
async function up(queryInterface) {
await queryInterface.createTable('users', {
id: {
type: Blorm.INTEGER,
allowNull: false,
primaryKey: true
},
name: {
type: Blorm.STRING,
allowNull: false
},
createdAt: {
type: Blorm.DATE,
allowNull: false
},
updatedAt: {
type: Blorm.DATE,
allowNull: false
}
});
}
async function down(queryInterface) {
await queryInterface.dropTable('users');
}
module.exports = { up, down };
Usage
Installation
Blormig is available on npm:
npm install blormig
Blormig instance
It is possible to configure an Blormig instance by passing an object to the constructor.
const { Blormig } = require('blormig');
const blormig = new Blormig({ /* ... options ... */ });
Executing migrations
The execute
method is a general purpose function that runs for every specified migrations the respective function.
const migrations = await blormig.execute({
migrations: ['some-id', 'some-other-id'],
method: 'up'
});
// returns an array of all executed/reverted migrations.
Getting all pending migrations
You can get a list of pending (i.e. not yet executed) migrations with the pending()
method:
const migrations = await blormig.pending();
// returns an array of all pending migrations.
Getting all executed migrations
You can get a list of already executed migrations with the executed()
method:
const migrations = await blormig.executed();
// returns an array of all already executed migrations
Executing pending migrations
The up
method can be used to execute all pending migrations.
const migrations = await blormig.up();
// returns an array of all executed migrations
It is also possible to pass the name of a migration in order to just run the migrations from the current state to the passed migration name (inclusive).
await blormig.up({ to: '20201235203251-task' });
You also have the ability to choose to run migrations from a specific migration, excluding it:
await blormig.up({ from: '20201235203251-task' });
In the above example blormig will execute all the pending migrations found after the specified migration. This is particularly useful if you are using migrations on your native desktop application and you don't need to run past migrations on new installs while they need to run on updated installations.
You can combine from
and to
options to select a specific subset:
await blormig.up({ from: '20201235203251-task', to: '20151201103412-items' });
Running specific migrations while ignoring the right order, can be done like this:
await blormig.up({ migrations: ['20201235203251-task', '20141101203501-task-2'] });
There are also shorthand version of that:
await blormig.up('20201235203251-task'); // Runs just the passed migration
await blormig.up(['20201235203251-task', '20141101203501-task-2']);
Reverting executed migration
The down
method can be used to revert the last executed migration.
const migration = await blormig.down();
// reverts the last migration and returns it.
It is possible to pass the name of a migration until which (inclusive) the migrations should be reverted. This allows the reverting of multiple migrations at once.
const migrations = await blormig.down({ to: '20141031080000-task' });
// returns an array of all reverted migrations.
To revert all migrations, you can pass 0 as the to
parameter:
await blormig.down({ to: 0 });
Reverting specific migrations while ignoring the right order, can be done like this:
await blormig.down({ migrations: ['20201235203251-task', '20141101203501-task-2'] });
There are also shorthand versions of that:
await blormig.down('20201235203251-task'); // Runs just the passed migration
await blormig.down(['20201235203251-task', '20141101203501-task-2']);
Migrations
There are two ways to specify migrations: via files or directly via an array of migrations.
Migration files
A migration file ideally exposes an up
and a down
async functions. They will perform the task of upgrading or downgrading the database.
module.exports = {
async up() {
/* ... */
},
async down() {
/* ... */
}
};
Migration files should be located in the same directory, according to the info you gave to the Blormig
constructor.
Direct migrations list
You can also specify directly a list of migrations to the Blormig
constructor. We recommend the usage of the Blormig.migrationsList()
function
as bellow:
const { Blormig, migrationsList } = require('blormig');
const blormig = new Blormig({
migrations: migrationsList(
[
{
// the name of the migration is mandatory
name: '00-first-migration',
async up(queryInterface) { /* ... */ },
async down(queryInterface) { /* ... */ }
},
{
name: '01-foo-bar-migration',
async up(queryInterface) { /* ... */ },
async down(queryInterface) { /* ... */ }
}
],
// an optional list of parameters that will be sent to the `up` and `down` functions
[
blorm.getQueryInterface()
]
)
});
Storages
Storages define where the migration data is stored.
JSON Storage
Using the json
storage will create a JSON file which will contain an array with all the executed migrations. You can specify the path to the file. The default for that is blormig.json
in the working directory of the process.
Blorm Storage
Using the blorm
storage will create a table in your SQL database called BlormMeta
containing an entry for each executed migration. You will have to pass a configured instance of Blorm or an existing Blorm model. Optionally you can specify the model name, table name, or column name. All major Blorm versions are supported.
MongoDB Storage
Using the mongodb
storage will create a collection in your MongoDB database called migrations
containing an entry for each executed migration. You will have either to pass a MongoDB Driver Collection as collection
property. Alternatively you can pass a established MongoDB Driver connection and a collection name.
Custom
In order to use custom storage, you have two options:
Method 1: Pass instance to constructor
You can pass your storage instance to Blormig constructor.
class CustomStorage {
constructor(...) {...}
logMigration(...) {...}
unlogMigration(...) {...}
executed(...) {...}
}
let blormig = new Blormig({ storage: new CustomStorage(...) })
Method 2: Pass module name to be required
Create a module which has to fulfill the following API. You can just pass the name of the module to the configuration and blormig will require it accordingly.
For example, if you're using TypeScript:
import { BlormigStorage } from 'blormig/lib/src/storages/type-helpers'
class MyStorage implements BlormigStorage {
/* ... */
}
module.exports = MyStorage;
Events
Blormig is an EventEmitter. Each of the following events will be called with name
and migration
as arguments. Events are a convenient place to implement application-specific logic that must run around each migration:
migrating
- A migration is about to be executed.migrated
- A migration has successfully been executed.reverting
- A migration is about to be reverted.reverted
- A migration has successfully been reverted.