migraguard

library0.16.12jsnpmunverified

PostgreSQL-first, schema-aware deployment control with LLM agents and deterministic CI gates. v0.16.12 — active development, frequent releases (weekly + hotfixes). Key differentiators: 38 AST-based lint rules, tamper detection without a DB connection (offline), regression detection on hotfix reverts, drift detection with shadow DB verification, and LLM-powered 'implement'/'audit'/'explain' commands that encode domain expertise into migration files. Supports MySQL and SQLite with 17 generic lint rules. Uses native CLI (psql/mysql/sqlite3) for execution; focuses on what to forbid rather than a rich execution engine.

database devops

npm install migraguard

package ↗

INSTALL

IMPORT

SIG · MIGRAGUARD

migraguard

databasejavascriptv0.16.12

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.

migraguard CLI

✓ npx migraguard --help

migraguard is primarily a CLI tool; no programmatic API is exposed.

TypeScript types

✓ import type { MigraGuardConfig } from 'migraguard'

Only types exported for config; no runtime exports. ESM-only.

CommonJS require

✓

✗ const { migraguard } = require('migraguard')

No CommonJS support; package is ESM-only. Use dynamic import if needed: import('migraguard').

Minimal workflow: install, create migration with migraguard:up/:down directives, run check (lint+tamper), apply with drift detection, and verify idempotency on a shadow database.

// Install npm install --save-dev migraguard // For LLM features (optional) npm install --save-dev agent-contracts-runtime // Create a migration SQL file mkdir -p migrations cat > migrations/001_add_users_table.sql << 'EOF' -- migraguard:up CREATE TABLE users ( id SERIAL PRIMARY KEY, email TEXT NOT NULL UNIQUE, name TEXT ); -- migraguard:down DROP TABLE IF EXISTS users; EOF // Check migration (lint, tamper detection) npx migraguard check --migrations-dir migrations --dialect postgres // Apply to database (with drift detection) DATABASE_URL='postgres://user:pass@localhost:5432/mydb' npx migraguard apply --with-drift-check --migrations-dir migrations --dialect postgres // Verify idempotency on shadow DB npx migraguard verify --shadow-database-url 'postgres://user:pass@localhost:5432/shadow' --migrations-dir migrations

Debug

Known issues

breakingNode.js >=20 required. Package will fail to install on Node 18 or lower.

fix

Update Node.js to version 20 or higher.

affects: >=0.16.0

breakingmigraguard is ESM-only. CommonJS require() will throw ERR_REQUIRE_ESM.

fix

Use import or dynamic import() in your project.

affects: >=0.16.0

gotchaLLM features require the agent-contracts-runtime package. If not installed, commands like 'implement' and 'audit' will fail silently or throw.

fix

Install agent-contracts-runtime with npm install --save-dev agent-contracts-runtime

affects: >=0.16.0

gotchaThe 'verify' command uses a shadow database. Ensure you have a separate database URL configured for shadow; using the same database as your target will cause data loss.

fix

Provide a different DATABASE_URL for --shadow-database-url.

affects: >=0.16.0

deprecatedPre-v0.15.0 migration file format (without -- migraguard:up/-- migraguard:down directives) is deprecated and will be removed in v1.0.

fix

Add '-- migraguard:up' and '-- migraguard:down' comments to your migration files.

affects: <0.16.0

gotchaMySQL and SQLite support only 17 generic lint rules (not the full 38). Some checks like CREATE INDEX CONCURRENTLY are PostgreSQL-specific.

fix

Use --dialect mysql or --dialect sqlite; expect fewer lint rules.

affects: >=0.16.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module

Using CommonJS require() on an ESM-only package.

fix

Use import instead: import 'migraguard' or use dynamic import().

Error: The agent-contracts-runtime package is required for LLM features.

Running implement/audit/explain without the optional dependency.

fix

Install: npm install --save-dev agent-contracts-runtime

Error: Shadow database URL is required for verify command.

Missing --shadow-database-url option.

fix

Provide --shadow-database-url 'postgres://user:pass@localhost:5432/shadowdb'

Error: Node.js version 20 or higher is required.

Running with an older Node.js version.

fix

Update Node.js to v20+ via nvm or download from nodejs.org

Error: Lock acquisition timeout - another migration may be in progress.

Concurrent apply attempt on the same database.

fix

Wait for the other process to finish, or use --force if safe (not recommended).

Upgrade

Version history

0.16.12latest on npm

Audit

Dependencies

mysql2optionalRequired for MySQL dialect support (npm install separately)

better-sqlite3optionalRequired for SQLite dialect support (npm install separately)

agent-contracts-runtimeoptionalRequired for LLM features (implement, audit, explain)

Agent activity

8 hits · last 30 days

node

Resources

packagemigraguard ↗