mongrator v1.0.4
mongrator
Create, list, do and undo migrations for mongo databases with mongoose and models. CLI and API.
Installation
$ npm i -s mongrator
Usage
CLI
Guide
Create, list, do and undo migrations for mongo databases with mongoose and models.
Commands:
mongrator create Create a new migration
mongrator up Run up migration(s)
mongrator down Run down migration(s)
mongrator list List the status of the migrations
Options:
--url URL of the database [string] [default: "mongodb://localhost:27017/test"]
--folder Folder of the migrations [string] [default: "db/migrations"]
--collection Name for the collection of the migrations [string] [default: "DatabaseMigrationsStatus"]
--debug To log or not to log [boolean] [default: true]
--keep-alive To leave the connection opened after the command or not [boolean] [default: false]
--logger File (*.js) that gets the logger function [string]
--mongoose File (*.js) that gets the mongoose instance [string]
--options File (*.js) that gets the options of the db connection [string]
--config-file File (*.js) that loads all the CLI parameters [string]
--version Show version number [boolean]
--help Show help [boolean]
Type mongrator <subcommand>
to see the help of any subcommand.
CLI Examples
mongrator up
and mongrator down
$ mongrator up # or <mongrator down>
--quantity 1 # Execute only 1 migration
--url mongodb://user@pass:ip.domain:27017/mydatabase # Specify the URL of the database
--folder database/migrations/folder # Folder of the migration files
--collection CollectionForMigrationsInMyDatabase # Name of the collection for the migrations in the database
--debug false # Disable debugging
--keep-alive true # Do not close connection once done
--logger my/file/to/my/logger.js # Load your custom logger function from a file
--mongoose database/mongoose/loader.js # Load your custom mongoose instance
--options database/configurations/loader.js # Load your configurations for the connection
mongrator list
$ mongrator list
--url mongodb://user@pass:ip.domain:27017/mydatabase # Specify the URL of the database
--folder database/migrations/folder # Folder of the migration files
--collection CollectionForMigrationsInMyDatabase # Name of the collection for the migrations in the database
--keep-alive true # Do not close connection once done
--logger my/file/to/my/logger.js # Load your custom logger function from a file
--mongoose database/mongoose/loader.js # Load your custom mongoose instance
--options database/configurations/loader.js # Load your configurations for the connection
mongrator create
$ mongrator list
--name migration-name # Specify the name of the migration
--template-path path/to/your/migrations-template.js # Specify the template file for the new migration
--url mongodb://user@pass:ip.domain:27017/mydatabase # Specify the URL of the database
--folder database/migrations/folder # Folder of the migration files
--collection CollectionForMigrationsInMyDatabase # Name of the collection for the migrations in the database
--keep-alive true # Do not close connection once done
--logger my/file/to/my/logger.js # Load your custom logger function from a file
--mongoose database/mongoose/loader.js # Load your custom mongoose instance
--options database/configurations/loader.js # Load your configurations for the connection
In case you needed to provide credentials secretly and/or through environmental variables, you can also:
$ mongrator <subcommand>
--config-file path/to/migrations-config.js # Specify all the options through a file
API
The API accepts almost the same options as the CLI.
These are the default options:
{
url: "mongodb://localhost:27017/test",
debug: true,
logger: true,
colorize: true,
folder: "db/migrations",
collection: "DatabaseMigrationsStatus",
mongoose: undefined,
keepAlive: true,
name: `unnamed`,
direction: "up",
quantity: -1, // This means "all the possible migrations"
templatePath: `${__dirname}/template/migration.js`, // This points to the same project, not the current working directory
options: {}
}
API examples
The same commands we showed previously for the CLI, in the API would look like follows.
But first, import the API.
const Mongrator = require("Mongrator");
Then, each command:
mongrator up
and mongrator down
const mongrator = new Mongrator({
quantity: 1,
url: "mongodb://user@pass:ip.domain:27017/mydatabase",
folder: "database/migrations/folder",
collection: "CollectionForMigrationsInMyDatabase",
debug: false,
keepAlive: true,
logger: require("./my/file/to/my/logger.js"),
mongoose: require("./database/mongoose/loader.js"),
options: require("./database/configurations/loader.js")
});
mongrator.up();
mongrator list
const mongrator = new Mongrator({
url: "mongodb://user@pass:ip.domain:27017/mydatabase",
folder: "database/migrations/folder",
collection: "CollectionForMigrationsInMyDatabase",
keepAlive: true,
logger: require("./my/file/to/my/logger.js"),
mongoose: require("./database/mongoose/loader.js"),
options: require("./database/configurations/loader.js")
});
mongrator.list();
mongrator create
const mongrator = new Mongrator({
name: "migratio-name",
templatePath: "path/to/your/migrations-template.js",
url: "mongodb://user@pass:ip.domain:27017/mydatabase",
folder: "database/migrations/folder",
collection: "CollectionForMigrationsInMyDatabase",
keepAlive: true,
logger: require("./my/file/to/my/logger.js"),
mongoose: require("./database/mongoose/loader.js"),
options: require("./database/configurations/loader.js")
});
mongrator.create();
In case you needed to provide credentials secretly and/or through environmental variables, you can also:
const mongrator = new Mongrator(require("path/to/migrations-config.js"));
Migration files
The migration files are very simple. They all return an object with:
- an
up
asynchronous method - a
down
asynchronous method
By being an asynchronous method, it means that it must return a Promise
.
The default template file looks like this:
module.exports = {
up: async function(mongoose, migrator) {
// @TODO: migration up here...
},
down: async function(mongoose, migrator) {
// @TODO: migration down here...
}
};
You can find examples of this kind of files in test/db/migrations/*.js
and on test/mongrator.test.js
files.
For example, the test/db/migrations/001-first.js
file, which loads a model, saves an instance and queries the collection:
require(__dirname + "/../models/User.js");
module.exports = {
up: async function(mongoose, migrator) {
const User = mongoose.model("User");
const user = new User({
name: "xxx 1",
password: "xxx",
email: "xxx@xxx.xxx"
});
await user.save();
// Example of a query in async/await notation for mongoose
const users = await User.find().exec();
migrator.log(users);
},
down: async function(mongoose) {
const User = mongoose.model("User");
await User.deleteMany({});
}
}
API logging
The logging is colorized to easily understand what is going on.
On blue, the informative logs.
On red, the error logs.
On green, the positive logs.
On yellow, the warning logs and statistics.
Also, there is a special notation at the begining of each line:
[ ]
: no changes. No persistent operations present.[·]
: soft changes. Operations that leave digital fingerprint, likeSELECTS
in database.[#]
: hard changes. Operations that leave digital fingerprint and modify resources on the machine, likeINSERTS, UPDATES, DELETES
in database, or writing to files.
This nomenclature informs about the type of operation carried by each step of the process.
Tests
Important: the tests will drop all the items at the User
collection.
To run the tests you need to:
1) Start database
There is a script that creates a database for the default URL at test/db/data
.
$ npm run test:start:db
2) Run tests
To run the tests you do:
$ npm run test
Note: for further doubts, it is good to check the tests.
Coverage
Right now I am not doing code coverage of this project. If the usage of the tool is extended, I surely will.
Issues
You can add your issues here.
Contributions
As I usually work isolatedly because companies in Spain do not want me to work with them, I am not very aware about how to cooperate on git for software development.
So, please, give me a job, and I most probably will learn as soon as possible how to fulfill this part of the README file.