@appenin/check-migrations-timestamps NPM

Check-migrations-timestamps

This tool helps you ensure that your migration files are in the correct order, based on their timestamps. You can use it with your CI or a pre-commit hook.

Prerequisites

This library should work with any ORM as long as the name of your migration files respect this format: [timestamp]-[migration-name].[extension], where the timestamp is yyyymmddhhmmss.

How does the library work

First, you should setup the library by including it in your workflow (for instance in a pre-commit hook and/or in your CI).
Then, whenever you commit new migration files, the library will check them against the files on your repository main branch. Any files whose timestamp is anterior to the last files on the repository or set at a future date will raise an issue, thus failing your pre-commit hook or your CI (depending on your usage).

How to install the library

npm install @appenin/check-migrations-timestamps --save-dev

yarn add @appenin/check-migrations-timestamps --dev

How to use the library

After installation, you should be able to run the check-migrations-timestamps binary directly:

npm check-migrations-timestamps [args]

yarn check-migrations-timestamps [args]

This library requires you to provide a path to your migrations folder. You may also wish to use some optional features. You can use yarn check-migrations-timestamps --help to see all the options available.

--migrationsPath - The path of your migrations folder
--mainBranch optional - The name of your repository's main branch, default to "origin/master"
--currentBranch optional - The name of the branch you want to check against the main branch, default to "HEAD"
--fromCI optional - On a CI environment, the script may require extra work (for instance, to fetch the new migration files), default to false
--currentBranch optional - If set to true, the script will suggest fixes for your migrations files, default to false

⚠️ On a CI environment, you should set fromCI to true and provide the mainBranch and currentBranch arguments explicitly.
On a local environment, the default values should suffice.

We highly suggest that you use the autoFix flag with your pre-commit hook. It should also work on your CI, but this would force you to manually pull any changes made this way.

Usage in a pre-commit hook

Using your pre-commit hook tool of choice, for instance husky, simply execute the library in your pre-commit script.

"husky": {
  "hooks": {
    "pre-commit": "yarn @appenin/check-migrations-timestamps --migrationsPath=db/sequelize/migrations --autoFix"
  }
}

If you were using other tools, like a linter, you may keep them.

Starting now, any commit wich include a wrongly named migration will fail and raise an error:
Example with pre-commit hook

Usage in CI

Simply add a dedicated stage to your CI, for instance with Gitlab:

"Check Migrations":
  stage: quality
  before_script:
    - yarn @appenin/check-migrations-timestamps --dev
  script:
    - yarn @appenin/check-migrations-timestamps --fromCI --migrationsPath=db/sequelize/migrations --mainBranch=origin/master --currentBranch=origin/$CI_COMMIT_REF_NAME).

Starting now, your pipeline will fail and raise an error any time you push a wrongly named migration:
Example with CI