okmodel 0.3.0 → 0.4.0

package/dist/shared/{2ssqrv66.js → n5y9zyj1.js}

@@ -2,7 +2,7 @@ import {
   creationOrder2,
   renameColumn2,
   renameTable2
-} from "./t616ynfn.js";
+} from "./8jb4ymh2.js";
 import {
   quoteIdent,
   ownedByView,
@@ -15,16 +15,16 @@ import {
   identitySequence,
   createTableSql,
   qualify
-} from "./wekze34d.js";
+} from "./41kv2xdm.js";
 import {
   isExactVersion,
   compareExtensionVersions,
   sameExtensionDefinition
-} from "./th14ygv2.js";
+} from "./8ktwd3rh.js";
 import {
   isDomain,
   sameEnumLabels
-} from "./qbxzvwwc.js";
+} from "./g7ez901n.js";
 import {
   quoteLiteral
 } from "./94ez8kzh.js";
@@ -41,9 +41,74 @@ import {
   OkmError2
 } from "./52szzakm.js";
 
+// src/tooling/migrate/type-name.ts
+function canonicalTypeName(typeName) {
+  const suffix = arraySuffix(typeName);
+  const scalar = suffix.length === 0 ? typeName : typeName.slice(0, -suffix.length);
+  return canonicalScalar(scalar) + suffix;
+}
+function arraySuffix(typeName) {
+  let end = typeName.length;
+  let suffix = "";
+  while (end >= 2 && typeName.endsWith("[]", end)) {
+    suffix = `[]${suffix}`;
+    end -= 2;
+  }
+  return suffix;
+}
+function canonicalScalar(typeName) {
+  const varying = /^(?:varchar|character varying)(\(\d+\))$/.exec(typeName);
+  if (varying !== null)
+    return `character varying${varying[1] ?? ""}`;
+  const fixed = /^(?:char|character)(\(\d+\))$/.exec(typeName);
+  if (fixed !== null)
+    return `character${fixed[1] ?? ""}`;
+  const timed = /^(timestamp with time zone|timestamp without time zone|time with time zone|time without time zone|timestamptz|timestamp|timetz|time)(\(\d+\))?$/.exec(typeName);
+  if (timed !== null)
+    return canonicalTime(timed[1] ?? "", timed[2] ?? "");
+  const numeric = /^(?:decimal|numeric)(\(\d+(?:,\d+)?\))?$/.exec(typeName);
+  if (numeric !== null)
+    return `numeric${numeric[1] ?? ""}`;
+  switch (typeName) {
+    case "int":
+    case "int4":
+    case "integer":
+      return "integer";
+    case "int8":
+    case "bigint":
+      return "bigint";
+    case "int2":
+    case "smallint":
+      return "smallint";
+    case "bool":
+    case "boolean":
+      return "boolean";
+    case "float8":
+    case "double precision":
+      return "double precision";
+    case "float4":
+    case "real":
+      return "real";
+    default:
+      return typeName;
+  }
+}
+function canonicalTime(name, precision) {
+  if (name === "timestamptz" || name === "timestamp with time zone") {
+    return `timestamp${precision} with time zone`;
+  }
+  if (name === "timestamp" || name === "timestamp without time zone") {
+    return `timestamp${precision} without time zone`;
+  }
+  if (name === "timetz" || name === "time with time zone") {
+    return `time${precision} with time zone`;
+  }
+  return `time${precision} without time zone`;
+}
+
 // src/dialects/pg/role/sql.ts
 var PRIVILEGE = /^(select|insert|update|delete|execute|usage)$/;
