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