[Alex-Dolid]

Summary

Release 2.4.0: migration logs for the application's users. Every migration gets ctx.logger,
bound to its run, and ctx.run; a line marked userland: true is also emitted as the
migration:log event, for the application to store and show. Migronaut stores none of it — it
captures and correlates, the application keeps. Plus architecture diagrams across the docs site, a
new How It Works page, and a home page that shows what 2.1 – 2.4 added.

Additive: a migration that never touches the new context fields, and a kit with no migration:log
listener, behave as before. Everything new is marked experimental.

What's new

Migration logs

• ctx.logger — the kit's logger with runId, migration, direction, batch, attempt and,
  on a queue, jobId / groupId bound into every line. Pino's (fields, msg) order works too.
• ctx.run — the same correlation as a frozen object; attempt is 2 or more when the driver
  retried the transaction and the body ran again.
• migration:log — emitted only for calls whose fields hold userland: true, whatever the
  logger's level and with logger: null. The payload is { kind, runId, …correlation, level, msg, data, at, seq, truncated? }; data is a bounded, redacted copy — credentials and the values a
  server error quotes are masked, an Error becomes { name, message, code?, codeName? }.
• Hooks get a logger too: beforeAll / afterAll the run's, the others the migration's.
• job: { id, groupId? } on up, down and redo (and { id } on runBackgroundSlice).
• Retried transactions, visible — attempts on migration:success / migration:error, the
  kit's log lines and the migronaut.migration span; migronaut.job.id / migronaut.job.group_id
  on the run span of a run that names a job.

Queue adapter

• Each job's run is told its job. Its userland: true lines land in the job's own log as one-line
  ✎ rows, matched by job id and run id, so a timed-out body never writes into the next job's
  log.
• The new userlandLogRows option (createMigrationQueue and both processors, default 1000) caps
  the rows one job's log takes; the rest are counted in one closing row.
• Background lanes mirror their slice's lines into the lane job's log. Lanes an up drives inline
  (backgroundInline) carry the run's jobId and groupId, so their lines land in that migration
  job's log.

Background migrations

• ctx.logger is bound to ctx.background — now frozen and typed BackgroundRunInfo, with the
  lane's runId, its jobId and the transaction attempt. A userland: true call emits
  migration:log with kind: 'background'; a dry run marks its lines dryRun: true and emits
  nothing.

Fixed

• An async event listener that rejects no longer crashes the process: the kit is an
  EventEmitter with captureRejections, and the rejection is a debug line.

Docs

• Migration Logs guide, with a storage recipe; the examples/migration-service app stores the
  logs and serves them over REST.
• Diagrams — Mermaid, drawn in the browser by a small theme component (mermaid is a docs-only
  devDependency, loaded only by a page that has a diagram). A new How It Works page (the engine
  and its entry points, the life of a run, the lock, where the state lives, background migrations,
  what a run reports), diagrams in Core Concepts, Transactions, Declared Collections, Document
  Versioning, Background Migrations, the queue adapter and Migration Logs, and four in
  ARCHITECTURE.md.
• Home page — twelve features that cover 2.1 – 2.4, a "How it fits together" diagram, the
  smaller features in one list; the Why page names the new features too.

Changed (for code typed against 2.3)

• ctx.background is frozen and typed BackgroundRunInfo. A type change on an experimental
  API: its generation is number | undefined (as it always was at runtime for the live drift
  watcher), so strict TypeScript that reads it as a number needs a check.
• ctx.logger is typed MigrationLogger — every MigronautLogger, and a pino instance, still fits.
  logger? and run? are optional on MigrationContext, so a context built by hand in a test
  still type-checks.
• The kit's log lines of a run that names a job carry jobId / groupId.

Not in this release

• No log storage, no kit.logs(), no migronaut logs command, no counters API — keeping the lines,
  and the UI that shows them, is the application's job (the guide has the recipe).
• The CLI's terminal output is unchanged: the default terminal logger does not print fields.

How to review

The commits are ordered so you can review them one at a time:

1. 8 feature phases — fix(core): contain rejected async event listeners …
   docs(examples): the migration service stores and serves migration logs;
2. 7 pre-release review fixes — fix(core): what a migration logs is copied safely …
   fix(core): mask quoted server values in log data strings too;
3. 5 docs commits — docs: render Mermaid diagrams on the docs site …
   docs: the Why page names what 2.1 to 2.4 added;
4. chore(release): 2.4.0.

Start with src/core/migration-logger.js (ARCHITECTURE §5 and the "What a migration logs" part of
§6.6), then src/bullmq/processor.js and src/bullmq/background-processor.js. "Things that look
like bugs but aren't" in CLAUDE.md lists the intentional behaviours: userland: true exactly, no
storage, rows routed by job id and run id, a job sealed before its last flush, inline lanes told
apart by their group.

Test plan

• prepublishOnly gate: lint, format:check, test:coverage, test:types, check:dts —
  2417 tests; coverage 97.89 / 93.44 / 98.52 (gate 90/90/90).
• Real-BullMQ suite (bullmq-redis.test.js): 75/75 on redis:7-alpine.
• size, docs:build (no warnings); all 26 docs diagrams render in the production build, in
  light and dark, and on a phone.
• Sharded-cluster and Atlas Search suites: not affected by this branch.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
migronaut	Ready	Preview	Oct 7, 2026 8:40pm UTC