Browse documentation

@dads-framework/authorization-migration

On this page

Scaffold and apply ordered SpiceDB schema snapshots and relationship migration steps.

Try it

The generated starter uses Postgres for authorization in assembly/services.ts. For the SpiceDB schema journal, see the repository's journal runner tests, which show ordered application and a rerun that skips applied entries.

Use Node.js 22 or later. The script creates a temporary journal, previews the first migration ID, then checks that scaffolding the same schema again is a no-op. No SpiceDB instance is needed to scaffold.

Shell
npm install @dads-framework/authorization-migration
npm install -D tsx

Save as scaffold-journal.mts and run npx tsx scaffold-journal.mts.

TypeScript
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
  listShippedAuthorizationMigrationIds,
  scaffoldMigration,
} from "@dads-framework/authorization-migration";

const journalFolder = await mkdtemp(join(tmpdir(), "dads-journal-"));
try {
  const input = {
    journalFolder,
    mode: "new",
    slug: "baseline",
    composedSchema: `
definition authz/migration_version {}
definition authz/migration_journal {
  relation applied: authz/migration_version
}
definition user {}
`,
  } satisfies Parameters<typeof scaffoldMigration>[0];

  console.log((await scaffoldMigration(input)).action);
  console.log(
    (await listShippedAuthorizationMigrationIds(journalFolder)).join(),
  );
  console.log((await scaffoldMigration(input)).action);
} finally {
  await rm(journalFolder, { recursive: true, force: true });
}

The script prints created, 0001_baseline, and up-to-date. To retain the generated index.ts, schema.zed, and migration.ts in your app, use an existing journal directory and omit the temporary directory cleanup.

Use it

Pass the generated index's journal, the absolute path of its directory, an AuthorizationMigrationStore, and a logger with an info method to runAuthorizationMigrations. For a development run against SpiceDB, start with a dedicated datastore and construct SpiceDbAuthorization from @dads-framework/authorization with its endpoint and credentials. Pass the adapter as store. A successful run logs the applied ID. Rerunning the same journal reports zero newly applied entries.

For independently authored patches, use scaffoldAuthorizationChange and pass their directory as changesFolder on the same runner. Each patch records the definitions it changes and the changes it depends on. renumberMigration moves a snapshot entry that collided with another branch.

What it refuses to do

The runner rejects gaps, duplicate entries, unregistered folders, and snapshots that drop the journal definition. A destructive entry after the baseline requires the relationship steps that make its schema write legal.

Contract

Each NNNN_slug holds a full schema snapshot. The runner calls beforeSchemaWrite, writes the snapshot, and then calls afterSchemaWrite when those steps are present. It records success as an authz/migration_version relationship. A failure leaves the marker unwritten. Make relationship steps safe to repeat when retrying an entry.