Simple extensible node migrator library.
Simple extensible one-way migration tool for performing various tasks in order in multiple environments.
- Can be used for running any kind of tasks that need to be executed on multiple environments.
- Works great for migrating database schemas and data but also for changing image file formats etc.
- The storage method is extensive so the information about which migrations have been carried out can be stored anywhere (database, simple file etc).
- Has built-in TypeORM storage that can use MySQL / MariaDB / Postgres / SQLite / Microsoft SQL Server / Oracle / WebSQL.
- Each migration is a simple async function receiving a custom context and returning anything serializable for success or throwing error on failure.
- Written in TypeScript.
- Includes 100% test coverage.
Installation
This package is distributed via npm
npm install migrator-jsCommands
-
yarn startto start the example application. -
yarn buildto build the production version. -
yarn testto run tests. -
yarn coverageto gather code coverage. -
yarn lintto lint the codebase. -
yarn prettierto run prettier. -
yarn auditto run all pre-commit checks (prettier, build, lint, test)
Example migration script
import { IMigrationContext } from "../";
export default async (context: IMigrationContext): Promise<string> => {
// run any query, crop images etc
const sum = await context.connection.query("SELECT 1+1 AS sum");
return `1+1=${sum}`;
};Example script that runs chosen migrations
Store it in src/scripts/migrate.ts etc and add NPM script to run it.
package.json
{
"scripts": {
"migrate": "yarn build && node build/example"
}
}src/scripts/migrate.ts
import chalk from "chalk";
import path from "path";
import { Migrator, MigratorTypeormStorage } from "../src";
// the contents of this file is usually kept in scripts/migrate.ts etc file and run through NPM scripts
// any context resources passed on to all migrations
export interface MigrationContext {
version: string;
}
async function run() {
// show an empty line between previous content
console.log("");
// create migrator
const migrator = new Migrator<MigrationContext>(
// this is the custom context matching MigrationContext
{
version: "1",
},
// migrator configuration
{
// pattern for finding the migration scripts
pattern: path.join(__dirname, "migrations", "!(*.spec|*.test|*.d).{ts,js}"),
// you can use MySQL / MariaDB / Postgres / SQLite / Microsoft SQL Server / Oracle / WebSQL
// see http://typeorm.io
storage: new MigratorTypeormStorage({
type: "sqlite",
database: path.join(__dirname, "..", "..", "migrate.sqlite3"),
}),
},
);
// attempt to run the migrator
try {
// run migrator providing pattern of migration files, storage to use and context to pass to each migration
// run the migrations and extract results
const { pendingMigrations, chosenMigrations, performedMigrations, failedMigrations } = await migrator.migrate();
// print results to console
if (pendingMigrations.length === 0) {
console.error(`${chalk.black.bgWhite(` NOTHING TO MIGRATE `)} `);
} else if (chosenMigrations.length === 0) {
console.error(`${chalk.black.bgWhite(` NO MIGRATIONS CHOSEN `)} `);
} else if (performedMigrations.length > 0 && failedMigrations.length === 0) {
console.error(`${chalk.black.bgGreen(` ALL MIGRATIONS SUCCEEDED `)} - ${performedMigrations.length} total`);
} else if (performedMigrations.length === 0 && failedMigrations.length > 0) {
console.error(`${chalk.black.bgRed(` ALL MIGRATIONS FAILED `)} - ${failedMigrations.length} total`);
} else {
console.error(
`${chalk.black.bgYellow(` SOME MIGRATIONS FAILED `)} - ${performedMigrations.length} succeeded, ${
failedMigrations.length
} failed`,
);
}
// exit with a non-zero code if any of the migrations failed
if (failedMigrations.length === 0) {
process.exit(0);
} else {
process.exit(1);
}
} catch (e) {
console.error(`${chalk.black.bgRed(` RUNNING MIGRATOR FAILED `)}`, e.stack);
} finally {
// gracefully close the connection
await migrator.close();
}
}
run().catch(e => console.error(chalk.black.bgRed(` RUNNING MIGRATOR FAILED `), e.stack));