migronautElegant MongoDB migrations for Node.js

Precise, safe migrations for MongoDB, with zero runtime dependencies. Run a single file, roll back anything, and preview every change before it touches your database.

Get Started

Why migronaut?

View on GitHub

📭

Zero dependencies

No runtime dependencies — only the mongodb driver as a peer. Your logger, BullMQ and OpenTelemetry are injected by you, never installed by migronaut.

How it got there

🎯

Precise runs, real rollbacks

Apply one file, migrate --to a point, or everything pending. Roll back a batch, the last N, one file, or redo — history is never deleted.

migronaut down

🔒

Safe by default

An atomic MongoDB lock with a heartbeat stops two deploys racing; checksums catch edited migrations, and a file merged late is flagged.

How the lock works

👀

Preview everything

dry-run shows what up or down would run, converge --dry-run what would change, and a background dry run rewrites a sample in an aborted transaction.

migronaut dry-run

🧭

Declared collections

Declare indexes and validators as an end state. converge applies the difference, refuses a conflict before any write, and never drops what you did not declare.

Declared collections

🔎

Atlas Search & Vector Search

Atlas Search and Vector Search indexes in the same declarations — updated in place, never dropped and rebuilt, and waited for without holding the lock.

Search indexes

🧬

Document versioning

A shape version and an optimistic-concurrency revision on every document — enforced by a validator, typed per version, written by your repository's helpers.

Document versioning

🌊

Background migrations

Rewrite huge collections beside the deploy: parallel lanes in any process, a checkpoint per batch, throttling, pause and resume, and a drift watch.

Background migrations

📬

Migrations as a queue

Optional BullMQ adapter — one migration per job, in an order MongoDB enforces, with schedules, enqueue-and-wait, and a queue for background migrations.

Migrations as a queue

🔭

OpenTelemetry

Hand it your tracer and meter: a span per run and per migration, the driver's spans nested inside, and metrics for durations, locks and background work.

OpenTelemetry

📝

Migration logs

ctx.logger binds the run, migration, attempt and queue job to every line — and lines marked userland become events your app can store and show its users.

Migration logs

📦

Bring your history

migronaut import adopts a migrate-mongo changelog as-is; baseline marks an existing database's migrations applied — no re-running, no rewriting files.

Migrate from migrate-mongo

How it fits together

One engine runs everything — from a terminal, inside your application at startup, or as a queue worker — and keeps all of its state in MongoDB, next to your data. It changes a database in three ways, each with its own guarantees.

How it works, step by step →

Also in the box

Opt-in transactions — a migration and its changelog record commit together
Lifecycle hooks & events — beforeAll … onError, and kit.on(…) for metrics
TypeScript, ESM & CommonJS — .ts natively on Node 22.18+
Mongoose — inject your instance, use your models in migrations
Seeding — seeds with a history of their own, per environment
CI gates & JSON output — status --check, converge --check, --json
migronaut audit — a read-only health check of the whole setup
Your own id format — ULID, CUID, UUIDv7 for every id it mints
Secrets at runtime — an async config factory

migronautElegant MongoDB migrations for Node.js

Zero dependencies

Precise runs, real rollbacks

Safe by default

Preview everything

Declared collections

Atlas Search & Vector Search

Document versioning

Background migrations

Migrations as a queue

OpenTelemetry

Migration logs

Bring your history

How it fits together ​

Also in the box ​

How it fits together

Also in the box