Aligator — MongoDB migration SDK + CLI

Aligator is a production-ready MongoDB migration system with a guided CLI and a programmable SDK. It uses deterministic schema diffing first; AI is optional and only assists with rename detection and script scaffolding—never as the source of truth.

Highlights

• SDK + CLI hybrid architecture
• Deterministic diff engine (code vs database)
• Guided CLI: migration plan summary, interactive rename review, streaming backups
• Structured migration files: MIG_0001_YYYY_MM_DD_slug.js
• Migration history, rollback, restore, and streaming per-version backups (cursor + batch size, not full in-memory loads)
• Config-driven: backup defaults, cli.interactive, ai.enableRenameDetection
• Logging via Pino (e.g. logs/aligator.log)

Installation

From a clone of this repo:

npm install
npm link   # optional: global `aligator` command

From npm (when published):

npm install @aliasgarbootwala/aligator
npx aligator --help

Configuration

Create aligator.config.js in the project root or run:

aligator init

Example:

export default {
  uri: process.env.MONGO_URI,
  modelsPath: "./models",
  migrationsPath: "./migrations",
  includePaths: [],
  excludePaths: [],
  projects: [],
  autoRun: false,
  backup: {
    enabled: true,
    defaultBatchSize: 100,
  },
  ignoreFields: ["__v", "_id"],
  strictMode: true,
  ai: {
    enabled: true,
    enableRenameDetection: true,
  },
  cli: {
    interactive: true,
  },
};

Legacy backup: true (boolean) is still supported and normalized to { enabled: true, defaultBatchSize: 100 }.

Supported config files:

• aligator.config.js (preferred)
• aligator.config.cjs
• aligator.config.json

Environment variables (see example.env if present):

MONGO_URI=mongodb://localhost:27017/<dbname>
# Optional — only if you use remote AI rename detection (enabled + endpoint):
AI_API_KEY=...
OPENROUTER_API_KEY=...
BASE_AI_ENDPOINT=https://openrouter.ai/api/v1/chat/completions
AI_MODEL=...
MAX_TOKEN=2000
LOG_LEVEL=info
NODE_ENV=development

CLI commands

| Command | Purpose | |--------|---------| | aligator init | Create a default config file | | aligator scan | Scan code-defined schemas vs database | | aligator diff | Show schema differences (table output) | | aligator generate | Diff → optional rename review → write migration file | | aligator migrate | Run latest migration (optional interactive backup wizard) | | aligator backup | Standalone streamed backup to backups/snapshot-* | | aligator history | Show applied migrations | | aligator restore <id> | Restore from backup for a migration id | | aligator rollback | Roll back last migration | | aligator forget <id> | Remove old migration |

aligator --help
aligator scan
aligator diff
aligator generate --name add_user_fields
aligator generate --non-interactive --accept-renames   # CI-style
aligator migrate
aligator migrate --dry
aligator migrate --force --non-interactive
aligator backup
aligator history

CLI behavior notes

• MONGO_URI is required for commands that connect to MongoDB.
• generate: AI_API_KEY (or config ai.apiKey) is required only when remote AI rename detection will run (ai.enabled + ai.endpoint + ai.enableRenameDetection not disabled). Heuristic-only rename detection does not need an API key.
• migrate does not require an AI key.
• --force: skips confirmation and interactive backup prompts (migrate / restore / rollback); backups still use config defaults when enabled.
• generate --non-interactive: skips prompts; use --accept-renames to apply detected renames without review.
• Output uses chalk, ora, boxen, and cli-table3 for readable tables and summaries.
• Renames in generated scripts use MongoDB $rename where applicable; interactive flow never applies renames without your confirmation.

SDK usage

import aligator from "@aliasgarbootwala/aligator";

await aligator.init({
  uri: process.env.MONGO_URI,
  autoRun: true,
});

SDK flow: load config → load models → scan DB → diff → generate migration if needed → optionally autoRun migration.

Folder layout

src/
  core/
    backup/           # streaming backup helpers
    diff/
    scanner/
    schema/
    ai/
    migration/
  cli/
    commands/
    flows.js          # high-level migrate / generate / backup flows
    prompts.js        # interactive prompts (Inquirer)
    ui/
    utils/
  sdk/
  utils/
  config/

migrations/
backups/

Safety

• _id and configured ignoreFields are excluded from destructive suggestions by default.
• Prefer reviewing generated migration files before production.
• Backups are written per migration id under backups/<migrationId>/ using streamed JSON array files compatible with restore.
• If AI is unavailable, heuristics and deterministic diff still apply.

Example workflow

aligator init
aligator diff
aligator generate --name add_user_fields
aligator migrate
aligator history

Troubleshooting

aligator prints nothing (no help, no errors)

This was caused by the entry script detecting “direct run” incorrectly when the global command is a symlink (e.g. bin/aligator → index.js). Use v2.1.0+, which resolves real paths so the CLI always loads. As a workaround you can run node ./node_modules/@aliasgarbootwala/aligator/index.js diff or node index.js diff from the package folder.

Connection / config errors

Ensure aligator.config.js exists, MONGO_URI is set, and models path matches your Mongoose models.

Production tips

• Set NODE_ENV=production to reduce noisy log formatting where applicable.
• Run generate in CI with --non-interactive and explicit flags; review artifacts before migrate.