chore: add a Postgres migration safety guard

Add a CI guard that checks new Prisma migrations for idempotent,
lock-safe DDL: creates must use IF NOT EXISTS, drops IF EXISTS, CREATE
TYPE, ADD CONSTRAINT and RENAME must sit in a guarded DO block, INSERTs
need ON CONFLICT, and indexes on existing tables must be built
CONCURRENTLY in a single-statement migration. The enforced cutoff date
is pinned in the `guard:migrations` script in
`apps/webapp/package.json`; `-- --all` audits the whole history locally.
A `-- migration-guard: allow <reason>` comment opts a single statement
out.

Mono-RevId: 7c937700bc4eae8b5b51fecdb60b620bf3c9807b

Author: matt-aitken

.claude/rules/database-safety.md

@@ -1,13 +1,16 @@
 ---
 paths:
   - "internal-packages/database/**"
+  - "internal-packages/run-ops-database/**"
 ---
 
 # Database Migration Safety
 
 - When adding indexes to **existing tables**, use `CREATE INDEX CONCURRENTLY IF NOT EXISTS` to avoid table locks. These must be in their own separate migration file (one index per file).
-- Indexes on **newly created tables** (same migration as `CREATE TABLE`) do not need CONCURRENTLY.
+- Indexes on **newly created tables** (same migration as `CREATE TABLE`) do not need CONCURRENTLY, but still need `IF NOT EXISTS`. On such a table, `ALTER TABLE ... DROP CONSTRAINT IF EXISTS "name", ADD CONSTRAINT "name" ...` in one statement is an accepted alternative to a DO block for the Prisma-generated constraints.
 - When indexing a **new column on an existing table**, split into two migrations: first `ADD COLUMN IF NOT EXISTS`, then `CREATE INDEX CONCURRENTLY IF NOT EXISTS` in a separate file.
 - After generating a migration with Prisma, remove extraneous lines for: `_BackgroundWorkerToBackgroundWorkerFile`, `_BackgroundWorkerToTaskQueue`, `_TaskRunToTaskRunTag`, `_WaitpointRunConnections`, `_completedWaitpoints`, `SecretStore_key_idx`, and unrelated TaskRun indexes.
+- Every statement must be idempotent so a migration can be re-run after a partial apply: `CREATE TABLE IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS`, `ADD VALUE IF NOT EXISTS`, `DROP ... IF EXISTS`, `DROP INDEX CONCURRENTLY IF EXISTS`. `CREATE TYPE`, `ADD CONSTRAINT` and `RENAME` have no `IF NOT EXISTS`, so wrap each one in a `DO $$ ... $$` block under an `IF NOT EXISTS (SELECT 1 FROM pg_type / pg_constraint / pg_attribute ...) THEN ... END IF` guard (or give the block an `EXCEPTION WHEN duplicate_object` handler). Data `INSERT`s need `ON CONFLICT`.
+- CI enforces this via `pnpm --filter webapp run guard:migrations`; the enforced cutoff date is the `--cutoff` pinned in that script in `apps/webapp/package.json` (rules in `apps/webapp/scripts/migrationSafetyGuard.core.ts`). A statement that genuinely cannot comply may carry `-- migration-guard: allow <reason>` on the line above it.
 - Never drop columns or tables without explicit approval.
 - New code should target `RunEngineVersion.V2` only.

.github/workflows/migration-guard.yml

@@ -0,0 +1,34 @@
+name: "🛡️ Migration Safety Guard"
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  migration-guard:
+    runs-on: warp-ubuntu-latest-x64-16x
+
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: ⎔ Setup pnpm
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+        with:
+          version: 10.33.2
+
+      - name: ⎔ Setup node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24.18.0
+          cache: "pnpm"
+
+      - name: 📥 Download deps
+        run: pnpm install --frozen-lockfile
+
+      - name: 🛡️ Migration safety guard
+        run: pnpm --filter webapp run guard:migrations

.github/workflows/pr_checks.yml

@@ -21,6 +21,7 @@ jobs:
       code: ${{ steps.code_filter.outputs.code }}
       typecheck_self: ${{ steps.filter.outputs.typecheck_self }}
       webapp: ${{ steps.filter.outputs.webapp == 'true' || steps.shared_packages_filter.outputs.shared_packages == 'true' }}
+      migrations: ${{ steps.filter.outputs.migrations }}
       packages: ${{ steps.filter.outputs.packages }}
       internal: ${{ steps.filter.outputs.internal == 'true' || steps.shared_packages_filter.outputs.shared_packages == 'true' }}
       obsmap: ${{ steps.filter.outputs.obsmap }}
@@ -73,6 +74,14 @@ jobs:
               - 'pnpm-lock.yaml'
               - 'pnpm-workspace.yaml'
               - 'turbo.json'
+            migrations:
+              - 'internal-packages/database/prisma/migrations/**'
+              - 'internal-packages/run-ops-database/prisma/migrations/**'
+              - 'apps/webapp/scripts/migrationSafetyGuard*.ts'
+              - 'apps/webapp/scripts/lib/**'
+              - 'apps/webapp/package.json'
+              - '.github/workflows/pr_checks.yml'
+              - '.github/workflows/migration-guard.yml'
             packages:
               - 'packages/**'
               - '.github/workflows/pr_checks.yml'
@@ -181,6 +190,11 @@ jobs:
     if: needs.changes.outputs.webapp == 'true'
     uses: ./.github/workflows/fk-cascade-guard.yml
 
+  migration-guard:
+    needs: changes
+    if: needs.changes.outputs.migrations == 'true'
+    uses: ./.github/workflows/migration-guard.yml
+
   webapp:
     needs: changes
     if: needs.changes.outputs.webapp == 'true'
@@ -238,6 +252,7 @@ jobs:
       - typecheck
       - runops-guard
       - fk-cascade-guard
+      - migration-guard
       - webapp
       - e2e-webapp
       - packages

apps/webapp/package.json

@@ -18,6 +18,7 @@
     "typecheck": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192\" tsc --noEmit -p ./tsconfig.check.json",
     "guard:runops-legacy": "cross-env NODE_OPTIONS=\"--max-old-space-size=8192\" tsx ./scripts/runOpsLegacyGuard.ts",
     "guard:fk-cascade-index": "tsx ./scripts/fkCascadeIndexGuard.ts",
+    "guard:migrations": "tsx ./scripts/migrationSafetyGuard.ts --cutoff 20260918",
     "env:check": "varlock load --agent",
     "env": "varlock run --inject vars --",
     "db:seed": "varlock run --inject vars -- tsx seed.ts",

apps/webapp/scripts/fkCascadeIndexGuard.ts

@@ -32,17 +32,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-
-function findRepoRoot(start: string): string {
-  let dir = path.resolve(start);
-  for (;;) {
-    if (fs.existsSync(path.join(dir, "pnpm-workspace.yaml"))) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir)
-      throw new Error("Could not locate repo root (pnpm-workspace.yaml not found)");
-    dir = parent;
-  }
-}
+import { findRepoRoot } from "./lib/repoRoot";
 
 const REPO_ROOT = findRepoRoot(process.cwd());
 

apps/webapp/scripts/lib/repoRoot.ts

@@ -0,0 +1,14 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Walks up from `start` to the pnpm workspace root the guard scripts resolve paths against. */
+export function findRepoRoot(start: string): string {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, "pnpm-workspace.yaml"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir)
+      throw new Error("Could not locate repo root (pnpm-workspace.yaml not found)");
+    dir = parent;
+  }
+}