sql-migrations

library1.0.7jsnpmunverified

A simple Node.js library for running raw SQL database migrations. Current stable version is 1.0.7, with infrequent releases. It supports PostgreSQL and MySQL via the 'pg' and 'mysql' npm packages as runtime adapters. Key differentiators include a simple file-based migration system, CLI and programmatic API, customizable parameter substitution in SQL scripts, and optional migration time filtering. Suitable for projects that prefer plain SQL over ORM-based migrations.

database

npm install sql-migrations

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-MIGRATIONS

sql-migrations

databasejavascriptv1.0.7

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.

run

✓ const { run } = require('sql-migrations');

✗ import { run } from 'sql-migrations';

Package is CommonJS only, no ESM exports.

migrate

✓ const { migrate } = require('sql-migrations');

✗ const migrate = require('sql-migrations').migrate;

Destructuring works; direct property access also fine.

rollback

✓ const { rollback } = require('sql-migrations');

✗ const rollback = require('sql-migrations').rollback;

Same as migrate.

Shows how to run database migrations programmatically using the pg adapter.

Debug

Known issues

breakingMigration files must be named with Unix timestamp in milliseconds (e.g., 1415860098827_up_migration_name.sql). Invalid filenames are silently ignored.

fix

Ensure migration filenames start with a 13-digit Unix timestamp followed by underscore.

affects: >=1.0.0

gotchaThe library does not create the database; it only connects to an existing one.

fix

Manually create the database before running migrations.

affects: >=1.0.0

gotchaParameter substitution uses simple string replacement. SQL injection possible if parameters come from untrusted input.

fix

Sanitize or validate parameters before passing them.

affects: >=1.0.0

gotchaThe library uses the global `console` object for logging by default. Custom logger must implement both `log` and `error` methods.

fix

Use setLogger() to provide a custom logger with log and error methods.

affects: >=1.0.0

gotchaminMigrationTime option expects a timestamp in milliseconds (number), not a Date object.

fix

Pass new Date('2018-01-01').getTime() instead of the Date object directly.

affects: >=1.0.0

Errors

Common errors & fixes

Error: The 'migrationsDir' configuration option is missing

Missing required migrationsDir property in configuration object.

fix

Provide migrationsDir: path.resolve(__dirname, 'migrations') in config.

Cannot find module 'pg'

pg adapter selected but pg package not installed.

fix

Run: npm install pg

Error: Migration file 1415860098827_up_migration_name.sql not found

Migration directory missing or incorrect path.

fix

Ensure migrationsDir is correct and migration files exist.

Upgrade

Version history

1.0.7latest on npm

Audit

Dependencies

pgoptionalPostgreSQL adapter – required if using pg adapter

mysqloptionalMySQL adapter – required if using mysql adapter

Agent activity

11 hits · last 30 days

node