migratable

library0.4.0jsnpmunverified

General-purpose migration and seeding framework for Node.js, built with TypeScript. v0.4.0 provides Migrator and Seeder classes to run upgrade/downgrade migrations and repeatable seed operations with a simple index-based sequence. Lightweight, actively maintained, and production-tested. Unlike database-specific tools, it keeps the context generic via a user-supplied ctx object, making it suitable for any data or configuration migration need. Migrations track state via a local cache file, while seeds run without persistence. Supports loading migrations from directories. Requires a Promise polyfill in older environments.

database devops

npm install migratable

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MIGRATABLE

migratable

databasejavascriptv0.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Migrator

✓ import { Migrator } from 'migratable'

✗ const Migrator = require('migratable').Migrator

The package ships TypeScript definitions, so the ESM import is preferred. CommonJS require is also supported but less common.

Seeder

✓ import { Seeder } from 'migratable'

✗ import Seeder from 'migratable'

Seeder is a named export, not a default export. Do not use default import.

Migrator (type)

✓ import type { Migrator } from 'migratable'

✗ import { Migrator } from 'migratable' // if only using type

For TypeScript type-only imports, use 'import type' to avoid emitting runtime code.

Seeder (type)

✓ import type { Seeder } from 'migratable'

✗ import { Seeder } from 'migratable' // if only using type

Similarly, use import type for type-only usage.

Shows basic usage of Migrator (upgrade/downgrade) and Seeder (perform) with context and error handling.

import { Migrator, Seeder } from 'migratable'; // Migrator example const migrator = new Migrator({ ctx: { db: 'my_db' }, cacheFilePath: './migratable.cache' }); migrator.add({ index: 1, upgrade: async (ctx) => { console.log('Upgrading with context:', ctx); }, downgrade: async (ctx) => { console.log('Downgrading...'); } }); migrator.upgrade() .then(() => console.log('Migrations done')) .catch(err => console.error(err)); // Seeder example const seeder = new Seeder({ ctx: { db: 'my_db' } }); seeder.add({ index: 1, perform: async (ctx) => { console.log('Seeding...'); } }); seeder.perform() .then(() => console.log('Seeding done')) .catch(err => console.error(err));

Debug

Known issues

gotchaThe cache file path must be writable. Default is './migratable.cache' and should be added to .gitignore to avoid committing migration state.

fix

Add './migratable.cache' to your .gitignore file.

affects: >=0.0.0

gotchaMigrations are tracked by index; reordering existing migrations will cause unexpected behavior or errors because the cache remembers the last index, not the migration content.

fix

Always append new migrations with a higher index. Never change the index of an already-applied migration.

affects: >=0.0.0

gotchaThe package uses Promises but does not include a polyfill. In Node < 0.12 or older browsers, Promises may be undefined.

fix

Install 'promise-polyfill' and import it before using migratable.

affects: >=0.0.0

deprecatedVersion 0.4.0 is marked as 'latest', but the package has not seen updates since 2017. Consider evaluating more actively maintained alternatives like 'node-pg-migrate' or 'umzug'.

fix

For new projects, prefer a more modern migration tool.

affects: >=0.4.0

gotchaaddDir expects migration files to export named fields (upgrade, downgrade, perform) or default export object. Incorrect export format will cause silent failures.

fix

Ensure each file in the migrations/seeds directory exports the required functions as named exports or a default object.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'migratable'

Package not installed or import path is incorrect.

fix

Run 'npm install migratable' and use correct import: import { Migrator } from 'migratable'.

Promise is not defined

Environment does not support Promises (e.g., older Node version).

fix

Install a Promise polyfill like 'promise-polyfill' and import it before migratable.

TypeError: migrator.add is not a function

migrator is not an instance of Migrator or import is wrong.

fix

Ensure you imported Migrator correctly: import { Migrator } from 'migratable' and instantiated with 'new Migrator()'.

ENOENT: no such file or directory, open './migratable.cache'

Cache file path is not writable or parent directory does not exist.

fix

Set cacheFilePath to a writable location or create the parent directory.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

promise-polyfilloptionalPromises may not be natively supported in older Node versions.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/xpepermint/migratablejs ↗

packagemigratable ↗

homepagehttps://github.com/xpepermint/migratablejs#readme ↗