-function privilegeSql(before, after, schema) {
+function privilegeSql(before, after, schema, recreated = new Set) {
   const beforeBy = index(before);
   const afterBy = index(after);
   const revoke = [];
@@ -53,10 +118,12 @@ function privilegeSql(before, after, schema) {
   for (const [key, object] of beforeBy) {
     if (afterBy.has(key))
       continue;
-    if (object.kind === "grant")
-      revoke.push(grantStatement(object, schema, true));
-    if (object.kind === "defaultPrivilege")
-      revoke.push(defaultStatement(object, true));
+    if (object.kind === "grant") {
+      revoke.push({ sql: grantStatement(object, schema, true), kind: "revoke" });
+    }
+    if (object.kind === "defaultPrivilege") {
+      revoke.push({ sql: defaultStatement(object, true), kind: "revoke-default" });
+    }
   }
   for (const [key, object] of afterBy) {
     const previous = beforeBy.get(key);
@@ -64,22 +131,28 @@ function privilegeSql(before, after, schema) {
       if (object.owner !== "managed")
         continue;
       if (previous === undefined) {
-        roles.push(createRoleSql(object));
+        roles.push({ sql: createRoleSql(object), kind: "create-role" });
         continue;
       }
       if (previous.kind !== "role" || previous.owner !== "managed")
         continue;
       if (previous.definition.login !== object.definition.login || previous.definition.inherit !== object.definition.inherit) {
-        roles.push(alterRoleSql(object));
+        roles.push({ sql: alterRoleSql(object), kind: "alter-role" });
       }
       continue;
     }
+    if (object.kind === "grant") {
+      const target = grantTargetKey(object.identity.object);
+      if (previous !== undefined && (target === undefined || !recreated.has(target)))
+        continue;
+      grant.push({ sql: grantStatement(object, schema, false), kind: "grant" });
+      continue;
+    }
     if (previous !== undefined)
       continue;
-    if (object.kind === "defaultPrivilege")
-      defaults.push(defaultStatement(object, false));
-    if (object.kind === "grant")
-      grant.push(grantStatement(object, schema, false));
+    if (object.kind === "defaultPrivilege") {
+      defaults.push({ sql: defaultStatement(object, false), kind: "grant-default" });
+    }
   }
   return { revoke, prepare: [...roles, ...defaults], grant };
 }
@@ -130,6 +203,24 @@ function defaultStatement(object, revoke) {
   const namespace = object.identity.namespace.form === "static" ? object.identity.namespace.name : "public";
   return `alter default privileges for role ${quoteIdent(object.identity.forRole)} in schema ${quoteIdent(namespace)} ${verb} ${privilege} on ${objectKindSql(object.identity.objectKind)} ${direction} ${quoteIdent(object.identity.grantee)}`;
 }
+function grantTargetKey(object) {
+  if (object.kind === "table" || object.kind === "view" || object.kind === "materializedView" || object.kind === "sequence") {
+    return identityKey2({ kind: object.kind, namespace: object.namespace, name: object.name });
+  }
+  if (object.kind !== "function")
+    return;
+  const open = object.name.lastIndexOf("(");
+  if (open < 0 || !object.name.endsWith(")"))
+    return;
+  const name = object.name.slice(0, open);
+  const args = object.name.slice(open + 1, -1);
+  return identityKey2({
+    kind: "function",
+    namespace: object.namespace,
+    name,
+    argTypes: args.length === 0 ? [] : args.split(",")
+  });
+}
 function grantTarget(object, schema) {
   const name = object.namespace.form === "static" ? object.namespace.name : schema;
   if (object.kind === "sequence")
@@ -165,6 +256,247 @@ function assertPrivilege(privilege) {
   }
 }
 
+// src/tooling/migrate/backfill.ts
+var DEFAULT_BACKFILL_BATCH_SIZE = 1000;
+var DEFAULT_BACKFILL_PAUSE_MS = 0;
+var DEFAULT_BACKFILL_STATEMENT_TIMEOUT_MS = 30000;
+var HEADER = /^-- backfill table=(\S+) key=(\S+) batch=(\d+)$/;
+var CAST_TYPE = /^[A-Za-z_][\w$ ]*(?:\([^)]*\))?(?:\[\])*$/;
+function batchSizeField(batchSize) {
+  return batchSize === undefined ? {} : { batchSize };
+}
+function resolveBatchSize(requested) {
+  const batch = requested ?? DEFAULT_BACKFILL_BATCH_SIZE;
+  if (!Number.isInteger(batch) || batch < 1) {
+    throw new OkmError2("invalid", "backfill.batchSize must be an integer of at least 1.", {
+      fix: {
+        summary: "Set defineConfig({ backfill: { batchSize } }) to a positive integer."
+      }
+    });
+  }
+  return batch;
+}
+function formatBackfillHeader(spec) {
+  return `-- backfill table=${spec.table} key=${spec.key.join(",")} batch=${String(spec.batch)}`;
+}
+function parseBackfillHeader(line) {
+  if (!line.startsWith("-- backfill "))
+    return;
+  const match = HEADER.exec(line);
+  const table = match?.[1];
+  const keyText = match?.[2];
+  const batchText = match?.[3];
+  const key = keyText === undefined ? [] : splitKey(keyText);
+  const batch = batchText === undefined ? Number.NaN : Number(batchText);
+  if (table === undefined || key.length === 0 || !Number.isInteger(batch) || batch < 1) {
+    throw new OkmError2("invalid", "A backfill header needs table=<table> key=<col> batch=<n>.", {
+      fix: {
+        summary: "Write -- backfill table=<table> key=<col[,col]> batch=<n> with a batch of at least 1."
+      }
+    });
+  }
+  return { table, key, batch };
+}
+function primaryKeyColumns(catalogs, table) {
+  for (const source of catalogs) {
+    const columns = keyOn(source, table);
+    if (columns !== undefined)
+      return columns;
+  }
+  throw new OkmError2("OKM1546", `Table ${table} has no primary key, so it cannot be backfilled.`, {
+    fix: {
+      summary: "Add a primary key. A backfill walks that key and does not scan the table."
+    }
+  });
+}
+function keyRangePredicate(columns) {
+  for (const column of columns)
+    assertCastType(column.dataType);
+  const lower = compareKey(columns, "$1", ">");
+  const upper = compareKey(columns, "$2", "<=");
+  return `($1::text is null or ${lower}) and ($2::text is null or ${upper})`;
+}
+function aboutBatchCount(rows, batch) {
+  if (!Number.isFinite(rows) || batch < 1)
+    return 0;
+  const rounded = Math.max(0, Math.round(rows));
+  if (rounded === 0)
+    return 0;
+  return Math.ceil(rounded / batch);
+}
+function keyOn(source, table) {
+  const constraint = source.objects.find((object) => object.kind === "constraint" && object.definition.constraintKind === "primaryKey" && object.identity.parent.name === table);
+  if (constraint === undefined || constraint.kind !== "constraint")
+    return;
+  const columns = [];
+  for (const name of constraint.definition.columns) {
+    const column = source.objects.find((object) => object.kind === "column" && object.identity.parent.name === table && object.identity.name === name);
+    if (column === undefined || column.kind !== "column") {
+      throw new OkmError2("OKM1546", `Table ${table} primary key column ${name} is not in the catalog.`, { fix: { summary: "Keep the primary key columns on the table." } });
+    }
+    columns.push({ quoted: quoteIdent(name), dataType: column.definition.dataType });
+  }
+  if (columns.length === 0)
+    return;
+  return columns;
+}
+function boundaryQuery(table, columns) {
+  for (const column of columns)
+    checkedCast(column.dataType);
+  const order = columns.map((column) => column.quoted).join(", ");
+  const first = columns[0];
+  const projected = columns.length === 1 && first !== undefined ? `${first.quoted}::text` : `jsonb_build_array(${columns.map((column) => `${column.quoted}::text`).join(", ")})::text`;
+  const lower = `($1::text is null or ${compareKey(columns, "$1", ">")})`;
+  return `select ${projected} as okm_key from ${table} where ${lower} order by ${order} offset $2::bigint limit 1`;
+}
+function checkedCast(dataType) {
+  assertCastType(dataType);
+  return dataType;
+}
+function compareKey(columns, param, operator) {
+  const first = columns[0];
+  if (first === undefined)
+    return "false";
+  if (columns.length === 1) {
+    return `${first.quoted} ${operator} ${param}::${first.dataType}`;
+  }
+  const left = columns.map((column) => column.quoted).join(", ");
+  const right = columns.map((column, index) => `((${param}::jsonb)->>${String(index)})::${column.dataType}`).join(", ");
+  return `(${left}) ${operator} (${right})`;
+}
+function assertCastType(dataType) {
+  if (CAST_TYPE.test(dataType))
+    return;
+  throw new OkmError2("OKM1546", `Primary key type ${dataType} cannot be used as a backfill bound.`, {
+    fix: {
+      summary: "Use an orderable scalar key. A backfill casts each bound to the key type."
+    }
+  });
+}
+function splitKey(text) {
+  const names = [];
+  let index = 0;
+  while (index < text.length) {
+    if (text[index] === '"') {
+      let value = "";
+      index += 1;
+      let closed = false;
+      while (index < text.length) {
+        const char = text[index];
+        if (char === '"' && text[index + 1] === '"') {
+          value += '"';
+          index += 2;
+          continue;
+        }
+        if (char === '"') {
+          index += 1;
+          closed = true;
+          break;
+        }
+        value += char ?? "";
+        index += 1;
+      }
+      if (!closed)
+        return [];
+      names.push(quoteIdent(value));
+      if (text[index] === ",")
+        index += 1;
+      continue;
+    }
+    const comma = text.indexOf(",", index);
+    const end = comma === -1 ? text.length : comma;
+    const raw = text.slice(index, end);
+    if (raw.length === 0)
+      return [];
+    names.push(quoteIdent(raw));
+    index = comma === -1 ? text.length : comma + 1;
+  }
+  return names;
+}
+
+// src/tooling/migrate/classify.ts
+var STEP_CLASS = {
+  "create-table": "expand",
+  "drop-table": "contract",
+  "add-column": "expand",
+  "add-column-required": "contract",
+  "drop-column": "contract",
+  "set-column-type": "contract",
+  "set-not-null": "contract",
+  "drop-not-null": "expand",
+  "set-default": "expand",
+  "drop-default": "contract",
+  "add-identity": "expand",
+  "drop-identity": "contract",
+  "set-identity-always": "contract",
+  "set-identity-by-default": "expand",
+  "add-constraint": "expand",
+  "validate-constraint": "expand",
+  "drop-constraint": "contract",
+  "drop-not-null-check": "expand",
+  "rename-constraint": "contract",
+  "widen-check": "expand",
+  "narrow-check": "contract",
+  "create-index": "expand",
+  "drop-index": "contract",
+  "rename-index": "contract",
+  "create-sequence": "expand",
+  "drop-sequence": "contract",
+  "create-enum": "expand",
+  "recreate-enum": "contract",
+  "add-enum-value": "expand",
+  "rename-enum": "contract",
+  "drop-enum": "contract",
+  "set-enum-column": "contract",
+  "create-domain": "expand",
+  "drop-domain": "contract",
+  "add-domain-check": "expand",
+  "validate-domain-check": "expand",
+  "drop-domain-check": "contract",
+  "rename-domain-check": "expand",
+  "create-extension": "expand",
+  "drop-extension": "contract",
+  "update-extension": "expand",
+  "move-extension": "contract",
+  "create-function": "expand",
+  "drop-function": "contract",
+  "replace-function": "expand",
+  "create-trigger": "expand",
+  "drop-trigger": "contract",
+  "create-view": "expand",
+  "drop-view": "contract",
+  "replace-view": "expand",
+  "create-matview": "expand",
+  "drop-matview": "contract",
+  "refresh-matview": "expand",
+  "create-role": "expand",
+  "alter-role": "contract",
+  grant: "expand",
+  revoke: "contract",
+  "grant-default": "expand",
+  "revoke-default": "contract",
+  "rename-table": "contract",
+  "rename-column": "contract",
+  "rename-sequence": "contract",
+  "backfill-expand": "expand",
+  "backfill-contract": "contract",
+  "raw-sql": "unclassified"
+};
+var STEP_KINDS = Object.keys(STEP_CLASS);
+function classOf(kind) {
+  return STEP_CLASS[kind];
+}
+function strictestClass(classes) {
+  if (classes.includes("contract"))
+    return "contract";
+  if (classes.includes("unclassified"))
+    return "unclassified";
+  return "expand";
+}
+function isStepKind(value) {
+  return Object.hasOwn(STEP_CLASS, value);
+}
+
 // src/tooling/migrate/extensions.ts
 var CREATE_EXTENSION = /^\s*create\s+extension\s+(?:"([^"]+)"|([A-Za-z_][\w$]*))/i;
 var UPDATE_EXTENSION = /^\s*alter\s+extension\s+(?:"([^"]+)"|([A-Za-z_][\w$]*))\s+update\s+to\s+'([^']*)'/i;
