suaveplan/packages/persistence/database/migration/src/status/migration-status/migration-status.md

migration-status

(no submodules)

Purpose

MigrationStatusDashboard provides a read-only view over the migration store. It computes per-migration status, aggregate counts, and a health check that can be wired into application readiness probes. Separating status reporting from the runner ensures that status queries never trigger migrations and can be called at any time without locking concerns.

Features

• getAll() — returns every registered migration with its current status (pending, applied, rolled-back).
• getSummary() — returns aggregate counts for total, applied, pending, and failed migrations.
• healthCheck() — returns { healthy, pendingCount, failedCount } suitable for a /healthz endpoint.
• getHistory(id) — returns all ledger entries for a specific migration id (supports audit queries).

Usage: Basic Example

import { MigrationStatusDashboard, MemoryMigrationStore } from "@suaveplan/migration";

const dashboard = new MigrationStatusDashboard({ store, migrations });
const summary = await dashboard.getSummary();
// { total: 5, applied: 4, pending: 1, failed: 0 }

Usage: Advanced Example

import { MigrationStatusDashboard } from "@suaveplan/migration";

const dashboard = new MigrationStatusDashboard({ store, migrations });
const health = await dashboard.healthCheck();
if (!health.healthy) {
  console.warn(`${health.pendingCount} pending migrations, ${health.failedCount} failed`);
}

API Reference

class MigrationStatusDashboard

Constructor: (config: StatusConfig)

• config.store — MigrationStoreAdapter.

• config.migrations — registered Migration[].

• config.clock? — injectable clock.

• getAll(): Promise<ExtendedMigrationStatus[]> — sorted by id.

• getSummary(): Promise<MigrationSummary> — { total, applied, pending, failed }.

• healthCheck(): Promise<MigrationHealthCheck> — { healthy, pendingCount, failedCount }.

• getHistory(id: string): Promise<MigrationHistoryEntry[]> — ledger entries for one migration.

Implementation Notes

healthy is true only when both pending === 0 and failed === 0. This is intentionally strict: unnapplied migrations in production are a deployment concern that should always be visible. The getHistory method supports audit use cases where the same migration may have been applied and rolled back multiple times.