<a id="dads-frameworkmigrations-the-postgres-migration-runner"></a>

# @dads-framework/migrations — the Postgres migration runner

Deploy schema changes in a repeatable order and check which migrations each database has applied. The runner applies `<utcTimestamp>_<slug>.migration.ts` files built with node-pg-migrate and records them in a journal. It validates the checked-in journal, keeps its immutable legacy prefix, checksums every applied file, takes an advisory lock, and applies pending dependency (`dependsOn`) migrations in one transaction. A file exporting `ownTransaction` commits alone; a file exporting `buildsIndexesConcurrently` runs only concurrent index statements, outside any transaction. Independent migrations keep stable filenames when another branch deploys first. The runner obtains its dedicated Postgres session from `@dads-framework/postgres` and closes it at the end of the run.

Where migrations live is the caller's to say. A `MigrationWorkspace` names a root, the folders to walk (each with the pattern that picks out its migration files and its owner), and the module aliases a migration may import. `defaultMigrationWorkspace(root)` is this repository's layout: every server part's `src/lib/**/migrations/` folder, plus an optional top-level `migrations/` folder owned by `app`.

`@dads-framework/migrations/journal-status` is the read-only view for reporting: the migration files a build ships and the database's applied journal, without bundling the runner or node-pg-migrate.

<a id="commands"></a>

## Commands

Each reads `DATABASE_URL` and `WORKSPACE_ROOT` (default `.`) and uses the default workspace. `dads-migration-check` uses the Postgres testing export to start an isolated container and requires the optional Testcontainers dependencies of `@dads-framework/postgres`.

| Bin | What it does |
| --- | --- |
| `dads-migrate` | apply every pending migration |
| `dads-migrate-adopt` | record a leftover schema as applied, only when it equals what the journal builds |
| `dads-migrate-status` | print `current`, `node-pg-pending`, `legacy-pending`, or a refusal |
| `dads-migration-new` | scaffold a migration for an owner, depending on the current frontier |
| `dads-migration-check` | rehearse added migrations against a pinned base commit in a throwaway Postgres |

<a id="try-it"></a>

## Try it

In a Node.js 22+ project, install the runner and create a migration.

```sh
npm install @dads-framework/migrations node-pg-migrate
mkdir -p migrations
cat > migrations/20260101000000_create_notes.migration.ts <<'EOF'
import type { MigrationBuilder } from "node-pg-migrate";

export const dependsOn = [];

export function up(pgm: MigrationBuilder) {
  pgm.createTable("notes", { id: { type: "serial", primaryKey: true } });
}

export function down(pgm: MigrationBuilder) {
  pgm.dropTable("notes");
}
EOF
```

Set `DATABASE_URL` to an empty PostgreSQL database where your role can create schemas and tables. From the project root, save this as `example.mts` and run `node --experimental-strip-types example.mts`.

```ts
import { runNodePgMigrations } from "@dads-framework/migrations";

const databaseUrl = process.env["DATABASE_URL"];
if (!databaseUrl) throw new Error("Set DATABASE_URL");

await runNodePgMigrations({
  databaseUrl,
  workspace: {
    root: process.cwd(),
    sources: [
      {
        root: "migrations",
        files: /^migrations\/[^/]+\.migration\.ts$/,
        owner: "app",
        required: true,
      },
    ],
    moduleAliases: {},
  },
});
console.log("Migrations complete");
```

The first run creates the `notes` table and records the migration in the journal. Running the script again skips the recorded migration.

In the generated app, `assembly/migrations.ts` points the runner at `migrations/`. [Starter runner](https://dadsframework.dev/docs/source/apps/kit-workbench/assembly/migrations.ts) · [Starter schema migration](https://dadsframework.dev/docs/source/apps/kit-workbench/migrations/20261120080000_starter.migration.ts)

<a id="what-it-refuses-to-do"></a>

## What it refuses to do

The runner uses a declared migration workspace. It refuses mismatched applied checksums before updating the schema.

Canonical page: <https://dadsframework.dev/docs/package-migrations>
