Registry / devops / migration-state

migration-state

library0.3.0jsnpmunverified

A Bun-based TypeScript CLI tool that reads PostgreSQL migration files from disk, applies them sequentially in-memory using @supabase/pg-parser (WASM PostgreSQL 17 parser), and outputs the final schema state as LLM-optimised markdown or JSON. v0.3.0 supports 46 DDL statement types and auto-detects migration tools including Flyway, golang-migrate, goose, dbmate, sql-migrate, Prisma, Drizzle, and Atlas. Unlike existing tools that require a live database connection, this runs purely offline, making it ideal for CI/CD and LLM context injection. Work-in-progress but functionally complete for common DDL patterns.

devops

npm install migration-state

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MIGRATION-STATE

migration-state

devopsjavascriptv0.3.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.

migration-state CLI

✓ bunx migration-state ./migrations

✗ npx migration-state ./migrations

Tool is designed for Bun runtime; npx might work but bunx is preferred and ensures correct runtime

migration-state (programmatic API)

✓ import { processMigrations } from 'migration-state'

✗ const { processMigrations } = require('migration-state')

Package is ESM-only, no CommonJS support. Use dynamic import if required in CJS contexts.

Config import (TypeScript)

✓ import type { Config } from 'migration-state'

✗ import { Config } from 'migration-state'

Config is a TypeScript type-only export. Use `import type` to avoid runtime errors in isolatedDeclarations.

Demonstrates basic CLI usage and programmatic API with table filtering for selective schema output.

// Ensure you have Bun installed (https://bun.sh/) // 1. Create sample migration files: mkdir -p migrations && cat > migrations/V1__create_users.sql << 'EOF' CREATE TABLE users ( id SERIAL PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE NOT NULL ); EOF cat > migrations/V2__add_age.sql << 'EOF' ALTER TABLE users ADD COLUMN age INTEGER DEFAULT 0; EOF // 2. Run migration-state: // bunx migration-state ./migrations --format json // Output will show final schema state after applying V1 and V2. // Programmatic usage (selective tables): import { processMigrations } from 'migration-state'; const result = await processMigrations('./migrations', { tool: 'auto', format: 'json', tables: ['users'] // filter only 'users' table }); console.log(JSON.stringify(result, null, 2));

Debug

Known issues

gotchaRequires Bun runtime; does not work with Node.js or Deno.

fix

Install Bun from https://bun.sh/ and use bunx instead of npx.

affects: >=0.1.0

gotchaParser @supabase/pg-parser only supports PostgreSQL DDL; unsupported statements like DDL triggers on other databases may produce incorrect output.

fix

Ensure migrations are PostgreSQL-specific. Use --quiet to suppress unknown statement warnings.

affects: >=0.1.0

gotchaMigration tool auto-detection may fail if file patterns match multiple tools (e.g., Flyway and golang-migrate have similar patterns).

fix

Explicitly set --tool option (flyway, golang-migrate, goose, dbmate, sql-migrate, prisma, drizzle, atlas, generic) when ambiguous.

affects: >=0.1.0

deprecatedOutput schema structure may change in minor versions; treat format as unstable.

fix

Do not depend on exact JSON shape; validate against expected fields. Pin to exact version if stability is required.

affects: >=0.1.0 <1.0.0

gotchaLarge migration sets may consume significant memory due to in-memory state reconstruction; no streaming support.

fix

Consider filtering with --tables or --schemas to reduce scope, or run on a per-folder basis.

affects: >=0.1.0

Errors

Common errors & fixes

bun: command not found

Bun is not installed or not in PATH.

fix

Install Bun via curl -fsSL https://bun.sh/install | bash or use the official installer.

error: Unknown migration tool for directory './migrations'

Migration file patterns do not match any known tool, or directory contains unsupported file types.

fix

Specify --tool option explicitly (e.g., --tool generic) or ensure migration files follow a supported naming convention (see README).

Error: Unsupported DDL statement: CREATE TABLE t (a int) WITH (oids=true)

Currently migration-state does not handle all PostgreSQL DDL variations (e.g., WITH (OIDS)).

fix

Simplify the DDL statement to avoid unsupported syntax, or file an issue on GitHub. Use --quiet to suppress warnings.

TypeError: Cannot read properties of undefined (reading 'statementType')

Rare edge case where parser returns unexpected AST; possibly due to malformed SQL or unsupported syntax.

fix

Validate SQL syntax (e.g., using psql -c or pg_parse). Strip problematic statements or report to package maintainer.

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

@supabase/pg-parserrequiredPostgreSQL SQL parser compiled to WASM, used to parse migration files into AST for schema reconstruction

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/mec07/migration-state ↗

packagemigration-state ↗

homepagehttps://github.com/mec07/migration-state#readme ↗