@@ -255,13 +587,7 @@ function alterExtension(before, after) {
         }
       });
     }
-    steps.push({
-      sql: `alter extension ${name} set schema ${quoteIdent(after.definition.schema)}`,
-      class: "contract",
-      action: "ddl",
-      lock: "ACCESS EXCLUSIVE",
-      transactional: true
-    });
+    steps.push(extensionStep(`alter extension ${name} set schema ${quoteIdent(after.definition.schema)}`, "move-extension"));
   }
   const previous = before.definition.version;
   const next = after.definition.version;
@@ -274,15 +600,27 @@ function alterExtension(before, after) {
       }
     });
   }
-  steps.push({
-    sql: `alter extension ${name} update to ${quoteLiteral(next)}`,
-    class: "expand",
+  steps.push(extensionStep(`alter extension ${name} update to ${quoteLiteral(next)}`, "update-extension", {
+    path: "unverified"
+  }));
+  return steps;
+}
+function extensionStep(sql, kind, extra) {
+  const classification = classOf(kind);
+  if (classification === "unclassified") {
+    throw new OkmError2("invalid", `Extension step ${kind} has no class.`, {
+      fix: { summary: "Classify the extension step as expand or contract." }
+    });
+  }
+  return {
+    sql,
+    kind,
+    class: classification,
     action: "ddl",
     lock: "ACCESS EXCLUSIVE",
     transactional: true,
-    path: "unverified"
-  });
-  return steps;
+    ...extra?.path !== undefined ? { path: extra.path } : {}
+  };
 }
 async function availableExtensions(connection, names) {
   const listed = await connection.execute(`select name from pg_available_extensions where name in (${names.map((_, index) => `$${String(index + 1)}`).join(", ")})`, names);
@@ -306,7 +644,7 @@ async function updatePath(connection, name, source, target) {
 }
 
 // src/tooling/migrate/managed.ts
-var MANAGED_TABLES = new Set(["okm_meta", "okm_history"]);
+var MANAGED_TABLES = new Set(["okm_meta", "okm_history", "okm_backfill"]);
 function omitManagedObjects(source) {
   let dropped = false;
   const objects = [];
@@ -348,72 +686,293 @@ function ownedByMigration(object) {
   }
 }
 function managedSequence(name) {
-  return name === "okm_meta" || name === "okm_history" || name.startsWith("okm_meta_") || name.startsWith("okm_history_");
+  return name === "okm_meta" || name === "okm_history" || name === "okm_backfill" || name.startsWith("okm_meta_") || name.startsWith("okm_history_") || name.startsWith("okm_backfill_");
 }
 
-// src/tooling/migrate/type-name.ts
-function canonicalTypeName(typeName) {
-  const suffix = arraySuffix(typeName);
-  const scalar = suffix.length === 0 ? typeName : typeName.slice(0, -suffix.length);
-  return canonicalScalar(scalar) + suffix;
+// src/tooling/migrate/safe.ts
+var ACCESS = "ACCESS EXCLUSIVE";
+var SHARE_UPDATE = "SHARE UPDATE EXCLUSIVE";
+var ROW = "ROW EXCLUSIVE";
+var VOLATILE_BUILTIN = new Set([
+  "clock_timestamp",
+  "gen_random_uuid",
+  "nextval",
+  "random",
+  "random_normal",
+  "setval",
+  "timeofday",
+  "uuidv7"
+]);
+var STABLE_BUILTIN = new Set([
+  "current_catalog",
+  "current_date",
+  "current_role",
+  "current_schema",
+  "current_time",
+  "current_timestamp",
+  "current_user",
+  "localtime",
+  "localtimestamp",
+  "now",
+  "session_user",
+  "statement_timestamp",
+  "transaction_timestamp"
+]);
+function stepsForExistingTable(object, schema, catalogs, batchSize) {
+  if (object.kind === "index")
+    return [concurrentIndexStep(object, schema)];
+  if (object.kind === "constraint")
+    return constraintSteps(object, schema);
+  if (object.kind === "column" && volatileDefault(object.definition.defaultExpression, catalogs)) {
+    return volatileColumnSteps(object, schema, catalogs, batchSize);
+  }
+  return;
 }
-function arraySuffix(typeName) {
-  let end = typeName.length;
-  let suffix = "";
-  while (end >= 2 && typeName.endsWith("[]", end)) {
-    suffix = `[]${suffix}`;
-    end -= 2;
+function notNullSteps(column, schema, setKind, catalogs) {
+  const tableName = column.identity.parent.name;
+  const columnName = column.identity.name;
+  const table = qualify(schema, tableName);
+  const quotedColumn = quoteIdent(columnName);
+  const constraint = quoteIdent(notNullConstraintName(tableName, columnName, catalogs));
+  return [
+    {
+      sql: `alter table ${table} add constraint ${constraint} check (${quotedColumn} is not null) not valid`,
+      kind: "add-constraint",
+      action: "ddl",
+      lock: ACCESS,
+      transactional: true
+    },
+    {
+      sql: `alter table ${table} validate constraint ${constraint}`,
+      kind: "validate-constraint",
+      action: "ddl",
+      lock: SHARE_UPDATE,
+      transactional: true
+    },
+    {
+      sql: `alter table ${table} alter column ${quotedColumn} set not null`,
+      kind: setKind,
+      action: "ddl",
+      lock: ACCESS,
+      transactional: true
+    },
+    {
+      sql: `alter table ${table} drop constraint ${constraint}`,
+      kind: "drop-not-null-check",
+      action: "ddl",
+      lock: ACCESS,
+      transactional: true
+    }
+  ];
+}
+function concurrentIndexSql(sql) {
+  const unique = "create unique index ";
+  const plain = "create index ";
+  if (sql.startsWith(unique))
+    return `create unique index concurrently ${sql.slice(unique.length)}`;
+  if (sql.startsWith(plain))
+    return `create index concurrently ${sql.slice(plain.length)}`;
+  return sql;
+}
+function concurrentDropIndexSql(sql) {
+  const prefix = "drop index ";
+  if (!sql.startsWith(prefix))
+    return sql;
+  return `drop index concurrently ${sql.slice(prefix.length)}`;
+}
+function volatileDefault(expression, catalogs) {
+  if (expression === undefined)
+    return false;
+  const known = catalogVolatility(catalogs);
+  for (const name of functionCalls(expression)) {
+    const lower = name.toLowerCase();
+    if (VOLATILE_BUILTIN.has(lower))
+      return true;
+    if (STABLE_BUILTIN.has(lower))
+      continue;
+    if (known.get(lower) === "volatile")
+      return true;
   }
-  return suffix;
+  return false;
 }
-function canonicalScalar(typeName) {
-  const varying = /^(?:varchar|character varying)(\(\d+\))$/.exec(typeName);
-  if (varying !== null)
-    return `character varying${varying[1] ?? ""}`;
-  const fixed = /^(?:char|character)(\(\d+\))$/.exec(typeName);
-  if (fixed !== null)
-    return `character${fixed[1] ?? ""}`;
-  const timed = /^(timestamp with time zone|timestamp without time zone|time with time zone|time without time zone|timestamptz|timestamp|timetz|time)(\(\d+\))?$/.exec(typeName);
-  if (timed !== null)
-    return canonicalTime(timed[1] ?? "", timed[2] ?? "");
-  const numeric = /^(?:decimal|numeric)(\(\d+(?:,\d+)?\))?$/.exec(typeName);
-  if (numeric !== null)
-    return `numeric${numeric[1] ?? ""}`;
-  switch (typeName) {
-    case "int":
-    case "int4":
-    case "integer":
-      return "integer";
-    case "int8":
-    case "bigint":
-      return "bigint";
-    case "int2":
-    case "smallint":
-      return "smallint";
-    case "bool":
-    case "boolean":
-      return "boolean";
-    case "float8":
-    case "double precision":
-      return "double precision";
-    case "float4":
-    case "real":
-      return "real";
-    default:
-      return typeName;
+function concurrentIndexStep(object, schema) {
+  const plain = createObjectSql(object, schema) ?? "";
+  return {
+    sql: concurrentIndexSql(plain),
+    kind: "create-index",
+    action: "ddl",
+    lock: SHARE_UPDATE,
+    transactional: false
+  };
+}
+function constraintSteps(object, schema) {
+  const kind = object.definition.constraintKind;
+  if (kind === "unique" || kind === "primaryKey")
+    return usingIndexSteps(object, schema);
+  return notValidSteps(object, schema);
+}
+function notValidSteps(object, schema) {
+  const plain = createObjectSql(object, schema);
+  if (plain === undefined)
+    return [];
+  const table = qualify(schema, object.identity.parent.name);
+  const name = quoteIdent(object.identity.name);
+  const referenced = object.definition.references;
+  const referencedLock = referenced === undefined ? undefined : qualify(schema, referenced.parent.name);
+  return [
+    {
+      sql: `${plain} not valid`,
+      kind: "add-constraint",
+      action: "ddl",
+      lock: referencedLock === undefined ? ACCESS : `${ACCESS}; SHARE ROW EXCLUSIVE on ${referencedLock}`,
+      transactional: true
+    },
+    {
+      sql: `alter table ${table} validate constraint ${name}`,
+      kind: "validate-constraint",
+      action: "ddl",
+      lock: referencedLock === undefined ? SHARE_UPDATE : `${SHARE_UPDATE}; ROW SHARE on ${referencedLock}`,
+      transactional: true
+    }
+  ];
+}
+function usingIndexSteps(object, schema) {
+  const table = qualify(schema, object.identity.parent.name);
+  const name = quoteIdent(object.identity.name);
+  const columns = object.definition.columns.map((column) => quoteIdent(column)).join(", ");
+  const nulls = object.definition.nullsNotDistinct ? " nulls not distinct" : "";
+  const verb = object.definition.constraintKind === "primaryKey" ? "primary key" : "unique";
+  const defer = object.definition.deferrable ? ` deferrable initially ${object.definition.initially}` : "";
+  return [
+    {
+      sql: `create unique index concurrently ${name} on ${table} (${columns})${nulls}`,
+      kind: "create-index",
+      action: "ddl",
+      lock: SHARE_UPDATE,
+      transactional: false
+    },
+    {
+      sql: `alter table ${table} add constraint ${name} ${verb} using index ${name}${defer}`,
+      kind: "add-constraint",
+      action: "ddl",
+      lock: ACCESS,
+      transactional: true
+    }
+  ];
+}
+function volatileColumnSteps(column, schema, catalogs, batchSize) {
+  const tableName = column.identity.parent.name;
+  const table = qualify(schema, tableName);
+  const name = quoteIdent(column.identity.name);
+  const collate = column.definition.collation === undefined ? "" : ` collate ${quoteIdent(column.definition.collation)}`;
+  const expression = column.definition.defaultExpression ?? "";
+  const key = primaryKeyColumns(catalogs, tableName);
+  const backfill = {
+    table,
+    key: key.map((item) => item.quoted),
+    batch: batchSize
+  };
+  const steps = [
+    {
+      sql: `alter table ${table} add column ${name} ${column.definition.dataType}${collate}`,
+      kind: "add-column",
+      action: "ddl",
+      lock: ACCESS,
+      transactional: true
+    },
+    {
+      sql: `alter table ${table} alter column ${name} set default ${expression}`,
+      kind: "set-default",
+      action: "ddl",
+      lock: ACCESS,
+      transactional: true
+    },
+    {
+      sql: `update ${table} set ${name} = ${expression} where ${name} is null and ${keyRangePredicate(key)}`,
+      kind: "backfill-expand",
+      action: "backfill",
+      lock: ROW,
+      transactional: false,
+      backfill
+    }
+  ];
+  if (!column.definition.nullable) {
+    steps.push(...notNullSteps(column, schema, "add-column", catalogs));
   }
+  return steps;
 }
-function canonicalTime(name, precision) {
-  if (name === "timestamptz" || name === "timestamp with time zone") {
-    return `timestamp${precision} with time zone`;
+function notNullConstraintName(table, column, catalogs) {
+  const taken = new Set;
+  for (const source of catalogs) {
+    for (const object of source.objects) {
+      if (object.kind === "constraint" || object.kind === "index")
+        taken.add(object.identity.name);
+    }
   }
-  if (name === "timestamp" || name === "timestamp without time zone") {
-    return `timestamp${precision} without time zone`;
+  const base = fitIdentifier2(`${table}_${column}_notnull`);
+  if (!taken.has(base))
+    return base;
+  return fitIdentifier2(`${table}_${column}_notnull_okm`);
+}
+function catalogVolatility(catalogs) {
+  const map = new Map;
+  for (const source of catalogs) {
+    for (const object of source.objects) {
+      if (object.kind !== "function")
+        continue;
+      const name = object.identity.name.toLowerCase();
+      const next = object.definition.volatility;
+      const current = map.get(name);
+      if (current === "volatile" || next === "volatile")
+        map.set(name, "volatile");
+      else if (current === undefined)
+        map.set(name, next);
+    }
   }
-  if (name === "timetz" || name === "time with time zone") {
-    return `time${precision} with time zone`;
+  return map;
+}
+function functionCalls(expression) {
+  const names = [];
+  let index = 0;
+  while (index < expression.length) {
+    const char = expression[index];
+    if (char === "'") {
+      index += 1;
+      while (index < expression.length) {
+        if (expression[index] === "'" && expression[index + 1] === "'") {
+          index += 2;
+          continue;
+        }
+        if (expression[index] === "'") {
+          index += 1;
+          break;
+        }
+        index += 1;
+      }
+      continue;
+    }
+    if (char !== undefined && /[A-Za-z_]/.test(char)) {
+      const start = index;
+      index += 1;
+      while (index < expression.length && /[\w$]/.test(expression[index] ?? ""))
+        index += 1;
+      let name = expression.slice(start, index);
+      if (expression[index] === ".") {
+        index += 1;
+        const qualifier = index;
+        while (index < expression.length && /[\w$]/.test(expression[index] ?? ""))
+          index += 1;
+        name = expression.slice(qualifier, index);
+      }
+      while (expression[index] === " ")
+        index += 1;
+      if (expression[index] === "(")
+        names.push(name);
+      continue;
+    }
+    index += 1;
   }
-  return `time${precision} without time zone`;
+  return names;
 }
 
 // src/tooling/migrate/values.ts
@@ -458,10 +1017,10 @@ function pair(table, column, value) {
 }
 
 // src/tooling/migrate/plan.ts
-var ACCESS = "ACCESS EXCLUSIVE";
+var ACCESS2 = "ACCESS EXCLUSIVE";
 var SHARE = "SHARE";
-var SHARE_UPDATE = "SHARE UPDATE EXCLUSIVE";
-var ROW = "ROW EXCLUSIVE";
+var SHARE_UPDATE2 = "SHARE UPDATE EXCLUSIVE";
+var ROW2 = "ROW EXCLUSIVE";
 function planMigration(input) {
   const request = {
     ...input,
@@ -469,6 +1028,7 @@ function planMigration(input) {
     after: omitManagedObjects(input.after)
   };
   const schema = request.schema ?? "public";
+  const batchSize = resolveBatchSize(request.batchSize);
   const renames = request.renames ?? [];
   const replacements = request.replacements ?? [];
   assertNoChains(replacements);
@@ -532,15 +1092,20 @@ function planMigration(input) {
   refuseRoutineDrops(beforeBy, afterBy, dropKeys);
   omitOwnedSequences(createKeys, afterBy, request.after);
   omitOwnedSequences(dropKeys, beforeBy, renamed);
-  const privileges = privilegeSql(renamed.objects, request.after.objects, schema);
+  const recreated = new Set;
+  for (const key of createKeys) {
+    if (dropKeys.has(key))
+      recreated.add(key);
+  }
+  const privileges = privilegeSql(renamed.objects, request.after.objects, schema, recreated);
   const steps = [];
   steps.push(...renameSteps(request.before, renames, schema));
-  for (const sql of privileges.revoke)
-    steps.push(step(sql, "contract", "ddl", ACCESS));
+  for (const item of privileges.revoke)
+    steps.push(step(item.sql, item.kind, "ddl", ACCESS2));
   steps.push(...keptNames.map((item) => renameShapeStep(item, schema)));
   steps.push(...enumAddSteps(enums));
   steps.push(...domainCheckSteps(beforeBy, afterBy, schema));
-  steps.push(...expandBackfills(picklists, enums, replacements, schema));
+  steps.push(...expandBackfills(picklists, enums, replacements, schema, [renamed, request.after], batchSize));
   const droppedTables = new Set([...dropKeys].map((key) => beforeBy.get(key)).filter((object) => object?.kind === "table").map((object) => object.identity.name));
   const deferred = new Set(picklists.map((change) => identityKey2(change.before.identity)));
   const typeDrops = [];
@@ -551,9 +1116,19 @@ function planMigration(input) {
     if (!dropKeys.has(key) || deferred.has(key) || covered(object, droppedTables))
       return;
     const sql = dropObjectSql(object, schema);
-    if (sql === undefined)
+    const kind = dropKind(object);
+    if (sql === undefined || kind === undefined)
+      return;
+    if (object.kind === "index" && hasTable(renamed, object.identity.parent.name)) {
+      steps.push({
+        ...step(concurrentDropIndexSql(sql), "drop-index", "ddl", SHARE_UPDATE2, false, [
+          object.identity.parent.name
+        ]),
+        safeRewrite: true
+      });
       return;
-    steps.push(step(sql, "contract", "ddl", ACCESS));
+    }
+    steps.push(step(sql, kind, "ddl", ACCESS2));
   };
   for (const object of reverse)
     if (object.kind === "trigger")
@@ -585,31 +1160,36 @@ function planMigration(input) {
     }
     emitDrop(object);
   }
-  for (const object of typeDrops) {
-    const sql = dropObjectSql(object, schema);
-    if (sql === undefined)
-      continue;
-    steps.push(step(sql, "contract", "ddl", ACCESS));
-  }
-  for (const object of extensionDrops) {
-    const sql = dropObjectSql(object, schema);
-    if (sql === undefined)
-      continue;
-    steps.push(step(sql, "contract", "ddl", ACCESS));
-  }
+  for (const object of typeDrops)
+    pushDrop(steps, object, schema);
+  for (const object of extensionDrops)
+    pushDrop(steps, object, schema);
   steps.push(...extensionAlterSteps(beforeBy, afterBy, dropKeys));
   for (const change of alters) {
-    for (const sql of alterColumnSql(alignedColumnType(change.before, change.after), change.after, schema)) {
-      steps.push(step(sql, alterClass(sql), "ddl", ACCESS));
+    const aligned = alignedColumnType(change.before, change.after);
+    const statements = alterColumnSql(aligned, change.after, schema);
+    const kinds = columnAlterKinds(aligned, change.after);
+    for (let index = 0;index < statements.length; index += 1) {
+      const sql = statements[index];
+      const kind = kinds[index];
+      if (sql === undefined || kind === undefined)
+        continue;
+      if (kind === "set-not-null") {
+        pushSafe(steps, notNullSteps(change.after, schema, "set-not-null", [renamed, request.after]));
+        continue;
+      }
+      steps.push(step(sql, kind, "ddl", ACCESS2));
     }
     const identitySql = identityChangeSql(change.before, change.after, schema);
-    if (identitySql !== undefined)
-      steps.push(step(identitySql, "expand", "ddl", ACCESS));
+    const identity = identityKind(change.before, change.after);
+    if (identitySql !== undefined && identity !== undefined) {
+      steps.push(step(identitySql, identity, "ddl", ACCESS2));
+    }
   }
   const createdTables = new Set([...createKeys].map((key) => afterBy.get(key)).filter((object) => object?.kind === "table").map((object) => object.identity.name));
   const emitted = new Set;
-  for (const sql of privileges.prepare)
-    steps.push(step(sql, "expand", "ddl", ACCESS));
+  for (const item of privileges.prepare)
+    steps.push(step(item.sql, item.kind, "ddl", ACCESS2));
   for (const object of creationOrder2(request.after)) {
     if (object.kind !== "extension")
       continue;
@@ -618,9 +1198,10 @@ function planMigration(input) {
       continue;
     emitted.add(key);
     const sql = createObjectSql(object, schema);
-    if (sql === undefined)
+    const kind = createKind(object, false);
+    if (sql === undefined || kind === undefined)
       continue;
-    steps.push(step(sql, "expand", "ddl", ACCESS));
+    steps.push(step(sql, kind, "ddl", ACCESS2));
   }
   for (const object of creationOrder2(request.after)) {
     if (object.kind !== "type")
@@ -630,9 +1211,10 @@ function planMigration(input) {
       continue;
     emitted.add(key);
     const sql = createObjectSql(object, schema);
-    if (sql === undefined)
+    const kind = createKind(object, false);
+    if (sql === undefined || kind === undefined)
       continue;
-    steps.push(step(sql, "expand", "ddl", ACCESS));
+    steps.push(step(sql, kind, "ddl", ACCESS2));
   }
   for (const object of creationOrder2(request.after)) {
     if (object.kind === "type" || object.kind === "extension" || object.kind === "function" || object.kind === "trigger" || object.kind === "view" || object.kind === "materializedView" || ownedByView(object)) {
@@ -650,13 +1232,21 @@ function planMigration(input) {
       continue;
     emitted.add(key);
     if (object.kind === "table") {
-      steps.push(step(createTableSql(object, request.after, schema), "expand", "ddl", ACCESS));
+      steps.push(step(createTableSql(object, request.after, schema), "create-table", "ddl", ACCESS2));
       continue;
     }
     const sql = createObjectSql(object, schema);
-    if (sql === undefined)
+    const kind = createKind(object, tableIsNew);
+    if (sql === undefined || kind === undefined)
       continue;
-    steps.push(step(sql, "expand", "ddl", object.kind === "index" ? SHARE : ACCESS));
+    if (!tableIsNew && parent !== undefined && hasTable(renamed, parent)) {
+      const safe = stepsForExistingTable(object, schema, [renamed, request.after], batchSize);
+      if (safe !== undefined) {
+        pushSafe(steps, safe);
+        continue;
+      }
+    }
+    steps.push(step(sql, kind, "ddl", object.kind === "index" ? SHARE : ACCESS2));
   }
   for (const change of replaces) {
     if (sameDefinition(change.before, change.after))
@@ -665,11 +1255,13 @@ function planMigration(input) {
     if (dropKeys.has(key) && createKeys.has(key))
       continue;
     const sql = change.kind === "function" ? functionSql(change.after, schema, true) : viewSql(change.after, schema, true);
+    const kind = change.kind === "function" ? "replace-function" : "replace-view";
     steps.push({
       sql,
-      class: "expand",
+      kind,
+      class: classOf(kind),
       action: "ddl",
-      lock: ACCESS,
+      lock: ACCESS2,
       transactional: true,
       behavior: "change"
     });
@@ -683,9 +1275,10 @@ function planMigration(input) {
         continue;
       emitted.add(key);
       const sql = createObjectSql(object, schema);
-      if (sql === undefined)
+      const created = createKind(object, false);
+      if (sql === undefined || created === undefined)
         continue;
-      steps.push(step(sql, "expand", "ddl", ACCESS));
+      steps.push(step(sql, created, "ddl", ACCESS2));
     }
   }
   for (const object of creationOrder2(request.after)) {
@@ -696,9 +1289,10 @@ function planMigration(input) {
       continue;
     emitted.add(key);
     const sql = createObjectSql(object, schema);
-    if (sql === undefined)
+    const kind = createKind(object, false);
+    if (sql === undefined || kind === undefined)
       continue;
-    steps.push(step(sql, "expand", "ddl", SHARE));
+    steps.push(step(sql, kind, "ddl", SHARE));
   }
   for (const object of creationOrder2(request.after)) {
     if (object.kind !== "materializedView")
@@ -707,18 +1301,18 @@ function planMigration(input) {
     if (!createKeys.has(key))
       continue;
     assertConcurrentRefresh(object, request.after);
-    steps.push(step(refreshMaterializedViewSql(object, schema, false), "expand", "backfill", ACCESS));
+    steps.push(step(refreshMaterializedViewSql(object, schema, false), "refresh-matview", "backfill", ACCESS2));
   }
-  for (const sql of privileges.grant)
-    steps.push(step(sql, "expand", "ddl", ACCESS));
-  steps.push(...contractSwaps(picklists, enums, replacements, schema));
+  for (const item of privileges.grant)
+    steps.push(step(item.sql, item.kind, "ddl", ACCESS2));
+  steps.push(...contractSwaps(picklists, enums, replacements, schema, [renamed, request.after], batchSize));
   return {
     name: request.name ?? "migration",
     class: overall(steps),
     steps
   };
 }
-function formatPlan(plan) {
+function formatPlan(plan, lockText) {
   const lines = [`-- class: ${plan.class}`, `-- name: ${plan.name}`, ""];
   if (plan.steps.length === 0) {
     lines.push("-- no steps");
@@ -728,14 +1322,21 @@ function formatPlan(plan) {
   }
   for (const item of plan.steps) {
     lines.push(`-- class: ${item.class}`);
+    if (item.kind !== undefined)
+      lines.push(`-- kind: ${item.kind}`);
     lines.push(`-- action: ${item.action}`);
-    lines.push(`-- lock: ${item.lock}`);
+    lines.push(`-- lock: ${lockText === undefined ? item.lock : lockText(item)}`);
+    if (item.backfill !== undefined)
+      lines.push(formatBackfillHeader(item.backfill));
     if (!item.transactional)
       lines.push("-- transactional: false");
     if (item.path !== undefined)
       lines.push(`-- path: ${item.path}`);
     if (item.behavior === "change")
       lines.push("-- behavior: change");
+    for (const allow of item.allows ?? []) {
+      lines.push(`-- okm-allow ${allow.code}: ${allow.reason}`);
+    }
     lines.push(`${item.sql};`);
     lines.push("");
   }
@@ -765,46 +1366,71 @@ function parsePlan(text) {
     if (lines[index] === "-- no steps")
       break;
     let stepClass = "expand";
+    let sawClass = false;
+    let stepKind;
     let action = "ddl";
     let lock = "";
     let transactional = true;
+    let backfill;
     let path;
     let behavior;
+    const allows = [];
     const sql = [];
     while (index < lines.length && (lines[index] ?? "") !== "") {
       const line = lines[index] ?? "";
       index += 1;
-      if (line.startsWith("-- class: "))
+      if (line.startsWith("-- class: ")) {
         stepClass = readClass(line.slice("-- class: ".length));
-      else if (line.startsWith("-- action: "))
+        sawClass = true;
+      } else if (line.startsWith("-- kind: ")) {
+        const kind = line.slice("-- kind: ".length);
+        if (isStepKind(kind))
+          stepKind = kind;
+      } else if (line.startsWith("-- action: "))
         action = line.endsWith("backfill") ? "backfill" : "ddl";
       else if (line.startsWith("-- lock: "))
         lock = line.slice("-- lock: ".length);
+      else if (line.startsWith("-- backfill "))
+        backfill = parseBackfillHeader(line);
       else if (line === "-- transactional: false")
         transactional = false;
       else if (line === "-- path: unverified")
         path = "unverified";
       else if (line === "-- behavior: change")
         behavior = "change";
+      else if (line.startsWith("-- okm-allow"))
+        allows.push(readAllow(line));
       else if (!line.startsWith("--"))
         sql.push(line);
     }
     const statement = sql.join(`
 `).replace(/;\s*$/, "");
     if (statement.length > 0) {
+      const kind = sawClass ? stepKind : "raw-sql";
+      const classification = sawClass ? stepClass : "unclassified";
       steps.push({
         sql: statement,
-        class: stepClass,
+        class: classification,
+        ...kind !== undefined ? { kind } : {},
         action,
         lock,
         transactional,
+        ...backfill !== undefined ? { backfill } : {},
         ...path !== undefined ? { path } : {},
-        ...behavior !== undefined ? { behavior } : {}
+        ...behavior !== undefined ? { behavior } : {},
+        ...allows.length > 0 ? { allows } : {}
       });
     }
   }
   return { name, class: steps.length === 0 ? planClass : overall(steps), steps };
 }
+var ALLOW = /^-- okm-allow\s+(OKM\d+)\s*(?::\s*(.*))?$/;
+function readAllow(line) {
+  const match = ALLOW.exec(line);
+  if (match === null)
+    return { code: "", reason: "" };
+  return { code: match[1] ?? "", reason: (match[2] ?? "").trim() };
+}
 function readClass(value) {
   if (value === "contract" || value === "unclassified")
     return value;
@@ -856,7 +1482,8 @@ function renameSteps(source, renames, schema) {
     if (rename.kind !== "table" || !hasTable(source, rename.from))
       continue;
     tables.set(rename.to, rename.from);
-    steps.push(step(`alter table ${qualify(schema, rename.from)} rename to ${quoteIdent(rename.to)}`, "contract", "ddl", ACCESS));
+    steps.push(step(`alter table ${qualify(schema, rename.from)} rename to ${quoteIdent(rename.to)}`, "rename-table", "ddl", ACCESS2));
+    steps.push(...sequenceRenames(source, rename, schema));
   }
   for (const rename of renames) {
     if (rename.kind !== "column")
@@ -864,7 +1491,25 @@ function renameSteps(source, renames, schema) {
     const previousTable = tables.get(rename.table) ?? rename.table;
     if (!hasColumn(source, previousTable, rename.from))
       continue;
-    steps.push(step(`alter table ${qualify(schema, rename.table)} rename column ${quoteIdent(rename.from)} to ${quoteIdent(rename.to)}`, "contract", "ddl", ACCESS));
+    steps.push(step(`alter table ${qualify(schema, rename.table)} rename column ${quoteIdent(rename.from)} to ${quoteIdent(rename.to)}`, "rename-column", "ddl", ACCESS2));
+  }
+  return steps;
+}
+function sequenceRenames(source, rename, schema) {
+  const steps = [];
+  for (const object of source.objects) {
+    if (object.kind !== "column" || object.definition.identity === undefined)
+      continue;
+    if (object.identity.parent.name !== rename.from)
+      continue;
+    const fromName = fitIdentifier2(`${rename.from}_${object.identity.name}_seq`);
+    const toName = fitIdentifier2(`${rename.to}_${object.identity.name}_seq`);
+    if (fromName === toName)
+      continue;
+    const owned = source.objects.some((item) => item.kind === "sequence" && item.identity.name === fromName);
+    if (!owned)
+      continue;
+    steps.push(step(`alter sequence ${qualify(schema, fromName)} rename to ${quoteIdent(toName)}`, "rename-sequence", "ddl", ACCESS2));
   }
   return steps;
 }
@@ -913,12 +1558,14 @@ function withoutNameKey(value) {
 }
 function renameShapeStep(pair, schema) {
   if (pair.from.kind === "index" && pair.to.kind === "index") {
-    return step(`alter index ${qualify(schema, pair.from.identity.name)} rename to ${quoteIdent(pair.to.identity.name)}`, "contract", "ddl", ACCESS);
+    return step(`alter index ${qualify(schema, pair.from.identity.name)} rename to ${quoteIdent(pair.to.identity.name)}`, "rename-index", "ddl", ACCESS2);
   }
   if (pair.from.kind !== "constraint" || pair.to.kind !== "constraint") {
-    return step("select 1", "unclassified", "ddl", ACCESS);
+    throw new OkmError2("invalid", "A same-shape rename is an index or a constraint.", {
+      fix: { summary: "The planner only renames an index or a constraint in place." }
+    });
   }
-  return step(`alter table ${qualify(schema, pair.from.identity.parent.name)} rename constraint ${quoteIdent(pair.from.identity.name)} to ${quoteIdent(pair.to.identity.name)}`, "contract", "ddl", ACCESS);
+  return step(`alter table ${qualify(schema, pair.from.identity.parent.name)} rename constraint ${quoteIdent(pair.from.identity.name)} to ${quoteIdent(pair.to.identity.name)}`, "rename-constraint", "ddl", ACCESS2);
 }
 function assertUnambiguous(beforeBy, afterBy) {
   const dropped = new Map;
@@ -1092,24 +1739,25 @@ function enumAddSteps(enums) {
     if (change.kind !== "add")
       continue;
     for (const sql of change.statements) {
-      steps.push(step(sql, "expand", "ddl", ACCESS, false));
+      steps.push(step(sql, "add-enum-value", "ddl", ACCESS2, false));
     }
   }
   return steps;
 }
-function expandBackfills(picklists, enums, replacements, schema) {
-  return dataSteps(picklists, enums, replacements, schema, "expand");
+function expandBackfills(picklists, enums, replacements, schema, catalogs, batchSize) {
+  return dataSteps(picklists, enums, replacements, schema, catalogs, batchSize, "expand");
 }
-function contractSwaps(picklists, enums, replacements, schema) {
+function contractSwaps(picklists, enums, replacements, schema, catalogs, batchSize) {
   const steps = [];
-  steps.push(...dataSteps(picklists, enums, replacements, schema, "contract"));
+  steps.push(...dataSteps(picklists, enums, replacements, schema, catalogs, batchSize, "contract"));
   for (const change of picklists) {
     const table = qualify(schema, change.after.identity.parent.name);
     const name = quoteIdent(change.after.identity.name);
-    steps.push(step(`alter table ${table} drop constraint ${name}`, change.removed.length > 0 ? "contract" : "expand", "ddl", ACCESS));
+    const kind = change.removed.length > 0 ? "narrow-check" : "widen-check";
+    steps.push(step(`alter table ${table} drop constraint ${name}`, kind, "ddl", ACCESS2));
     const expression = change.after.definition.expression ?? "true";
-    steps.push(step(`alter table ${table} add constraint ${name} check (${expression}) not valid`, change.removed.length > 0 ? "contract" : "expand", "ddl", ACCESS));
-    steps.push(step(`alter table ${table} validate constraint ${name}`, change.removed.length > 0 ? "contract" : "expand", "ddl", SHARE_UPDATE));
+    steps.push(step(`alter table ${table} add constraint ${name} check (${expression}) not valid`, kind, "ddl", ACCESS2));
+    steps.push(step(`alter table ${table} validate constraint ${name}`, kind, "ddl", SHARE_UPDATE2));
   }
   for (const change of enums) {
     if (change.kind !== "replace")
@@ -1117,19 +1765,20 @@ function contractSwaps(picklists, enums, replacements, schema) {
     const type = qualify(schema, change.name);
     const old = quoteIdent(`${change.name}_old`);
     const labels = change.labels.map((label) => quoteLiteral(label)).join(", ");
-    steps.push(step(`alter type ${type} rename to ${old}`, "contract", "ddl", ACCESS));
-    steps.push(step(`create type ${type} as enum (${labels})`, "contract", "ddl", ACCESS));
+    steps.push(step(`alter type ${type} rename to ${old}`, "rename-enum", "ddl", ACCESS2));
+    steps.push(step(`create type ${type} as enum (${labels})`, "recreate-enum", "ddl", ACCESS2));
     for (const column of change.columns) {
       const table = qualify(schema, column.table);
       const name = quoteIdent(column.column);
-      steps.push(step(`alter table ${table} alter column ${name} type ${type} using ${name}::text::${type}`, "contract", "ddl", ACCESS));
+      steps.push(step(`alter table ${table} alter column ${name} type ${type} using ${name}::text::${type}`, "set-enum-column", "ddl", ACCESS2));
     }
-    steps.push(step(`drop type ${qualify(schema, `${change.name}_old`)}`, "contract", "ddl", ACCESS));
+    steps.push(step(`drop type ${qualify(schema, `${change.name}_old`)}`, "drop-enum", "ddl", ACCESS2));
   }
   return steps;
 }
-function dataSteps(picklists, enums, replacements, schema, phase) {
+function dataSteps(picklists, enums, replacements, schema, catalogs, batchSize, phase) {
   const steps = [];
+  const kind = phase === "expand" ? "backfill-expand" : "backfill-contract";
   for (const change of picklists) {
     if (change.removed.length === 0)
       continue;
@@ -1138,7 +1787,7 @@ function dataSteps(picklists, enums, replacements, schema, phase) {
       const replacement = findReplacement(replacements, table, change.column, value);
       if (replacement === undefined)
         continue;
-      steps.push(step(updateSql(schema, table, change.column, value, replacement.to), phase, "backfill", ROW));
+      steps.push(backfillStep(updateSql(schema, table, change.column, value, replacement.to, catalogs, batchSize), kind));
     }
   }
   for (const change of enums) {
@@ -1151,7 +1800,7 @@ function dataSteps(picklists, enums, replacements, schema, phase) {
         const replacement = findReplacement(replacements, column.table, column.column, value);
         if (replacement === undefined)
           continue;
-        steps.push(step(updateSql(schema, column.table, column.column, value, replacement.to, true), phase, "backfill", ROW));
+        steps.push(backfillStep(updateSql(schema, column.table, column.column, value, replacement.to, catalogs, batchSize, true), kind));
       }
     }
   }
@@ -1271,10 +1920,10 @@ function domainCheckSteps(beforeBy, afterBy, schema) {
     const current = quoteIdent(fitIdentifier2(`${name}_check`));
     const upcoming = quoteIdent(fitIdentifier2(`${name}_check_next`));
     const expression = next.definition.check;
-    steps.push(step(`alter domain ${type} add constraint ${upcoming} check (${expression}) not valid`, "expand", "ddl", ACCESS));
-    steps.push(step(`alter domain ${type} validate constraint ${upcoming}`, "expand", "ddl", ACCESS));
-    steps.push(step(`alter domain ${type} drop constraint ${current}`, "contract", "ddl", ACCESS));
-    steps.push(step(`alter domain ${type} rename constraint ${upcoming} to ${current}`, "expand", "ddl", ACCESS));
+    steps.push(step(`alter domain ${type} add constraint ${upcoming} check (${expression}) not valid`, "add-domain-check", "ddl", ACCESS2));
+    steps.push(step(`alter domain ${type} validate constraint ${upcoming}`, "validate-domain-check", "ddl", ACCESS2));
+    steps.push(step(`alter domain ${type} drop constraint ${current}`, "drop-domain-check", "ddl", ACCESS2));
+    steps.push(step(`alter domain ${type} rename constraint ${upcoming} to ${current}`, "rename-domain-check", "ddl", ACCESS2));
   }
   return steps;
 }
@@ -1448,6 +2097,40 @@ function omitOwnedSequences(keys, by, source) {
       keys.delete(key);
   }
 }
+var TRAILING_CAST = /^(.*)::((?:timestamp|time)(?:\(\d+\))? (?:with|without) time zone|character varying(?:\(\d+\))?|[A-Za-z_][\w$]*(?:\([^)]*\))?)$/;
+function canonicalDefault(expression, dataType) {
+  if (expression === undefined)
+    return {};
+  const match = TRAILING_CAST.exec(expression.trim());
+  const body = match?.[1]?.trim();
+  const cast = match?.[2];
+  if (body === undefined || body.length === 0 || cast === undefined)
+    return { defaultExpression: expression };
+  if (!defaultCastMatches(cast, dataType))
+    return { defaultExpression: expression };
+  return { defaultExpression: body };
+}
+function defaultCastMatches(cast, dataType) {
+  if (canonicalTypeName(cast) === canonicalTypeName(dataType))
+    return true;
+  const castBase = reprintedDefaultBase(cast);
+  const columnBase = reprintedDefaultBase(dataType);
+  return castBase !== undefined && castBase === columnBase;
+}
+function reprintedDefaultBase(typeName) {
+  const raw = typeName.trim();
+  if (/^(?:bpchar|character|char)(?:\(\d+\))?$/.test(raw))
+    return "character";
+  const canonical = canonicalTypeName(raw);
+  if (/^character varying(?:\(\d+\))?$/.test(canonical))
+    return "character varying";
+  if (/^character(?:\(\d+\))?$/.test(canonical))
+    return "character";
+  const time = /^(timestamp|time)(?:\(\d+\))? (with time zone|without time zone)$/.exec(canonical);
+  if (time !== null)
+    return `${time[1] ?? ""} ${time[2] ?? ""}`;
+  return;
+}
 function sameDefinition(left, right) {
   if (left.kind === "materializedView" && right.kind === "materializedView") {
     return stable(canonicalColumns(left.definition.columns)) === stable(canonicalColumns(right.definition.columns)) && left.definition.query === right.definition.query;
@@ -1457,6 +2140,11 @@ function sameDefinition(left, right) {
 function forComparison(object) {
   switch (object.kind) {
     case "column":
+      return {
+        ...object.definition,
+        dataType: canonicalTypeName(object.definition.dataType),
+        ...canonicalDefault(object.definition.defaultExpression, object.definition.dataType)
+      };
     case "sequence":
       return { ...object.definition, dataType: canonicalTypeName(object.definition.dataType) };
     case "view":
@@ -1528,22 +2216,30 @@ function anchoredParent(object) {
   }
   return;
 }
-function alterClass(sql) {
-  if (sql.includes("set data type") || sql.includes("set not null"))
-    return "contract";
-  return "expand";
-}
 function overall(steps) {
-  if (steps.some((item) => item.class === "contract"))
-    return "contract";
-  if (steps.some((item) => item.class === "unclassified"))
-    return "unclassified";
-  return "expand";
+  return strictestClass(steps.map((item) => item.class));
 }
-function updateSql(schema, table, column, from, to, cast = false) {
+function updateSql(schema, table, column, from, to, catalogs, batchSize, cast = false) {
+  const key = primaryKeyColumns(catalogs, table);
+  const qualified = qualify(schema, table);
   const value = to === null ? "null" : quoteLiteral(to);
   const compare = cast ? `${quoteIdent(column)}::text` : quoteIdent(column);
-  return `update ${qualify(schema, table)} set ${quoteIdent(column)} = ${value} where ${compare} = ${quoteLiteral(from)}`;
+  const where = `${compare} = ${quoteLiteral(from)}`;
+  const backfill = {
+    table: qualified,
+    key: key.map((item) => item.quoted),
+    batch: batchSize
+  };
+  return {
+    sql: `update ${qualified} set ${quoteIdent(column)} = ${value} where ${where} and ${keyRangePredicate(key)}`,
+    backfill
+  };
+}
+function backfillStep(planned, kind) {
+  return {
+    ...step(planned.sql, kind, "backfill", ROW2, false),
+    backfill: planned.backfill
+  };
 }
 function hasTable(source, name) {
   return source.objects.some((object) => object.kind === "table" && object.identity.name === name);
@@ -1554,8 +2250,167 @@ function hasColumn(source, table, name) {
 function index2(source) {
   return source.objects.map((object) => ({ key: identityKey2(object.identity), object }));
 }
-function step(sql, classification, action, lock, transactional = true) {
-  return { sql, class: classification, action, lock, transactional };
+function step(sql, kind, action, lock, transactional = true, extraTables) {
+  const tables = touchedTables(sql, lock, extraTables);
+  return {
+    sql,
+    kind,
+    class: classOf(kind),
+    action,
+    lock,
+    transactional,
+    ...tables.length > 0 ? { tables } : {}
+  };
+}
+function pushSafe(steps, safe) {
+  for (const item of safe) {
+    steps.push({
+      ...step(item.sql, item.kind, item.action, item.lock, item.transactional),
+      safeRewrite: true,
+      ...item.backfill !== undefined ? { backfill: item.backfill } : {}
+    });
+  }
+}
+var TABLE_PREFIX = /\b(?:create|alter|drop)\s+table(?:\s+if\s+exists)?\s+|\bupdate\s+|\binsert\s+into\s+|\breferences\s+|\bon\s+table\s+|\bon\s+/gi;
+function touchedTables(sql, lock, extra) {
+  const names = [];
+  const text = `${sql}
+${lock}`;
+  TABLE_PREFIX.lastIndex = 0;
+  for (let match = TABLE_PREFIX.exec(text);match !== null; match = TABLE_PREFIX.exec(text)) {
+    const found = readQualified(text, match.index + match[0].length);
+    if (found !== undefined)
+      pushTable(names, found.name);
+  }
+  for (const name of extra ?? [])
+    pushTable(names, name);
+  return names;
+}
+function pushTable(names, name) {
+  if (!names.includes(name))
+    names.push(name);
+}
+function readQualified(text, start) {
+  const schema = readIdent(text, start);
+  if (schema === undefined)
+    return;
+  if (text[schema.end] !== "." || text[schema.end + 1] !== '"')
+    return;
+  const name = readIdent(text, schema.end + 1);
+  if (name === undefined || text[name.end] === ".")
+    return;
+  return name;
+}
+function readIdent(text, start) {
+  if (text[start] !== '"')
+    return;
+  let value = "";
+  let index = start + 1;
+  while (index < text.length) {
+    const char = text[index];
+    if (char === '"') {
+      if (text[index + 1] === '"') {
+        value += '"';
+        index += 2;
+        continue;
+      }
+      return { name: value, end: index + 1 };
+    }
+    value += char ?? "";
+    index += 1;
+  }
+  return;
+}
+function pushDrop(steps, object, schema) {
+  const sql = dropObjectSql(object, schema);
+  const kind = dropKind(object);
+  if (sql === undefined || kind === undefined)
+    return;
+  steps.push(step(sql, kind, "ddl", ACCESS2));
+}
+function createKind(object, tableIsNew) {
+  switch (object.kind) {
+    case "table":
+      return "create-table";
+    case "column":
+      return requiredColumn(object) && !tableIsNew ? "add-column-required" : "add-column";
+    case "index":
+      return "create-index";
+    case "constraint":
+      return "add-constraint";
+    case "sequence":
+      return "create-sequence";
+    case "type":
+      return isDomain(object.definition) ? "create-domain" : "create-enum";
+    case "extension":
+      return "create-extension";
+    case "function":
+      return "create-function";
+    case "trigger":
+      return "create-trigger";
+    case "view":
+      return "create-view";
+    case "materializedView":
+      return "create-matview";
+    default:
+      return;
+  }
+}
+function dropKind(object) {
+  switch (object.kind) {
+    case "table":
+      return "drop-table";
+    case "column":
+      return "drop-column";
+    case "index":
+      return "drop-index";
+    case "constraint":
+      return "drop-constraint";
+    case "sequence":
+      return "drop-sequence";
+    case "type":
+      return isDomain(object.definition) ? "drop-domain" : "drop-enum";
+    case "extension":
+      return "drop-extension";
+    case "function":
+      return "drop-function";
+    case "trigger":
+      return "drop-trigger";
+    case "view":
+      return "drop-view";
+    case "materializedView":
+      return "drop-matview";
+    default:
+      return;
+  }
+}
+function requiredColumn(column) {
+  const definition = column.definition;
+  return !definition.nullable && definition.defaultExpression === undefined && definition.identity === undefined && definition.generated === undefined;
+}
+function columnAlterKinds(before, after) {
+  const kinds = [];
+  if (before.definition.dataType !== after.definition.dataType || before.definition.collation !== after.definition.collation) {
+    kinds.push("set-column-type");
+  }
+  if (before.definition.nullable !== after.definition.nullable) {
+    kinds.push(after.definition.nullable ? "drop-not-null" : "set-not-null");
+  }
+  if (before.definition.defaultExpression !== after.definition.defaultExpression) {
+    kinds.push(after.definition.defaultExpression === undefined ? "drop-default" : "set-default");
+  }
+  return kinds;
+}
+function identityKind(before, after) {
+  if (stable(before.definition.identity) === stable(after.definition.identity))
+    return;
+  const next = after.definition.identity;
+  const previous = before.definition.identity;
+  if (next === undefined)
+    return "drop-identity";
+  if (previous === undefined)
+    return "add-identity";
+  return next.always ? "set-identity-always" : "set-identity-by-default";
 }
 function stable(value) {
   return JSON.stringify(order(value));
@@ -1573,4 +2428,4 @@ function order(value) {
   return value;
 }
 
-export { createdRoleName, changesRole, assertExtensionsAvailable, omitManagedObjects, parseReplace, planMigration, formatPlan, parsePlan, staleRenames };
+export { canonicalTypeName, createdRoleName, changesRole, DEFAULT_BACKFILL_PAUSE_MS, DEFAULT_BACKFILL_STATEMENT_TIMEOUT_MS, batchSizeField, aboutBatchCount, boundaryQuery, checkedCast, classOf, strictestClass, assertExtensionsAvailable, omitManagedObjects, parseReplace, planMigration, formatPlan, parsePlan, staleRenames };