migrationpilot

library1.5.0jsnpmunverified

MigrationPilot is a static analysis tool for PostgreSQL schema migrations that parses SQL using the libpg-query PostgreSQL parser, classifies locks, flags dangerous patterns with 83 safety rules, scores risk, and suggests safe alternatives — all without touching a database. Current stable version is 1.5.0, released as an npm package and GitHub Action. Key differentiators: works offline via static analysis, supports CLI/Library/GitHub Action, auto-detects 14 migration frameworks, includes a git hook, and generates SARIF output for code scanning. Requires Node.js >=22.

devops

npm install migrationpilot

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MIGRATIONPILOT

migrationpilot

devopsjavascriptv1.5.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.

migrationpilot

✓ import { analyze } from 'migrationpilot'

✗ const pilot = require('migrationpilot')

Package is ESM-only since v1.5.0; no CJS support.

analyze

✓ import { analyze } from 'migrationpilot'

✗ const { analyze } = require('migrationpilot')

Use ESM imports; require() will throw.

check

✓ import { check } from 'migrationpilot'

Async function that returns a report object.

Shows how to import the analyze function, pass a SQL string, and read the risk score and violations from the returned report.

import { analyze } from 'migrationpilot'; const sql = `CREATE INDEX idx_users_email ON users (email);`; try { const report = await analyze(sql, { pgVersion: 17, format: 'json' }); console.log('Risk score:', report.score); console.log('Violations:', report.violations); } catch (error) { console.error('Analysis failed:', error); }

Debug

Known issues

gotchaThe analyze() function does not connect to a database; it performs static analysis only. Do not expect it to validate against a live schema.

fix

Use the check() function with a database connection if live validation is needed.

affects: >=1.0.0

deprecatedThe plan() command is deprecated and will be removed in v2.0.0.

fix

Use analyze() with --format timeline instead.

affects: >=1.4.0

breakingNode.js <22 is no longer supported starting v1.5.0.

fix

Upgrade Node.js to version 22 or later.

affects: >=1.5.0

gotchaThe GitHub Action must be pinned to @v1 (major tag) to avoid breaking changes. The action may use a different underlying package version.

fix

Use mickelsamuel/migrationpilot@v1 (not @v1.5.0).

affects: >=1.0.0

gotchaThe --fix flag auto-applies safe alternatives but may introduce syntactically correct but semantically incorrect SQL. Always review changes.

fix

Use --fix in CI only after manual review.

affects: >=1.1.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

The package is ESM-only, but the project is using CommonJS (require).

fix

Add "type": "module" to package.json or switch to .mjs files.

TypeError: migrationpilot.analyze is not a function

Incorrect import (named import used for default export).

fix

Use import { analyze } from 'migrationpilot'.

Error: SQL parse error: syntax error at or near "CONCURRENTLY"

The migration contains syntax not supported by the target PostgreSQL version (e.g., CONCURRENTLY in older versions).

fix

Set the --pg-version option to match your target database version.

Upgrade

Version history

1.5.0latest on npm

Audit

Dependencies

noderequiredRequires Node.js >=22.0.0

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/mickelsamuel/migrationpilot ↗

packagemigrationpilot ↗

homepagehttps://migrationpilot.dev ↗