Skip to content

The open-source app everyone uses to manage agents at work

feat(db): add migration safety lint

Nicky Leach22001bbd2f5c
diff --git a/packages/db/package.json b/packages/db/package.json
index 90b6edd6c0..1b1aae509a 100644
--- a/packages/db/package.json
+++ b/packages/db/package.json
@@ -35,7 +35,7 @@
"dist"
],
"scripts": {
- "check:migrations": "tsx src/check-migration-numbering.ts",
+ "check:migrations": "tsx src/check-migration-numbering.ts && tsx src/check-migration-safety.ts",
"build": "pnpm run check:migrations && tsc && cp -r src/migrations dist/migrations",
"clean": "rm -rf dist",
"typecheck": "pnpm run check:migrations && tsc --noEmit",
diff --git a/packages/db/src/check-migration-safety.test.ts b/packages/db/src/check-migration-safety.test.ts
new file mode 100644
index 0000000000..57e3dd220b
--- /dev/null
+++ b/packages/db/src/check-migration-safety.test.ts
@@ -0,0 +1,492 @@
+import { describe, expect, it } from "vitest";
+import {
+ analyzeMigrationSafety,
+ type MigrationSafetyInput,
+} from "./check-migration-safety.js";
+import {
+ TABLE_SIZE_ESTIMATE_FACTOR,
+ TABLE_SIZE_BUCKET_THRESHOLDS,
+ type TableSizeEstimate,
+} from "./table-size-estimates.js";
+
+const testEstimates: readonly TableSizeEstimate[] = [
+ {
+ table: "issue_comments",
+ localRows: 5_034,
+ estimateFactor: TABLE_SIZE_ESTIMATE_FACTOR,
+ estimatedRows: 5_034 * TABLE_SIZE_ESTIMATE_FACTOR,
+ bucket: "large",
+ },
+ {
+ table: "companies",
+ localRows: 1,
+ estimateFactor: TABLE_SIZE_ESTIMATE_FACTOR,
+ estimatedRows: TABLE_SIZE_ESTIMATE_FACTOR,
+ bucket: "small",
+ },
+];
+
+function analyze(sql: string) {
+ const migrations: readonly MigrationSafetyInput[] = [{ fileName: "9999_fixture.sql", sql }];
+ return analyzeMigrationSafety(migrations, { baselineIds: [], estimates: testEstimates });
+}
+
+describe("migration safety check", () => {
+ it("documents the large table threshold used by the estimates", () => {
+ expect(TABLE_SIZE_BUCKET_THRESHOLDS.largeRows).toBe(1_000_000);
+ expect(testEstimates[0]?.estimatedRows).toBeGreaterThanOrEqual(
+ TABLE_SIZE_BUCKET_THRESHOLDS.largeRows,
+ );
+ });
+
+ it("fails a 0126-shaped batched loop over a large table without a support index", () => {
+ const result = analyze(`
+ DO $$
+ DECLARE
+ last_comment_id uuid := '00000000-0000-0000-0000-000000000000'::uuid;
+ BEGIN
+ LOOP
+ WITH batch AS MATERIALIZED (
+ SELECT c."id"
+ FROM "issue_comments" c
+ WHERE c."id" > last_comment_id
+ AND c."author_agent_id" IS NULL
+ ORDER BY c."id"
+ LIMIT 5000
+ )
+ UPDATE "issue_comments" c
+ SET "derived_author_agent_id" = NULL
+ FROM batch b
+ WHERE c."id" = b."id";
+
+ EXIT WHEN NOT FOUND;
+ END LOOP;
+ END $$;
+ `);
+
+ expect(result.newFindings.map((finding) => finding.rule)).toEqual(
+ expect.arrayContaining([
+ "loop-mutation-large-table",
+ "batched-mutation-large-table-missing-index",
+ ]),
+ );
+ expect(result.newFindings[0]?.table).toBe("issue_comments");
+ });
+
+ it("passes the same bounded large-table backfill when a matching concurrent support index exists", () => {
+ const result = analyze(`
+ CREATE INDEX CONCURRENTLY IF NOT EXISTS "issue_comments_fixture_backfill_idx"
+ ON "issue_comments" USING btree ("id")
+ WHERE "author_agent_id" IS NULL;--> statement-breakpoint
+ DO $$
+ DECLARE
+ last_comment_id uuid := '00000000-0000-0000-0000-000000000000'::uuid;
+ BEGIN
+ LOOP
+ WITH batch AS MATERIALIZED (
+ SELECT c."id"
+ FROM "issue_comments" c
+ WHERE c."id" > last_comment_id
+ AND c."author_agent_id" IS NULL
+ ORDER BY c."id"
+ LIMIT 5000
+ )
+ UPDATE "issue_comments" c
+ SET "derived_author_agent_id" = NULL
+ FROM batch b
+ WHERE c."id" = b."id";
+
+ EXIT WHEN NOT FOUND;
+ END LOOP;
+ END $$;
+ `);
+
+ expect(result.newFindings).toEqual([]);
+ });
+
+ it("does not suppress missing-index finding when a partial support index predicate is incompatible with the batch WHERE", () => {
+ const result = analyze(`
+ CREATE INDEX CONCURRENTLY IF NOT EXISTS "issue_comments_fixture_backfill_idx"
+ ON "issue_comments" USING btree ("id")
+ WHERE "author_agent_id" IS NOT NULL;--> statement-breakpoint
+ DO $$
+ DECLARE
+ last_comment_id uuid := '00000000-0000-0000-0000-000000000000'::uuid;
+ BEGIN
+ LOOP
+ WITH batch AS MATERIALIZED (
+ SELECT c."id"
+ FROM "issue_comments" c
+ WHERE c."id" > last_comment_id
+ AND c."author_agent_id" IS NULL
+ ORDER BY c."id"
+ LIMIT 5000
+ )
+ UPDATE "issue_comments" c
+ SET "derived_author_agent_id" = NULL
+ FROM batch b
+ WHERE c."id" = b."id";
+
+ EXIT WHEN NOT FOUND;
+ END LOOP;
+ END $$;
+ `);
+
+ expect(result.newFindings.map((finding) => finding.rule)).toContain(
+ "batched-mutation-large-table-missing-index",
+ );
+ });
+
+ it("passes a batched backfill over a small-bucket table", () => {
+ const result = analyze(`
+ DO $$
+ BEGIN
+ LOOP
+ WITH batch AS (
+ SELECT "id"
+ FROM "companies"
+ ORDER BY "id"
+ LIMIT 100
+ )
+ UPDATE "companies" c
+ SET "description" = c."description"
+ FROM batch b
+ WHERE c."id" = b."id";
+
+ EXIT WHEN NOT FOUND;
+ END LOOP;
+ END $$;
+ `);
+
+ expect(result.newFindings).toEqual([]);
+ });
+
+ it("flags UPDATE ... FROM (SELECT ... LIMIT N) subquery batch on a large table", () => {
+ const result = analyze(`
+ UPDATE "issue_comments" c
+ SET "derived_author_agent_id" = NULL
+ FROM (
+ SELECT "id"
+ FROM "issue_comments"
+ WHERE "author_agent_id" IS NULL
+ ORDER BY "id"
+ LIMIT 5000
+ ) batch
+ WHERE c."id" = batch."id";
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "batched-mutation-large-table-missing-index",
+ );
+ });
+
+ it("flags UPDATE ... FROM (SELECT ... FETCH FIRST N ROWS ONLY) subquery batch on a large table", () => {
+ const result = analyze(`
+ UPDATE "issue_comments" c
+ SET "derived_author_agent_id" = NULL
+ FROM (
+ SELECT "id"
+ FROM "issue_comments"
+ WHERE "author_agent_id" IS NULL
+ ORDER BY "id"
+ FETCH FIRST 5000 ROWS ONLY
+ ) batch
+ WHERE c."id" = batch."id";
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "batched-mutation-large-table-missing-index",
+ );
+ });
+
+ it("flags UPDATE ... FROM (SELECT ... FETCH NEXT N ROWS ONLY) subquery batch on a large table", () => {
+ const result = analyze(`
+ UPDATE "issue_comments" c
+ SET "derived_author_agent_id" = NULL
+ FROM (
+ SELECT "id"
+ FROM "issue_comments"
+ WHERE "author_agent_id" IS NULL
+ ORDER BY "id"
+ FETCH NEXT 5000 ROWS ONLY
+ ) batch
+ WHERE c."id" = batch."id";
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "batched-mutation-large-table-missing-index",
+ );
+ });
+
+ it("flags UPDATE ... FROM (SELECT ... FETCH FIRST N ROWS WITH TIES) subquery batch on a large table", () => {
+ const result = analyze(`
+ UPDATE "issue_comments" c
+ SET "derived_author_agent_id" = NULL
+ FROM (
+ SELECT "id"
+ FROM "issue_comments"
+ WHERE "author_agent_id" IS NULL
+ ORDER BY "id"
+ FETCH FIRST 5000 ROWS WITH TIES
+ ) batch
+ WHERE c."id" = batch."id";
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "batched-mutation-large-table-missing-index",
+ );
+ });
+
+ it("flags UPDATE ... FROM (SELECT ... FETCH FIRST ROW ONLY) subquery batch on a large table", () => {
+ const result = analyze(`
+ UPDATE "issue_comments" c
+ SET "derived_author_agent_id" = NULL
+ FROM (
+ SELECT "id"
+ FROM "issue_comments"
+ WHERE "author_agent_id" IS NULL
+ ORDER BY "id"
+ FETCH FIRST ROW ONLY
+ ) batch
+ WHERE c."id" = batch."id";
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "batched-mutation-large-table-missing-index",
+ );
+ });
+
+ it("flags UPDATE ... WHERE IN (SELECT ... LIMIT N) subquery batch on a large table", () => {
+ const result = analyze(`
+ UPDATE "issue_comments"
+ SET "derived_author_agent_id" = NULL
+ WHERE "id" IN (
+ SELECT "id"
+ FROM "issue_comments"
+ WHERE "author_agent_id" IS NULL
+ ORDER BY "id"
+ LIMIT 5000
+ );
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "batched-mutation-large-table-missing-index",
+ );
+ });
+
+ it("flags a CTE with a selective WHERE when the outer UPDATE has no WHERE clause", () => {
+ const result = analyze(`
+ WITH selective AS (
+ SELECT "id" FROM "issue_comments" WHERE "author_agent_id" IS NULL
+ )
+ UPDATE "issue_comments"
+ SET "derived_author_agent_id" = NULL
+ FROM selective;
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "full-table-mutation-large-table",
+ );
+ });
+
+ it("does not treat WHERE inside a block comment as a selective predicate", () => {
+ const result = analyze(`
+ UPDATE "issue_comments"
+ SET "derived_author_agent_id" = NULL /* ignored
+ /* nested WHERE "id" > '0' */
+ still ignored
+ */;
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "full-table-mutation-large-table",
+ );
+ });
+
+ it("does not treat WHERE inside an inline line comment as a selective predicate", () => {
+ const result = analyze(`
+ UPDATE "issue_comments"
+ SET "derived_author_agent_id" = NULL -- WHERE "id" > '0'
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "full-table-mutation-large-table",
+ );
+ });
+
+ it("does not treat WHERE inside a string literal as a selective predicate", () => {
+ const result = analyze(`
+ UPDATE "issue_comments"
+ SET "body" = 'WHERE "id" > ''0''';
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "full-table-mutation-large-table",
+ );
+ });
+
+ it("does not treat WHERE inside a tagged dollar-quoted string as a selective predicate", () => {
+ const result = analyze(`
+ UPDATE "issue_comments"
+ SET "body" = $msg$WHERE "id" > '0'$msg$;
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "full-table-mutation-large-table",
+ );
+ });
+
+ it("does not treat WHERE inside an untagged dollar-quoted string as a selective predicate", () => {
+ const result = analyze(`
+ UPDATE "issue_comments"
+ SET "body" = $$WHERE "id" > '0'$$;
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "full-table-mutation-large-table",
+ );
+ });
+
+ it("still accepts a real selective WHERE clause", () => {
+ const result = analyze(`
+ UPDATE "issue_comments"
+ SET "derived_author_agent_id" = NULL
+ WHERE "id" > '0';
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).not.toContain(
+ "full-table-mutation-large-table",
+ );
+ });
+
+ it("does not suppress full-table finding when WHERE only constrains a joined table", () => {
+ const result = analyze(`
+ UPDATE "issue_comments"
+ SET "derived_author_agent_id" = NULL
+ FROM "companies"
+ WHERE "companies"."id" = '00000000-0000-0000-0000-000000000000';
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "full-table-mutation-large-table",
+ );
+ });
+
+ it("does not suppress full-table finding when WHERE only constrains a joined table via an unquoted alias", () => {
+ const result = analyze(`
+ UPDATE "issue_comments"
+ SET "derived_author_agent_id" = NULL
+ FROM "companies" c
+ WHERE c."id" = '00000000-0000-0000-0000-000000000000';
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "full-table-mutation-large-table",
+ );
+ });
+
+ it("does not suppress full-table finding when WHERE only constrains an unquoted joined table", () => {
+ const result = analyze(`
+ UPDATE "issue_comments"
+ SET "derived_author_agent_id" = NULL
+ FROM companies
+ WHERE companies.id = '00000000-0000-0000-0000-000000000000';
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "full-table-mutation-large-table",
+ );
+ });
+
+ it("does not suppress missing-index finding when support index uses an expression", () => {
+ const result = analyze(`
+ CREATE INDEX CONCURRENTLY IF NOT EXISTS "issue_comments_expr_idx"
+ ON "issue_comments" ((lower("body")));--> statement-breakpoint
+ UPDATE "issue_comments" c
+ SET "derived_author_agent_id" = NULL
+ FROM (
+ SELECT "id"
+ FROM "issue_comments"
+ ORDER BY "id"
+ LIMIT 5000
+ ) b
+ WHERE c."id" = b."id";
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "batched-mutation-large-table-missing-index",
+ );
+ });
+
+ it("flags a batch backfill when the support index does not cover the ORDER BY key", () => {
+ const result = analyze(`
+ CREATE INDEX CONCURRENTLY IF NOT EXISTS "issue_comments_author_idx"
+ ON "issue_comments" ("author_agent_id");--> statement-breakpoint
+ DO $$
+ DECLARE
+ last_id uuid := '00000000-0000-0000-0000-000000000000'::uuid;
+ BEGIN
+ LOOP
+ WITH batch AS MATERIALIZED (
+ SELECT "id"
+ FROM "issue_comments"
+ WHERE "id" > last_id
+ ORDER BY "id"
+ LIMIT 5000
+ )
+ UPDATE "issue_comments" c
+ SET "derived_author_agent_id" = NULL
+ FROM batch b
+ WHERE c."id" = b."id";
+
+ EXIT WHEN NOT FOUND;
+ END LOOP;
+ END $$;
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "batched-mutation-large-table-missing-index",
+ );
+ });
+
+ it("flags a batch backfill when the support index only covers a later ORDER BY column", () => {
+ const result = analyze(`
+ CREATE INDEX CONCURRENTLY IF NOT EXISTS "issue_comments_created_idx"
+ ON "issue_comments" ("created_at");--> statement-breakpoint
+ DO $$
+ DECLARE
+ last_id uuid := '00000000-0000-0000-0000-000000000000'::uuid;
+ BEGIN
+ LOOP
+ WITH batch AS MATERIALIZED (
+ SELECT "id"
+ FROM "issue_comments"
+ WHERE "id" > last_id
+ ORDER BY "id", "created_at"
+ LIMIT 5000
+ )
+ UPDATE "issue_comments" c
+ SET "derived_author_agent_id" = NULL
+ FROM batch b
+ WHERE c."id" = b."id";
+
+ EXIT WHEN NOT FOUND;
+ END LOOP;
+ END $$;
+ `);
+
+ expect(result.newFindings.map((f) => f.rule)).toContain(
+ "batched-mutation-large-table-missing-index",
+ );
+ });
+
+ it("honors suppressions only when they name a rule and reason", () => {
+ const result = analyze(`
+ -- paperclip:migration-safety-ignore full-table-mutation-large-table: one-time metadata reset approved in issue thread
+ UPDATE "issue_comments"
+ SET "derived_author_source" = NULL;
+ `);
+
+ expect(result.newFindings).toEqual([]);
+ });
+});
diff --git a/packages/db/src/check-migration-safety.ts b/packages/db/src/check-migration-safety.ts
new file mode 100644
index 0000000000..1f0e47a9ac
--- /dev/null
+++ b/packages/db/src/check-migration-safety.ts
@@ -0,0 +1,1052 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { MIGRATION_SAFETY_BASELINE } from "./migration-safety-baseline.js";
+import {
+ getTableSizeEstimate,
+ isKnownLargeTable,
+ type TableSizeEstimate,
+} from "./table-size-estimates.js";
+
+const migrationsDir = fileURLToPath(new URL("./migrations", import.meta.url));
+
+export type MigrationSafetyRule =
+ | "loop-mutation-large-table"
+ | "batched-mutation-large-table-missing-index"
+ | "full-table-mutation-large-table"
+ | "large-create-index-not-concurrently";
+
+export type MigrationSafetySeverity = "error" | "warning";
+
+export type MigrationSafetyFinding = {
+ readonly id: string;
+ readonly rule: MigrationSafetyRule;
+ readonly severity: MigrationSafetySeverity;
+ readonly migration: string;
+ readonly table: string;
+ readonly statement: string;
+ readonly message: string;
+};
+
+export type MigrationSafetyInput = {
+ readonly fileName: string;
+ readonly sql: string;
+};
+
+export type MigrationSafetyResult = {
+ readonly findings: readonly MigrationSafetyFinding[];
+ readonly newFindings: readonly MigrationSafetyFinding[];
+ readonly baselineFindings: readonly MigrationSafetyFinding[];
+ readonly staleBaselineIds: readonly string[];
+};
+
+type RuleMetadata = {
+ readonly severity: MigrationSafetySeverity;
+ readonly message: string;
+};
+
+type CreateIndexInfo = {
+ readonly table: string;
+ readonly columns: readonly string[];
+ readonly predicate: string | null;
+ readonly predicateColumns: readonly string[];
+ readonly concurrently: boolean;
+ readonly statement: string;
+};
+
+type MutationInfo = {
+ readonly table: string;
+ readonly statementSql: string;
+ readonly keywordIndex: number;
+};
+
+const RULE_METADATA: Record<MigrationSafetyRule, RuleMetadata> = {
+ "loop-mutation-large-table": {
+ severity: "error",
+ message: "DO $$ loop mutates a known-large table without a same-migration support index",
+ },
+ "batched-mutation-large-table-missing-index": {
+ severity: "error",
+ message: "Batched LIMIT mutation over a known-large table lacks a same-migration support index",
+ },
+ "full-table-mutation-large-table": {
+ severity: "error",
+ message: "Known-large table mutation does not have a selective WHERE clause",
+ },
+ "large-create-index-not-concurrently": {
+ severity: "warning",
+ message: "CREATE INDEX on a known-large table is missing CONCURRENTLY",
+ },
+};
+
+const RESERVED_ALIAS_WORDS = new Set([
+ "add",
+ "alter",
+ "as",
+ "delete",
+ "from",
+ "on",
+ "returning",
+ "set",
+ "using",
+ "where",
+ "with",
+]);
+
+function normalizeIdentifier(value: string): string {
+ return value
+ .trim()
+ .replace(/^"public"\s*\.\s*/i, "")
+ .replace(/^public\s*\.\s*/i, "")
+ .replace(/^"/, "")
+ .replace(/"$/, "")
+ .replaceAll('""', '"');
+}
+
+function normalizeSql(value: string): string {
+ return value.replace(/\s+/g, " ").trim();
+}
+
+function statementExcerpt(statement: string): string {
+ const normalized = normalizeSql(statement);
+ if (normalized.length <= 700) return normalized;
+ return `${normalized.slice(0, 700)}...`;
+}
+
+function findingId(
+ rule: MigrationSafetyRule,
+ migration: string,
+ table: string,
+ statement: string,
+): string {
+ return createHash("sha256")
+ .update(`${rule}\0${migration}\0${table}\0${normalizeSql(statement)}`)
+ .digest("hex")
+ .slice(0, 16);
+}
+
+function splitSqlStatements(sql: string): string[] {
+ const breakpointParts = sql
+ .split(/-->\s*statement-breakpoint/g)
+ .map((part) => part.trim())
+ .filter((part) => part.length > 0);
+ if (breakpointParts.length > 1) return breakpointParts;
+
+ const statements: string[] = [];
+ let start = 0;
+ let singleQuoted = false;
+ let dollarQuoteTag: string | null = null;
+
+ for (let index = 0; index < sql.length; index += 1) {
+ if (dollarQuoteTag) {
+ if (sql.startsWith(dollarQuoteTag, index)) {
+ index += dollarQuoteTag.length - 1;
+ dollarQuoteTag = null;
+ }
+ continue;
+ }
+
+ const char = sql[index];
+ if (singleQuoted) {
+ if (char === "'" && sql[index + 1] === "'") {
+ index += 1;
+ } else if (char === "'") {
+ singleQuoted = false;
+ }
+ continue;
+ }
+
+ if (char === "'") {
+ singleQuoted = true;
+ continue;
+ }
+
+ if (char === "$") {
+ const tag = dollarQuoteTagAt(sql, index);
+ if (tag) {
+ dollarQuoteTag = tag;
+ index += dollarQuoteTag.length - 1;
+ }
+ continue;
+ }
+
+ if (char === ";") {
+ const statement = sql.slice(start, index + 1).trim();
+ if (statement.length > 0) statements.push(statement);
+ start = index + 1;
+ }
+ }
+
+ const tail = sql.slice(start).trim();
+ if (tail.length > 0) statements.push(tail);
+ return statements;
+}
+
+function ignoreRules(statement: string): Set<string> {
+ const rules = new Set<string>();
+ const pattern = /--\s*paperclip:migration-safety-ignore\s+([a-z0-9-]+|all)\s*:\s*(\S.*)$/gim;
+ for (const match of statement.matchAll(pattern)) {
+ const rule = match[1];
+ const reason = match[2]?.trim();
+ if (rule && reason) rules.add(rule);
+ }
+ return rules;
+}
+
+function isIgnored(statement: string, rule: MigrationSafetyRule): boolean {
+ const ignored = ignoreRules(statement);
+ return ignored.has(rule) || ignored.has("all");
+}
+
+function skipSingleQuotedLiteral(statement: string, startIndex: number): number {
+ let index = startIndex + 1;
+ while (index < statement.length) {
+ if (statement[index] === "'" && statement[index + 1] === "'") {
+ index += 2;
+ continue;
+ }
+ if (statement[index] === "'") return index + 1;
+ index += 1;
+ }
+ return index;
+}
+
+function skipDoubleQuotedIdentifier(statement: string, startIndex: number): number {
+ let index = startIndex + 1;
+ while (index < statement.length) {
+ if (statement[index] === '"' && statement[index + 1] === '"') {
+ index += 2;
+ continue;
+ }
+ if (statement[index] === '"') return index + 1;
+ index += 1;
+ }
+ return index;
+}
+
+function skipLineComment(statement: string, startIndex: number): number {
+ const newlineIndex = statement.indexOf("\n", startIndex + 2);
+ return newlineIndex === -1 ? statement.length : newlineIndex;
+}
+
+function skipBlockComment(statement: string, startIndex: number): number {
+ let depth = 1;
+ let index = startIndex + 2;
+ while (index < statement.length && depth > 0) {
+ if (statement.startsWith("/*", index)) {
+ depth += 1;
+ index += 2;
+ continue;
+ }
+ if (statement.startsWith("*/", index)) {
+ depth -= 1;
+ index += 2;
+ continue;
+ }
+ index += 1;
+ }
+ return index;
+}
+
+function skipDollarQuotedString(statement: string, startIndex: number): number {
+ const tag = dollarQuoteTagAt(statement, startIndex);
+ if (!tag) return startIndex;
+ const closeIndex = statement.indexOf(tag, startIndex + tag.length);
+ return closeIndex === -1 ? statement.length : closeIndex + tag.length;
+}
+
+function stripSqlComments(statement: string): string {
+ let stripped = "";
+ let index = 0;
+
+ while (index < statement.length) {
+ const char = statement[index];
+ const next = statement[index + 1];
+
+ if (char === "'") {
+ const literalEnd = skipSingleQuotedLiteral(statement, index);
+ stripped += statement.slice(index, literalEnd);
+ index = literalEnd;
+ continue;
+ }
+
+ if (char === '"') {
+ const identifierEnd = skipDoubleQuotedIdentifier(statement, index);
+ stripped += statement.slice(index, identifierEnd);
+ index = identifierEnd;
+ continue;
+ }
+
+ if (char === "$") {
+ const dollarEnd = skipDollarQuotedString(statement, index);
+ if (dollarEnd !== index) {
+ stripped += statement.slice(index, dollarEnd);
+ index = dollarEnd;
+ continue;
+ }
+ }
+
+ if (char === "-" && next === "-") {
+ stripped += " ";
+ index = skipLineComment(statement, index);
+ continue;
+ }
+
+ if (char === "/" && next === "*") {
+ stripped += " ";
+ const commentEnd = skipBlockComment(statement, index);
+ for (let commentIndex = index; commentIndex < commentEnd; commentIndex += 1) {
+ if (statement[commentIndex] === "\n") stripped += "\n";
+ }
+ index = commentEnd;
+ continue;
+ }
+
+ stripped += char;
+ index += 1;
+ }
+
+ return stripped;
+}
+
+function skipSqlTrivia(statement: string, index: number): number {
+ const char = statement[index];
+ const next = statement[index + 1];
+ if (char === "'") return skipSingleQuotedLiteral(statement, index);
+ if (char === '"') return skipDoubleQuotedIdentifier(statement, index);
+ if (char === "$") {
+ const end = skipDollarQuotedString(statement, index);
+ if (end !== index) return end;
+ }
+ if (char === "-" && next === "-") return skipLineComment(statement, index);
+ if (char === "/" && next === "*") return skipBlockComment(statement, index);
+ return index;
+}
+
+function identifierList(value: string): string[] {
+ return [...value.matchAll(/"([^"]+)"|(?:^|[\s,(])([A-Za-z_][A-Za-z0-9_]*)/g)]
+ .map((match) => normalizeIdentifier(match[1] ?? match[2] ?? ""))
+ .filter((identifier) => identifier.length > 0)
+ .filter((identifier) => !RESERVED_ALIAS_WORDS.has(identifier.toLowerCase()));
+}
+
+function plainIndexColumns(columnSpec: string): string[] {
+ // Only include simple column references. Skip expression columns such as
+ // (id * 2) or lower(col) — PostgreSQL cannot use those to satisfy ORDER BY
+ // on the plain column, so they must not suppress a missing-index finding.
+ return splitSqlList(columnSpec).flatMap((part) => {
+ const trimmed = part.trim();
+ if (/\(/.test(trimmed)) return [];
+ return identifierList(trimmed);
+ });
+}
+
+function splitSqlList(value: string): string[] {
+ const parts: string[] = [];
+ let start = 0;
+ let depth = 0;
+ let singleQuoted = false;
+ let doubleQuoted = false;
+
+ for (let index = 0; index < value.length; index += 1) {
+ const char = value[index];
+
+ if (singleQuoted) {
+ if (char === "'" && value[index + 1] === "'") {
+ index += 1;
+ } else if (char === "'") {
+ singleQuoted = false;
+ }
+ continue;
+ }
+
+ if (doubleQuoted) {
+ if (char === '"' && value[index + 1] === '"') {
+ index += 1;
+ } else if (char === '"') {
+ doubleQuoted = false;
+ }
+ continue;
+ }
+
+ if (char === "'") {
+ singleQuoted = true;
+ continue;
+ }
+
+ if (char === '"') {
+ doubleQuoted = true;
+ continue;
+ }
+
+ if (char === "(") {
+ depth += 1;
+ continue;
+ }
+
+ if (char === ")") {
+ depth = Math.max(0, depth - 1);
+ continue;
+ }
+
+ if (char === "," && depth === 0) {
+ const part = value.slice(start, index).trim();
+ if (part) parts.push(part);
+ start = index + 1;
+ }
+ }
+
+ const tail = value.slice(start).trim();
+ if (tail) parts.push(tail);
+ return parts;
+}
+
+function orderByExpressionColumn(value: string): string | null {
+ const withoutSortModifiers = value
+ .replace(/\bCOLLATE\s+(?:"[^"]+"|[A-Za-z_][A-Za-z0-9_]*)/gi, " ")
+ .replace(/\bNULLS\s+(?:FIRST|LAST)\b/gi, " ")
+ .replace(/\b(?:ASC|DESC)\b/gi, " ");
+ const identifiers = [
+ ...withoutSortModifiers.matchAll(/"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*)/g),
+ ]
+ .map((match) => normalizeIdentifier(match[1] ?? match[2] ?? ""))
+ .filter((identifier) => identifier.length > 0)
+ .filter((identifier) => !RESERVED_ALIAS_WORDS.has(identifier.toLowerCase()));
+ return identifiers[identifiers.length - 1] ?? null;
+}
+
+function predicateColumns(statement: string): string[] {
+ const columns = new Set<string>();
+ const sql = stripSqlComments(statement);
+ const predicatePattern = /\b(?:WHERE|ORDER\s+BY|ON)\b([\s\S]*?)(?=\b(?:LIMIT|RETURNING|GROUP\s+BY|ORDER\s+BY|SET|FROM)\b|$)/gi;
+ for (const match of sql.matchAll(predicatePattern)) {
+ for (const identifier of identifierList(match[1] ?? "")) {
+ columns.add(identifier);
+ }
+ }
+ return [...columns];
+}
+
+type KeywordOccurrence = {
+ readonly index: number;
+ readonly depth: number;
+ readonly length: number;
+};
+
+function keywordOccurrenceAt(
+ sql: string,
+ index: number,
+ pattern: RegExp,
+): RegExpMatchArray | null {
+ const previous = sql[index - 1];
+ if (previous && /[A-Za-z0-9_]/.test(previous)) return null;
+ return sql.slice(index).match(pattern);
+}
+
+function keywordOccurrences(sql: string, pattern: RegExp): KeywordOccurrence[] {
+ const occurrences: KeywordOccurrence[] = [];
+ let depth = 0;
+ let index = 0;
+
+ while (index < sql.length) {
+ const char = sql[index];
+
+ if (char === "'") {
+ index = skipSingleQuotedLiteral(sql, index);
+ continue;
+ }
+
+ if (char === '"') {
+ index = skipDoubleQuotedIdentifier(sql, index);
+ continue;
+ }
+
+ if (char === "(") {
+ depth += 1;
+ index += 1;
+ continue;
+ }
+
+ if (char === ")") {
+ depth = Math.max(0, depth - 1);
+ index += 1;
+ continue;
+ }
+
+ const match = keywordOccurrenceAt(sql, index, pattern);
+ if (match) {
+ occurrences.push({ index, depth, length: match[0].length });
+ index += match[0].length;
+ continue;
+ }
+
+ index += 1;
+ }
+
+ return occurrences;
+}
+
+function batchWhereClausesBeforeOrderBy(statement: string): string[] {
+ const sql = stripSqlComments(statement);
+ const whereOccurrences = keywordOccurrences(sql, /^\bWHERE\b/i);
+ const orderByOccurrences = keywordOccurrences(sql, /^\bORDER\s+BY\b/i);
+ const clauses: string[] = [];
+
+ for (const orderBy of orderByOccurrences) {
+ const where = whereOccurrences
+ .filter((candidate) => candidate.depth === orderBy.depth && candidate.index < orderBy.index)
+ .at(-1);
+ if (!where) continue;
+
+ const clause = sql.slice(where.index + where.length, orderBy.index).trim();
+ if (clause) clauses.push(clause);
+ }
+
+ return clauses;
+}
+
+function hasBalancedOuterParens(value: string): boolean {
+ if (!value.startsWith("(") || !value.endsWith(")")) return false;
+ let depth = 0;
+
+ for (let index = 0; index < value.length; index += 1) {
+ const char = value[index];
+ if (char === "'") {
+ index = skipSingleQuotedLiteral(value, index) - 1;
+ continue;
+ }
+ if (char === '"') {
+ index = skipDoubleQuotedIdentifier(value, index) - 1;
+ continue;
+ }
+ if (char === "(") depth += 1;
+ if (char === ")") depth -= 1;
+ if (depth === 0 && index < value.length - 1) return false;
+ }
+
+ return depth === 0;
+}
+
+function stripOuterParens(value: string): string {
+ let stripped = normalizeSql(value).replace(/;$/, "").trim();
+ while (hasBalancedOuterParens(stripped)) {
+ stripped = normalizeSql(stripped.slice(1, -1));
+ }
+ return stripped;
+}
+
+function splitConjunctivePredicate(value: string): string[] {
+ const terms: string[] = [];
+ const sql = stripOuterParens(value);
+ let depth = 0;
+ let start = 0;
+ let index = 0;
+
+ while (index < sql.length) {
+ const char = sql[index];
+
+ if (char === "'") {
+ index = skipSingleQuotedLiteral(sql, index);
+ continue;
+ }
+
+ if (char === '"') {
+ index = skipDoubleQuotedIdentifier(sql, index);
+ continue;
+ }
+
+ if (char === "(") {
+ depth += 1;
+ index += 1;
+ continue;
+ }
+
+ if (char === ")") {
+ depth = Math.max(0, depth - 1);
+ index += 1;
+ continue;
+ }
+
+ const match = depth === 0 ? keywordOccurrenceAt(sql, index, /^\bAND\b/i) : null;
+ if (match) {
+ const term = stripOuterParens(sql.slice(start, index));
+ if (term) terms.push(term);
+ start = index + match[0].length;
+ index = start;
+ continue;
+ }
+
+ index += 1;
+ }
+
+ const tail = stripOuterParens(sql.slice(start));
+ if (tail) terms.push(tail);
+ return terms;
+}
+
+function lowercaseSqlOutsideSingleQuotedLiterals(value: string): string {
+ let lowered = "";
+ let index = 0;
+
+ while (index < value.length) {
+ if (value[index] === "'") {
+ const end = skipSingleQuotedLiteral(value, index);
+ lowered += value.slice(index, end);
+ index = end;
+ continue;
+ }
+
+ lowered += value[index]?.toLowerCase() ?? "";
+ index += 1;
+ }
+
+ return lowered;
+}
+
+function normalizePredicateTerm(term: string): string {
+ const normalized = stripOuterParens(term)
+ .replace(
+ /(?:"[^"]+"|[A-Za-z_][A-Za-z0-9_]*)\s*\.\s*("[^"]+"|[A-Za-z_][A-Za-z0-9_]*)/g,
+ "$1",
+ )
+ .replace(/"([^"]+)"/g, "$1")
+ .replace(/\s+/g, " ")
+ .trim();
+ return lowercaseSqlOutsideSingleQuotedLiterals(normalized);
+}
+
+function predicateTerms(value: string): Set<string> {
+ return new Set(splitConjunctivePredicate(value).map(normalizePredicateTerm));
+}
+
+function orderByColumns(statement: string): string[] {
+ const columns: string[] = [];
+ const sql = stripSqlComments(statement);
+ const pattern = /\bORDER\s+BY\b([\s\S]*?)(?=\b(?:LIMIT|RETURNING|GROUP\s+BY|WHERE|SET|FROM|END|LOOP)\b|$)/gi;
+ for (const match of sql.matchAll(pattern)) {
+ for (const expression of splitSqlList(match[1] ?? "")) {
+ const column = orderByExpressionColumn(expression);
+ if (column && !columns.includes(column)) {
+ columns.push(column);
+ }
+ }
+ }
+ return columns;
+}
+
+function parseCreateIndexes(statement: string): CreateIndexInfo[] {
+ const indexes: CreateIndexInfo[] = [];
+ const sql = stripSqlComments(statement);
+ const pattern =
+ /\bCREATE\s+(?:UNIQUE\s+)?INDEX\s+(CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?(?:"[^"]+"|[A-Za-z_][A-Za-z0-9_]*)\s+ON\s+(?:(?:"public"|public)\s*\.\s*)?(?:"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*))\s*(?:USING\s+[A-Za-z_][A-Za-z0-9_]*\s*)?\(([\s\S]*?)\)(?:\s+WHERE\s+([\s\S]*))?/gi;
+
+ for (const match of sql.matchAll(pattern)) {
+ const table = normalizeIdentifier(match[2] ?? match[3] ?? "");
+ if (!table) continue;
+ const predicate = match[5]?.trim().replace(/;$/, "").trim() ?? "";
+ indexes.push({
+ table,
+ columns: plainIndexColumns(match[4] ?? ""),
+ predicate: predicate.length > 0 ? predicate : null,
+ predicateColumns: predicateColumns(predicate),
+ concurrently: Boolean(match[1]),
+ statement,
+ });
+ }
+
+ return indexes;
+}
+
+function parseMutations(statement: string): MutationInfo[] {
+ const mutations: MutationInfo[] = [];
+ const sql = stripSqlComments(statement);
+ const updatePattern =
+ /\bUPDATE\s+(?:ONLY\s+)?(?:(?:"public"|public)\s*\.\s*)?(?:"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*))(?:\s+(?:AS\s+)?(?:"?([A-Za-z_][A-Za-z0-9_]*)"?))?/gi;
+ const deletePattern =
+ /\bDELETE\s+FROM\s+(?:ONLY\s+)?(?:(?:"public"|public)\s*\.\s*)?(?:"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*))(?:\s+(?:AS\s+)?(?:"?([A-Za-z_][A-Za-z0-9_]*)"?))?/gi;
+
+ for (const match of sql.matchAll(updatePattern)) {
+ const table = normalizeIdentifier(match[1] ?? match[2] ?? "");
+ if (table) {
+ mutations.push({ table, statementSql: sql, keywordIndex: match.index ?? 0 });
+ }
+ }
+
+ for (const match of sql.matchAll(deletePattern)) {
+ const table = normalizeIdentifier(match[1] ?? match[2] ?? "");
+ if (table) {
+ mutations.push({ table, statementSql: sql, keywordIndex: match.index ?? 0 });
+ }
+ }
+
+ return mutations;
+}
+
+function hasDoLoop(statement: string): boolean {
+ return /\bDO\s+\$[A-Za-z_]*\$[\s\S]*\bLOOP\b/i.test(statement);
+}
+
+function hasBatchedLimitMutation(statement: string): boolean {
+ const hasLimit = /\bLIMIT\s+(?:\d+|[A-Za-z_][A-Za-z0-9_]*|\$[0-9]+)\b/i.test(statement);
+ const hasFetchLimit =
+ /\bFETCH\s+(?:FIRST|NEXT)(?:\s+(?:\d+|[A-Za-z_][A-Za-z0-9_]*|\$[0-9]+))?\s+ROWS?\s+(?:ONLY|WITH\s+TIES)\b/i.test(statement);
+ const hasDml = /\b(?:UPDATE|DELETE)\b/i.test(statement);
+ return (hasLimit || hasFetchLimit) && hasDml;
+}
+
+function dollarQuoteTagAt(statement: string, startIndex: number): string | null {
+ if (statement[startIndex] !== "$") return null;
+ const match = statement.slice(startIndex).match(/^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/);
+ return match?.[0] ?? null;
+}
+
+function topLevelWhereClause(statement: string, startIndex: number): string | null {
+ // Walk character-by-character, tracking paren depth.
+ // Only consider WHERE keywords at depth 0 after the target mutation.
+ let depth = 0;
+ let i = startIndex;
+ while (i < statement.length) {
+ const nextIndex = skipSqlTrivia(statement, i);
+ if (nextIndex !== i) {
+ i = nextIndex;
+ continue;
+ }
+
+ const ch = statement[i];
+ if (ch === "(") {
+ depth++;
+ i++;
+ continue;
+ }
+ if (ch === ")") {
+ depth = Math.max(0, depth - 1);
+ i++;
+ continue;
+ }
+ if (depth === 0) {
+ const rem = statement.slice(i);
+ const m = rem.match(/^\bWHERE\b/i);
+ if (m) return rem.slice(m[0].length);
+ }
+ i++;
+ }
+ return null;
+}
+
+function hasSelectiveWhere(mutation: MutationInfo): boolean {
+ const afterWhere = topLevelWhereClause(mutation.statementSql, mutation.keywordIndex);
+ if (!afterWhere) return false;
+
+ const whereClause = normalizeSql(afterWhere).replace(/;$/, "");
+ if (/^(?:true|1\s*=\s*1)$/i.test(whereClause)) return false;
+ if (!/(?:=|<>|!=|<|>|\bIN\s*\(|\bEXISTS\s*\(|\bLIKE\b|\bIS\s+(?:NOT\s+)?NULL\b)/i.test(whereClause))
+ return false;
+
+ // A WHERE that only constrains joined tables is not a filter on the target table.
+ // Collect every table-qualified column reference (both "tbl"."col" and alias."col").
+ const qualRefs = [
+ ...whereClause.matchAll(/"([^"]+)"\s*\.\s*(?:"[^"]+"|\w+)/g),
+ ...whereClause.matchAll(/\b([A-Za-z_][A-Za-z0-9_]*)\s*\."[^"]+"/g),
+ ...whereClause.matchAll(/\b([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)\b/g),
+ ].map((m) => normalizeIdentifier(m[1] ?? "")).filter(Boolean);
+
+ if (qualRefs.length > 0) {
+ // Resolve unquoted aliases from UPDATE/FROM/JOIN clauses to their real table names.
+ const aliasMap = new Map<string, string>();
+ const aliasPattern =
+ /\b(?:UPDATE|FROM|JOIN)\s+(?:"public"\s*\.\s*)?(?:"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*))\s+(?:AS\s+)?(?:"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*))\b/gi;
+ for (const m of stripSqlComments(mutation.statementSql).matchAll(aliasPattern)) {
+ const tbl = normalizeIdentifier(m[1] ?? m[2] ?? "");
+ const alias = normalizeIdentifier(m[3] ?? m[4] ?? "");
+ if (tbl && alias && !RESERVED_ALIAS_WORDS.has(alias.toLowerCase())) aliasMap.set(alias, tbl);
+ }
+ const refTables = qualRefs.map((r) => aliasMap.get(r) ?? r);
+ if (!refTables.some((t) => t === mutation.table)) {
+ // All refs resolve to other tables. Confirm no bare unqualified identifiers remain.
+ const noQual = whereClause
+ .replace(/"[^"]+"\s*\.\s*(?:"[^"]+"|\w+)/g, " ")
+ .replace(/\b[A-Za-z_][A-Za-z0-9_]*\s*\."[^"]+"/g, " ")
+ .replace(/\b[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*/g, " ")
+ .replace(/'(?:[^']|'')*'/g, " ");
+ const SQL_KW =
+ /\b(?:AND|OR|NOT|IN|EXISTS|LIKE|IS|NULL|TRUE|FALSE|BETWEEN|CASE|WHEN|THEN|END|CAST|AS|ANY|ALL|SOME)\b/gi;
+ if (!/\b[A-Za-z_][A-Za-z0-9_]*\b/.test(noQual.replace(SQL_KW, " "))) return false;
+ }
+ }
+
+ return true;
+}
+
+function hasLeadingOrderPrefix(
+ supportIndex: CreateIndexInfo,
+ orderColumns: readonly string[],
+ statement: string,
+): boolean {
+ const indexedColumns = supportIndex.columns;
+ const prefixLength = Math.min(indexedColumns.length, orderColumns.length);
+ if (prefixLength === 0) return false;
+ for (let index = 0; index < prefixLength; index += 1) {
+ if (indexedColumns[index] !== orderColumns[index]) return false;
+ }
+ if (!supportIndex.predicate) return true;
+
+ const indexPredicateTerms = predicateTerms(supportIndex.predicate);
+ if (indexPredicateTerms.size === 0) return false;
+
+ return batchWhereClausesBeforeOrderBy(statement).some((whereClause) => {
+ const batchTerms = predicateTerms(whereClause);
+ return [...indexPredicateTerms].every((term) => batchTerms.has(term));
+ });
+}
+
+function hasOrderPrefixCompatibleIndex(
+ supportIndex: CreateIndexInfo,
+ orderColumns: readonly string[],
+ statement: string,
+): boolean {
+ return hasLeadingOrderPrefix(supportIndex, orderColumns, statement);
+}
+
+function hasMatchingSupportIndex(
+ indexes: readonly CreateIndexInfo[],
+ mutation: MutationInfo,
+ statement: string,
+): boolean {
+ const matchingIndexes = indexes.filter((index) => index.table === mutation.table);
+ if (matchingIndexes.length === 0) return false;
+
+ // ORDER BY columns are the batch-progression key. If the statement orders its
+ // batch, the support index must cover the ordered key prefix using index key
+ // columns; predicate-only overlap cannot stand in for an unindexed cursor.
+ const orderCols = orderByColumns(statement);
+ const allPredicateCols = new Set(predicateColumns(statement));
+ if (allPredicateCols.size === 0) return true;
+
+ if (orderCols.length > 0) {
+ return matchingIndexes.some((index) =>
+ hasOrderPrefixCompatibleIndex(index, orderCols, statement),
+ );
+ }
+
+ return matchingIndexes.some((index) => {
+ const indexedColumns = new Set([...index.columns, ...index.predicateColumns]);
+ return [...allPredicateCols].some((col) => indexedColumns.has(col));
+ });
+}
+
+function estimateSuffix(table: string, estimates: ReadonlyMap<string, TableSizeEstimate>): string {
+ const estimate = estimates.get(table) ?? getTableSizeEstimate(table);
+ if (!estimate) return "bucket=large";
+ return `bucket=${estimate.bucket}, localRows=${estimate.localRows}, estimatedRows=${estimate.estimatedRows}`;
+}
+
+function makeFinding(
+ rule: MigrationSafetyRule,
+ migration: string,
+ table: string,
+ statement: string,
+ estimates: ReadonlyMap<string, TableSizeEstimate>,
+): MigrationSafetyFinding {
+ const metadata = RULE_METADATA[rule];
+ return {
+ id: findingId(rule, migration, table, statement),
+ rule,
+ severity: metadata.severity,
+ migration,
+ table,
+ statement: statementExcerpt(statement),
+ message: `${metadata.message} (${estimateSuffix(table, estimates)})`,
+ };
+}
+
+function addFindingOnce(
+ findings: MigrationSafetyFinding[],
+ seen: Set<string>,
+ finding: MigrationSafetyFinding,
+): void {
+ const key = `${finding.rule}:${finding.migration}:${finding.table}:${finding.id}`;
+ if (seen.has(key)) return;
+ seen.add(key);
+ findings.push(finding);
+}
+
+function estimatesByTable(
+ estimates: readonly TableSizeEstimate[] | undefined,
+): ReadonlyMap<string, TableSizeEstimate> {
+ if (!estimates) return new Map();
+ return new Map(estimates.map((estimate) => [estimate.table, estimate]));
+}
+
+function tableIsLarge(table: string, estimates: ReadonlyMap<string, TableSizeEstimate>): boolean {
+ if (estimates.size > 0) return estimates.get(table)?.bucket === "large";
+ return isKnownLargeTable(table);
+}
+
+export function analyzeMigrationSafety(
+ migrations: readonly MigrationSafetyInput[],
+ options: {
+ readonly baselineIds?: readonly string[];
+ readonly estimates?: readonly TableSizeEstimate[];
+ } = {},
+): MigrationSafetyResult {
+ const findings: MigrationSafetyFinding[] = [];
+ const seen = new Set<string>();
+ const estimates = estimatesByTable(options.estimates);
+
+ for (const migration of migrations) {
+ const statements = splitSqlStatements(migration.sql);
+ const migrationIndexes = statements.flatMap(parseCreateIndexes);
+
+ for (const statement of statements) {
+ for (const index of parseCreateIndexes(statement)) {
+ if (
+ tableIsLarge(index.table, estimates) &&
+ !index.concurrently &&
+ !isIgnored(statement, "large-create-index-not-concurrently")
+ ) {
+ addFindingOnce(
+ findings,
+ seen,
+ makeFinding(
+ "large-create-index-not-concurrently",
+ migration.fileName,
+ index.table,
+ statement,
+ estimates,
+ ),
+ );
+ }
+ }
+
+ const mutations = parseMutations(statement)
+ .filter((mutation) => tableIsLarge(mutation.table, estimates));
+ for (const mutation of mutations) {
+ const hasSupportIndex = hasMatchingSupportIndex(migrationIndexes, mutation, statement);
+
+ if (
+ hasDoLoop(statement) &&
+ !hasSupportIndex &&
+ !isIgnored(statement, "loop-mutation-large-table")
+ ) {
+ addFindingOnce(
+ findings,
+ seen,
+ makeFinding(
+ "loop-mutation-large-table",
+ migration.fileName,
+ mutation.table,
+ statement,
+ estimates,
+ ),
+ );
+ }
+
+ if (
+ hasBatchedLimitMutation(statement) &&
+ !hasSupportIndex &&
+ !isIgnored(statement, "batched-mutation-large-table-missing-index")
+ ) {
+ addFindingOnce(
+ findings,
+ seen,
+ makeFinding(
+ "batched-mutation-large-table-missing-index",
+ migration.fileName,
+ mutation.table,
+ statement,
+ estimates,
+ ),
+ );
+ }
+
+ if (
+ !hasSelectiveWhere(mutation) &&
+ !isIgnored(statement, "full-table-mutation-large-table")
+ ) {
+ addFindingOnce(
+ findings,
+ seen,
+ makeFinding(
+ "full-table-mutation-large-table",
+ migration.fileName,
+ mutation.table,
+ statement,
+ estimates,
+ ),
+ );
+ }
+ }
+ }
+ }
+
+ const baselineIds = new Set(options.baselineIds ?? MIGRATION_SAFETY_BASELINE.map((entry) => entry.id));
+ const foundIds = new Set(findings.map((finding) => finding.id));
+ const newFindings = findings.filter((finding) => !baselineIds.has(finding.id));
+ const baselineFindings = findings.filter((finding) => baselineIds.has(finding.id));
+ const staleBaselineIds = [...baselineIds].filter((id) => !foundIds.has(id));
+
+ return {
+ findings,
+ newFindings,
+ baselineFindings,
+ staleBaselineIds,
+ };
+}
+
+async function readMigrations(): Promise<MigrationSafetyInput[]> {
+ const files = (await readdir(migrationsDir))
+ .filter((entry) => entry.endsWith(".sql"))
+ .sort();
+
+ return Promise.all(
+ files.map(async (fileName) => ({
+ fileName,
+ sql: await readFile(new URL(`./migrations/${fileName}`, import.meta.url), "utf8"),
+ })),
+ );
+}
+
+function formatFinding(finding: MigrationSafetyFinding): string {
+ return [
+ `[${finding.rule}] ${finding.migration} table=${finding.table} severity=${finding.severity} id=${finding.id}`,
+ finding.message,
+ `Statement: ${finding.statement}`,
+ ].join("\n");
+}
+
+function formatNewFindings(findings: readonly MigrationSafetyFinding[]): string {
+ const rendered = findings.map(formatFinding).join("\n\n");
+ return [
+ `Migration safety check found ${findings.length} new finding(s).`,
+ "Add a same-migration support index, use CONCURRENTLY where applicable, or add",
+ "`-- paperclip:migration-safety-ignore <rule>: <reason>` next to the statement.",
+ "",
+ rendered,
+ ].join("\n");
+}
+
+async function main() {
+ const result = analyzeMigrationSafety(await readMigrations());
+
+ if (result.newFindings.length > 0) {
+ throw new Error(formatNewFindings(result.newFindings));
+ }
+
+ const staleSuffix = result.staleBaselineIds.length > 0
+ ? ` (${result.staleBaselineIds.length} stale baseline id(s) ignored)`
+ : "";
+ console.log(
+ `Migration safety check passed: ${result.baselineFindings.length} historical finding(s) covered by baseline${staleSuffix}.`,
+ );
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ try {
+ await main();
+ } catch (error) {
+ const detail = error instanceof Error ? error.message : String(error);
+ console.error(`${basename(process.argv[1])}: ${detail}`);
+ process.exitCode = 1;
+ }
+}
diff --git a/packages/db/src/migration-safety-baseline.ts b/packages/db/src/migration-safety-baseline.ts
new file mode 100644
index 0000000000..4c424b5022
--- /dev/null
+++ b/packages/db/src/migration-safety-baseline.ts
@@ -0,0 +1,157 @@
+export type MigrationSafetyBaselineEntry = {
+ readonly id: string;
+ readonly rule: string;
+ readonly migration: string;
+ readonly table: string;
+ readonly reason: string;
+};
+
+export const MIGRATION_SAFETY_BASELINE = [
+ {
+ id: "2cfa16c89e561306",
+ rule: "large-create-index-not-concurrently",
+ migration: "0000_mature_masked_marvel.sql",
+ table: "activity_log",
+ reason: "Initial schema history predates the migration-safety guard.",
+ },
+ {
+ id: "2e21c87a27d0ecf3",
+ rule: "large-create-index-not-concurrently",
+ migration: "0000_mature_masked_marvel.sql",
+ table: "issue_comments",
+ reason: "Initial schema history predates the migration-safety guard.",
+ },
+ {
+ id: "3fa7b338f437c89d",
+ rule: "large-create-index-not-concurrently",
+ migration: "0000_mature_masked_marvel.sql",
+ table: "issue_comments",
+ reason: "Initial schema history predates the migration-safety guard.",
+ },
+ {
+ id: "26bf13d0e36e3bd0",
+ rule: "large-create-index-not-concurrently",
+ migration: "0001_fast_northstar.sql",
+ table: "agent_wakeup_requests",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "da73c844de91f262",
+ rule: "large-create-index-not-concurrently",
+ migration: "0001_fast_northstar.sql",
+ table: "agent_wakeup_requests",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "b86e70ea500d5d9e",
+ rule: "large-create-index-not-concurrently",
+ migration: "0001_fast_northstar.sql",
+ table: "agent_wakeup_requests",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "d12aeab5a11d37fe",
+ rule: "large-create-index-not-concurrently",
+ migration: "0001_fast_northstar.sql",
+ table: "heartbeat_run_events",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "80d2cc53747b47bc",
+ rule: "large-create-index-not-concurrently",
+ migration: "0001_fast_northstar.sql",
+ table: "heartbeat_run_events",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "8985fd1ec26c0449",
+ rule: "large-create-index-not-concurrently",
+ migration: "0001_fast_northstar.sql",
+ table: "heartbeat_run_events",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "06065c3f2e8bca76",
+ rule: "large-create-index-not-concurrently",
+ migration: "0003_shallow_quentin_quire.sql",
+ table: "activity_log",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "d0cb536e5b329013",
+ rule: "large-create-index-not-concurrently",
+ migration: "0003_shallow_quentin_quire.sql",
+ table: "activity_log",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "b84802ae05be9943",
+ rule: "large-create-index-not-concurrently",
+ migration: "0024_far_beast.sql",
+ table: "issue_comments",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "3eaba6ddfa29a678",
+ rule: "large-create-index-not-concurrently",
+ migration: "0024_far_beast.sql",
+ table: "issue_comments",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "2874b94c3f294f53",
+ rule: "large-create-index-not-concurrently",
+ migration: "0051_young_korg.sql",
+ table: "issue_comments",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "f0a44a3401b28d62",
+ rule: "large-create-index-not-concurrently",
+ migration: "0060_orange_annihilus.sql",
+ table: "issue_reference_mentions",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "f1fbb786a033df8d",
+ rule: "large-create-index-not-concurrently",
+ migration: "0060_orange_annihilus.sql",
+ table: "issue_reference_mentions",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "f74aa7dfb0152788",
+ rule: "large-create-index-not-concurrently",
+ migration: "0060_orange_annihilus.sql",
+ table: "issue_reference_mentions",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "3c1237481d6ee00d",
+ rule: "large-create-index-not-concurrently",
+ migration: "0060_orange_annihilus.sql",
+ table: "issue_reference_mentions",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "21cf0a7bb66a4058",
+ rule: "large-create-index-not-concurrently",
+ migration: "0060_orange_annihilus.sql",
+ table: "issue_reference_mentions",
+ reason: "Historical migration predates the migration-safety guard.",
+ },
+ {
+ id: "567b97176f9f06c3",
+ rule: "large-create-index-not-concurrently",
+ migration: "0132_issue_comment_derived_attribution_fast.sql",
+ table: "issue_comments",
+ reason: "Existing issue-attribution backfill branch uses a temporary support index before this guard landed.",
+ },
+ {
+ id: "38d8055cc228913d",
+ rule: "full-table-mutation-large-table",
+ migration: "0132_issue_comment_derived_attribution_fast.sql",
+ table: "issue_comments",
+ reason: "Batched DO-loop backfill with keyset pagination (LIMIT 5000 per batch); reviewed and approved as part of PAP-1505 fix. Already merged to master before this guard landed.",
+ },
+] as const satisfies readonly MigrationSafetyBaselineEntry[];
diff --git a/packages/db/src/table-size-estimates.ts b/packages/db/src/table-size-estimates.ts
new file mode 100644
index 0000000000..8a6d680af4
--- /dev/null
+++ b/packages/db/src/table-size-estimates.ts
@@ -0,0 +1,178 @@
+export type TableSizeBucket = "large" | "medium" | "small";
+
+export type LocalTableRowCount = {
+ readonly table: string;
+ readonly localRows: number;
+};
+
+export type TableSizeEstimate = LocalTableRowCount & {
+ readonly estimateFactor: number;
+ readonly estimatedRows: number;
+ readonly bucket: TableSizeBucket;
+};
+
+export const TABLE_SIZE_ESTIMATE_SOURCE = {
+ collectedAt: "2026-07-06",
+ database: "default local dev embedded Postgres",
+ method: "SELECT count(*) in a read-only transaction",
+} as const;
+
+export const TABLE_SIZE_ESTIMATE_FACTOR = 250;
+
+export const TABLE_SIZE_BUCKET_THRESHOLDS = {
+ largeRows: 1_000_000,
+ mediumRows: 100_000,
+} as const;
+
+export const LOCAL_TABLE_ROW_COUNTS = [
+ { table: "agent_wakeup_requests", localRows: 52_791 },
+ { table: "activity_log", localRows: 22_930 },
+ { table: "issue_reference_mentions", localRows: 13_218 },
+ { table: "heartbeat_run_events", localRows: 10_833 },
+ { table: "issue_comments", localRows: 5_034 },
+ { table: "document_revisions", localRows: 3_906 },
+ { table: "heartbeat_runs", localRows: 3_620 },
+ { table: "workspace_operations", localRows: 3_600 },
+ { table: "environment_leases", localRows: 3_492 },
+ { table: "cost_events", localRows: 3_330 },
+ { table: "agent_task_sessions", localRows: 1_743 },
+ { table: "documents", localRows: 1_692 },
+ { table: "issue_documents", localRows: 1_678 },
+ { table: "issues", localRows: 1_609 },
+ { table: "secret_access_events", localRows: 933 },
+ { table: "issue_read_states", localRows: 608 },
+ { table: "issue_thread_interactions", localRows: 455 },
+ { table: "issue_relations", localRows: 445 },
+ { table: "execution_workspaces", localRows: 414 },
+ { table: "agent_config_revisions", localRows: 145 },
+ { table: "document_annotation_anchor_snapshots", localRows: 132 },
+ { table: "document_annotation_comments", localRows: 122 },
+ { table: "document_annotation_threads", localRows: 80 },
+ { table: "routine_revisions", localRows: 64 },
+ { table: "issue_tree_hold_members", localRows: 62 },
+ { table: "routine_runs", localRows: 52 },
+ { table: "issue_recovery_actions", localRows: 50 },
+ { table: "assets", localRows: 46 },
+ { table: "issue_attachments", localRows: 44 },
+ { table: "principal_permission_grants", localRows: 25 },
+ { table: "company_memberships", localRows: 19 },
+ { table: "agent_runtime_state", localRows: 18 },
+ { table: "agents", localRows: 18 },
+ { table: "routine_triggers", localRows: 16 },
+ { table: "company_skills", localRows: 15 },
+ { table: "routine_documents", localRows: 14 },
+ { table: "routines", localRows: 14 },
+ { table: "issue_inbox_archives", localRows: 13 },
+ { table: "issue_approvals", localRows: 12 },
+ { table: "company_secret_bindings", localRows: 11 },
+ { table: "issue_tree_holds", localRows: 10 },
+ { table: "approvals", localRows: 9 },
+ { table: "session", localRows: 9 },
+ { table: "issue_work_products", localRows: 7 },
+ { table: "company_skill_versions", localRows: 6 },
+ { table: "feedback_exports", localRows: 6 },
+ { table: "feedback_votes", localRows: 6 },
+ { table: "issue_execution_decisions", localRows: 6 },
+ { table: "company_secret_versions", localRows: 3 },
+ { table: "company_secrets", localRows: 3 },
+ { table: "projects", localRows: 3 },
+ { table: "approval_comments", localRows: 2 },
+ { table: "goals", localRows: 2 },
+ { table: "project_goals", localRows: 2 },
+ { table: "project_workspaces", localRows: 2 },
+ { table: "account", localRows: 1 },
+ { table: "companies", localRows: 1 },
+ { table: "environments", localRows: 1 },
+ { table: "instance_settings", localRows: 1 },
+ { table: "instance_user_roles", localRows: 1 },
+ { table: "user", localRows: 1 },
+ { table: "agent_api_keys", localRows: 0 },
+ { table: "agent_memberships", localRows: 0 },
+ { table: "board_api_keys", localRows: 0 },
+ { table: "budget_incidents", localRows: 0 },
+ { table: "budget_policies", localRows: 0 },
+ { table: "cli_auth_challenges", localRows: 0 },
+ { table: "cloud_upstream_connections", localRows: 0 },
+ { table: "cloud_upstream_runs", localRows: 0 },
+ { table: "company_logos", localRows: 0 },
+ { table: "company_secret_provider_configs", localRows: 0 },
+ { table: "company_skill_comments", localRows: 0 },
+ { table: "company_skill_stars", localRows: 0 },
+ { table: "company_user_sidebar_preferences", localRows: 0 },
+ { table: "environment_custom_image_setup_sessions", localRows: 0 },
+ { table: "environment_custom_image_templates", localRows: 0 },
+ { table: "external_object_mentions", localRows: 0 },
+ { table: "external_objects", localRows: 0 },
+ { table: "finance_events", localRows: 0 },
+ { table: "heartbeat_run_watchdog_decisions", localRows: 0 },
+ { table: "inbox_dismissals", localRows: 0 },
+ { table: "invites", localRows: 0 },
+ { table: "issue_labels", localRows: 0 },
+ { table: "issue_plan_decompositions", localRows: 0 },
+ { table: "issue_watchdogs", localRows: 0 },
+ { table: "join_requests", localRows: 0 },
+ { table: "labels", localRows: 0 },
+ { table: "pipeline_automation_executions", localRows: 0 },
+ { table: "pipeline_case_blockers", localRows: 0 },
+ { table: "pipeline_case_documents", localRows: 0 },
+ { table: "pipeline_case_events", localRows: 0 },
+ { table: "pipeline_case_issue_links", localRows: 0 },
+ { table: "pipeline_cases", localRows: 0 },
+ { table: "pipeline_documents", localRows: 0 },
+ { table: "pipeline_stages", localRows: 0 },
+ { table: "pipeline_transitions", localRows: 0 },
+ { table: "pipelines", localRows: 0 },
+ { table: "plugin_company_settings", localRows: 0 },
+ { table: "plugin_config", localRows: 0 },
+ { table: "plugin_database_namespaces", localRows: 0 },
+ { table: "plugin_entities", localRows: 0 },
+ { table: "plugin_job_runs", localRows: 0 },
+ { table: "plugin_jobs", localRows: 0 },
+ { table: "plugin_logs", localRows: 0 },
+ { table: "plugin_managed_resources", localRows: 0 },
+ { table: "plugin_migrations", localRows: 0 },
+ { table: "plugin_state", localRows: 0 },
+ { table: "plugin_webhook_deliveries", localRows: 0 },
+ { table: "plugins", localRows: 0 },
+ { table: "project_memberships", localRows: 0 },
+ { table: "user_secret_declarations", localRows: 0 },
+ { table: "user_secret_definitions", localRows: 0 },
+ { table: "user_sidebar_preferences", localRows: 0 },
+ { table: "verification", localRows: 0 },
+ { table: "workspace_runtime_services", localRows: 0 },
+] as const satisfies readonly LocalTableRowCount[];
+
+function bucketForEstimatedRows(estimatedRows: number): TableSizeBucket {
+ if (estimatedRows >= TABLE_SIZE_BUCKET_THRESHOLDS.largeRows) return "large";
+ if (estimatedRows >= TABLE_SIZE_BUCKET_THRESHOLDS.mediumRows) return "medium";
+ return "small";
+}
+
+export const TABLE_SIZE_ESTIMATES: readonly TableSizeEstimate[] = LOCAL_TABLE_ROW_COUNTS.map(
+ ({ table, localRows }) => {
+ const estimatedRows = localRows * TABLE_SIZE_ESTIMATE_FACTOR;
+ return {
+ table,
+ localRows,
+ estimateFactor: TABLE_SIZE_ESTIMATE_FACTOR,
+ estimatedRows,
+ bucket: bucketForEstimatedRows(estimatedRows),
+ };
+ },
+);
+
+export const TABLE_SIZE_ESTIMATES_BY_TABLE: ReadonlyMap<string, TableSizeEstimate> = new Map(
+ TABLE_SIZE_ESTIMATES.map((estimate) => [estimate.table, estimate]),
+);
+
+export function getTableSizeEstimate(table: string): TableSizeEstimate | undefined {
+ return TABLE_SIZE_ESTIMATES_BY_TABLE.get(table);
+}
+
+export function getTableSizeBucket(table: string): TableSizeBucket {
+ return getTableSizeEstimate(table)?.bucket ?? "small";
+}
+
+export function isKnownLargeTable(table: string): boolean {
+ return getTableSizeBucket(table) === "large";
+}