@dbsp/adapter-pgsql 2.0.0 → 3.0.0

package/dist/index.js

@@ -1100,9 +1100,8 @@ function nullConstNode() {
 function columnRef(column, table, schema, naming = identityNaming) {
   const fields = [];
   if (schema) {
-    const dbSchema = naming.toDatabase(schema);
-    validateIdentifier(dbSchema, "schema");
-    fields.push(stringNode(dbSchema));
+    validateIdentifier(schema, "schema");
+    fields.push(stringNode(schema));
   }
   if (table) {
     const dbTable = naming.toDatabase(table);
@@ -1133,9 +1132,8 @@ function rangeVar(table, alias, schema, naming = identityNaming) {
     relpersistence: "p"
   };
   if (schema) {
-    const dbSchema = naming.toDatabase(schema);
-    validateIdentifier(dbSchema, "schema");
-    rv.schemaname = dbSchema;
+    validateIdentifier(schema, "schema");
+    rv.schemaname = schema;
   }
   if (alias) {
     const dbAlias = naming.toDatabase(alias);
@@ -1334,7 +1332,8 @@ function insertStmt(options) {
     relpersistence: "p"
   };
   if (options.schema) {
-    relation.schemaname = naming.toDatabase(options.schema);
+    validateIdentifier(options.schema, "schema");
+    relation.schemaname = options.schema;
   }
   const stmt = {
     relation
@@ -1364,7 +1363,8 @@ function updateStmt(options) {
     relpersistence: "p"
   };
   if (options.schema) {
-    relation.schemaname = naming.toDatabase(options.schema);
+    validateIdentifier(options.schema, "schema");
+    relation.schemaname = options.schema;
   }
   const stmt = {
     relation,
@@ -1392,7 +1392,8 @@ function deleteStmt(options) {
     relpersistence: "p"
   };
   if (options.schema) {
-    relation.schemaname = naming.toDatabase(options.schema);
+    validateIdentifier(options.schema, "schema");
+    relation.schemaname = options.schema;
   }
   const stmt = {
     relation
@@ -4634,7 +4635,7 @@ function resolveColumnPgType(columnName, ctx) {
   const column = table.columns.find((c) => c.name === columnName);
   if (!column) return void 0;
   if (column.originalDbType) {
-    const targetSchema = ctx.schema !== void 0 ? ctx.naming.toDatabase(ctx.schema) : void 0;
+    const targetSchema = ctx.schema;
     const typeName = renderColumnDbType(column, targetSchema).trim();
     validateDbType(typeName);
     return dbTypeCastTarget(typeName);
@@ -12060,7 +12061,7 @@ function quoteRoleName(name) {
 function qualifyTableIdent(tableName, schemaName, naming) {
   const table = quoteIdent2(naming.toDatabase(tableName), "table");
   if (schemaName) {
-    return `${quoteIdent2(naming.toDatabase(schemaName), "schema")}.${table}`;
+    return `${quoteIdent2(schemaName, "schema")}.${table}`;
   }
   return table;
 }
@@ -12118,6 +12119,72 @@ function generateCommentsPhase(ctx) {
   return statements;
 }
 
+// src/check-constraint-name.ts
+var CheckConstraintNameCollisionError = class extends Error {
+  constructor(table, firstAuthoredName, secondAuthoredName, databaseName) {
+    super(
+      `CHECK constraint name collision on table "${table}": authored constraints "${firstAuthoredName}" and "${secondAuthoredName}" both resolve to physical name "${databaseName}". Rename one of the constraints.`
+    );
+    this.table = table;
+    this.firstAuthoredName = firstAuthoredName;
+    this.secondAuthoredName = secondAuthoredName;
+    this.databaseName = databaseName;
+    this.name = "CheckConstraintNameCollisionError";
+  }
+  table;
+  firstAuthoredName;
+  secondAuthoredName;
+  databaseName;
+};
+function getCheckConstraintDatabaseName(check, naming) {
+  return naming.toDatabase(check.name);
+}
+function assertNoCheckConstraintNameCollisions(table, naming) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const check of table.checkConstraints ?? []) {
+    const databaseName = getCheckConstraintDatabaseName(check, naming);
+    const previous = seen.get(databaseName);
+    if (previous !== void 0) {
+      throw new CheckConstraintNameCollisionError(
+        table.name,
+        previous,
+        check.name,
+        databaseName
+      );
+    }
+    seen.set(databaseName, check.name);
+  }
+}
+
+// src/check-expression.ts
+var CHECK_NOT_VALID_SUFFIX = /^(?<clause>\s*CHECK\s*\(.*\)(?:\s+NO\s+INHERIT)?)\s+NOT\s+VALID\s*$/isu;
+function toCheckConstraintClause(expression) {
+  const trimmed = stripNotValidSuffix(expression.trim()).trim();
+  if (/^CHECK\s*\(/iu.test(trimmed)) {
+    return trimmed;
+  }
+  return `CHECK (${trimmed})`;
+}
+function splitCheckConstraintState(check) {
+  return {
+    expression: toCheckConstraintClause(check.expression),
+    notValid: check.notValid !== void 0 ? check.notValid : hasNotValidSuffix(check.expression)
+  };
+}
+function renderCheckConstraintClause(check) {
+  const state = splitCheckConstraintState(check);
+  return state.notValid ? `${state.expression} NOT VALID` : state.expression;
+}
+function isCheckConstraintNotValid(check) {
+  return splitCheckConstraintState(check).notValid;
+}
+function stripNotValidSuffix(expression) {
+  return expression.replace(CHECK_NOT_VALID_SUFFIX, "$<clause>");
+}
+function hasNotValidSuffix(expression) {
+  return CHECK_NOT_VALID_SUFFIX.test(expression);
+}
+
 // src/ddl/phases/constraints.ts
 init_validate();
 function generateConstraintsPhase(ctx) {
@@ -12132,10 +12199,13 @@ function generateConstraintsPhase(ctx) {
   }
   if (sup(caps, caps?.supportsDDLCheckConstraints)) {
     for (const table of tables) {
+      assertNoCheckConstraintNameCollisions(table, naming);
       for (const check of table.checkConstraints ?? []) {
         const qualifiedTable = qualifyTableIdent(table.name, schemaName, naming);
-        const constraintName = quoteIdent2(check.name);
-        const expression = check.expression;
+        const constraintName = quoteIdent2(
+          getCheckConstraintDatabaseName(check, naming)
+        );
+        const expression = renderCheckConstraintClause(check);
         validateCheckExpression(expression, "check constraint expression");
         statements.push(
           `ALTER TABLE ${qualifiedTable} ADD CONSTRAINT ${constraintName} ${expression};`
@@ -12162,13 +12232,13 @@ function generateDropStatementsPhase(ctx) {
 
 // src/ddl/phases/enum-types.ts
 function generateEnumTypesPhase(ctx) {
-  const { schema, schemaName, naming, caps } = ctx;
+  const { schema, schemaName, caps } = ctx;
   if (!schema.enums || !sup(caps, caps?.supportsDDLEnumTypes)) {
     return [];
   }
   const statements = [];
   for (const [, enumDef] of schema.enums) {
-    const effectiveSchema = schemaName !== void 0 ? naming.toDatabase(schemaName) : enumDef.schema;
+    const effectiveSchema = schemaName !== void 0 ? schemaName : enumDef.schema;
     const enumName = effectiveSchema && effectiveSchema !== "public" && effectiveSchema !== "pg_catalog" ? `${quoteIdent2(effectiveSchema, "schema")}.${quoteIdent2(enumDef.name, "table")}` : quoteIdent2(enumDef.name, "table");
     const values = enumDef.values.map((v) => {
       validateEnumLabel(v, "enum value");
@@ -12191,12 +12261,36 @@ function generateExtensionsPhase(ctx) {
 }
 
 // src/ddl/schema-diff.ts
+import { validateSchemaIndexOptions } from "@dbsp/core";
 init_db_type();
 init_naming_plugin();
-import { validateSchemaIndexOptions } from "@dbsp/core";
+var ExpressionCanonicalizationUnavailableError = class extends Error {
+  constructor(surfaces) {
+    super(
+      `compareSchemata strict expression canonicalization was requested, but this pure compile-only path cannot ask PostgreSQL to canonicalise raw SQL expression surfaces. Use comparePgsqlDatabaseSchema() for live CHECK constraint canonicalization; index predicates and index expressions are not covered by the live canonicalizer. Omit requireExpressionCanonicalization for best-effort raw string comparison. Surfaces: ${surfaces.join(", ")}`
+    );
+    this.surfaces = surfaces;
+    this.name = "ExpressionCanonicalizationUnavailableError";
+  }
+  surfaces;
+};
 function compareSchemata(schema, db, options) {
+  const caps = options?.dialectCapabilities;
+  const sup2 = (flag) => !caps || flag === true;
+  const supportsCheckConstraints = sup2(caps?.supportsDDLCheckConstraints);
+  if (options?.requireExpressionCanonicalization) {
+    assertNoExpressionSurfaces(schema, db, {
+      includeCheckConstraints: supportsCheckConstraints
+    });
+  }
   const changes = [];
-  const plugin = options?.dbCasing !== void 0 ? getNamingPluginForDbCasing(options.dbCasing) : void 0;
+  const schemaNaming = options?.dbCasing !== void 0 ? getNamingPluginForDbCasing(options.dbCasing) : identityNaming;
+  if (supportsCheckConstraints) {
+    for (const table of schema.tables.values()) {
+      assertNoCheckConstraintNameCollisions(table, schemaNaming);
+    }
+  }
+  const plugin = options?.dbCasing !== void 0 ? schemaNaming : void 0;
   const schemaTables = plugin ? normalizeTableMap(schema.tables, plugin) : new Map(schema.tables);
   const dbTables = new Map(db.tables);
   const externalTables = new Set(
@@ -12204,8 +12298,6 @@ function compareSchemata(schema, db, options) {
       (name) => plugin ? plugin.toDatabase(name) : name
     )
   );
-  const caps = options?.dialectCapabilities;
-  const sup2 = (flag) => !caps || flag === true;
   if (sup2(caps?.supportsDDLEnumTypes)) {
     compareEnums(schema, db, changes);
   }
@@ -12244,7 +12336,7 @@ function compareSchemata(schema, db, options) {
           meta: { index: idx }
         });
       }
-      if (sup2(caps?.supportsDDLCheckConstraints)) {
+      if (supportsCheckConstraints) {
         for (const check of schemaTable.checkConstraints ?? []) {
           changes.push({
             kind: "add_check_constraint",
@@ -12281,7 +12373,7 @@ function compareSchemata(schema, db, options) {
     comparePrimaryKeys(schemaTable, dbTable, changes);
     compareForeignKeys(schemaTable, dbTable, changes);
     compareIndexes(schemaTable, dbTable, changes);
-    if (sup2(caps?.supportsDDLCheckConstraints)) {
+    if (supportsCheckConstraints) {
       compareCheckConstraints(schemaTable, dbTable, changes);
     }
     if (sup2(caps?.supportsDDLComments)) {
@@ -12308,6 +12400,47 @@ function compareSchemata(schema, db, options) {
     summary: buildSummary(changes)
   };
 }
+function assertNoExpressionSurfaces(schema, db, options) {
+  const surfaces = [
+    ...collectExpressionSurfaces("schema", schema, options),
+    ...collectExpressionSurfaces("database", db, options)
+  ];
+  if (surfaces.length > 0) {
+    throw new ExpressionCanonicalizationUnavailableError(surfaces);
+  }
+}
+function collectExpressionSurfaces(label, model, options) {
+  const includeCheckConstraints = options?.includeCheckConstraints ?? true;
+  const includeIndexPredicates = options?.includeIndexPredicates ?? true;
+  const includeIndexExpressions = options?.includeIndexExpressions ?? true;
+  const surfaces = [];
+  for (const table of model.tables.values()) {
+    if (includeCheckConstraints) {
+      for (const check of table.checkConstraints ?? []) {
+        surfaces.push(
+          `${label}.${table.name}.CHECK(${formatConstraintName(check)})`
+        );
+      }
+    }
+    for (const index of table.indexes) {
+      const indexName = index.name ?? `<unnamed:${index.columns.join(",")}>`;
+      if (includeIndexPredicates && index.where !== void 0) {
+        surfaces.push(`${label}.${table.name}.INDEX(${indexName}).WHERE`);
+      }
+      if (includeIndexExpressions) {
+        for (let i = 0; i < (index.expressions?.length ?? 0); i++) {
+          surfaces.push(
+            `${label}.${table.name}.INDEX(${indexName}).EXPRESSION[${i}]`
+          );
+        }
+      }
+    }
+  }
+  return surfaces;
+}
+function formatConstraintName(check) {
+  return check.name || "<unnamed>";
+}
 function normalizeTableMap(tables, plugin) {
   const result = /* @__PURE__ */ new Map();
   for (const [_key, table] of tables) {
@@ -12351,6 +12484,12 @@ function normalizeTable(table, plugin) {
         )
       } : {}
     })),
+    ...table.checkConstraints !== void 0 ? {
+      checkConstraints: table.checkConstraints.map((check) => ({
+        ...check,
+        name: getCheckConstraintDatabaseName(check, plugin)
+      }))
+    } : {},
     ...table.partition ? {
       partition: {
         strategy: table.partition.strategy,
@@ -12855,9 +12994,14 @@ function comparePartitions(schema, db, changes) {
 function compareCheckConstraints(schema, db, changes) {
   const schemaChecks = schema.checkConstraints ?? [];
   const dbChecks = db.checkConstraints ?? [];
-  const schemaMap = new Map(schemaChecks.map((c) => [c.name, c]));
-  const dbMap = new Map(dbChecks.map((c) => [c.name, c]));
-  for (const [name, check] of schemaMap) {
+  const schemaMap = new Map(
+    schemaChecks.map((check) => [check.name, normalizeCheckForDiff(check)])
+  );
+  const dbMap = new Map(
+    dbChecks.map((check) => [check.name, normalizeCheckForDiff(check)])
+  );
+  for (const [name, checkEntry] of schemaMap) {
+    const { check } = checkEntry;
     if (!dbMap.has(name)) {
       changes.push({
         kind: "add_check_constraint",
@@ -12867,25 +13011,25 @@ function compareCheckConstraints(schema, db, changes) {
         meta: { check }
       });
     } else {
-      const dbCheck = dbMap.get(name);
-      if (check.expression !== dbCheck.expression) {
+      const dbCheckEntry = dbMap.get(name);
+      if (checkEntry.expression !== dbCheckEntry.expression) {
         changes.push({
           kind: "drop_check_constraint",
           table: schema.name,
           destructive: true,
           details: `Drop CHECK constraint "${name}" (expression changed)`,
-          meta: { check: dbCheck }
+          meta: { check: dbCheckEntry.check }
         });
         changes.push({
           kind: "add_check_constraint",
           table: schema.name,
-          destructive: false,
+          destructive: true,
           details: `Add CHECK constraint "${name}" ${check.expression}`,
           meta: { check }
         });
       } else {
-        const dbNotValid = dbCheck.notValid ?? false;
-        const schemaNotValid = check.notValid ?? false;
+        const dbNotValid = dbCheckEntry.notValid;
+        const schemaNotValid = checkEntry.notValid;
         if (dbNotValid && !schemaNotValid) {
           changes.push({
             kind: "validate_constraint",
@@ -12894,22 +13038,45 @@ function compareCheckConstraints(schema, db, changes) {
             details: `Validate CHECK constraint "${name}"`,
             meta: { check }
           });
+        } else if (!dbNotValid && schemaNotValid) {
+          changes.push({
+            kind: "drop_check_constraint",
+            table: schema.name,
+            destructive: true,
+            details: `Drop CHECK constraint "${name}" to re-add NOT VALID`,
+            meta: { check: dbCheckEntry.check }
+          });
+          changes.push({
+            kind: "add_check_constraint",
+            table: schema.name,
+            destructive: true,
+            details: `Re-add CHECK constraint "${name}" ${check.expression} NOT VALID`,
+            meta: { check }
+          });
         }
       }
     }
   }
-  for (const [name, check] of dbMap) {
+  for (const [name, checkEntry] of dbMap) {
     if (!schemaMap.has(name)) {
       changes.push({
         kind: "drop_check_constraint",
         table: schema.name,
         destructive: true,
         details: `Drop CHECK constraint "${name}"`,
-        meta: { check }
+        meta: { check: checkEntry.check }
       });
     }
   }
 }
+function normalizeCheckForDiff(check) {
+  const state = splitCheckConstraintState(check);
+  return {
+    check,
+    expression: state.expression,
+    notValid: state.notValid
+  };
+}
 function compareEnums(schema, db, changes) {
   const schemaEnums = schema.enums ?? /* @__PURE__ */ new Map();
   const dbEnums = db.enums ?? /* @__PURE__ */ new Map();
@@ -13147,6 +13314,7 @@ function buildSummary(changes) {
         constraints.dropped++;
         break;
       case "alter_foreign_key":
+      case "validate_constraint":
         constraints.altered++;
         break;
       case "create_index":
@@ -13509,8 +13677,8 @@ function failSafeUnknownDownChange(kind) {
     destructive: true
   };
 }
-function isChangeSupported(kind, caps) {
-  switch (kind) {
+function isChangeSupported(change, caps) {
+  switch (change.kind) {
     case "create_enum":
     case "drop_enum":
     case "alter_enum_add_value":
@@ -13525,6 +13693,8 @@ function isChangeSupported(kind, caps) {
     case "add_check_constraint":
     case "drop_check_constraint":
       return caps.supportsDDLCheckConstraints === true;
+    case "validate_constraint":
+      return isValidateConstraintSupported(change, caps);
     case "add_comment":
     case "drop_comment":
       return caps.supportsDDLComments === true;
@@ -13541,11 +13711,20 @@ function isChangeSupported(kind, caps) {
       return true;
   }
 }
+function isValidateConstraintSupported(change, caps) {
+  if (change.meta?.check !== void 0) {
+    return caps.supportsDDLCheckConstraints === true;
+  }
+  if (change.meta?.fk !== void 0) {
+    return caps.supportsDDLForeignKeys !== false;
+  }
+  return true;
+}
 function changesAppliedByUp(diff, options) {
   const includeDestructive = options?.includeDestructive ?? true;
   const filteredChanges = includeDestructive ? diff.changes : diff.changes.filter((c) => !c.destructive);
   const caps = options?.dialectCapabilities;
-  return caps ? filteredChanges.filter((c) => isChangeSupported(c.kind, caps)) : filteredChanges;
+  return caps ? filteredChanges.filter((c) => isChangeSupported(c, caps)) : filteredChanges;
 }
 function generateMigrationSQL(diff, options) {
   const schemaName = options?.schemaName;
@@ -13814,11 +13993,10 @@ function upDropIndex(change, schemaName) {
 function upAddCheckConstraint(change, schemaName) {
   const check = change.meta?.check;
   if (!check) return void 0;
-  const expression = check.expression;
-  const notValid = check.notValid ? " NOT VALID" : "";
+  const expression = renderCheckConstraintClause(check);
   validateCheckExpression(expression, "migration check constraint expression");
   return buildDoBlock(
-    "BEGIN ALTER TABLE " + qualifyTable(change.table, schemaName) + " ADD CONSTRAINT " + quoteIdent2(check.name, "alias") + " " + expression + notValid + "; EXCEPTION WHEN duplicate_object THEN NULL; END"
+    "BEGIN ALTER TABLE " + qualifyTable(change.table, schemaName) + " ADD CONSTRAINT " + quoteIdent2(check.name, "alias") + " " + expression + "; EXCEPTION WHEN duplicate_object THEN NULL; END"
   );
 }
 function upValidateConstraint(change, schemaName) {
@@ -14215,7 +14393,7 @@ ${add}`, destructive: false };
     case "drop_check_constraint": {
       const check = change.meta?.check;
       if (!check) return { sql: void 0, destructive: true };
-      const expression = check.expression;
+      const expression = renderCheckConstraintClause(check);
       validateCheckExpression(expression, "migration check constraint (down)");
       return {
         sql: buildDoBlock(
@@ -14567,13 +14745,13 @@ function formatDefault(value) {
 
 // src/ddl/phases/sequences.ts
 function generateSequencesPhase(ctx) {
-  const { schema, schemaName, naming, caps } = ctx;
+  const { schema, schemaName, caps } = ctx;
   if (!schema.sequences || !sup(caps, caps?.supportsDDLSequences)) {
     return [];
   }
   const statements = [];
   for (const [, seq] of schema.sequences) {
-    const seqName = schemaName ? `${quoteIdent2(naming.toDatabase(schemaName), "schema")}.${quoteIdent2(seq.name, "table")}` : quoteIdent2(seq.name, "table");
+    const seqName = schemaName ? `${quoteIdent2(schemaName, "schema")}.${quoteIdent2(seq.name, "table")}` : quoteIdent2(seq.name, "table");
     statements.push(buildSequenceClause("CREATE SEQUENCE", seqName, seq));
   }
   return statements;
@@ -14643,11 +14821,10 @@ function quoteIdentifier(name) {
   validateIdentifier(name, "alias");
   return `"${name.replace(/"/g, '""')}"`;
 }
-function qualifyTable2(tableName, schemaName, naming, transformSchema = true) {
+function qualifyTable2(tableName, schemaName, naming) {
   const table = quoteIdentifier(naming.toDatabase(tableName));
   if (schemaName) {
-    const schema = transformSchema ? naming.toDatabase(schemaName) : schemaName;
-    return `${quoteIdentifier(schema)}.${table}`;
+    return `${quoteIdentifier(schemaName)}.${table}`;
   }
   return table;
 }
@@ -14657,10 +14834,9 @@ function generateDropTable(tableName, schemaName, naming) {
 }
 function generateCreateTable(table, schemaName, naming) {
   const qualifiedTable = qualifyTable2(table.name, schemaName, naming);
-  const targetSchema = schemaName ? naming.toDatabase(schemaName) : void 0;
   const elements = [];
   for (const col of table.columns) {
-    elements.push(generateColumnDef(col, naming, targetSchema));
+    elements.push(generateColumnDef(col, naming, schemaName));
   }
   if (table.primaryKey !== void 0) {
     const rawPk = table.primaryKey;
@@ -14719,7 +14895,7 @@ function generateAlterTableAddFK(tableName, fk, schemaName, naming) {
     `fk_${tableName}_${fk.columns.join("_")}`
   );
   const fkCols = fk.columns.map((col) => quoteIdentifier(naming.toDatabase(col))).join(", ");
-  const refTable = fk.references.schema !== void 0 ? qualifyTable2(fk.references.table, fk.references.schema, naming, false) : qualifyTable2(fk.references.table, schemaName, naming);
+  const refTable = fk.references.schema !== void 0 ? qualifyTable2(fk.references.table, fk.references.schema, naming) : qualifyTable2(fk.references.table, schemaName, naming);
   const refCols = fk.references.columns.map((col) => quoteIdentifier(naming.toDatabase(col))).join(", ");
   const onDelete = fk.onDelete ? ` ON DELETE ${mapOnDeleteAction(fk.onDelete)}` : "";
   const onUpdate = fk.onUpdate ? ` ON UPDATE ${mapOnDeleteAction(fk.onUpdate)}` : "";
@@ -14820,6 +14996,494 @@ function generateCreatePolicy(tableName, policy, schemaName, naming) {
   return `CREATE POLICY ${policyName} ON ${qualifiedTable}${forClause}${asClause}${toClause}${usingClause}${withCheckClause};`;
 }
 
+// src/expression-canonicalizer.ts
+import { randomUUID } from "crypto";
+import { ModelIRImpl } from "@dbsp/core";
+init_naming_plugin();
+init_validate();
+var CheckConstraintCanonicalizationError = class extends Error {
+  constructor(table, constraints, cause) {
+    super(
+      `Could not canonicalize CHECK constraint expression(s) for table "${table}" (${constraints.map((name) => `"${name}"`).join(", ")}), and strict expression canonicalization was requested: ${errorMessage(cause)}`
+    );
+    this.table = table;
+    this.constraints = constraints;
+    this.cause = cause;
+    this.name = "CheckConstraintCanonicalizationError";
+  }
+  table;
+  constraints;
+  cause;
+};
+async function canonicalizeCheckConstraints(adapter, desired, dbModel, options) {
+  const targets = collectCheckConstraintTargets(desired, dbModel, options);
+  if (targets.length === 0) {
+    return desired;
+  }
+  const canonicalChecksByTable = /* @__PURE__ */ new Map();
+  const names = createCheckCanonicalizationNameScope();
+  let workError;
+  try {
+    try {
+      await createMissingDesiredEnumTypes(adapter, desired, dbModel, options);
+      for (let i = 0; i < targets.length; i++) {
+        const target = targets[i];
+        const canonicalChecks = await canonicalizeTableChecksBestEffort(
+          adapter,
+          target,
+          i,
+          options,
+          names
+        );
+        if (canonicalChecks !== void 0) {
+          canonicalChecksByTable.set(target.modelKey, canonicalChecks);
+        }
+      }
+    } catch (error) {
+      workError = error;
+    }
+  } catch (error) {
+    workError = error;
+  }
+  if (workError !== void 0) {
+    if (options?.requireCanonicalization) {
+      throw workError;
+    }
+    for (const target of targets) {
+      if (!canonicalChecksByTable.has(target.modelKey)) {
+        reportCanonicalizationFailure(target, workError, options);
+      }
+    }
+  }
+  return cloneModelWithCanonicalChecks(desired, canonicalChecksByTable);
+}
+function collectCheckConstraintTargets(desired, dbModel, options) {
+  const plugin = options?.dbCasing !== void 0 ? getNamingPluginForDbCasing(options.dbCasing) : identityNaming;
+  const targets = [];
+  for (const [modelKey, table] of desired.tables) {
+    const checks = table.checkConstraints ?? [];
+    if (checks.length === 0) continue;
+    const dbTableName = plugin.toDatabase(table.name);
+    const dbTable = dbModel.tables.get(dbTableName);
+    targets.push({
+      modelKey,
+      modelTable: table,
+      ...dbTable !== void 0 ? { dbTable } : {},
+      dbTableName,
+      checks,
+      dbCheckNames: checks.map(
+        (check) => getCheckConstraintDatabaseName(check, plugin)
+      )
+    });
+  }
+  return targets;
+}
+async function canonicalizeTableChecksBestEffort(adapter, target, targetIndex, options, names) {
+  try {
+    return await adapter.transaction(
+      (tx) => canonicalizeTableChecks(tx, target, targetIndex, options, names)
+    );
+  } catch (error) {
+    if (error instanceof CheckConstraintCanonicalizationError) {
+      throw error;
+    }
+    if (options?.requireCanonicalization) {
+      throw new CheckConstraintCanonicalizationError(
+        target.dbTableName,
+        target.dbCheckNames,
+        error
+      );
+    }
+    reportCanonicalizationFailure(target, error, options);
+    return void 0;
+  }
+}
+async function canonicalizeTableChecks(adapter, target, targetIndex, options, names) {
+  const tempTableName = `${names.tempPrefix}_${targetIndex}`;
+  const tempTable = quoteIdent2(tempTableName, "table");
+  const naming = namingForOptions(options);
+  const targetSchema = options?.schemaName;
+  const dbColumnsByName = new Map(
+    (target.dbTable?.columns ?? []).map((column) => [column.name, column])
+  );
+  const columnDefs = target.modelTable.columns.map(
+    (column) => generateScratchColumnDef(column, dbColumnsByName, naming, targetSchema)
+  );
+  await adapter.executeRaw(
+    `CREATE TEMP TABLE ${tempTable} (${columnDefs.join(", ")}) ON COMMIT DROP`
+  );
+  const tempConstraintNamesByIndex = /* @__PURE__ */ new Map();
+  const canonicalChecks = [...target.checks];
+  for (let i = 0; i < target.checks.length; i++) {
+    const check = target.checks[i];
+    const tempConstraintName = `${names.tempPrefix}_${targetIndex}_${i}`;
+    try {
+      await adapter.transaction(async (tx) => {
+        const expression = renderCheckConstraintClause(check);
+        validateCheckExpression(expression, "canonicalized check constraint");
+        await tx.executeRaw(
+          `ALTER TABLE ${tempTable} ADD CONSTRAINT ${quoteIdent2(tempConstraintName, "alias")} ${expression}`
+        );
+      });
+      tempConstraintNamesByIndex.set(i, tempConstraintName);
+    } catch (error) {
+      if (options?.requireCanonicalization) {
+        throw new CheckConstraintCanonicalizationError(
+          target.dbTableName,
+          [target.dbCheckNames[i]],
+          error
+        );
+      }
+      reportConstraintCanonicalizationFailure(target, i, error, options);
+    }
+  }
+  const tempConstraintNames = [...tempConstraintNamesByIndex.values()];
+  if (tempConstraintNames.length === 0) {
+    return canonicalChecks;
+  }
+  const rows = await adapter.executeRaw(
+    `SELECT conname AS name,
+		        pg_get_constraintdef(oid, false) AS expression
+		   FROM pg_constraint
+		  WHERE conrelid = $1::regclass
+		    AND conname = ANY($2::text[])
+		  ORDER BY array_position($2::text[], conname)`,
+    [tempTableName, tempConstraintNames]
+  );
+  const canonicalByTempName = new Map(
+    rows.map((row) => [row.name, stripNotValidSuffix(row.expression)])
+  );
+  for (const [i, tempConstraintName] of tempConstraintNamesByIndex) {
+    const check = target.checks[i];
+    const expression = canonicalByTempName.get(tempConstraintName);
+    if (expression === void 0) {
+      const error = new Error(
+        `PostgreSQL did not return canonical CHECK expression for "${target.modelTable.name}" constraint "${check.name}"`
+      );
+      if (options?.requireCanonicalization) {
+        throw new CheckConstraintCanonicalizationError(
+          target.dbTableName,
+          [target.dbCheckNames[i]],
+          error
+        );
+      }
+      reportConstraintCanonicalizationFailure(target, i, error, options);
+      continue;
+    }
+    const notValid = isCheckConstraintNotValid(check);
+    canonicalChecks[i] = {
+      ...check,
+      expression,
+      ...notValid ? { notValid: true } : {}
+    };
+  }
+  return canonicalChecks;
+}
+function generateScratchColumnDef(column, dbColumnsByName, naming, targetSchema) {
+  const dbColumn = dbColumnsByName.get(naming.toDatabase(column.name));
+  const typeColumn = !column.originalDbType?.trim() && dbColumn?.originalDbType?.trim() && column.type === dbColumn.type ? dbColumn : column;
+  const scratchColumn = typeColumn.autoIncrement === true ? { ...typeColumn, autoIncrement: false } : typeColumn;
+  return `${quoteIdent2(naming.toDatabase(column.name), "column")} ${mapColumnType(scratchColumn, targetSchema)}`;
+}
+async function createMissingDesiredEnumTypes(adapter, desired, dbModel, options) {
+  const missingEnums = missingDesiredEnums(desired, dbModel);
+  if (missingEnums.size === 0) return;
+  const naming = namingForOptions(options);
+  const enumModel = new ModelIRImpl(/* @__PURE__ */ new Map(), /* @__PURE__ */ new Map(), missingEnums);
+  const phaseContext = {
+    schema: enumModel,
+    tables: [],
+    schemaName: options?.schemaName,
+    naming,
+    caps: void 0,
+    fkAutoIndex: false,
+    includeDropStatements: false
+  };
+  const statements = generateEnumTypesPhase(phaseContext);
+  for (const statement of statements) {
+    try {
+      await adapter.transaction(async (tx) => {
+        await tx.executeRaw(statement);
+      });
+    } catch {
+    }
+  }
+}
+function createCheckCanonicalizationNameScope() {
+  const callId = randomUUID().replace(/-/gu, "").slice(0, 12);
+  return {
+    tempPrefix: `_dbsp_check_canon_${callId}`
+  };
+}
+function missingDesiredEnums(desired, dbModel) {
+  const desiredEnums = desired.enums ?? /* @__PURE__ */ new Map();
+  const dbEnums = dbModel.enums ?? /* @__PURE__ */ new Map();
+  const missing = /* @__PURE__ */ new Map();
+  for (const [name, enumDef] of desiredEnums) {
+    if (!dbEnums.has(name)) {
+      missing.set(name, enumDef);
+    }
+  }
+  return missing;
+}
+function namingForOptions(options) {
+  return options?.dbCasing !== void 0 ? getNamingPluginForDbCasing(options.dbCasing) : identityNaming;
+}
+function reportCanonicalizationFailure(target, cause, options) {
+  for (let i = 0; i < target.checks.length; i++) {
+    reportConstraintCanonicalizationFailure(target, i, cause, options);
+  }
+}
+function reportConstraintCanonicalizationFailure(target, checkIndex, cause, options) {
+  const dbCheckName = target.dbCheckNames[checkIndex];
+  const message = `Could not canonicalize CHECK constraint "${target.dbTableName}"."${dbCheckName}" with PostgreSQL; falling back to best-effort raw string comparison. Reason: ${errorMessage(cause)}`;
+  const warning = {
+    table: target.dbTableName,
+    constraint: dbCheckName,
+    message,
+    cause
+  };
+  if (options?.onWarning) {
+    options.onWarning(warning);
+  } else {
+    console.warn(`Warning: ${message}`);
+  }
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function cloneModelWithCanonicalChecks(model, canonicalChecksByTable) {
+  const tables = /* @__PURE__ */ new Map();
+  for (const [key, table] of model.tables) {
+    const checks = canonicalChecksByTable.get(key);
+    tables.set(
+      key,
+      checks === void 0 ? table : {
+        ...table,
+        checkConstraints: checks
+      }
+    );
+  }
+  return new ModelIRImpl(
+    tables,
+    new Map(model.relations),
+    model.enums === void 0 ? void 0 : new Map(model.enums),
+    model.extensions,
+    model.sequences === void 0 ? void 0 : new Map(model.sequences),
+    model.externalTables
+  );
+}
+
+// src/ddl/live-diff.ts
+var NonConvergentSchemaDiffError = class extends Error {
+  constructor(table, constraint, desiredExpression, databaseExpression) {
+    super(
+      `Non-convergent CHECK constraint diff for "${table}"."${constraint}": the same expression drift was reported after applying the previous diff. Desired expression: ${desiredExpression}. Database expression: ${databaseExpression}.`
+    );
+    this.table = table;
+    this.constraint = constraint;
+    this.desiredExpression = desiredExpression;
+    this.databaseExpression = databaseExpression;
+    this.name = "NonConvergentSchemaDiffError";
+  }
+  table;
+  constraint;
+  desiredExpression;
+  databaseExpression;
+};
+var CheckConstraintNewEnumValueError = class extends Error {
+  constructor(table, constraint, addedEnumValues) {
+    const candidates = addedEnumValues.map(({ enumName, value }) => `"${value}" (enum "${enumName}")`).join(", ");
+    super(
+      `PostgreSQL could not canonicalise CHECK constraint "${table}"."${constraint}", and this migration also adds enum value(s): ${candidates}. PostgreSQL cannot use an enum value in the transaction that adds it, and dbsp applies each migration in one transaction, so this constraint cannot be proven applicable. Apply the enum change on its own first, then add or update the constraint.`
+    );
+    this.table = table;
+    this.constraint = constraint;
+    this.addedEnumValues = addedEnumValues;
+    this.name = "CheckConstraintNewEnumValueError";
+  }
+  table;
+  constraint;
+  addedEnumValues;
+};
+async function comparePgsqlDatabaseSchema(adapter, desired, options) {
+  const dbModel = await adapter.introspect(toIntrospectionOptions(options));
+  const compareCheckConstraints2 = supportsDDLCheckConstraints(options);
+  const useCanonicalizer = compareCheckConstraints2 && (options?.canonicalizeExpressions ?? true);
+  const rawCheckExpressionSurfaces = /* @__PURE__ */ new Set();
+  const desiredForCompare = useCanonicalizer ? await adapter.withScratchScope(
+    (scratch) => canonicalizeCheckConstraints(
+      scratch,
+      desired,
+      dbModel,
+      toCanonicalizerOptions(options, rawCheckExpressionSurfaces)
+    )
+  ) : desired;
+  if (options?.requireExpressionCanonicalization && (useCanonicalizer || !compareCheckConstraints2)) {
+    assertNoUncanonicalizedLiveExpressionSurfaces(desiredForCompare, dbModel);
+  }
+  const diff = compareSchemata(
+    desiredForCompare,
+    dbModel,
+    toCompareOptions(options, {
+      delegateExpressionCanonicalization: options?.requireExpressionCanonicalization === true && !useCanonicalizer && compareCheckConstraints2
+    })
+  );
+  if (useCanonicalizer && rawCheckExpressionSurfaces.size > 0) {
+    assertNoCheckFallbackUsesAddedEnumValue(diff, rawCheckExpressionSurfaces);
+  }
+  if (options?.previouslyAppliedDiff !== void 0) {
+    if (!useCanonicalizer) {
+      assertNoRepeatedExpressionSurfaceDrift(
+        options.previouslyAppliedDiff,
+        diff
+      );
+    } else if (rawCheckExpressionSurfaces.size > 0) {
+      assertNoRepeatedExpressionSurfaceDrift(
+        options.previouslyAppliedDiff,
+        diff,
+        rawCheckExpressionSurfaces
+      );
+    }
+  }
+  return diff;
+}
+function assertNoUncanonicalizedLiveExpressionSurfaces(desired, dbModel) {
+  const surfaces = [
+    ...collectExpressionSurfaces("schema", desired, {
+      includeCheckConstraints: false
+    }),
+    ...collectExpressionSurfaces("database", dbModel, {
+      includeCheckConstraints: false
+    })
+  ];
+  if (surfaces.length > 0) {
+    throw new ExpressionCanonicalizationUnavailableError(surfaces);
+  }
+}
+function assertNoRepeatedExpressionSurfaceDrift(previouslyAppliedDiff, currentDiff, rawCheckExpressionSurfaces) {
+  const previousDrifts = collectCheckExpressionDrifts(previouslyAppliedDiff);
+  if (previousDrifts.size === 0) return;
+  for (const [key, current] of collectCheckExpressionDrifts(currentDiff)) {
+    if (rawCheckExpressionSurfaces !== void 0 && !rawCheckExpressionSurfaces.has(key)) {
+      continue;
+    }
+    const previous = previousDrifts.get(key);
+    if (previous !== void 0 && previous.desiredExpression === current.desiredExpression && previous.databaseExpression === current.databaseExpression) {
+      throw new NonConvergentSchemaDiffError(
+        current.table,
+        current.constraint,
+        current.desiredExpression,
+        current.databaseExpression
+      );
+    }
+  }
+}
+function collectCheckExpressionDrifts(diff) {
+  const dropped = /* @__PURE__ */ new Map();
+  const drifts = /* @__PURE__ */ new Map();
+  for (const change of diff.changes) {
+    if (change.kind === "drop_check_constraint") {
+      const check = checkFromChange(change);
+      if (check === void 0) continue;
+      dropped.set(driftKey(change.table, check.name), check.expression);
+      continue;
+    }
+    if (change.kind === "add_check_constraint") {
+      const check = checkFromChange(change);
+      if (check === void 0) continue;
+      const key = driftKey(change.table, check.name);
+      const databaseExpression = dropped.get(key);
+      if (databaseExpression === void 0) continue;
+      drifts.set(key, {
+        table: change.table,
+        constraint: check.name,
+        desiredExpression: check.expression,
+        databaseExpression
+      });
+    }
+  }
+  return drifts;
+}
+function checkFromChange(change) {
+  const check = change.meta?.check;
+  if (check === void 0 || typeof check.name !== "string" || typeof check.expression !== "string") {
+    return void 0;
+  }
+  return check;
+}
+function driftKey(table, constraint) {
+  return JSON.stringify([table, constraint]);
+}
+function assertNoCheckFallbackUsesAddedEnumValue(diff, rawCheckExpressionSurfaces) {
+  const addedEnumValues = collectAddedEnumValues(diff);
+  if (addedEnumValues.length === 0) return;
+  for (const change of diff.changes) {
+    if (change.kind !== "add_check_constraint") continue;
+    const check = checkFromChange(change);
+    if (check === void 0) continue;
+    if (!rawCheckExpressionSurfaces.has(driftKey(change.table, check.name))) {
+      continue;
+    }
+    throw new CheckConstraintNewEnumValueError(
+      change.table,
+      check.name,
+      addedEnumValues
+    );
+  }
+}
+function collectAddedEnumValues(diff) {
+  const added = [];
+  for (const change of diff.changes) {
+    if (change.kind !== "alter_enum_add_value") continue;
+    const enumDef = change.meta?.enum;
+    const value = change.meta?.value;
+    if (enumDef === void 0 || typeof value !== "string") continue;
+    added.push({ enumName: formatEnumName(enumDef), value });
+  }
+  return added;
+}
+function formatEnumName(enumDef) {
+  return enumDef.schema !== void 0 ? `${enumDef.schema}.${enumDef.name}` : enumDef.name;
+}
+function toIntrospectionOptions(options) {
+  return {
+    ...options?.schema !== void 0 ? { schema: options.schema } : {}
+  };
+}
+function supportsDDLCheckConstraints(options) {
+  const caps = options?.dialectCapabilities;
+  return caps === void 0 || caps.supportsDDLCheckConstraints === true;
+}
+function toCanonicalizerOptions(options, rawCheckExpressionSurfaces) {
+  return {
+    ...options?.schema !== void 0 ? { schemaName: options.schema } : {},
+    ...options?.dbCasing !== void 0 ? { dbCasing: options.dbCasing } : {},
+    ...options?.requireExpressionCanonicalization !== void 0 ? { requireCanonicalization: options.requireExpressionCanonicalization } : {},
+    onWarning: (warning) => {
+      recordRawCheckExpressionSurface(rawCheckExpressionSurfaces, warning);
+      if (options?.onWarning !== void 0) {
+        options.onWarning(warning.message);
+      } else {
+        console.warn(`Warning: ${warning.message}`);
+      }
+    }
+  };
+}
+function recordRawCheckExpressionSurface(rawCheckExpressionSurfaces, warning) {
+  rawCheckExpressionSurfaces.add(driftKey(warning.table, warning.constraint));
+}
+function toCompareOptions(options, strictness) {
+  return {
+    ...options?.dbCasing !== void 0 ? { dbCasing: options.dbCasing } : {},
+    ...options?.dialectCapabilities !== void 0 ? { dialectCapabilities: options.dialectCapabilities } : {},
+    ...options?.ignoreUnmanagedExtensions !== void 0 ? { ignoreUnmanagedExtensions: options.ignoreUnmanagedExtensions } : {},
+    ...strictness.delegateExpressionCanonicalization ? {
+      requireExpressionCanonicalization: true
+    } : {}
+  };
+}
+
 // src/ddl/migration-file.ts
 function generateMigrationFile(diff, options) {
   const upStatements = generateMigrationSQL(diff, options);
@@ -15163,9 +15827,12 @@ function vectorDims(column) {
 
 // src/introspection.ts
 init_assert_field();
-init_db_type();
-import { ModelIRImpl } from "@dbsp/core";
+import { ModelIRImpl as ModelIRImpl2 } from "@dbsp/core";
 import { buildRelationKeyFields } from "@dbsp/types";
+init_db_type();
+function isCheckedOutClient(connection) {
+  return typeof connection === "object" && connection !== null && "release" in connection && typeof connection.release === "function";
+}
 function parseExpressionsList(raw) {
   const results = [];
   let depth = 0;
@@ -15187,34 +15854,22 @@ function parseExpressionsList(raw) {
   return results;
 }
 async function queryAllCatalogs(pool, schema) {
-  const [
-    columnsResult,
-    pksResult,
-    fksResult,
-    indexesResult,
-    uniqueColumnsResult,
-    enumsResult,
-    commentsResult,
-    checksResult,
-    partitionsResult,
-    extensionsResult,
-    sequencesResult,
-    rlsResult,
-    policiesResult,
-    formattedColumnTypesResult
-  ] = await Promise.all([
-    // 1. Columns (including identity and collation)
-    pool.query(
-      `SELECT table_name, column_name, data_type, udt_name, is_nullable, column_default,
+  const catalogQueries = [
+    () => (
+      // 1. Columns (including identity and collation)
+      pool.query(
+        `SELECT table_name, column_name, data_type, udt_name, is_nullable, column_default,
 			        collation_name, is_identity, identity_generation
 			 FROM information_schema.columns
 			 WHERE table_schema = $1
 			 ORDER BY table_name, ordinal_position`,
-      [schema]
+        [schema]
+      )
     ),
-    // 2. Primary keys
-    pool.query(
-      `SELECT tc.table_name, kcu.column_name
+    () => (
+      // 2. Primary keys
+      pool.query(
+        `SELECT tc.table_name, kcu.column_name
 			 FROM information_schema.table_constraints tc
 			 JOIN information_schema.key_column_usage kcu
 			   ON tc.constraint_name = kcu.constraint_name
@@ -15222,11 +15877,13 @@ async function queryAllCatalogs(pool, schema) {
 			 WHERE tc.constraint_type = 'PRIMARY KEY'
 			   AND tc.table_schema = $1
 			 ORDER BY tc.table_name, kcu.ordinal_position`,
-      [schema]
+        [schema]
+      )
     ),
-    // 3. Foreign keys
-    pool.query(
-      `SELECT
+    () => (
+      // 3. Foreign keys
+      pool.query(
+        `SELECT
 			   c.conname AS constraint_name,
 			   source_rel.relname AS source_table,
 			   source_attr.attname AS source_column,
@@ -15265,18 +15922,20 @@ async function queryAllCatalogs(pool, schema) {
 			   AND c.conparentid = 0
 			   AND source_ns.nspname = $1
 			 ORDER BY c.conname, cols.ord`,
-      [schema]
+        [schema]
+      )
     ),
-    // 4. Indexes (excluding PK-backing indexes and unique-constraint-backing indexes).
-    // Unique constraints created via col.unique / UNIQUE keyword in DDL produce an implicit
-    // backing index that is NOT a user-defined index — it is tracked via col.unique on the
-    // ColumnIR instead. Including it here would cause spurious drop_index diffs on roundtrip.
-    // Enhanced to capture:
-    //   - INCLUDE columns (PG11+): indkey positions > indnkeyatts
-    //   - Expression index entries: attnum = 0 in indkey → pg_get_expr(indexprs)
-    //   - Per-column operator classes: pg_opclass join on indclass, non-default only
-    pool.query(
-      `SELECT
+    () => (
+      // 4. Indexes (excluding PK-backing indexes and unique-constraint-backing indexes).
+      // Unique constraints created via col.unique / UNIQUE keyword in DDL produce an implicit
+      // backing index that is NOT a user-defined index — it is tracked via col.unique on the
+      // ColumnIR instead. Including it here would cause spurious drop_index diffs on roundtrip.
+      // Enhanced to capture:
+      //   - INCLUDE columns (PG11+): indkey positions > indnkeyatts
+      //   - Expression index entries: attnum = 0 in indkey → pg_get_expr(indexprs)
+      //   - Per-column operator classes: pg_opclass join on indclass, non-default only
+      pool.query(
+        `SELECT
 			   i.relname AS index_name,
 			   t.relname AS table_name,
 			   -- Key columns (attnum != 0 means real column, within key positions)
@@ -15326,11 +15985,13 @@ async function queryAllCatalogs(pool, schema) {
 			 GROUP BY i.relname, t.relname, ix.indisunique, am.amname,
 			          ix.indpred, ix.indrelid, ix.indexprs, i.reloptions
 			 ORDER BY t.relname, i.relname`,
-      [schema]
+        [schema]
+      )
     ),
-    // 5. Single-column UNIQUE constraints tracked as ColumnIR.unique
-    pool.query(
-      `SELECT rel.relname AS table_name, att.attname AS column_name, c.conname AS constraint_name
+    () => (
+      // 5. Single-column UNIQUE constraints tracked as ColumnIR.unique
+      pool.query(
+        `SELECT rel.relname AS table_name, att.attname AS column_name, c.conname AS constraint_name
 				 FROM pg_constraint c
 				 JOIN pg_class rel ON rel.oid = c.conrelid
 				 JOIN pg_namespace ns ON ns.oid = rel.relnamespace
@@ -15338,11 +15999,13 @@ async function queryAllCatalogs(pool, schema) {
 				 WHERE c.contype = 'u'
 				   AND array_length(c.conkey, 1) = 1
 				   AND ns.nspname = $1`,
-      [schema]
+        [schema]
+      )
     ),
-    // 6. ENUM types
-    pool.query(
-      `SELECT
+    () => (
+      // 6. ENUM types
+      pool.query(
+        `SELECT
 			   t.typname AS name,
 			   n.nspname AS schema,
 			   array_agg(e.enumlabel ORDER BY e.enumsortorder) AS values
@@ -15352,11 +16015,13 @@ async function queryAllCatalogs(pool, schema) {
 			 WHERE t.typtype = 'e'
 			   AND n.nspname = $1
 			 GROUP BY t.typname, n.nspname`,
-      [schema]
+        [schema]
+      )
     ),
-    // 7. Comments (table and column level) from pg_description
-    pool.query(
-      `SELECT
+    () => (
+      // 7. Comments (table and column level) from pg_description
+      pool.query(
+        `SELECT
 			   c.relname AS table_name,
 			   a.attname AS column_name,
 			   d.description AS comment
@@ -15366,23 +16031,29 @@ async function queryAllCatalogs(pool, schema) {
 			 LEFT JOIN pg_attribute a ON a.attrelid = d.objoid AND a.attnum = d.objsubid
 			 WHERE n.nspname = $1
 			   AND d.objsubid >= 0`,
-      [schema]
+        [schema]
+      )
     ),
-    // 8. CHECK constraints
-    pool.query(
-      `SELECT
+    () => (
+      // 8. CHECK constraints
+      pool.query(
+        `SELECT
 			   c.conname AS name,
 			   pg_get_constraintdef(c.oid, false) AS expression,
-			   c.conrelid::regclass::text AS raw_table
+			   NOT c.convalidated AS not_valid,
+			   r.relname AS raw_table
 			 FROM pg_constraint c
-			 JOIN pg_namespace n ON n.oid = c.connamespace
+			 JOIN pg_class r ON r.oid = c.conrelid
+			 JOIN pg_namespace n ON n.oid = r.relnamespace
 			 WHERE c.contype = 'c'
 			   AND n.nspname = $1`,
-      [schema]
+        [schema]
+      )
     ),
-    // 9. Partition configurations
-    pool.query(
-      `SELECT
+    () => (
+      // 9. Partition configurations
+      pool.query(
+        `SELECT
 			   c.relname AS table_name,
 			   p.partstrat AS strategy,
 			   array_agg(a.attname ORDER BY pk.n) AS columns
@@ -15393,37 +16064,45 @@ async function queryAllCatalogs(pool, schema) {
 			 JOIN pg_attribute a ON a.attrelid = p.partrelid AND a.attnum = pk.attnum
 			 WHERE n.nspname = $1
 			 GROUP BY c.relname, p.partstrat`,
-      [schema]
+        [schema]
+      )
     ),
-    // 10. Installed extensions (no schema param — queries globally; skip plpgsql)
-    pool.query(
-      `SELECT extname AS name
+    () => (
+      // 10. Installed extensions (no schema param — queries globally; skip plpgsql)
+      pool.query(
+        `SELECT extname AS name
 			 FROM pg_extension
 			 WHERE extname != 'plpgsql'`
+      )
     ),
-    // 11. Sequences not backed by SERIAL
-    pool.query(
-      `SELECT s.sequencename AS name, s.start_value, s.increment_by, s.min_value, s.max_value, s.cycle
+    () => (
+      // 11. Sequences not backed by SERIAL
+      pool.query(
+        `SELECT s.sequencename AS name, s.start_value, s.increment_by, s.min_value, s.max_value, s.cycle
 			 FROM pg_sequences s
 			 LEFT JOIN pg_class c ON c.relname = s.sequencename AND c.relkind = 'S'
 			   AND c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = s.schemaname)
 			 LEFT JOIN pg_depend d ON d.objid = c.oid AND d.deptype = 'a'
 			 WHERE s.schemaname = $1
 			   AND d.objid IS NULL`,
-      [schema]
+        [schema]
+      )
     ),
-    // 12. RLS enabled state per table
-    pool.query(
-      `SELECT c.relname AS table_name, c.relrowsecurity AS rls_enabled
+    () => (
+      // 12. RLS enabled state per table
+      pool.query(
+        `SELECT c.relname AS table_name, c.relrowsecurity AS rls_enabled
 			 FROM pg_class c
 			 JOIN pg_namespace n ON n.oid = c.relnamespace
 			 WHERE n.nspname = $1
 			   AND c.relkind = 'r'`,
-      [schema]
+        [schema]
+      )
     ),
-    // 13. Row-Level Security policies
-    pool.query(
-      `SELECT
+    () => (
+      // 13. Row-Level Security policies
+      pool.query(
+        `SELECT
 			   c.relname AS table_name,
 			   p.polname AS policy_name,
 			   p.polcmd AS cmd,
@@ -15435,19 +16114,21 @@ async function queryAllCatalogs(pool, schema) {
 			 JOIN pg_class c ON c.oid = p.polrelid
 			 JOIN pg_namespace n ON n.oid = c.relnamespace
 			 WHERE n.nspname = $1`,
-      [schema]
+        [schema]
+      )
     ),
-    // 14. Faithful SQL-facing column types via format_type, for three cases:
-    // (a) typmod-bearing columns (atttypmod <> -1) — varchar(120), numeric(10,2),
-    //     timestamptz(3), bit(8), vector(768) — to preserve modifier fidelity (#261);
-    // (b) array columns (typcategory 'A') — so integer[] is stored as `integer[]`
-    //     rather than the internal `_int4` udt_name;
-    // (c) non-pg_catalog scalar types — enums/composites/domains in user schemas.
-    // `type_schema` is the type's OWN namespace (pg_type.typnamespace). The IR stores
-    // it structurally and keeps `originalDbType` bare, so DDL/cast emission can decide
-    // whether the type follows the target schema or remains absolute.
-    pool.query(
-      `SELECT c.relname AS table_name,
+    () => (
+      // 14. Faithful SQL-facing column types via format_type, for three cases:
+      // (a) typmod-bearing columns (atttypmod <> -1) — varchar(120), numeric(10,2),
+      //     timestamptz(3), bit(8), vector(768) — to preserve modifier fidelity (#261);
+      // (b) array columns (typcategory 'A') — so integer[] is stored as `integer[]`
+      //     rather than the internal `_int4` udt_name;
+      // (c) non-pg_catalog scalar types — enums/composites/domains in user schemas.
+      // `type_schema` is the type's OWN namespace (pg_type.typnamespace). The IR stores
+      // it structurally and keeps `originalDbType` bare, so DDL/cast emission can decide
+      // whether the type follows the target schema or remains absolute.
+      pool.query(
+        `SELECT c.relname AS table_name,
 			        a.attname AS column_name,
 			        format_type(a.atttypid, a.atttypmod) AS db_type,
 			        tn.nspname AS type_schema
@@ -15465,9 +16146,32 @@ async function queryAllCatalogs(pool, schema) {
 			     OR t.typcategory = 'A'
 			     OR t.typnamespace <> 'pg_catalog'::regnamespace
 			   )`,
-      [schema]
+        [schema]
+      )
     )
-  ]);
+  ];
+  const results = pool.sequentialCatalogReads ? [] : await Promise.all(catalogQueries.map((query) => query()));
+  if (pool.sequentialCatalogReads) {
+    for (const query of catalogQueries) {
+      results.push(await query());
+    }
+  }
+  const [
+    columnsResult,
+    pksResult,
+    fksResult,
+    indexesResult,
+    uniqueColumnsResult,
+    enumsResult,
+    commentsResult,
+    checksResult,
+    partitionsResult,
+    extensionsResult,
+    sequencesResult,
+    rlsResult,
+    policiesResult,
+    formattedColumnTypesResult
+  ] = results;
   return {
     columns: columnsResult.rows,
     pks: pksResult.rows,
@@ -15503,10 +16207,11 @@ function buildPartitionMap(rows) {
 function buildCheckMap(rows) {
   const result = /* @__PURE__ */ new Map();
   for (const ck of rows) {
-    const tableName = ck.raw_table.replace(/^".*"\.|^.*\./u, "");
+    const tableName = ck.raw_table;
     const checkIR = {
       name: ck.name,
-      expression: ck.expression
+      expression: stripNotValidSuffix(ck.expression),
+      ...ck.not_valid ? { notValid: true } : {}
     };
     const existing = result.get(tableName);
     if (existing) {
@@ -15782,6 +16487,20 @@ function buildSequenceMap(rows) {
   return result;
 }
 async function introspect(pool, options) {
+  if (isCheckedOutClient(pool)) {
+    throw new Error(
+      "introspect() takes a pg.Pool, and was given a checked-out pg.PoolClient. That client may be sitting inside a transaction that belongs to you, and a catalog query that fails there would abort it. dbsp will not guess whose transaction it is: declare it \u2014 new PgsqlAdapter(client, { borrowedClient: true }).introspect() \u2014 and the declaration is what buys the savepoint protection."
+    );
+  }
+  return introspectWithExecutor(
+    {
+      dbspProtectedCatalogExecutor: true,
+      query: (sql, parameters) => parameters === void 0 ? pool.query(sql) : pool.query(sql, [...parameters])
+    },
+    options
+  );
+}
+async function introspectWithExecutor(pool, options) {
   const schema = options?.schema ?? "public";
   const warnings = [];
   const raw = await queryAllCatalogs(pool, schema);
@@ -15839,7 +16558,7 @@ async function introspect(pool, options) {
       externalTables.add(fk.target);
     }
   }
-  const modelIR = new ModelIRImpl(
+  const modelIR = new ModelIRImpl2(
     tables,
     relations,
     enumMap,
@@ -16026,18 +16745,18 @@ function mapDeleteRule(rule) {
   }
 }
 function filterTables(tableNames, options) {
-  let result = tableNames;
-  if (options?.include?.length) {
-    result = result.filter(
-      (name) => options.include.some((pattern) => matchGlob(pattern, name))
-    );
+  return tableNames.filter(
+    (name) => isTableInIntrospectionScope(name, options)
+  );
+}
+function isTableInIntrospectionScope(tableName, options) {
+  if (options?.include?.length && !options.include.some((pattern) => matchGlob(pattern, tableName))) {
+    return false;
   }
-  if (options?.exclude?.length) {
-    result = result.filter(
-      (name) => !options.exclude.some((pattern) => matchGlob(pattern, name))
-    );
+  if (options?.exclude?.length && options.exclude.some((pattern) => matchGlob(pattern, tableName))) {
+    return false;
   }
-  return result;
+  return true;
 }
 function matchGlob(pattern, value) {
   if (!pattern.includes("*")) return pattern === value;
@@ -16388,7 +17107,7 @@ function compileInsertFrom(config, ctx, state) {
     relpersistence: "p"
   };
   if (sourceSchema) {
-    sourceRelation.schemaname = naming.toDatabase(sourceSchema);
+    sourceRelation.schemaname = sourceSchema;
   }
   const selectQuery = {
     SelectStmt: {
@@ -16470,7 +17189,7 @@ function compileUpsertFrom(config, ctx, state) {
     relpersistence: "p"
   };
   if (sourceSchema) {
-    sourceRelation.schemaname = naming.toDatabase(sourceSchema);
+    sourceRelation.schemaname = sourceSchema;
   }
   const selectQuery = {
     SelectStmt: {
@@ -16855,19 +17574,21 @@ init_naming_plugin();
 init_param_ref();
 
 // src/pgsql-adapter.ts
+import { randomBytes } from "crypto";
 import { POSTGRESQL_CAPABILITIES as POSTGRESQL_CAPABILITIES2, plan as planFn2 } from "@dbsp/core";
 import { getNqlBindingRefName as getNqlBindingRefName2, isNqlBindingRef as isNqlBindingRef2 } from "@dbsp/types/internal";
 
 // src/adapter-compiler-includes.ts
 init_ast_helpers();
+import { toColumnList as toColumnList8 } from "@dbsp/types";
 init_deparse();
 init_handlers();
-import { toColumnList as toColumnList8 } from "@dbsp/types";
 function compileSubqueryInclude(info, parentIds, _options, deps) {
   const schemaName = deps.schemaName;
   const state = createCompilerState();
   if (parentIds.length === 0) {
-    const tableName = schemaName ? `"${deps.naming.toDatabase(schemaName)}"."${deps.naming.toDatabase(info.targetTable)}"` : `"${deps.naming.toDatabase(info.targetTable)}"`;
+    const dbTargetTable = deps.naming.toDatabase(info.targetTable);
+    const tableName = schemaName ? `${quoteIdent2(schemaName, "schema")}.${quoteIdent2(dbTargetTable, "table")}` : quoteIdent2(dbTargetTable, "table");
     return {
       sql: `SELECT * FROM ${tableName} WHERE FALSE`,
       parameters: []
@@ -16898,7 +17619,7 @@ function compileSubqueryInclude(info, parentIds, _options, deps) {
         inh: true,
         relpersistence: "p",
         ...schemaName && {
-          schemaname: deps.naming.toDatabase(schemaName)
+          schemaname: schemaName
         }
       }
     }
@@ -18606,7 +19327,7 @@ function getColumnTypes(tableName, columns, deps) {
   const table = deps.model.getTable(tableName);
   if (!table) return void 0;
   let result;
-  const targetSchema = deps.schemaName !== void 0 ? deps.naming.toDatabase(deps.schemaName) : void 0;
+  const targetSchema = deps.schemaName;
   for (const col of columns) {
     const columnIR = table.columns.find((c) => c.name === col);
     if (columnIR) {
@@ -19720,6 +20441,224 @@ function mapFetchDirection(direction) {
 init_validate();
 var MAX_NQL_RUNTIME_BINDING_VALUES_PARAMETERS = 32e3;
 var RESOLVE_TABLE_SCHEMA_SQL = (tableParam) => `(SELECT n.nspname FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = to_regclass(quote_ident(${tableParam})))`;
+var NO_ACTIVE_SQL_TRANSACTION = "25P01";
+var IN_FAILED_SQL_TRANSACTION = "25P02";
+var INVALID_SAVEPOINT_SPECIFICATION = "3B001";
+var SAVEPOINT_RANDOM_BYTES = 16;
+var RAW_SQL_TRANSACTION_CONTROL_MESSAGE = "Transaction control through raw SQL inside a scope dbsp is managing is unsupported. `COMMIT`, `ROLLBACK`, and `PREPARE TRANSACTION` end the transaction dbsp is working inside; dbsp detects that and fails loudly, but the data is already whatever your statement made it. Raw savepoint control (`SAVEPOINT`, `RELEASE SAVEPOINT`, `ROLLBACK TO SAVEPOINT`) can alter the savepoint stack before dbsp sees the command tag; dbsp poisons the scope, but it cannot make that command un-run. Manage your transaction outside dbsp's calls.";
+var RAW_SQL_MULTI_COMMAND_MESSAGE = "dbsp cannot reason about a multi-command raw call inside a transaction it manages. Those commands have already run, and dbsp cannot undo what they already did. Send one command per call, or manage the transaction yourself.";
+var ABORTED_COMMIT_MESSAGE = "PostgreSQL returned ROLLBACK for COMMIT. The transaction was already aborted, no changes were committed, and dbsp is reporting that failed commit explicitly.";
+var TRANSACTION_ABORTED_MESSAGE = "PostgreSQL transaction is aborted because a statement failed inside a dbsp-managed scope and that failure was caught. Roll back the surrounding transaction; the swallowed statement failure is the cause worth reporting.";
+var SAVEPOINT_SCOPE_BUSY_MESSAGE = "Cannot start another dbsp savepoint scope on this PostgreSQL connection because one is already active. Savepoint scopes are single-flight per connection; await the active dbsp operation before starting another.";
+var SAVEPOINT_SCOPE_OWNER_MESSAGE = "This PostgreSQL connection is currently inside a dbsp-managed scope owned by another transaction adapter. Use the transaction adapter passed to the callback instead of an ancestor adapter.";
+var TRANSACTION_SCOPE_ENDED_MESSAGE = "This PostgreSQL transaction adapter belongs to a transaction that has ended.";
+var NESTED_TRANSACTION_NOT_AWAITED_MESSAGE = "Nested transactions must be awaited before the transaction callback returns.";
+var TRANSACTION_CONTROL_COMMAND_TAGS = /* @__PURE__ */ new Set([
+  "BEGIN",
+  "START",
+  "START TRANSACTION",
+  "COMMIT",
+  "ROLLBACK",
+  "SAVEPOINT",
+  "RELEASE",
+  "PREPARE",
+  "PREPARE TRANSACTION"
+]);
+var PREPARE_COMMAND_TAG = "PREPARE";
+var pgsqlAdapterInternalOptionsKey = /* @__PURE__ */ Symbol(
+  "dbsp-pgsql-adapter-internal-options"
+);
+var activeClientScopes = /* @__PURE__ */ new WeakMap();
+var PgsqlRawSqlTransactionControlError = class extends Error {
+  dbspRawSqlTransactionControl = true;
+  constructor(cause) {
+    super(RAW_SQL_TRANSACTION_CONTROL_MESSAGE, { cause });
+    this.name = "PgsqlRawSqlTransactionControlError";
+  }
+};
+var PgsqlTransactionAbortedCommitError = class extends Error {
+  dbspTransactionAbortedCommit = true;
+  constructor(cause) {
+    super(ABORTED_COMMIT_MESSAGE, { cause });
+    this.name = "PgsqlTransactionAbortedCommitError";
+  }
+};
+var PgsqlTransactionAbortedError = class extends Error {
+  dbspTransactionAborted = true;
+  constructor(cause) {
+    super(TRANSACTION_ABORTED_MESSAGE, { cause });
+    this.name = "PgsqlTransactionAbortedError";
+  }
+};
+function isPoolClientLike(connection) {
+  return typeof connection === "object" && connection !== null && "release" in connection && typeof connection.release === "function";
+}
+function poolClientTransactionOpen(client) {
+  const status = client._txStatus;
+  if (status === "T" || status === "E") return true;
+  if (status === "I") return false;
+  return void 0;
+}
+function isPgErrorWithCode(error, code) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function nextSavepointName() {
+  return `dbsp_savepoint_${randomBytes(SAVEPOINT_RANDOM_BYTES).toString("hex")}`;
+}
+function createScopeToken() {
+  return /* @__PURE__ */ Symbol("dbsp-pgsql-scope");
+}
+function createScopeState(statementLock = { tail: void 0 }) {
+  return {
+    poisoned: void 0,
+    statementLock,
+    children: {
+      open: 0,
+      failure: void 0,
+      transactions: /* @__PURE__ */ new Set()
+    },
+    closing: false,
+    streamFailureRecovery: void 0
+  };
+}
+var ObservedChildTransactionPromise = class extends Promise {
+  static get [Symbol.species]() {
+    return Promise;
+  }
+  #markObserved;
+  constructor(promise, markObserved) {
+    super((resolve, reject) => {
+      promise.then(resolve, reject);
+    });
+    this.#markObserved = markObserved;
+  }
+  // biome-ignore lint/suspicious/noThenProperty: await and Promise.all must mark nested transaction promises observed.
+  then(onfulfilled, onrejected) {
+    this.#markObserved();
+    return super.then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    this.#markObserved();
+    return super.catch(onrejected);
+  }
+  finally(onfinally) {
+    this.#markObserved();
+    return super.finally(onfinally);
+  }
+};
+function normalizeCommandTag(command) {
+  return command?.trim().toUpperCase();
+}
+function isTransactionControlCommandTag(command) {
+  const normalized = normalizeCommandTag(command);
+  return normalized !== void 0 && TRANSACTION_CONTROL_COMMAND_TAGS.has(normalized);
+}
+function isPrepareCommandTag(command) {
+  return normalizeCommandTag(command) === PREPARE_COMMAND_TAG;
+}
+function queryResults(result) {
+  return Array.isArray(result) ? result : [result];
+}
+function queryResultMetadata(result) {
+  return {
+    command: result.command,
+    rowCount: result.rowCount
+  };
+}
+function queryResultsMetadata(result) {
+  return queryResults(result).map(queryResultMetadata);
+}
+function lastQueryResult(result) {
+  if (Array.isArray(result)) {
+    const last = result.at(-1);
+    if (last === void 0) {
+      throw new Error("PostgreSQL returned no query results");
+    }
+    return last;
+  }
+  return result;
+}
+function describeThrown(error) {
+  if (error instanceof Error && error.message) return error.message;
+  if (typeof error === "string") return error;
+  return String(error);
+}
+function createCleanupFailureError(action, originalError, cleanupError) {
+  const error = new AggregateError(
+    [originalError, cleanupError],
+    `${action}: ${describeThrown(cleanupError)}. The original failure is available as cause.`
+  );
+  Object.defineProperties(error, {
+    cause: { value: originalError, configurable: true },
+    cleanupError: { value: cleanupError, configurable: true },
+    originalError: { value: originalError, configurable: true }
+  });
+  return error;
+}
+function createCleanupOnlyError(action, cleanupError) {
+  const error = new AggregateError(
+    [cleanupError],
+    `${action}: ${describeThrown(cleanupError)}.`
+  );
+  Object.defineProperty(error, "cleanupError", {
+    value: cleanupError,
+    configurable: true
+  });
+  return error;
+}
+function addCleanupErrorToOriginal(originalError, cleanupError) {
+  if (originalError instanceof Error) {
+    if (!Object.hasOwn(originalError, "cause")) {
+      Object.defineProperty(originalError, "cause", {
+        value: cleanupError,
+        configurable: true
+      });
+    }
+    if (!Object.hasOwn(originalError, "cleanupError")) {
+      Object.defineProperty(originalError, "cleanupError", {
+        value: cleanupError,
+        configurable: true
+      });
+    }
+    return originalError;
+  }
+  return createCleanupFailureError(
+    "PostgreSQL stream cleanup failed: CLOSE cursor failed after the stream failed",
+    originalError,
+    cleanupError
+  );
+}
+function cleanupReleaseReason(error) {
+  if (typeof error !== "object" || error === null || !("cleanupError" in error)) {
+    return void 0;
+  }
+  const cleanupError = error.cleanupError;
+  return cleanupError instanceof Error ? cleanupError : true;
+}
+function isRawSqlTransactionControlError(error) {
+  return typeof error === "object" && error !== null && "dbspRawSqlTransactionControl" in error && error.dbspRawSqlTransactionControl === true;
+}
+function isSavepointUnavailableError(error) {
+  return isPgErrorWithCode(error, NO_ACTIVE_SQL_TRANSACTION) || isPgErrorWithCode(error, INVALID_SAVEPOINT_SPECIFICATION);
+}
+function addRawSqlTransactionContext(error) {
+  const context = "dbsp rolled back the failed raw SQL to a savepoint, so the surrounding transaction is still usable. Side effects that do not participate in transactional rollback, including sequence advancement and session-level advisory locks, are not undone.";
+  if (error instanceof Error) {
+    error.message = `${error.message}; ${context}`;
+    Object.defineProperty(error, "dbspRawSqlContext", {
+      value: context,
+      configurable: true
+    });
+  }
+  return error;
+}
+function protectedStatementCleanupAction(rawSqlStatement, detail) {
+  const prefix = rawSqlStatement ? "PostgreSQL raw SQL cleanup failed" : "PostgreSQL protected statement cleanup failed";
+  return `${prefix}: ${detail}`;
+}
+function raise(error) {
+  throw error;
+}
 function renumberSqlParams2(sql, offset) {
   if (offset === 0) return sql;
   return sql.replace(/\$(\d+)/g, (_match, num) => {
@@ -19866,8 +20805,8 @@ function mapRuntimeBindingColumnType(type) {
 function findRuntimeBindingSourceTable(model, sourceTable) {
   return model.getTable(sourceTable) ?? [...model.tables.values()].find((table) => table.name === sourceTable);
 }
-function runtimeCastTargetSchema(schemaName, naming) {
-  return schemaName !== void 0 ? naming.toDatabase(schemaName) : void 0;
+function runtimeCastTargetSchema(schemaName, _naming) {
+  return schemaName;
 }
 function resolveRuntimeBindingColumnType(bindingName, sourceTable, columnName, schemaName, naming) {
   const column = sourceTable.columns.find(
@@ -20108,9 +21047,38 @@ function createNqlBindingSelectPlan(query) {
     }
   };
 }
-var PgsqlAdapter = class _PgsqlAdapter {
+function isPgsqlAdapterInternalOptions(options) {
+  return typeof options === "object" && options !== null && pgsqlAdapterInternalOptionsKey in options && options[pgsqlAdapterInternalOptionsKey] === true;
+}
+function hasBorrowedClientOption(options) {
+  return typeof options === "object" && options !== null && "borrowedClient" in options && options.borrowedClient === true;
+}
+function hasManagedTransactionsOption(options) {
+  return typeof options === "object" && options !== null && "managedTransactions" in options && options.managedTransactions === true;
+}
+function isAdapterManagedTransactionOption(options) {
+  return isPgsqlAdapterInternalOptions(options) && options.adapterManagedTransaction === true;
+}
+function getDbspScopeTokenOption(options) {
+  return isPgsqlAdapterInternalOptions(options) ? options.dbspScopeToken : void 0;
+}
+function getDbspScopeStateOption(options) {
+  return isPgsqlAdapterInternalOptions(options) ? options.dbspScopeState : void 0;
+}
+function createPgsqlAdapterFromConstructionOptions(connection, options) {
+  return new PgsqlAdapter(
+    connection,
+    options
+  );
+}
+var PgsqlAdapter = class {
   pool;
   client;
+  borrowedClient;
+  managedTransactions;
+  adapterManagedTransaction;
+  scopeToken;
+  scopeState;
   schemaName;
   _dbCasing;
   naming;
@@ -20119,25 +21087,42 @@ var PgsqlAdapter = class _PgsqlAdapter {
   _capabilities;
   defaultPk;
   deriveFk;
-  /**
-   * Create a new PgsqlAdapter.
-   *
-   * @param pool - pg.Pool instance, PoolClient (transactions), or undefined (compile-only mode)
-   * @param options - Optional configuration
-   */
   constructor(pool, options) {
+    const declaredBorrowed = hasBorrowedClientOption(options);
     if (pool != null) {
-      if ("release" in pool && typeof pool.release === "function") {
+      if (isPoolClientLike(pool)) {
+        if (!declaredBorrowed) {
+          throw new Error(
+            "PgsqlAdapter received a pg PoolClient without borrowedClient: true. A checked-out client belongs to whoever checked it out: declare it with borrowedClient: true, and pass managedTransactions: true if dbsp should run transactions on it."
+          );
+        }
         this.client = pool;
-        this.pool = pool;
+        this.pool = void 0;
+        this.borrowedClient = true;
       } else {
+        if (declaredBorrowed) {
+          throw new Error(
+            "borrowedClient: true requires a pg PoolClient, not a pg Pool."
+          );
+        }
         this.pool = pool;
         this.client = void 0;
+        this.borrowedClient = false;
       }
     } else {
+      if (declaredBorrowed) {
+        throw new Error(
+          "borrowedClient: true requires a pg PoolClient; no connection was given."
+        );
+      }
       this.pool = void 0;
       this.client = void 0;
+      this.borrowedClient = false;
     }
+    this.managedTransactions = hasManagedTransactionsOption(options);
+    this.adapterManagedTransaction = isAdapterManagedTransactionOption(options);
+    this.scopeToken = getDbspScopeTokenOption(options);
+    this.scopeState = getDbspScopeStateOption(options);
     this.schemaName = options?.schemaName;
     this._dbCasing = options?.dbCasing ?? "preserve";
     this.naming = getNamingPluginForDbCasing(this._dbCasing);
@@ -20145,10 +21130,12 @@ var PgsqlAdapter = class _PgsqlAdapter {
     this.logger = options?.logger;
     this.defaultPk = options?.defaultPkColumnName ?? DEFAULT_PK_COLUMN;
     this.deriveFk = options?.deriveFkColumnName ?? defaultFkDerivation;
+    const supportsManagedTransactions = this.pool != null || this.client != null && this.managedTransactions;
     this._capabilities = {
       supportsReturning: true,
       supportsSchemas: true,
-      supportsStreaming: pool != null,
+      supportsStreaming: supportsManagedTransactions,
+      supportsTransactions: supportsManagedTransactions,
       supportsRecursiveCTE: true,
       supportsWindowFunctions: true,
       supportsArrayType: true
@@ -20164,13 +21151,25 @@ var PgsqlAdapter = class _PgsqlAdapter {
    * deriveFkColumnName, etc.) are propagated to scoped/transactional adapters.
    */
   cloneOptions(overrides) {
+    const adapterManagedTransaction = overrides.adapterManagedTransaction ?? this.adapterManagedTransaction ? true : void 0;
+    const scopeToken = overrides.dbspScopeToken ?? this.scopeToken;
+    const scopeState = overrides.dbspScopeState ?? this.scopeState;
+    const hasInternalOptions = adapterManagedTransaction === true || scopeToken !== void 0 || scopeState !== void 0;
     return {
+      ...hasInternalOptions && {
+        [pgsqlAdapterInternalOptionsKey]: true
+      },
       ...this.schemaName !== void 0 && { schemaName: this.schemaName },
       ...this._dbCasing !== void 0 && { dbCasing: this._dbCasing },
       ...this.model !== void 0 && { model: this.model },
       ...this.logger !== void 0 && { logger: this.logger },
       defaultPkColumnName: this.defaultPk,
       deriveFkColumnName: this.deriveFk,
+      ...this.borrowedClient && { borrowedClient: true },
+      ...this.managedTransactions && { managedTransactions: true },
+      ...adapterManagedTransaction === true && { adapterManagedTransaction },
+      ...scopeToken !== void 0 && { dbspScopeToken: scopeToken },
+      ...scopeState !== void 0 && { dbspScopeState: scopeState },
       ...overrides
     };
   }
@@ -20417,7 +21416,7 @@ var PgsqlAdapter = class _PgsqlAdapter {
     return this._dbCasing;
   }
   /**
-   * Get the underlying pg Pool instance.
+   * Get the underlying pg Pool or borrowed PoolClient instance.
    */
   getPoolInstance() {
     return this.requireConnection();
@@ -20682,8 +21681,7 @@ var PgsqlAdapter = class _PgsqlAdapter {
    * Results are transformed to use model naming convention (e.g., snake_case → camelCase)
    */
   async execute(query) {
-    const executor = this.requireConnection();
-    const result = await executor.query(query.sql, [...query.parameters]);
+    const result = await this.executeQueryProtectingOpenTransaction(query.sql, query.parameters);
     return this.transformResultRows(result.rows);
   }
   /**
@@ -20741,32 +21739,117 @@ var PgsqlAdapter = class _PgsqlAdapter {
     const adapter = this;
     async function* streamGenerator() {
       if (adapter.client) {
-        yield* adapter.streamWithClient(adapter.client, query, chunkSize);
+        if (!adapter.managedTransactions) {
+          throw new Error(
+            "stream() requires a PostgreSQL transaction because cursors do not survive outside one. This adapter uses a borrowed PoolClient; pass managedTransactions: true to let dbsp open a transaction or savepoint for the stream."
+          );
+        }
+        yield* adapter.streamWithManagedClient(
+          adapter.client,
+          query,
+          chunkSize
+        );
         return;
       }
       const pool = adapter.requireConnection();
       const client = await pool.connect();
+      let begun = false;
       let committed = false;
+      let streamFailed = false;
+      let releaseScope;
+      let scopeToken;
+      let scopeState;
+      let releaseError;
+      let cleanupErrorToThrow;
+      let streamRolledBackBeforeClose = false;
       try {
-        await client.query("BEGIN");
-        yield* adapter.streamWithClient(client, query, chunkSize);
-        await client.query("COMMIT");
+        scopeToken = createScopeToken();
+        scopeState = createScopeState();
+        releaseScope = adapter.enterTransactionScope(
+          client,
+          scopeToken,
+          scopeState
+        );
+        await adapter.executeScopeBoundaryStatement(
+          client,
+          scopeToken,
+          scopeState,
+          "BEGIN"
+        );
+        begun = true;
+        scopeState.streamFailureRecovery = async () => {
+          await adapter.rollbackTransactionIfOpen(
+            client,
+            scopeToken,
+            scopeState
+          );
+          streamRolledBackBeforeClose = true;
+        };
+        yield* adapter.streamWithClient(
+          client,
+          query,
+          chunkSize,
+          scopeToken,
+          scopeState.streamFailureRecovery
+        );
+        adapter.closeScopeAndAssertChildren(scopeState);
+        await adapter.drainScopeWork(scopeState);
+        adapter.throwIfScopePoisoned(scopeState);
+        const commitResult = await adapter.executeScopeBoundaryStatement(
+          client,
+          scopeToken,
+          scopeState,
+          "COMMIT"
+        );
         committed = true;
+        adapter.assertCommitSucceeded(commitResult);
       } catch (error) {
-        await client.query("ROLLBACK");
-        throw error;
+        let transactionError = error;
+        try {
+          adapter.closeScopeAndAssertChildren(scopeState);
+        } catch (scopeError) {
+          transactionError = scopeError;
+        }
+        streamFailed = true;
+        if (begun && !committed && !streamRolledBackBeforeClose) {
+          try {
+            await adapter.rollbackTransactionIfOpen(
+              client,
+              scopeToken,
+              scopeState
+            );
+          } catch (rollbackErr) {
+            releaseError = rollbackErr instanceof Error ? rollbackErr : true;
+            throw createCleanupFailureError(
+              "PostgreSQL stream cleanup failed: ROLLBACK failed after the stream failed",
+              transactionError,
+              rollbackErr
+            );
+          }
+        }
+        throw transactionError;
       } finally {
-        if (!committed) {
+        if (begun && !committed && !streamFailed && !streamRolledBackBeforeClose) {
+          adapter.closeScope(scopeState);
           try {
-            await client.query("ROLLBACK");
+            await adapter.rollbackTransactionIfOpen(
+              client,
+              scopeToken,
+              scopeState
+            );
           } catch (rollbackErr) {
-            adapter.logger?.debug?.(
-              "Rollback failed during cleanup",
+            releaseError = rollbackErr instanceof Error ? rollbackErr : true;
+            cleanupErrorToThrow = createCleanupOnlyError(
+              "PostgreSQL stream cleanup failed: ROLLBACK failed after the stream was closed early",
               rollbackErr
             );
           }
         }
-        client.release();
+        releaseScope?.();
+        adapter.releaseClient(client, releaseError);
+        if (cleanupErrorToThrow !== void 0) {
+          raise(cleanupErrorToThrow);
+        }
       }
     }
     return streamGenerator();
@@ -20774,16 +21857,26 @@ var PgsqlAdapter = class _PgsqlAdapter {
   /**
    * Internal: Stream with an existing client using cursors.
    */
-  async *streamWithClient(client, query, chunkSize) {
+  async *streamWithClient(client, query, chunkSize, allowedScopeToken, recoverBeforeCloseOnError) {
     const cursorName = generateCursorName();
-    await client.query(
+    await this.executeConnectionStatement(
+      client,
       `DECLARE ${cursorName} NO SCROLL CURSOR FOR ${query.sql}`,
-      query.parameters
+      query.parameters,
+      {
+        ...allowedScopeToken !== void 0 && { allowedScopeToken }
+      }
     );
+    let streamError;
     try {
       while (true) {
-        const result = await client.query(
-          `FETCH FORWARD ${chunkSize} FROM ${cursorName}`
+        const result = await this.executeConnectionStatement(
+          client,
+          `FETCH FORWARD ${chunkSize} FROM ${cursorName}`,
+          void 0,
+          {
+            ...allowedScopeToken !== void 0 && { allowedScopeToken }
+          }
         );
         if (result.rows.length === 0) {
           break;
@@ -20795,8 +21888,263 @@ var PgsqlAdapter = class _PgsqlAdapter {
           break;
         }
       }
+    } catch (error) {
+      streamError = error;
+      throw error;
+    } finally {
+      if (streamError !== void 0 && recoverBeforeCloseOnError !== void 0) {
+        try {
+          await recoverBeforeCloseOnError();
+        } catch (cleanupErr) {
+          raise(
+            createCleanupFailureError(
+              "PostgreSQL stream cleanup failed: rollback before CLOSE cursor failed after the stream failed",
+              streamError,
+              cleanupErr
+            )
+          );
+        }
+      }
+      try {
+        await this.executeConnectionStatement(
+          client,
+          `CLOSE ${cursorName}`,
+          void 0,
+          {
+            ...allowedScopeToken !== void 0 && { allowedScopeToken },
+            allowPoisonedScope: true
+          }
+        );
+      } catch (cleanupErr) {
+        if (streamError !== void 0) {
+          raise(addCleanupErrorToOriginal(streamError, cleanupErr));
+        }
+        raise(
+          createCleanupOnlyError(
+            "PostgreSQL stream cleanup failed: CLOSE cursor failed",
+            cleanupErr
+          )
+        );
+      }
+    }
+  }
+  async *streamWithManagedClient(client, query, chunkSize) {
+    if (this.adapterManagedTransaction) {
+      this.assertCanUseClient(client, this.scopeToken);
+      yield* this.streamWithClient(
+        client,
+        query,
+        chunkSize,
+        this.scopeToken,
+        this.scopeState?.streamFailureRecovery
+      );
+      return;
+    }
+    yield* this.streamWithManagedClientSavepointScope(
+      client,
+      query,
+      chunkSize
+    );
+  }
+  async *streamWithManagedClientSavepointScope(client, query, chunkSize) {
+    const savepointName = nextSavepointName();
+    const scopeToken = this.scopeToken ?? createScopeToken();
+    const scopeState = this.scopeState ?? createScopeState();
+    const releaseScope = this.enterSavepointScope(
+      client,
+      scopeToken,
+      scopeState,
+      "statement"
+    );
+    try {
+      await this.executeConnectionStatement(
+        client,
+        `SAVEPOINT ${savepointName}`,
+        void 0,
+        {
+          allowedScopeToken: scopeToken,
+          inspectTransactionControl: false
+        }
+      );
+    } catch (error) {
+      releaseScope();
+      if (isPgErrorWithCode(error, NO_ACTIVE_SQL_TRANSACTION)) {
+        yield* this.streamWithClientTransaction(client, query, chunkSize);
+        return;
+      }
+      throw error;
+    }
+    let completed = false;
+    let streamError;
+    let savepointRolledBackBeforeClose = false;
+    const recoverStreamFailure = async () => {
+      const rolledBack = await this.rollbackSavepoint(
+        client,
+        savepointName,
+        scopeToken,
+        scopeState
+      );
+      savepointRolledBackBeforeClose ||= rolledBack;
+    };
+    try {
+      yield* this.streamWithClient(
+        client,
+        query,
+        chunkSize,
+        scopeToken,
+        recoverStreamFailure
+      );
+      completed = true;
+    } catch (error) {
+      streamError = error;
+      throw error;
+    } finally {
+      try {
+        this.closeScope(scopeState);
+        if (completed) {
+          this.assertScopeChildrenSettled(scopeState);
+          await this.drainScopeWork(scopeState);
+          this.throwIfScopePoisoned(scopeState);
+          try {
+            await this.executeScopeBoundaryStatement(
+              client,
+              scopeToken,
+              scopeState,
+              `RELEASE SAVEPOINT ${savepointName}`,
+              {
+                allowAncestorScopeToken: true
+              }
+            );
+          } catch (releaseErr) {
+            raise(
+              await this.rollbackSavepointAfterReleaseFailure(
+                client,
+                savepointName,
+                scopeToken,
+                scopeState,
+                releaseErr,
+                "PostgreSQL stream cleanup failed: RELEASE SAVEPOINT failed after the stream completed"
+              )
+            );
+          }
+        } else {
+          try {
+            if (savepointRolledBackBeforeClose) {
+              await this.releaseSavepoint(
+                client,
+                savepointName,
+                scopeToken,
+                scopeState
+              );
+            } else {
+              await this.rollbackAndReleaseSavepoint(
+                client,
+                savepointName,
+                scopeToken,
+                scopeState
+              );
+            }
+          } catch (cleanupErr) {
+            if (streamError !== void 0) {
+              raise(
+                createCleanupFailureError(
+                  "PostgreSQL stream cleanup failed: savepoint cleanup failed after the stream failed",
+                  streamError,
+                  cleanupErr
+                )
+              );
+            }
+            raise(
+              createCleanupOnlyError(
+                "PostgreSQL stream cleanup failed: savepoint cleanup failed after the stream was closed early",
+                cleanupErr
+              )
+            );
+          }
+        }
+      } finally {
+        releaseScope();
+      }
+    }
+  }
+  async *streamWithClientTransaction(client, query, chunkSize) {
+    let begun = false;
+    let committed = false;
+    let streamFailed = false;
+    let cleanupErrorToThrow;
+    let releaseScope;
+    let scopeToken;
+    let scopeState;
+    let streamRolledBackBeforeClose = false;
+    try {
+      scopeToken = createScopeToken();
+      scopeState = createScopeState();
+      releaseScope = this.enterTransactionScope(client, scopeToken, scopeState);
+      await this.executeScopeBoundaryStatement(
+        client,
+        scopeToken,
+        scopeState,
+        "BEGIN"
+      );
+      begun = true;
+      scopeState.streamFailureRecovery = async () => {
+        await this.rollbackTransactionIfOpen(client, scopeToken, scopeState);
+        streamRolledBackBeforeClose = true;
+      };
+      yield* this.streamWithClient(
+        client,
+        query,
+        chunkSize,
+        scopeToken,
+        scopeState.streamFailureRecovery
+      );
+      this.closeScopeAndAssertChildren(scopeState);
+      await this.drainScopeWork(scopeState);
+      this.throwIfScopePoisoned(scopeState);
+      const commitResult = await this.executeScopeBoundaryStatement(
+        client,
+        scopeToken,
+        scopeState,
+        "COMMIT"
+      );
+      committed = true;
+      this.assertCommitSucceeded(commitResult);
+    } catch (error) {
+      let transactionError = error;
+      try {
+        this.closeScopeAndAssertChildren(scopeState);
+      } catch (scopeError) {
+        transactionError = scopeError;
+      }
+      streamFailed = true;
+      if (begun && !committed && !streamRolledBackBeforeClose) {
+        try {
+          await this.rollbackTransactionIfOpen(client, scopeToken, scopeState);
+        } catch (rollbackErr) {
+          throw createCleanupFailureError(
+            "PostgreSQL stream cleanup failed: ROLLBACK failed after the stream failed",
+            transactionError,
+            rollbackErr
+          );
+        }
+      }
+      throw transactionError;
     } finally {
-      await client.query(`CLOSE ${cursorName}`);
+      if (begun && !committed && !streamFailed && !streamRolledBackBeforeClose) {
+        this.closeScope(scopeState);
+        try {
+          await this.rollbackTransactionIfOpen(client, scopeToken, scopeState);
+        } catch (rollbackErr) {
+          cleanupErrorToThrow = createCleanupOnlyError(
+            "PostgreSQL stream cleanup failed: ROLLBACK failed after the stream was closed early",
+            rollbackErr
+          );
+        }
+      }
+      releaseScope?.();
+      if (cleanupErrorToThrow !== void 0) {
+        raise(cleanupErrorToThrow);
+      }
     }
   }
   // =========================================================================
@@ -20816,58 +22164,1041 @@ var PgsqlAdapter = class _PgsqlAdapter {
    * ```
    */
   async introspect(options) {
-    if (!this.pool) {
+    const executor = this.client ?? this.pool;
+    if (!executor) {
       throw new Error(
         "Cannot introspect without a database connection (compile-only adapter)"
       );
     }
-    return introspect(this.pool, options);
+    return introspectWithExecutor(
+      {
+        // The brand says this executor already carries the savepoint protection
+        // the connection's ownership calls for. A bare PoolClient cannot get here.
+        dbspProtectedCatalogExecutor: true,
+        query: (sql, parameters) => this.executeConnectionStatement(executor, sql, parameters, {
+          protectBorrowedClientTransaction: this.client !== void 0 && !this.adapterManagedTransaction
+        }),
+        sequentialCatalogReads: this.client !== void 0
+      },
+      options
+    );
   }
   // =========================================================================
   // TransactionalAdapter Methods
   // =========================================================================
   /**
    * Execute a callback within a database transaction.
+   *
+   * ## What this guarantees
+   *
+   * The callback's work commits together or not at all; a statement issued inside
+   * the transaction never executes after its boundary, even if you forget to
+   * `await` it; a nested `transaction()` is a real savepoint; and the connection
+   * never goes back to the pool with a transaction still open on it.
+   *
+   * ## What it cannot guarantee, and you should know before you reach for raw SQL
+   *
+   * **Raw SQL that ends the transaction ends it.** `COMMIT`, `ROLLBACK` and
+   * `PREPARE TRANSACTION` issued through `executeRaw` — or through several commands
+   * in one call — reach PostgreSQL and take effect *before* dbsp is told what they
+   * were: the command tag arrives after the statement has run. dbsp detects it, kills
+   * the scope so nothing else escapes, and throws — but **it cannot un-run what your
+   * statement already did**, and `transaction()` rejecting does not mean nothing was
+   * committed.
+   *
+   * The same holds for session state raw SQL creates: a sequence that advanced stays
+   * advanced, an advisory lock stays held, a `PREPARE` or a `SET` you issued survives
+   * on a pooled connection. dbsp cleans up only what dbsp created.
+   *
+   * This is the contract of an escape hatch, not an oversight — see #327. If you need
+   * transaction control, own the transaction: take a client, `BEGIN` on it yourself,
+   * and hand dbsp a `borrowedClient` **without** `managedTransactions`. dbsp will then
+   * contain its own statements inside *your* transaction instead of the other way round.
    */
-  async transaction(fn4) {
+  transaction(fn4) {
+    const childObserver = this.createChildTransactionObserver();
     if (this.client) {
-      return fn4(this);
+      if (!this.managedTransactions) {
+        return Promise.reject(
+          new Error(
+            "transaction() was called on a PgsqlAdapter created with a borrowed PoolClient. This connection is yours, so the transaction is yours. Pass managedTransactions: true to let dbsp run transactions on it through a savepoint, and read the managedTransactions option documentation for the limits of that contract."
+          )
+        );
+      }
+      return this.observeChildTransaction(
+        this.transactionWithManagedClient(
+          this.client,
+          fn4,
+          childObserver,
+          "release"
+        ),
+        childObserver
+      );
     }
-    const pool = this.requireConnection();
-    const client = await pool.connect();
+    let pool;
     try {
-      await client.query("BEGIN");
-      const txOptions = this.cloneOptions({});
-      const txAdapter = new _PgsqlAdapter(client, txOptions);
-      const result = await fn4(txAdapter);
-      await client.query("COMMIT");
-      return result;
+      pool = this.requireConnection();
     } catch (error) {
-      await client.query("ROLLBACK");
-      throw error;
-    } finally {
-      client.release();
-    }
+      return Promise.reject(error);
+    }
+    return this.observeChildTransaction(
+      (async () => {
+        const client = await pool.connect();
+        let releaseError;
+        try {
+          return await this.transactionWithClientTransaction(
+            client,
+            fn4,
+            childObserver,
+            "commit"
+          );
+        } catch (error) {
+          releaseError = cleanupReleaseReason(error);
+          throw error;
+        } finally {
+          this.releaseClient(client, releaseError);
+        }
+      })(),
+      childObserver
+    );
   }
   /**
-   * Create a schema-scoped adapter for multi-tenant queries.
+   * Execute scratch PostgreSQL work in a scope that always rolls back on success.
+   *
+   * This is intentionally PostgreSQL-adapter-specific. It is used for catalog
+   * shaped scratch DDL such as CHECK expression canonicalisation, where the
+   * caller needs PostgreSQL's rendering but must not keep the scratch objects.
+   * Rollback here is cleanup of dbsp-created work, not a sandbox for arbitrary
+   * session effects.
    */
-  withSchema(schemaName) {
-    validateIdentifier(schemaName, "schema");
-    const options = this.cloneOptions({ schemaName });
-    return new _PgsqlAdapter(this.client ?? this.pool ?? void 0, options);
-  }
-  // =========================================================================
-  // RawSqlAdapter Methods
+  withScratchScope(fn4) {
+    const childObserver = this.createChildTransactionObserver();
+    if (this.client) {
+      return this.observeChildTransaction(
+        this.transactionWithManagedClient(
+          this.client,
+          fn4,
+          childObserver,
+          "rollback"
+        ),
+        childObserver
+      );
+    }
+    let pool;
+    try {
+      pool = this.requireConnection();
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return this.observeChildTransaction(
+      (async () => {
+        const client = await pool.connect();
+        let releaseError;
+        try {
+          return await this.transactionWithClientTransaction(
+            client,
+            fn4,
+            childObserver,
+            "rollback"
+          );
+        } catch (error) {
+          releaseError = cleanupReleaseReason(error);
+          throw error;
+        } finally {
+          this.releaseClient(client, releaseError);
+        }
+      })(),
+      childObserver
+    );
+  }
+  createManagedClientAdapter(client, scopeToken, scopeState) {
+    return createPgsqlAdapterFromConstructionOptions(
+      client,
+      this.cloneOptions({
+        borrowedClient: true,
+        managedTransactions: true,
+        adapterManagedTransaction: true,
+        dbspScopeToken: scopeToken,
+        dbspScopeState: scopeState
+      })
+    );
+  }
+  createChildTransactionObserver() {
+    if (!this.adapterManagedScopeIsLive()) return void 0;
+    const parentChildren = this.scopeState?.children;
+    if (parentChildren === void 0) return void 0;
+    let resolveSettled;
+    const settledPromise = new Promise((resolve) => {
+      resolveSettled = resolve;
+    });
+    const child = {
+      observed: false,
+      failure: void 0,
+      settled: false,
+      settledPromise,
+      resolveSettled
+    };
+    parentChildren.open++;
+    parentChildren.transactions.add(child);
+    let released = false;
+    const release = (failure) => {
+      if (released) return;
+      released = true;
+      if (failure !== void 0 && child.failure === void 0) {
+        child.failure = failure;
+        if (!child.observed && parentChildren.failure === void 0) {
+          parentChildren.failure = failure;
+        }
+      }
+      parentChildren.open--;
+      child.settled = true;
+      child.resolveSettled();
+    };
+    return { observed: false, child, parentChildren, release };
+  }
+  observeChildTransaction(promise, observer) {
+    if (observer === void 0) return promise;
+    const observed = new ObservedChildTransactionPromise(promise, () => {
+      this.markChildTransactionObserved(observer);
+    });
+    void Promise.prototype.then.call(observed, void 0, () => void 0);
+    return observed;
+  }
+  markChildTransactionObserved(observer) {
+    if (observer.observed) return;
+    observer.observed = true;
+    const child = observer.child;
+    child.observed = true;
+    const parentChildren = observer.parentChildren;
+    if (child.failure !== void 0 && parentChildren.failure === child.failure) {
+      this.refreshScopeChildrenFailure(parentChildren);
+    }
+  }
+  refreshScopeChildrenFailure(children) {
+    children.failure = void 0;
+    for (const child of children.transactions) {
+      if (!child.observed && child.failure !== void 0) {
+        children.failure = child.failure;
+        return;
+      }
+    }
+  }
+  async transactionWithManagedClient(client, fn4, childObserver, successAction = "release") {
+    return this.transactionWithManagedClientSavepointScope(
+      client,
+      fn4,
+      childObserver,
+      successAction
+    );
+  }
+  async transactionWithManagedClientSavepointScope(client, fn4, childObserver, successAction = "release") {
+    const savepointName = nextSavepointName();
+    const scopeToken = createScopeToken();
+    const scopeState = createScopeState(this.scopeState?.statementLock);
+    const txAdapter = this.createManagedClientAdapter(
+      client,
+      scopeToken,
+      scopeState
+    );
+    let releaseScope;
+    try {
+      releaseScope = this.enterSavepointScope(
+        client,
+        scopeToken,
+        scopeState,
+        "transaction",
+        childObserver
+      );
+    } catch (error) {
+      childObserver?.release({ error });
+      throw error;
+    }
+    let scopeFailure;
+    let savepointRolledBackBeforeClose = false;
+    try {
+      await this.executeConnectionStatement(
+        client,
+        `SAVEPOINT ${savepointName}`,
+        void 0,
+        {
+          allowedScopeToken: scopeToken,
+          inspectTransactionControl: false
+        }
+      );
+    } catch (error) {
+      if (isPgErrorWithCode(error, NO_ACTIVE_SQL_TRANSACTION)) {
+        releaseScope();
+        return this.transactionWithClientTransaction(
+          client,
+          fn4,
+          childObserver,
+          successAction === "rollback" ? "rollback" : "commit"
+        );
+      }
+      releaseScope({ error });
+      throw error;
+    }
+    scopeState.streamFailureRecovery = async () => {
+      const rolledBack = await this.rollbackSavepoint(
+        client,
+        savepointName,
+        scopeToken,
+        scopeState
+      );
+      savepointRolledBackBeforeClose ||= rolledBack;
+    };
+    try {
+      let result;
+      try {
+        result = await fn4(txAdapter);
+        this.closeScopeAndAssertChildren(scopeState);
+        await this.drainScopeWork(scopeState);
+        this.throwIfScopePoisoned(scopeState);
+      } catch (error) {
+        let transactionError = error;
+        try {
+          this.closeScopeAndAssertChildren(scopeState);
+        } catch (scopeError) {
+          transactionError = scopeError;
+        }
+        let cleanupErr;
+        try {
+          let rolledBack = savepointRolledBackBeforeClose;
+          if (!rolledBack) {
+            rolledBack = await this.rollbackSavepoint(
+              client,
+              savepointName,
+              scopeToken,
+              scopeState
+            );
+          }
+          await this.drainScopeChildren(scopeState);
+          if (rolledBack) {
+            await this.releaseSavepoint(
+              client,
+              savepointName,
+              scopeToken,
+              scopeState
+            );
+          }
+        } catch (error2) {
+          cleanupErr = error2;
+        }
+        if (cleanupErr !== void 0) {
+          await this.drainScopeChildren(scopeState);
+          if (isRawSqlTransactionControlError(transactionError) && isSavepointUnavailableError(cleanupErr)) {
+            scopeFailure = { error: transactionError };
+            throw transactionError;
+          }
+          const cleanupFailure = createCleanupFailureError(
+            "PostgreSQL transaction cleanup failed: savepoint cleanup failed after the transaction body failed; the caller transaction may now be in an unknown state",
+            transactionError,
+            cleanupErr
+          );
+          scopeFailure = { error: cleanupFailure };
+          throw cleanupFailure;
+        }
+        await this.drainScopeChildren(scopeState);
+        transactionError = this.scopePoisonOutranksError(
+          scopeState,
+          transactionError
+        );
+        scopeFailure = { error: transactionError };
+        throw transactionError;
+      }
+      try {
+        if (successAction === "rollback") {
+          try {
+            await this.rollbackAndReleaseSavepoint(
+              client,
+              savepointName,
+              scopeToken,
+              scopeState,
+              { ignoreNoActiveTransaction: false }
+            );
+          } catch (rollbackErr) {
+            const cleanupFailure = createCleanupOnlyError(
+              "PostgreSQL scratch scope cleanup failed: ROLLBACK TO SAVEPOINT/RELEASE SAVEPOINT failed after the scratch body returned",
+              rollbackErr
+            );
+            scopeFailure = { error: cleanupFailure };
+            throw cleanupFailure;
+          }
+          return result;
+        }
+        await this.executeScopeBoundaryStatement(
+          client,
+          scopeToken,
+          scopeState,
+          `RELEASE SAVEPOINT ${savepointName}`,
+          {
+            allowAncestorScopeToken: true
+          }
+        );
+      } catch (releaseErr) {
+        const cleanupFailure = await this.rollbackSavepointAfterReleaseFailure(
+          client,
+          savepointName,
+          scopeToken,
+          scopeState,
+          releaseErr,
+          "PostgreSQL transaction cleanup failed: RELEASE SAVEPOINT failed after the transaction body returned"
+        );
+        scopeFailure = { error: cleanupFailure };
+        throw cleanupFailure;
+      }
+      return result;
+    } finally {
+      releaseScope(scopeFailure);
+    }
+  }
+  async transactionWithClientTransaction(client, fn4, childObserver, successAction = "commit") {
+    let begun = false;
+    let committed = false;
+    let releaseScope;
+    let scopeToken;
+    let scopeState;
+    let scopeFailure;
+    let transactionRolledBackBeforeClose = false;
+    try {
+      scopeToken = createScopeToken();
+      scopeState = createScopeState();
+      releaseScope = this.enterTransactionScope(
+        client,
+        scopeToken,
+        scopeState,
+        childObserver
+      );
+      await this.executeScopeBoundaryStatement(
+        client,
+        scopeToken,
+        scopeState,
+        "BEGIN"
+      );
+      begun = true;
+      scopeState.streamFailureRecovery = async () => {
+        await this.rollbackTransactionIfOpen(client, scopeToken, scopeState);
+        transactionRolledBackBeforeClose = true;
+      };
+      const txAdapter = this.createManagedClientAdapter(
+        client,
+        scopeToken,
+        scopeState
+      );
+      const result = await fn4(txAdapter);
+      this.closeScopeAndAssertChildren(scopeState);
+      await this.drainScopeWork(scopeState);
+      this.throwIfScopePoisoned(scopeState);
+      if (successAction === "rollback") {
+        transactionRolledBackBeforeClose = true;
+        try {
+          await this.rollbackTransactionIfOpen(
+            client,
+            scopeToken,
+            scopeState,
+            false
+          );
+        } catch (rollbackErr) {
+          const cleanupFailure = createCleanupOnlyError(
+            "PostgreSQL scratch scope cleanup failed: ROLLBACK failed after the scratch body returned",
+            rollbackErr
+          );
+          scopeFailure = { error: cleanupFailure };
+          throw cleanupFailure;
+        }
+        return result;
+      }
+      const commitResult = await this.executeScopeBoundaryStatement(
+        client,
+        scopeToken,
+        scopeState,
+        "COMMIT"
+      );
+      committed = true;
+      this.assertCommitSucceeded(commitResult);
+      return result;
+    } catch (error) {
+      let transactionError = error;
+      try {
+        this.closeScopeAndAssertChildren(scopeState);
+      } catch (scopeError) {
+        transactionError = scopeError;
+      }
+      if (begun && !committed && !transactionRolledBackBeforeClose) {
+        try {
+          await this.rollbackTransactionIfOpen(client, scopeToken, scopeState);
+        } catch (rollbackErr) {
+          const cleanupFailure = createCleanupFailureError(
+            "PostgreSQL transaction cleanup failed: ROLLBACK failed after the transaction body failed",
+            transactionError,
+            rollbackErr
+          );
+          scopeFailure = { error: cleanupFailure };
+          await this.drainScopeChildren(scopeState);
+          throw cleanupFailure;
+        }
+      }
+      await this.drainScopeChildren(scopeState);
+      transactionError = this.scopePoisonOutranksError(
+        scopeState,
+        transactionError
+      );
+      scopeFailure = { error: transactionError };
+      throw transactionError;
+    } finally {
+      if (releaseScope === void 0) {
+        if (scopeFailure !== void 0) {
+          childObserver?.release(scopeFailure);
+        }
+      } else {
+        releaseScope(scopeFailure);
+      }
+    }
+  }
+  releaseClient(client, error) {
+    if (error === void 0) {
+      client.release();
+      return;
+    }
+    client.release(error);
+  }
+  async rollbackAndReleaseSavepoint(client, savepointName, allowedScopeToken, scopeState, options) {
+    const rolledBack = await this.rollbackSavepoint(
+      client,
+      savepointName,
+      allowedScopeToken,
+      scopeState,
+      options
+    );
+    if (!rolledBack) return;
+    await this.releaseSavepoint(
+      client,
+      savepointName,
+      allowedScopeToken,
+      scopeState
+    );
+  }
+  async rollbackSavepoint(client, savepointName, allowedScopeToken, scopeState, options) {
+    try {
+      await this.executeScopeBoundaryStatement(
+        client,
+        allowedScopeToken,
+        scopeState,
+        `ROLLBACK TO SAVEPOINT ${savepointName}`,
+        {
+          allowAncestorScopeToken: true,
+          allowPoisonedScope: true
+        }
+      );
+    } catch (error) {
+      if ((options?.ignoreNoActiveTransaction ?? true) && isPgErrorWithCode(error, NO_ACTIVE_SQL_TRANSACTION)) {
+        return false;
+      }
+      throw error;
+    }
+    return true;
+  }
+  async releaseSavepoint(client, savepointName, allowedScopeToken, scopeState) {
+    await this.executeScopeBoundaryStatement(
+      client,
+      allowedScopeToken,
+      scopeState,
+      `RELEASE SAVEPOINT ${savepointName}`,
+      {
+        allowAncestorScopeToken: true,
+        allowPoisonedScope: true
+      }
+    );
+  }
+  async rollbackTransactionIfOpen(client, allowedScopeToken, scopeState, ignoreNoActiveTransaction = true) {
+    if (allowedScopeToken === void 0 || scopeState === void 0) {
+      throw new Error(
+        "Cannot roll back a dbsp-managed PostgreSQL transaction without a registered dbsp scope."
+      );
+    }
+    try {
+      await this.executeScopeBoundaryStatement(
+        client,
+        allowedScopeToken,
+        scopeState,
+        "ROLLBACK",
+        {
+          allowAncestorScopeToken: true,
+          allowPoisonedScope: true
+        }
+      );
+    } catch (error) {
+      if (ignoreNoActiveTransaction && isPgErrorWithCode(error, NO_ACTIVE_SQL_TRANSACTION)) {
+        return;
+      }
+      throw error;
+    }
+  }
+  classifyTransactionStateError(error) {
+    if (isPgErrorWithCode(error, NO_ACTIVE_SQL_TRANSACTION)) {
+      return "no-active-transaction";
+    }
+    if (isPgErrorWithCode(error, IN_FAILED_SQL_TRANSACTION)) {
+      return "transaction-aborted";
+    }
+    if (isPgErrorWithCode(error, INVALID_SAVEPOINT_SPECIFICATION)) {
+      return "savepoint-gone";
+    }
+    return void 0;
+  }
+  async probeTransactionState(client, allowedScopeToken) {
+    const probeSavepointName = nextSavepointName();
+    try {
+      await this.executeConnectionStatement(
+        client,
+        `SAVEPOINT ${probeSavepointName}`,
+        void 0,
+        {
+          ...allowedScopeToken !== void 0 && { allowedScopeToken },
+          allowClosingScope: true,
+          allowPoisonedScope: true,
+          inspectTransactionControl: false,
+          protectBorrowedClientTransaction: false
+        }
+      );
+    } catch (error) {
+      const state = this.classifyTransactionStateError(error);
+      if (state === "no-active-transaction" || state === "savepoint-gone") {
+        return "no-active-transaction";
+      }
+      if (state === "transaction-aborted") return "transaction-aborted";
+      return "unknown";
+    }
+    try {
+      await this.executeConnectionStatement(
+        client,
+        `RELEASE SAVEPOINT ${probeSavepointName}`,
+        void 0,
+        {
+          ...allowedScopeToken !== void 0 && { allowedScopeToken },
+          allowClosingScope: true,
+          allowPoisonedScope: true,
+          inspectTransactionControl: false,
+          protectBorrowedClientTransaction: false
+        }
+      );
+    } catch {
+      return "unknown";
+    }
+    return "live";
+  }
+  async classifySavepointReleaseFailure(client, allowedScopeToken, releaseErr, cleanupAction) {
+    const directState = this.classifyTransactionStateError(releaseErr);
+    if (directState === "no-active-transaction" || directState === "savepoint-gone") {
+      return this.poisonClientScopeStack(
+        client,
+        createCleanupOnlyError(cleanupAction, releaseErr),
+        "cleanup"
+      );
+    }
+    if (directState === "transaction-aborted") {
+      return this.poisonClientScope(
+        client,
+        allowedScopeToken,
+        new PgsqlTransactionAbortedError(releaseErr),
+        "cleanup"
+      );
+    }
+    const probedState = await this.probeTransactionState(
+      client,
+      allowedScopeToken
+    );
+    if (probedState === "no-active-transaction") {
+      return this.poisonClientScopeStack(
+        client,
+        createCleanupOnlyError(cleanupAction, releaseErr),
+        "cleanup"
+      );
+    }
+    if (probedState === "transaction-aborted") {
+      return this.poisonClientScope(
+        client,
+        allowedScopeToken,
+        new PgsqlTransactionAbortedError(releaseErr),
+        "cleanup"
+      );
+    }
+    return createCleanupOnlyError(cleanupAction, releaseErr);
+  }
+  async rollbackSavepointAfterReleaseFailure(client, savepointName, allowedScopeToken, scopeState, releaseErr, cleanupAction) {
+    try {
+      await this.executeScopeBoundaryStatement(
+        client,
+        allowedScopeToken,
+        scopeState,
+        `ROLLBACK TO SAVEPOINT ${savepointName}`,
+        {
+          allowAncestorScopeToken: true,
+          allowPoisonedScope: true
+        }
+      );
+    } catch (rollbackErr) {
+      const classifiedRollbackFailure = await this.classifySavepointReleaseFailure(
+        client,
+        allowedScopeToken,
+        rollbackErr,
+        cleanupAction
+      );
+      if (isRawSqlTransactionControlError(classifiedRollbackFailure) || classifiedRollbackFailure instanceof PgsqlTransactionAbortedError) {
+        return classifiedRollbackFailure;
+      }
+      return createCleanupFailureError(
+        `${cleanupAction}; ROLLBACK TO SAVEPOINT also failed and the caller transaction may now be in an unknown state`,
+        releaseErr,
+        rollbackErr
+      );
+    }
+    try {
+      await this.releaseSavepoint(
+        client,
+        savepointName,
+        allowedScopeToken,
+        scopeState
+      );
+    } catch (releaseAfterRollbackErr) {
+      return createCleanupFailureError(
+        `${cleanupAction}; RELEASE SAVEPOINT also failed after ROLLBACK TO SAVEPOINT and the caller transaction may now be in an unknown state`,
+        releaseErr,
+        releaseAfterRollbackErr
+      );
+    }
+    return createCleanupOnlyError(cleanupAction, releaseErr);
+  }
+  enterTransactionScope(client, scopeToken, scopeState, childObserver) {
+    const current = this.currentClientScope(client);
+    if (current === void 0 && this.scopeToken !== void 0) {
+      throw new Error(TRANSACTION_SCOPE_ENDED_MESSAGE);
+    }
+    if (current !== void 0) {
+      const ownScope = this.scopeToken === void 0 ? void 0 : this.findClientScope(client, this.scopeToken);
+      if (ownScope?.state.closing) {
+        throw new Error(TRANSACTION_SCOPE_ENDED_MESSAGE);
+      }
+      if (current.state.closing) {
+        throw new Error(TRANSACTION_SCOPE_ENDED_MESSAGE);
+      }
+      this.assertScopeNotPoisoned(current);
+      if (current.token !== this.scopeToken) {
+        throw new Error(SAVEPOINT_SCOPE_OWNER_MESSAGE);
+      }
+      throw new Error(SAVEPOINT_SCOPE_BUSY_MESSAGE);
+    }
+    return this.pushClientScope(
+      client,
+      {
+        kind: "transaction",
+        token: scopeToken,
+        state: scopeState
+      },
+      childObserver
+    );
+  }
+  enterSavepointScope(client, scopeToken, scopeState, purpose, childObserver) {
+    const current = this.currentClientScope(client);
+    if (current === void 0 && this.scopeToken !== void 0) {
+      throw new Error(TRANSACTION_SCOPE_ENDED_MESSAGE);
+    }
+    if (current !== void 0) {
+      const ownScope = this.scopeToken === void 0 ? void 0 : this.findClientScope(client, this.scopeToken);
+      if (ownScope?.state.closing) {
+        throw new Error(TRANSACTION_SCOPE_ENDED_MESSAGE);
+      }
+      if (current.state.closing) {
+        throw new Error(TRANSACTION_SCOPE_ENDED_MESSAGE);
+      }
+      this.assertScopeNotPoisoned(current);
+      if (current.state.statementLock.tail !== void 0) {
+        throw new Error(SAVEPOINT_SCOPE_BUSY_MESSAGE);
+      }
+      if (current.kind === "statement-savepoint") {
+        throw new Error(SAVEPOINT_SCOPE_BUSY_MESSAGE);
+      }
+      if (current.token !== this.scopeToken) {
+        throw new Error(SAVEPOINT_SCOPE_OWNER_MESSAGE);
+      }
+      if (purpose !== "transaction") {
+        throw new Error(SAVEPOINT_SCOPE_BUSY_MESSAGE);
+      }
+    }
+    return this.pushClientScope(
+      client,
+      {
+        kind: purpose === "transaction" ? "transaction-savepoint" : "statement-savepoint",
+        token: scopeToken,
+        state: scopeState
+      },
+      childObserver
+    );
+  }
+  pushClientScope(client, scope, childObserver) {
+    const stack = activeClientScopes.get(client);
+    if (stack === void 0) {
+      activeClientScopes.set(client, [scope]);
+    } else {
+      stack.push(scope);
+    }
+    let released = false;
+    return (failure) => {
+      if (released) return;
+      released = true;
+      try {
+        const currentStack = activeClientScopes.get(client);
+        if (currentStack === void 0) return;
+        const index = currentStack.indexOf(scope);
+        if (index === -1) return;
+        currentStack.splice(index, 1);
+        if (currentStack.length === 0) {
+          activeClientScopes.delete(client);
+        }
+      } finally {
+        childObserver?.release(failure);
+      }
+    };
+  }
+  currentClientScope(client) {
+    return activeClientScopes.get(client)?.at(-1);
+  }
+  assertCanUseClient(client, allowedScopeToken = this.scopeToken, allowAncestorScopeToken = false, allowClosingScope = false, allowPoisonedScope = false) {
+    const stack = activeClientScopes.get(client);
+    const current = stack?.at(-1);
+    if (allowedScopeToken === void 0) {
+      if (current === void 0) return;
+      throw new Error(SAVEPOINT_SCOPE_OWNER_MESSAGE);
+    }
+    if (current?.token === allowedScopeToken) {
+      this.assertUsableScopeAncestors(
+        stack,
+        stack.length - 1,
+        allowClosingScope,
+        allowPoisonedScope
+      );
+      if (current.state.closing && !allowClosingScope) {
+        throw new Error(TRANSACTION_SCOPE_ENDED_MESSAGE);
+      }
+      if (!allowPoisonedScope) {
+        this.assertScopeNotPoisoned(current);
+      }
+      return;
+    }
+    const allowedScope = this.findClientScope(client, allowedScopeToken);
+    if (allowedScope?.state.closing && !allowClosingScope) {
+      throw new Error(TRANSACTION_SCOPE_ENDED_MESSAGE);
+    }
+    if (allowAncestorScopeToken && allowedScope !== void 0) {
+      this.assertUsableScopeAncestors(
+        stack,
+        stack.indexOf(allowedScope),
+        allowClosingScope,
+        allowPoisonedScope
+      );
+      if (!allowPoisonedScope) {
+        this.assertScopeNotPoisoned(allowedScope);
+      }
+      return;
+    }
+    if (allowedScope === void 0) {
+      throw new Error(TRANSACTION_SCOPE_ENDED_MESSAGE);
+    }
+    throw new Error(SAVEPOINT_SCOPE_OWNER_MESSAGE);
+  }
+  assertUsableScopeAncestors(stack, scopeIndex, allowClosingScope, allowPoisonedScope) {
+    for (let index = 0; index < scopeIndex; index++) {
+      const ancestor = stack[index];
+      if (ancestor === void 0) continue;
+      if (ancestor.state.closing && !allowClosingScope) {
+        throw new Error(TRANSACTION_SCOPE_ENDED_MESSAGE);
+      }
+      if (!allowPoisonedScope) {
+        this.assertScopeNotPoisoned(ancestor);
+      }
+    }
+  }
+  findClientScope(client, scopeToken) {
+    const stack = activeClientScopes.get(client);
+    if (stack === void 0) return void 0;
+    if (scopeToken === void 0) return stack.at(-1);
+    for (let index = stack.length - 1; index >= 0; index--) {
+      const scope = stack[index];
+      if (scope?.token === scopeToken) return scope;
+    }
+    return void 0;
+  }
+  assertScopeNotPoisoned(scope) {
+    this.throwIfScopePoisoned(scope.state);
+  }
+  throwIfScopePoisoned(scopeState) {
+    const poison = scopeState.poisoned;
+    if (poison !== void 0) {
+      throw poison.error;
+    }
+  }
+  scopePoisonOutranksError(scopeState, error) {
+    const poison = scopeState?.poisoned;
+    if (poison === void 0 || poison.error === error) return error;
+    if (poison.origin === "cleanup") {
+      if (error instanceof Error && !Object.hasOwn(error, "cause")) {
+        Object.defineProperty(error, "cause", {
+          value: poison.error,
+          configurable: true
+        });
+      }
+      return error;
+    }
+    if (!isRawSqlTransactionControlError(poison.error)) {
+      return error;
+    }
+    Object.defineProperty(poison.error, "cause", {
+      value: error,
+      configurable: true
+    });
+    return poison.error;
+  }
+  poisonScopeState(scopeState, error, origin = "caller") {
+    const poison = scopeState.poisoned;
+    if (poison === void 0 || poison.origin === "cleanup" && origin === "caller") {
+      scopeState.poisoned = { error, origin };
+      return error;
+    }
+    return poison.error;
+  }
+  poisonClientScope(client, scopeToken, error, origin) {
+    const scope = this.findClientScope(client, scopeToken);
+    if (scope === void 0) return error;
+    return this.poisonScopeState(scope.state, error, origin);
+  }
+  poisonClientScopeStack(client, error, origin) {
+    const stack = activeClientScopes.get(client);
+    if (stack === void 0 || stack.length === 0) return error;
+    let poisonedError;
+    for (const scope of stack) {
+      const scopeError = this.poisonScopeState(scope.state, error, origin);
+      poisonedError ??= scopeError;
+    }
+    return poisonedError ?? error;
+  }
+  async runWithScopeStatementLock(scopeState, fn4) {
+    const lock = scopeState.statementLock;
+    const previous = lock.tail ?? Promise.resolve();
+    let release;
+    const next = new Promise((resolve) => {
+      release = resolve;
+    });
+    const tail = previous.catch(() => void 0).then(() => next);
+    lock.tail = tail;
+    await previous.catch(() => void 0);
+    try {
+      return await fn4();
+    } finally {
+      release();
+      if (lock.tail === tail) {
+        lock.tail = void 0;
+      }
+    }
+  }
+  closeScope(scopeState) {
+    if (scopeState !== void 0) {
+      scopeState.closing = true;
+    }
+  }
+  closeScopeAndAssertChildren(scopeState) {
+    this.closeScope(scopeState);
+    if (scopeState !== void 0) {
+      this.assertScopeChildrenSettled(scopeState);
+    }
+  }
+  async drainScopeStatements(scopeState) {
+    await scopeState.statementLock.tail?.catch(() => void 0);
+  }
+  async drainScopeChildren(scopeState) {
+    if (scopeState === void 0) return;
+    while (scopeState.children.open > 0) {
+      const pending = [...scopeState.children.transactions].filter(
+        (child) => !child.settled
+      );
+      if (pending.length === 0) return;
+      await Promise.all(pending.map((child) => child.settledPromise));
+    }
+  }
+  assertScopeChildrenSettled(scopeState) {
+    const failure = scopeState.children.failure;
+    if (failure !== void 0) {
+      throw failure.error;
+    }
+    if (scopeState.children.open > 0) {
+      throw new Error(NESTED_TRANSACTION_NOT_AWAITED_MESSAGE);
+    }
+    for (const child of scopeState.children.transactions) {
+      if (!child.observed) {
+        throw new Error(NESTED_TRANSACTION_NOT_AWAITED_MESSAGE);
+      }
+    }
+  }
+  async drainScopeWork(scopeState) {
+    await this.drainScopeStatements(scopeState);
+  }
+  async executeScopeBoundaryStatement(client, scopeToken, scopeState, sql, options = {}) {
+    const boundaryOptions = {
+      ...options,
+      allowedScopeToken: scopeToken,
+      allowClosingScope: true,
+      inspectTransactionControl: false,
+      protectBorrowedClientTransaction: false
+    };
+    return this.runWithScopeStatementLock(
+      scopeState,
+      () => this.executeConnectionStatementUnlocked(
+        client,
+        sql,
+        void 0,
+        boundaryOptions,
+        scopeToken
+      )
+    );
+  }
+  assertCommitSucceeded(result) {
+    if (result.command === "ROLLBACK") {
+      throw new PgsqlTransactionAbortedCommitError(result);
+    }
+  }
+  /**
+   * Create a schema-scoped adapter for multi-tenant queries.
+   */
+  withSchema(schemaName) {
+    validateIdentifier(schemaName, "schema");
+    const options = this.cloneOptions({ schemaName });
+    return createPgsqlAdapterFromConstructionOptions(
+      this.client ?? this.pool ?? void 0,
+      options
+    );
+  }
+  // =========================================================================
+  // RawSqlAdapter Methods
   // =========================================================================
   /**
    * Execute raw SQL directly.
    *
    * ⚠️  WARNING: Use parameter placeholders ($1, $2, etc.) for all values.
+   *
+   * Transaction control through raw SQL inside a scope dbsp is managing is
+   * unsupported. `COMMIT`, `ROLLBACK`, and `PREPARE TRANSACTION` end the
+   * transaction dbsp is working inside; dbsp detects that and fails loudly, but
+   * the data is already whatever your statement made it. Raw savepoint control
+   * (`SAVEPOINT`, `RELEASE SAVEPOINT`, `ROLLBACK TO SAVEPOINT`) can alter the
+   * savepoint stack before dbsp sees the command tag; dbsp poisons the scope, but
+   * it cannot make that command un-run. Manage your transaction outside dbsp's
+   * calls.
    */
   async executeRaw(sql, parameters = []) {
-    const executor = this.requireConnection();
-    const result = await executor.query(sql, [...parameters]);
+    const result = await this.executeQueryProtectingOpenTransaction(
+      sql,
+      parameters,
+      { rawSqlStatement: true }
+    );
     return result.rows;
   }
   // =========================================================================
@@ -20898,19 +23229,311 @@ var PgsqlAdapter = class _PgsqlAdapter {
    * @since DDL-TABLE-001
    */
   async executeDDL(sql) {
-    if (!this.pool) {
+    if (!this.client && !this.pool) {
       throw new Error("Cannot execute DDL on compile-only adapter");
     }
-    await this.pool.query(sql);
+    await this.executeQueryProtectingOpenTransaction(sql);
   }
   /**
-   * Whether this adapter instance is scoped inside a transaction.
-   * Guards unsafe DDL operations (VACUUM, CREATE INDEX CONCURRENTLY).
+   * Whether a transaction is open on this adapter's connection.
+   * This is true for dbsp-managed scopes and for borrowed pg clients whose
+   * ReadyForQuery status says the caller has an open transaction.
    *
    * @since DDL-TABLE-001
    */
   get inTransaction() {
-    return this.client !== void 0;
+    if (this.adapterManagedTransaction) return this.adapterManagedScopeIsLive();
+    if (this.client === void 0) return false;
+    return poolClientTransactionOpen(this.client) !== false;
+  }
+  adapterManagedScopeIsLive() {
+    if (!this.adapterManagedTransaction || this.client === void 0 || this.scopeToken === void 0 || this.scopeState === void 0) {
+      return false;
+    }
+    return this.findClientScope(this.client, this.scopeToken)?.state === this.scopeState;
+  }
+  async executeQueryProtectingOpenTransaction(sql, parameters, options = {}) {
+    return this.executeConnectionStatement(
+      this.requireConnection(),
+      sql,
+      parameters,
+      {
+        ...options,
+        protectBorrowedClientTransaction: this.client !== void 0 && !this.adapterManagedTransaction
+      }
+    );
+  }
+  async executeConnectionStatement(executor, sql, parameters, options = {}) {
+    const shouldProtect = options.protectBorrowedClientTransaction ?? false;
+    if (shouldProtect && isPoolClientLike(executor)) {
+      return this.executeConnectionStatementInSavepoint(
+        executor,
+        sql,
+        parameters,
+        options
+      );
+    }
+    const allowedScopeToken = options.allowedScopeToken ?? this.scopeToken;
+    if (isPoolClientLike(executor)) {
+      this.assertCanUseClient(
+        executor,
+        allowedScopeToken,
+        options.allowAncestorScopeToken ?? false,
+        options.allowClosingScope ?? false,
+        options.allowPoisonedScope ?? false
+      );
+    }
+    const managedScope = isPoolClientLike(executor) && options.inspectTransactionControl !== false && options.allowPoisonedScope !== true ? this.findClientScope(executor, allowedScopeToken) : void 0;
+    if (managedScope !== void 0) {
+      return this.runWithScopeStatementLock(
+        managedScope.state,
+        () => this.executeConnectionStatementUnlocked(
+          executor,
+          sql,
+          parameters,
+          { ...options, allowClosingScope: true },
+          allowedScopeToken
+        )
+      );
+    }
+    return this.executeConnectionStatementUnlocked(
+      executor,
+      sql,
+      parameters,
+      options,
+      allowedScopeToken
+    );
+  }
+  async executeConnectionStatementUnlocked(executor, sql, parameters, options, allowedScopeToken) {
+    if (isPoolClientLike(executor)) {
+      this.assertCanUseClient(
+        executor,
+        allowedScopeToken,
+        options.allowAncestorScopeToken ?? false,
+        options.allowClosingScope ?? false,
+        options.allowPoisonedScope ?? false
+      );
+    }
+    let pendingError;
+    let result;
+    try {
+      const rawResult = await this.issueConnectionQuery(
+        executor,
+        sql,
+        parameters
+      );
+      if (options.inspectTransactionControl !== false) {
+        await this.assertNoTransactionControlCommand(
+          executor,
+          rawResult,
+          allowedScopeToken
+        );
+        this.assertNoMultiCommandRawCall(
+          executor,
+          rawResult,
+          allowedScopeToken
+        );
+      }
+      result = lastQueryResult(rawResult);
+    } catch (error) {
+      pendingError = error;
+      if (isPoolClientLike(executor) && options.inspectTransactionControl !== false && options.allowPoisonedScope !== true) {
+        this.poisonClientScope(
+          executor,
+          allowedScopeToken,
+          new PgsqlTransactionAbortedError(error)
+        );
+      }
+    }
+    if (pendingError !== void 0) {
+      throw pendingError;
+    }
+    if (result === void 0) {
+      throw new Error("PostgreSQL returned no query results");
+    }
+    return result;
+  }
+  async executeConnectionStatementInSavepoint(client, sql, parameters, options = {}) {
+    const rawSqlStatement = options.rawSqlStatement ?? false;
+    const savepointName = nextSavepointName();
+    const scopeToken = this.scopeToken ?? createScopeToken();
+    const scopeState = this.scopeState ?? createScopeState();
+    const releaseScope = this.enterSavepointScope(
+      client,
+      scopeToken,
+      scopeState,
+      "statement"
+    );
+    try {
+      await this.executeConnectionStatement(
+        client,
+        `SAVEPOINT ${savepointName}`,
+        void 0,
+        {
+          allowedScopeToken: scopeToken,
+          inspectTransactionControl: false,
+          protectBorrowedClientTransaction: false
+        }
+      );
+    } catch (error) {
+      releaseScope();
+      if (isPgErrorWithCode(error, NO_ACTIVE_SQL_TRANSACTION)) {
+        return this.executeConnectionStatement(client, sql, parameters, {
+          ...options,
+          inspectTransactionControl: options.inspectTransactionControl ?? true,
+          protectBorrowedClientTransaction: false
+        });
+      }
+      throw error;
+    }
+    let result;
+    try {
+      result = await this.executeConnectionStatement(
+        client,
+        sql,
+        parameters,
+        {
+          ...options,
+          allowedScopeToken: scopeToken,
+          inspectTransactionControl: options.inspectTransactionControl ?? true,
+          protectBorrowedClientTransaction: false
+        }
+      );
+    } catch (error) {
+      this.closeScope(scopeState);
+      try {
+        await this.rollbackAndReleaseSavepoint(
+          client,
+          savepointName,
+          scopeToken,
+          scopeState
+        );
+      } catch (cleanupErr) {
+        if (isRawSqlTransactionControlError(error) && isSavepointUnavailableError(cleanupErr)) {
+          throw error;
+        }
+        throw createCleanupFailureError(
+          protectedStatementCleanupAction(
+            rawSqlStatement,
+            "savepoint cleanup failed after the protected statement failed; the caller transaction may now be in an unknown state"
+          ),
+          error,
+          cleanupErr
+        );
+      } finally {
+        releaseScope();
+      }
+      if (isRawSqlTransactionControlError(error)) {
+        throw error;
+      }
+      if (rawSqlStatement) {
+        throw addRawSqlTransactionContext(error);
+      }
+      throw error;
+    }
+    try {
+      this.closeScopeAndAssertChildren(scopeState);
+      await this.drainScopeWork(scopeState);
+      this.throwIfScopePoisoned(scopeState);
+      await this.executeScopeBoundaryStatement(
+        client,
+        scopeToken,
+        scopeState,
+        `RELEASE SAVEPOINT ${savepointName}`,
+        {
+          protectBorrowedClientTransaction: false
+        }
+      );
+    } catch (releaseErr) {
+      throw await this.rollbackSavepointAfterReleaseFailure(
+        client,
+        savepointName,
+        scopeToken,
+        scopeState,
+        releaseErr,
+        protectedStatementCleanupAction(
+          rawSqlStatement,
+          "RELEASE SAVEPOINT failed after the protected statement succeeded"
+        )
+      );
+    } finally {
+      releaseScope();
+    }
+    return result;
+  }
+  async issueConnectionQuery(executor, sql, parameters) {
+    if (parameters === void 0) {
+      return executor.query(sql);
+    }
+    return executor.query(sql, [...parameters]);
+  }
+  assertNoMultiCommandRawCall(executor, result, allowedScopeToken) {
+    if (!Array.isArray(result) || !isPoolClientLike(executor)) return;
+    const current = this.currentClientScope(executor);
+    if (current === void 0 || current.token !== allowedScopeToken) return;
+    throw this.poisonClientScope(
+      executor,
+      allowedScopeToken,
+      new Error(RAW_SQL_MULTI_COMMAND_MESSAGE, {
+        cause: queryResultsMetadata(result)
+      })
+    );
+  }
+  async assertNoTransactionControlCommand(executor, result, allowedScopeToken) {
+    if (!isPoolClientLike(executor)) return;
+    const current = this.currentClientScope(executor);
+    if (current === void 0 || current.token !== allowedScopeToken) return;
+    const controlCause = Array.isArray(result) ? queryResultsMetadata(result) : void 0;
+    for (const queryResult of queryResults(result)) {
+      if (isPrepareCommandTag(queryResult.command)) {
+        await this.assertPrepareDidNotEndTransaction(
+          executor,
+          allowedScopeToken,
+          queryResult,
+          controlCause
+        );
+        continue;
+      }
+      if (isTransactionControlCommandTag(queryResult.command)) {
+        throw this.poisonClientScopeStack(
+          executor,
+          new PgsqlRawSqlTransactionControlError(controlCause ?? queryResult)
+        );
+      }
+    }
+  }
+  async assertPrepareDidNotEndTransaction(client, allowedScopeToken, queryResult, cause = queryResult) {
+    const probeSavepointName = nextSavepointName();
+    try {
+      await this.executeConnectionStatement(
+        client,
+        `SAVEPOINT ${probeSavepointName}`,
+        void 0,
+        {
+          ...allowedScopeToken !== void 0 && { allowedScopeToken },
+          inspectTransactionControl: false,
+          protectBorrowedClientTransaction: false
+        }
+      );
+    } catch (error) {
+      if (isPgErrorWithCode(error, NO_ACTIVE_SQL_TRANSACTION)) {
+        throw this.poisonClientScopeStack(
+          client,
+          new PgsqlRawSqlTransactionControlError(cause)
+        );
+      }
+      throw error;
+    }
+    await this.executeConnectionStatement(
+      client,
+      `RELEASE SAVEPOINT ${probeSavepointName}`,
+      void 0,
+      {
+        ...allowedScopeToken !== void 0 && { allowedScopeToken },
+        inspectTransactionControl: false,
+        protectBorrowedClientTransaction: false
+      }
+    );
   }
   /**
    * Resolve the explicit schema for a catalog read: an explicit argument, else
@@ -20929,7 +23552,6 @@ var PgsqlAdapter = class _PgsqlAdapter {
    * @param schema - Schema name (defaults to the search_path-resolved schema)
    */
   async listIndexes(table, schema, options) {
-    const executor = this.requireConnection();
     const params = [table, this.explicitSchema(schema) ?? null];
     let sql = `SELECT indexname, indexdef FROM pg_indexes WHERE tablename = $1 AND schemaname = COALESCE($2, ${RESOLVE_TABLE_SCHEMA_SQL("$1")})`;
     if (options?.namePattern) {
@@ -20937,7 +23559,7 @@ var PgsqlAdapter = class _PgsqlAdapter {
       params.push(options.namePattern);
     }
     sql += " ORDER BY indexname";
-    const result = await executor.query(sql, params);
+    const result = await this.executeQueryProtectingOpenTransaction(sql, params);
     return result.rows.map((row) => {
       const def = row.indexdef;
       const unique = /\bCREATE UNIQUE INDEX\b/i.test(def);
@@ -20954,8 +23576,7 @@ var PgsqlAdapter = class _PgsqlAdapter {
    * @param schema - Schema name (defaults to the search_path-resolved schema)
    */
   async indexExists(name, table, schema) {
-    const executor = this.requireConnection();
-    const result = await executor.query(
+    const result = await this.executeQueryProtectingOpenTransaction(
       `SELECT EXISTS (SELECT 1 FROM pg_indexes WHERE indexname = $1 AND tablename = $2 AND schemaname = COALESCE($3, ${RESOLVE_TABLE_SCHEMA_SQL("$2")})) AS exists`,
       [name, table, this.explicitSchema(schema) ?? null]
     );
@@ -20973,14 +23594,12 @@ var PgsqlAdapter = class _PgsqlAdapter {
    * @param schema - Schema name (defaults to the search_path-resolved schema)
    */
   async storageSize(table, schema) {
-    const executor = this.requireConnection();
     const schemaName = this.explicitSchema(schema);
     const quotedTable = `"${table.replace(/"/g, '""')}"`;
     const identifier = schemaName !== void 0 ? `"${schemaName.replace(/"/g, '""')}".${quotedTable}` : quotedTable;
-    const result = await executor.query(
-      `SELECT pg_total_relation_size($1::regclass)::bigint AS size`,
-      [identifier]
-    );
+    const result = await this.executeQueryProtectingOpenTransaction(`SELECT pg_total_relation_size($1::regclass)::bigint AS size`, [
+      identifier
+    ]);
     return Number(result.rows[0]?.size ?? 0);
   }
   /**
@@ -21034,8 +23653,22 @@ var PgsqlAdapter = class _PgsqlAdapter {
     validateIdentifier(value, identifierType);
   }
 };
-function createPgsqlAdapter(pool, options) {
-  return new PgsqlAdapter(pool, options);
+function createPgsqlAdapter(connection, options) {
+  if (isPoolClientLike(connection)) {
+    if (!hasBorrowedClientOption(options)) {
+      throw new Error(
+        "createPgsqlAdapter() received a pg PoolClient. Pass borrowedClient: true to declare that the caller owns this connection."
+      );
+    }
+  } else if (hasBorrowedClientOption(options)) {
+    throw new Error(
+      "createPgsqlAdapter() received borrowedClient: true with a pg Pool. Pass a PoolClient when borrowing a caller-owned connection."
+    );
+  }
+  return createPgsqlAdapterFromConstructionOptions(
+    connection,
+    options ?? {}
+  );
 }
 function createPgsqlCompileOnlyAdapter(options) {
   return new PgsqlAdapter(
@@ -21085,12 +23718,20 @@ function matchesAnyPattern(value, patterns) {
 init_validate();
 export {
   CamelCaseNamingPlugin,
+  CheckConstraintCanonicalizationError,
+  CheckConstraintNewEnumValueError,
   DEFAULT_PK_COLUMN,
   DEFAULT_REDACTION_PATTERNS,
+  ExpressionCanonicalizationUnavailableError,
   IdentityNamingPlugin,
   InvalidIdentifierError,
+  NonConvergentSchemaDiffError,
   PgsqlAdapter,
+  PgsqlRawSqlTransactionControlError,
+  PgsqlTransactionAbortedCommitError,
+  PgsqlTransactionAbortedError,
   PlanCompiler,
+  assertNoRepeatedExpressionSurfaceDrift,
   bm25Search,
   booleanSearch,
   boost,
@@ -21109,7 +23750,9 @@ export {
   buildStreamingStatements,
   camelCaseNaming,
   canGenerateCreateIndex,
+  canonicalizeCheckConstraints,
   collectAndValidateParamRefs,
+  comparePgsqlDatabaseSchema,
   compareSchemata,
   compileDelete,
   compileInsert,