Installation

npm install -g dbforge-cli

# Optional: PostgreSQL support
npm install pg

# Optional: MySQL support
npm install mysql2

Commands

Free Commands (7)

| Command | Description | |---------|-------------| | dbforge inspect <connection> | Schema inspection — tables, columns, types, relations | | dbforge diff <source> <target> | Compare two database schemas | | dbforge generate <connection> --changes <desc> | Generate migration SQL from description | | dbforge status <connection> | Migration status — applied and pending | | dbforge validate <connection> --sql <file> | Dry-run validate a migration file | | dbforge indexes <connection> | Suggest missing indexes | | dbforge visualize <connection> | ER diagram (Mermaid output) |

Pro Commands (6) — require PRO_LICENSE env var

| Command | Description | |---------|-------------| | dbforge apply <connection> --file <migration.sql> | Execute migration with snapshot tracking | | dbforge rollback <connection> | Rollback last N migrations | | dbforge seed <connection> | Generate realistic INSERT statements | | dbforge export <connection> --format prisma\|drizzle\|knex | Export schema to ORM models | | dbforge squash <migrations-dir> | Squash multiple migrations into one | | dbforge mask <connection> | Generate data masking script for PII |

Usage Examples

Inspect a SQLite database

dbforge inspect ./mydb.sqlite

# Inspect a specific table
dbforge inspect ./mydb.sqlite --table users

# JSON output
dbforge inspect ./mydb.sqlite --json

Diff two databases

dbforge diff ./dev.sqlite ./staging.sqlite
dbforge diff postgresql://localhost/dev postgresql://localhost/staging

Generate migration SQL

# Natural language description
dbforge generate :memory: --changes "add column bio TEXT to users"

# JSON changes array (pipe-friendly)
dbforge generate ./mydb.sqlite --changes '[{"type":"add_column","table":"users","column":"bio","description":"add bio","payload":{"columnType":"TEXT"}}]'

# Knex format
dbforge generate ./mydb.sqlite --changes "add column bio TEXT to users" --format knex

# Drizzle format
dbforge generate ./mydb.sqlite --changes "add column bio TEXT to users" --format drizzle

Check migration status

dbforge status ./mydb.sqlite
dbforge status postgresql://user:pass@localhost/mydb --json

Validate a migration

dbforge validate ./mydb.sqlite --sql ./migrations/001_add_users.sql

Suggest missing indexes

dbforge indexes ./mydb.sqlite

# Analyse a specific query
dbforge indexes ./mydb.sqlite --query "SELECT * FROM orders WHERE user_id = ?"

Visualize as Mermaid ER diagram

dbforge visualize ./mydb.sqlite

Example output:

erDiagram
  users {
    INTEGER id PK
    TEXT email
    TEXT name
  }

  posts {
    INTEGER id PK
    INTEGER user_id
    TEXT title
  }

  posts }o--|| users : "user_id"

Pro Commands

# Set license key
export PRO_LICENSE=your-license-key

# Apply a migration
dbforge apply ./mydb.sqlite --file ./migrations/001_init.sql

# Rollback last migration
dbforge rollback ./mydb.sqlite

# Rollback last 3 migrations
dbforge rollback ./mydb.sqlite --count 3

# Generate seed data (10 rows per table)
dbforge seed ./mydb.sqlite --count 10

# Export to Prisma schema
dbforge export ./mydb.sqlite --format prisma

# Export to Drizzle ORM
dbforge export ./mydb.sqlite --format drizzle

# Export to Knex migrations
dbforge export ./mydb.sqlite --format knex

# Squash all migrations in a directory
dbforge squash ./migrations --output ./squashed.sql

# Generate PII masking script
dbforge mask ./mydb.sqlite

# Actually execute the masking
dbforge mask ./mydb.sqlite --execute

Connection Strings

| Database | Connection String | |----------|------------------| | SQLite (in-memory) | :memory: | | SQLite (file) | ./path/to/db.sqlite or /abs/path/to/db.db | | PostgreSQL | postgresql://user:pass@host:5432/dbname | | MySQL | mysql://user:pass@host:3306/dbname or mysql2://... |

Output Formats

All commands support --format table|json and --json shorthand.

# Default table output
dbforge inspect :memory:

# JSON output
dbforge inspect :memory: --json
dbforge inspect :memory: --format json

Global Options

| Option | Description | |--------|-------------| | --json | Output as JSON | | --format <format> | Output format (table or json) |

Architecture

src/
├── index.ts               # CLI entry point (commander.js)
├── types.ts               # Shared TypeScript types
├── adapters/
│   ├── interface.ts       # DatabaseAdapter interface
│   ├── factory.ts         # Adapter factory (lazy imports)
│   ├── sqlite.ts          # better-sqlite3 adapter (built-in)
│   ├── postgres.ts        # pg adapter (optional peer dep)
│   └── mysql.ts           # mysql2 adapter (optional peer dep)
├── lib/
│   ├── connection.ts      # Connection string utilities
│   ├── migration-tracker.ts  # _dbforge_migrations tracking
│   ├── sql-generator.ts   # SQL / Knex / Drizzle generators
│   ├── formatters.ts      # CLI table + Mermaid formatters
│   └── path-validation.ts # Connection string validation
└── commands/
    ├── inspect.ts         # dbforge inspect
    ├── diff.ts            # dbforge diff
    ├── generate.ts        # dbforge generate
    ├── status.ts          # dbforge status
    ├── validate.ts        # dbforge validate
    ├── indexes.ts         # dbforge indexes
    ├── visualize.ts       # dbforge visualize
    └── pro/
        ├── apply.ts       # dbforge apply [PRO]
        ├── rollback.ts    # dbforge rollback [PRO]
        ├── seed.ts        # dbforge seed [PRO]
        ├── export.ts      # dbforge export [PRO]
        ├── squash.ts      # dbforge squash [PRO]
        └── mask.ts        # dbforge mask [PRO]

Development

# Install dependencies
npm install

# Type check
npm run typecheck

# Build
npm run build

# Run tests
npm test

# Run tests with PostgreSQL
TEST_PG_URL=postgresql://localhost/test npm test

# Run tests with MySQL
TEST_MYSQL_URL=mysql://root:pass@localhost/test npm test