Migrations

Better IAM owns its schema: three tables and their indexes, created and upgraded by its own migrations. You never write migration files for it and never generate ORM models. Each release ships an ordered list of named schema steps; running the migration applies the ones your database has not seen yet and records each in the iam_migrations table. Run it once per deploy, before the new release serves traffic.

Usage

Run migrations with the CLI

npx better-iam migrate --config better-iam.config.mjs

migrate loads the configuration (from --config, BETTER_IAM_CONFIG, or the nearest better-iam.config.mjs, .js, or .ts), calls iam.initialize(), and prints Database and plugin migrations applied. It is idempotent: running it again on an up-to-date database changes nothing.

Without a configuration file, the CLI builds the adapter from BETTER_IAM_DATABASE_URL and BETTER_IAM_SECRET (see Databases). Plugins are not configured in that mode, so their migrations do not run.

Run migrations from code

iam.initialize() does the same work as the CLI command. Call it from a deploy script or a release hook:

import { iam } from '../iam';

try {
  await iam.initialize();
} finally {
  await iam.store.close();
}

initialize() runs four steps, in order:

1. store.migrate(): applies the built-in schema steps the database lacks, inside the adapter's serialized write transaction.
2. Each plugin's migrate(store), each in its own transaction.
3. Starts the retention window of tenants deleted before deletion timestamps existed (sets deletedAt).
4. Chains audit events recorded before the audit chain existed, for tenants that have no chain yet. The first initialize() after upgrading from an unchained release backfills the whole log in one transaction.

The Nuxt module calls iam.initialize() before first use by default; set betterIam: { initialize: false } in nuxt.config.ts to run it as a deploy step instead. The other integrations never migrate on their own.

Load the CLI configuration in a script

loadConfig() from better-iam/cli resolves and instantiates the configuration file exactly like the CLI does, which keeps one source of truth for scripts, workers, and tests:

import { loadConfig } from 'better-iam/cli';

const iam = await loadConfig({ config: 'better-iam.config.mjs' });
try {
  await iam.initialize();
} finally {
  await iam.store.close();
}

Apply only the schema

store.migrate() creates and upgrades the tables and indexes without running plugin migrations or data backfills. store-import and store-copy use it on their target, because initialize() may write records and the target must stay empty until the import.

import { postgresAdapter } from 'better-iam/adapter-postgres';

const database = postgresAdapter({ connectionString: process.env.DATABASE_URL! });
try {
  await database.migrate();
} finally {
  await database.close();
}

Check which migrations ran

doctor prints the applied steps with their times under storage.migrations, and reports schema-behind (an error) when the database lacks a step of the running release or has no schema at all:

npx better-iam doctor --config better-iam.config.mjs --query 'storage.migrations[].name'

In code, iam.selfCheck() returns the same storage description and findings, and iam.store.describe() returns just the description:

import { schemaMigrations } from 'better-iam/core';
import { iam } from '../iam';

const description = await iam.store.describe?.();
const applied = new Set(description?.migrations.map((migration) => migration.name));
const missing = schemaMigrations('sqlite')
  .map((migration) => migration.name)
  .filter((name) => !applied.has(name));
console.log({ schemaVersion: description?.schemaVersion, missing });
await iam.store.close();

schemaMigrations('sqlite') and schemaMigrations('postgres') list the same step names; only their SQL differs.

Schema steps

A released step never changes; new indexes and fields get a new step. Steps only add tables and indexes, and use IF NOT EXISTS. The exact index names and fields are listed in Schema.

The iam_migrations table

applyMigrations creates two bookkeeping tables before any step:

CREATE TABLE IF NOT EXISTS iam_schema_version (
  id INTEGER PRIMARY KEY CHECK (id = 1),
  version INTEGER NOT NULL
);
CREATE TABLE IF NOT EXISTS iam_migrations (
  name TEXT PRIMARY KEY,
  applied_at BIGINT NOT NULL
);

• iam_migrations holds one row per applied step: its name and applied_at in epoch milliseconds. A step whose name is present is skipped.
• iam_schema_version holds a single row with version = 1. A database with any other version is refused with SCHEMA_VERSION, so a release never runs against a schema generation it does not understand.

All missing steps run inside one serialized write transaction of the adapter: their statements and ledger rows commit together, or not at all. On PostgreSQL, the 0002_query_indexes step first rewrites existing rows that jsonb cannot hold (see value encoding).

Plugin migrations

A plugin's migrate(store) callback runs on every initialize(), in its own transaction, after the built-in steps. Plugin migrations are not recorded in iam_migrations, so they must be idempotent: check whether their work is done before doing it. Plugins store their records through the same IamStore, in collections of their own; they do not create tables. See Adapters and plugins.

Upgrades

When you upgrade Better IAM, run the new release's migration before the new release serves traffic. See Upgrade Better IAM for release-specific notes.

• Rolling upgrades. Instances of the previous release keep working while the new one migrates and starts: steps only add indexes and tables, and a release ignores ledger rows it does not know. On PostgreSQL, old instances read rows rewritten by the value encoding raw, which only matters for records holding U+0000 or unpaired surrogates.
• Concurrent migrations are safe. Two instances that migrate at once serialize on the adapter's lock; the second sees the first's ledger rows and applies nothing. On PostgreSQL, a migration waits up to ten minutes for the lock instead of the usual lockTimeoutMs.
• Index builds block writes. Every step builds its indexes inside the migration transaction, which holds the adapter's write lock. On large tables, IAM writes wait until it commits (on PostgreSQL, reads continue; on SQLite and libSQL, reads in the migrating process also wait), so plan a maintenance window for upgrades that add steps.
• No down migrations. There is no command to undo a step. Rolling the application back to an earlier release is supported by the rule above; restoring an older schema means restoring a backup.
• After a bulk load on PostgreSQL, run VACUUM ANALYZE iam_records so the GIN index's pending list is merged and planner statistics are current.

CI and deploys

Run migrations as an explicit pipeline step, never from a request handler. A typical setup:

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:17-alpine
        env:
          POSTGRES_PASSWORD: ci-password
          POSTGRES_DB: iam_test
        ports: ['5432:5432']
        options: >-
          --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
    env:
      DATABASE_URL: postgres://postgres:ci-password@localhost:5432/iam_test
      BETTER_IAM_SECRET: ci-only-secret-with-at-least-32-characters
      BETTER_IAM_BASE_URL: http://localhost:3000
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx better-iam migrate --config better-iam.config.mjs
      - run: npm test

npx better-iam migrate --config better-iam.config.mjs

npx better-iam doctor --config better-iam.config.mjs --strict --retention-days 30

Errors

Next steps