skills/docs/persistence/database/migration/src/planner/migration-planner/migration-planner.md

migration-planner

(no submodules)

Purpose

The migration planner produces MigrationPlan objects that describe which migrations should be applied or rolled back, without executing them. Separating planning from execution makes dry-run reporting straightforward, enables validation before any database writes, and simplifies unit testing by removing I/O dependencies from the planning step.

Features

• sortMigrations(migrations) — lexicographic sort by id, putting numeric prefixes in ascending order.
• planUp(all, applied) — returns all pending (not-yet-applied) migrations sorted ascending.
• planDown(all, applied, steps?) — returns the last N applied migrations in reverse (rollback) order.
• checksumForMigration(migration) — returns the stored checksum or computes one from the up function body.

Usage: Basic Example

import { planUp, sortMigrations } from "@suaveplan/migration";

const plan = planUp(allMigrations, []);
// plan.toApply contains all migrations in ascending id order

Usage: Advanced Example

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

// Rollback only the last 2 applied migrations
const plan = planDown(allMigrations, appliedRecords, 2);
// plan.toRollback[0] is the most recently applied migration

API Reference

sortMigrations(migrations: Migration[]): Migration[]

Returns a new array sorted by id ascending. Does not mutate the input.

planUp(all: Migration[], applied: MigrationRecord[]): MigrationPlan

Returns { toApply: Migration[], toRollback: [] }. toApply contains migrations whose id is not in applied.

planDown(all: Migration[], applied: MigrationRecord[], steps?: number): MigrationPlan

Returns { toApply: [], toRollback: Migration[] }. toRollback is at most steps migrations (all if omitted), most-recent first.

checksumForMigration(migration: Migration): string

Returns migration.checksum if set, otherwise computes SHA-256 of migration.up.toString().

Implementation Notes

planDown reverses the sorted applied list before slicing, ensuring rollbacks proceed in most-recent-first order (LIFO). sortMigrations uses localeCompare for reliable multi-character prefix handling.