Browse documentation

@dads-framework/migrations — the Postgres migration runner

On this page

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.

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

Try it

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

Shell
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.

TypeScript
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 · Starter schema migration

What it refuses to do

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