@homeflare/alchemy 0.46.0 → 0.47.0

package/src/postgres/schema-drop-2bp01.test.ts

@@ -11,12 +11,13 @@
  */
 import { describe, expect, test } from 'bun:test';
 import * as Effect from 'effect/Effect';
-import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { SqlError } from 'effect/sql/SqlError';
 import type { PgExecutor } from './database-sql.ts';
 import { classifyInstalled } from './installed-classifier.ts';
 import { postgresRunnerConnection } from './connection.ts';
 import { type PsqlRunner, makePsqlExecutor } from './psql-executor.ts';
 import { isDependentObjectsError } from './schema-sql.ts';
+import { stripPin } from './search-path.ts';
 import { PostgresSchemaDropNotEmptyError } from './schema-errors.ts';
 import { dropWithClient, postgresSchemaHandlers } from './schema.ts';
 import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
@@ -25,16 +26,16 @@ const baseProps: PostgresSchemaProps = { name: 'ledger', database: 'postgres', o
 
 const socket2bp01 = (): Promise<SqlError> => classifyInstalled('2BP01');
 
-/** Emptiness check says empty; the following DROP is the server's real `2BP01`. */
+/** The live row is ours; the atomic `DO` drop is the server's real `2BP01`. */
 const emptyThenRefuse = (drop: Effect.Effect<ReadonlyArray<object>, SqlError>): PgExecutor => ({
   unsafe: <A extends object>(text: string) => {
-    if (text.startsWith('SELECT current_database()')) {
-      return Effect.succeed([{ database: 'postgres' }] as unknown as ReadonlyArray<A>);
+    if (text.startsWith('DO ')) return drop as Effect.Effect<ReadonlyArray<A>, SqlError>;
+    if (text.includes('FROM pg_catalog.pg_namespace')) {
+      return Effect.succeed([
+        { name: 'ledger', oid: 1, owner: 'tim', comment: null, database: 'postgres' },
+      ] as unknown as ReadonlyArray<A>);
     }
-    if (text.includes('AS empty')) {
-      return Effect.succeed([{ empty: true }] as unknown as ReadonlyArray<A>);
-    }
-    return drop as Effect.Effect<ReadonlyArray<A>, SqlError>;
+    return Effect.succeed([{ database: 'postgres' }] as unknown as ReadonlyArray<A>);
   },
   transaction: () => Effect.void,
 });
@@ -54,12 +55,18 @@ describe('2BP01 classification', () => {
   });
 
   test('the runner transport classifies a verbose 2BP01 line as the typed not-empty tag', async () => {
-    const run: PsqlRunner = ({ stdin }) => {
-      if (stdin.includes('current_database()')) {
-        return Promise.resolve({ code: 0, stdout: '[{"database":"postgres"}]', stderr: '' });
+    const run: PsqlRunner = ({ stdin: raw }) => {
+      const stdin = stripPin(raw);
+      if (!stdin.startsWith('DO ') && stdin.includes('FROM pg_catalog.pg_namespace')) {
+        return Promise.resolve({
+          code: 0,
+          stdout:
+            '[{"name":"ledger","oid":"1","owner":"tim","comment":null,"database":"postgres"}]',
+          stderr: '',
+        });
       }
-      if (stdin.includes('AS empty')) {
-        return Promise.resolve({ code: 0, stdout: '[{"empty":true}]', stderr: '' });
+      if (!stdin.startsWith('DO ') && stdin.includes('current_database()')) {
+        return Promise.resolve({ code: 0, stdout: '[{"database":"postgres"}]', stderr: '' });
       }
       return Promise.resolve({
         code: 3,
@@ -92,18 +99,23 @@ describe('2BP01 classification', () => {
     // Order is load-bearing (schema-handlers.test.ts#route): the probe must answer PRESENT so
     // the absent-database short-circuit does not swallow the test, and the ownership re-read
     // must answer the row the persisted output vouches for, so the delete reaches the DROP.
-    const run: PsqlRunner = ({ stdin }) => {
-      if (stdin.includes('AS empty')) {
-        return Promise.resolve({ code: 0, stdout: '[{"empty":true}]', stderr: '' });
+    const run: PsqlRunner = ({ stdin: raw }) => {
+      const stdin = stripPin(raw);
+      if (stdin.startsWith('DO ')) {
+        return Promise.resolve({
+          code: 3,
+          stdout: '',
+          stderr: 'ERROR:  2BP01: dependent objects still exist\n',
+        });
       }
-      if (stdin.includes('FROM pg_namespace')) {
+      if (stdin.includes('FROM pg_catalog.pg_namespace')) {
         return Promise.resolve({
           code: 0,
           stdout: '[{"name":"ledger","oid":1,"owner":"tim"}]',
           stderr: '',
         });
       }
-      if (stdin.includes('FROM pg_database')) {
+      if (stdin.includes('FROM pg_catalog.pg_database')) {
         return Promise.resolve({ code: 0, stdout: '[{"present":1}]', stderr: '' });
       }
       if (stdin.includes('current_database()')) {

package/src/postgres/schema-drop-real.test.ts

@@ -0,0 +1,190 @@
+/**
+ * The atomic schema drop against a REAL PostgreSQL. The in-memory fake substitutes a COUNT for the
+ * dependency scan and cannot lock, so it cannot see the three defects Codex found in PR 357:
+ * an advisory lock that DDL ignores, a closure that missed `pg_collation`, and a TOAST table
+ * counted as foreign.
+ *
+ * ⛔ SKIPPED LOUDLY WITHOUT A SERVER. Set `HF_TEST_POSTGRES=1` and the libpq variables
+ *   (`PGHOST`, `PGUSER`, `PGDATABASE`, `PGPASSWORD` or a socket); the kit has no container
+ *   harness of its own (measured 2026-10-06: no podman/initdb use in `packages/alchemy` tests).
+ *   The connected role needs `CREATE` on the database. Every schema is uniquely named and dropped
+ *   on every exit path; nothing else is touched.
+ */
+import { afterAll, describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { type PsqlRunner, makePsqlExecutor } from './psql-executor.ts';
+import { PostgresSchemaCascadeCrossSchemaRefused } from './schema-errors.ts';
+import { PostgresSchemaCascadeSequencesRefused } from './schema-sequence-error.ts';
+import { dropWithClient } from './schema.ts';
+
+const enabled = process.env['HF_TEST_POSTGRES'] === '1';
+if (!enabled) {
+  console.warn(
+    'SKIPPED schema-drop-real.test.ts: no PostgreSQL. Set HF_TEST_POSTGRES=1 (+ PG* env) to run it.',
+  );
+}
+const suite = enabled ? describe : describe.skip;
+
+const database = process.env['PGDATABASE'] ?? 'postgres';
+const username = process.env['PGUSER'] ?? 'postgres';
+
+const spawnPsql = async (argv: readonly string[], stdin: string) => {
+  const proc = Bun.spawn([...argv], {
+    stdin: new TextEncoder().encode(stdin),
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, stdout, stderr };
+};
+const runner: PsqlRunner = ({ argv, stdin }) => spawnPsql(argv, stdin);
+const pg = makePsqlExecutor(runner, { database, username });
+const psql = (sql: string) =>
+  spawnPsql(
+    ['psql', '-X', '-q', '-A', '-t', '-v', 'ON_ERROR_STOP=1', '-U', username, '-d', database],
+    sql,
+  );
+
+const stamp = `${Date.now().toString(36)}${Math.floor(Math.random() * 1e4)}`;
+const names: string[] = [];
+const fresh = (label: string): string => {
+  const name = `hf_${label}_${stamp}`;
+  names.push(name);
+  return name;
+};
+afterAll(async () => {
+  if (!enabled) return;
+  for (const name of names) await psql(`DROP SCHEMA IF EXISTS "${name}" CASCADE;`);
+});
+
+const present = async (name: string): Promise<boolean> =>
+  (await psql(`SELECT count(*) FROM pg_namespace WHERE nspname = '${name}';`)).stdout.trim() ===
+  '1';
+const props = (name: string) => ({ name, database, cascade: true });
+
+suite('atomic drop on a real PostgreSQL', () => {
+  test("an isolated text table cascades: its TOAST relation is the table's", async () => {
+    const a = fresh('toast');
+    await psql(`CREATE SCHEMA "${a}"; CREATE TABLE "${a}".t (x text);`);
+    await Effect.runPromise(dropWithClient(pg, props(a)));
+    expect(await present(a)).toBe(false);
+  });
+
+  test("a collation used by another schema's table refuses the cascade", async () => {
+    const a = fresh('coll_a');
+    const b = fresh('coll_b');
+    await psql(
+      `CREATE SCHEMA "${a}"; CREATE COLLATION "${a}".c (provider = libc, locale = 'C');
+       CREATE SCHEMA "${b}"; CREATE TABLE "${b}".t (x text COLLATE "${a}".c);
+       INSERT INTO "${b}".t VALUES ('kept');`,
+    );
+    const error = await Effect.runPromise(Effect.flip(dropWithClient(pg, props(a))));
+    expect(error).toBeInstanceOf(PostgresSchemaCascadeCrossSchemaRefused);
+    expect(await present(a)).toBe(true);
+    expect((await psql(`SELECT x FROM "${b}".t;`)).stdout.trim()).toBe('kept');
+  });
+
+  test('a replacement attempted while the drop holds its locks waits and is refused', async () => {
+    const a = fresh('race');
+    await psql(`CREATE SCHEMA "${a}"; CREATE TABLE "${a}".t (x text);`);
+    // Holder: an open transaction reading the table keeps our LOCK TABLE waiting AFTER the
+    // schema-object lock is taken — a deterministic pause between lock and drop.
+    const holder = spawnPsql(
+      ['psql', '-X', '-q', '-v', 'ON_ERROR_STOP=1', '-U', username, '-d', database],
+      `BEGIN; SELECT 1 FROM "${a}".t; SELECT pg_sleep(4); COMMIT;`,
+    );
+    await Bun.sleep(700);
+    const drop = Effect.runPromise(dropWithClient(pg, props(a)));
+    // ⛔ MATCH THE WAIT BY ITS BLOCKER, NOT BY QUERY TEXT: `pg_stat_activity.query` is cut at
+    //   `track_activity_query_size` (1024 bytes by default) and the `DO` body's `LOCK TABLE`
+    //   sits past it, so a text match never fired and the rival ran after the drop had finished
+    //   (measured on PostgreSQL 18, 2026-10-06). A backend blocked by another one is the drop.
+    let parked = false;
+    for (let i = 0; i < 30 && !parked; i += 1) {
+      const waiting = await psql(
+        `SELECT count(*) FROM pg_stat_activity WHERE wait_event_type = 'Lock' AND cardinality(pg_catalog.pg_blocking_pids(pid)) > 0 AND query LIKE 'DO %' AND pid <> pg_backend_pid();`,
+      );
+      parked = waiting.stdout.trim() !== '0';
+      if (!parked) await Bun.sleep(100);
+    }
+    expect(parked).toBe(true);
+    // The drop is now parked holding the namespace lock. A competing DROP + CREATE must not get in.
+    const rival = await psql(
+      `SET lock_timeout = '800ms'; BEGIN; DROP SCHEMA "${a}" CASCADE; CREATE SCHEMA "${a}"; COMMIT;`,
+    );
+    expect(rival.code).not.toBe(0);
+    expect(rival.stderr).toContain('lock timeout');
+    await holder;
+    await drop;
+    expect(await present(a)).toBe(false);
+  });
+
+  test('a cascade of a schema holding a sequence refuses and loses nothing', async () => {
+    const a = fresh('seq_a');
+    const b = fresh('seq_b');
+    await psql(
+      `CREATE SCHEMA "${a}"; CREATE TABLE "${a}".t (id serial, x text);
+       INSERT INTO "${a}".t (x) VALUES ('kept');
+       CREATE SCHEMA "${b}"; CREATE VIEW "${b}".v AS SELECT last_value FROM "${a}".t_id_seq;`,
+    );
+    const error = await Effect.runPromise(Effect.flip(dropWithClient(pg, props(a))));
+    expect(error).toBeInstanceOf(PostgresSchemaCascadeSequencesRefused);
+    expect(error).toMatchObject({ schema: a, sequences: 1 });
+    expect(await present(a)).toBe(true);
+    expect((await psql(`SELECT x FROM "${a}".t;`)).stdout.trim()).toBe('kept');
+    expect((await psql(`SELECT count(*) FROM "${b}".v;`)).stdout.trim()).toBe('1');
+  });
+
+  test('a table added to a foreign extension refuses the cascade (ownership edge leaves)', async () => {
+    const a = fresh('ext_a');
+    const b = fresh('ext_b');
+    await psql(
+      `CREATE SCHEMA "${b}"; CREATE EXTENSION hstore SCHEMA "${b}";
+       CREATE SCHEMA "${a}"; CREATE TABLE "${a}".t (id int);
+       ALTER EXTENSION hstore ADD TABLE "${a}".t;`,
+    );
+    try {
+      const error = await Effect.runPromise(Effect.flip(dropWithClient(pg, props(a))));
+      expect(error).toBeInstanceOf(PostgresSchemaCascadeCrossSchemaRefused);
+      expect(await present(a)).toBe(true);
+      const kept = await psql(`SELECT count(*) FROM pg_extension WHERE extname = 'hstore';`);
+      expect(kept.stdout.trim()).toBe('1');
+    } finally {
+      await psql(`ALTER EXTENSION hstore DROP TABLE "${a}".t; DROP EXTENSION IF EXISTS hstore;`);
+    }
+  });
+
+  test('a rename-then-recreate while the drop is parked is refused, the replacement survives', async () => {
+    const a = fresh('ren');
+    const saved = fresh('ren_saved');
+    await psql(`CREATE SCHEMA "${a}"; CREATE TABLE "${a}".t (x text);`);
+    const holder = spawnPsql(
+      ['psql', '-X', '-q', '-v', 'ON_ERROR_STOP=1', '-U', username, '-d', database],
+      `BEGIN; SELECT 1 FROM "${a}".t; SELECT pg_sleep(4); COMMIT;`,
+    );
+    await Bun.sleep(700);
+    const drop = Effect.runPromise(Effect.flip(dropWithClient(pg, props(a))));
+    let parked = false;
+    for (let i = 0; i < 30 && !parked; i += 1) {
+      const waiting = await psql(
+        `SELECT count(*) FROM pg_stat_activity WHERE wait_event_type = 'Lock' AND cardinality(pg_catalog.pg_blocking_pids(pid)) > 0 AND query LIKE 'DO %' AND pid <> pg_backend_pid();`,
+      );
+      parked = waiting.stdout.trim() !== '0';
+      if (!parked) await Bun.sleep(100);
+    }
+    expect(parked).toBe(true);
+    // RENAME takes no namespace object lock, so it commits while the drop waits.
+    const swap = await psql(
+      `ALTER SCHEMA "${a}" RENAME TO "${saved}"; CREATE SCHEMA "${a}"; CREATE TABLE "${a}".keep (id int);`,
+    );
+    expect(swap.code).toBe(0);
+    await holder;
+    await drop;
+    expect((await psql(`SELECT count(*) FROM "${a}".keep;`)).stdout.trim()).toBe('0');
+    expect(await present(saved)).toBe(true);
+  });
+});

package/src/postgres/schema-drop-sql.ts

@@ -0,0 +1,135 @@
+/**
+ * The atomic `DROP SCHEMA` `Postgres.Schema` issues: ONE `DO` statement that takes a lock,
+ * re-proves the schema inside the same transaction, refuses what must not be dropped, and only
+ * then drops.
+ *
+ * ⛔ PROOF AND DROP ARE ONE STATEMENT, ONE TRANSACTION. Before 2026-10-02 the re-read, the
+ *   emptiness check and the `DROP` were three autocommit statements — three `psql` processes on
+ *   the runner transport — so an out-of-band drop-and-recreate between them was dropped by name,
+ *   `CASCADE` included (Opus read of PR 334). A `DO` block is atomic on both transports and needs
+ *   no `BEGIN`/`COMMIT` the runner would have to thread through.
+ * ⛔ THE LOCK MUST CONFLICT WITH DDL, NOT ONLY WITH OTHER RUNS OF THIS PROVIDER. An advisory lock
+ *   (`pg_advisory_xact_lock`) is cooperative: an ordinary `DROP SCHEMA` + `CREATE SCHEMA` ignores
+ *   it, and the by-name `DROP` below would then drop the REPLACEMENT, `CASCADE` included (Codex
+ *   read of PR 357, 2026-10-06). So, BEFORE the re-verify and held to the end of the transaction:
+ *   (1) `COMMENT ON SCHEMA <name> IS <its current comment>` — `CommentObject` resolves the schema
+ *   through `get_object_address(…, ShareUpdateExclusiveLock)`, which locks the namespace OBJECT
+ *   (`LockDatabaseObject`), and `DROP SCHEMA` takes `AccessExclusiveLock` on that same object
+ *   (`AcquireDeletionLock`), so a concurrent drop waits for us; (2) on a cascade, `LOCK TABLE …
+ *   IN ACCESS EXCLUSIVE MODE` on every table-like relation in the schema, which holds off a
+ *   concurrent creator of a dependent (a view or foreign key reads the table it references).
+ *   Lock modes: PostgreSQL docs, explicit-locking.html §13.3; `COMMENT`: sql-comment.html.
+ *   `lock_timeout` turns any wait into `55P03`, an unclassified error: the drop is REFUSED, never
+ *   forced. A comment-less schema is rewritten as `IS NULL`, which still takes the lock.
+ * ⛔ RENAME TAKES NO SUCH LOCK (Codex read of PR 357, 2026-10-06): `ALTER SCHEMA … RENAME` updates
+ *   `pg_namespace` without locking the object, so a rename-then-`CREATE SCHEMA` of the same name
+ *   committed while we waited on a table lock would make the by-name `DROP` delete the
+ *   REPLACEMENT. The last statement before the `DROP` re-reads the name of the verified OID and
+ *   refuses `HF001` if it moved; only the statements between that read and the `DROP` remain.
+ * ⛔ SEQUENCES REFUSE THE CASCADE (`HF004`, KNOWN LIMIT; `schema-sequence-error.ts`). `LOCK TABLE`
+ *   cannot lock a sequence, so an uncommitted `CREATE VIEW b.v AS SELECT last_value FROM a.s` is
+ *   invisible to the closure scan, and PostgreSQL's deletion (locks first, THEN scans dependents)
+ *   would cascade into `b.v` once it commits. A schema with serial or identity columns therefore
+ *   cannot be cascade-dropped here: drop its contents first. The check runs before any table lock.
+ * ⚠️ NOT COVERED: a type,
+ *   function or collation created in ANOTHER schema to use ours has no relation to wait on. The
+ *   advisory lock stays: it serialises runs of this provider, which is cheap and correct.
+ * ★ THE VALUES ARE LITERALS INSIDE THE BODY, AND THE BODY IS ONE `E'…'` LITERAL. A `DO` body
+ *   takes no bind parameters, and a dollar-quote tag could be forged by a schema NAME containing
+ *   it; `quoteStringLiteral` doubles backslashes and quotes, so nesting it twice is exact.
+ *   The `DROP` text inside is `buildDropSchemaSql` run through `EXECUTE`, so the quoting rule is
+ *   the same single one.
+ * ★ REFUSALS ARE CUSTOM SQLSTATEs, read from `reason.cause.code` exactly like `2BP01`
+ *   (`schema-sql.ts#isDependentObjectsError`): `HF001` identity changed, `HF002` not empty,
+ *   `HF003` dependents in another schema, `HF004` a cascade over a schema holding a sequence. Class `HF` is not `42`, so both transports wrap it as
+ *   `UnknownError` with the raw code. The `HF003` message carries a COUNT only: another owner's
+ *   object names must not reach this stack's logs.
+ */
+import type { SqlError } from 'effect/sql/SqlError';
+import { quoteStringLiteral } from './database-sql.ts';
+import { OUTSIDE_DEPENDENTS_SQL } from './schema-closure-sql.ts';
+import { buildDropSchemaSql, emptyPredicate } from './schema-sql.ts';
+
+export const IDENTITY_CHANGED = 'HF001';
+export const NOT_EMPTY = 'HF002';
+export const CROSS_SCHEMA_DEPENDENTS = 'HF003';
+export const CASCADE_SEQUENCES = 'HF004';
+
+/** How long any lock in the block may wait before the drop is refused (`55P03`, fails closed). */
+const LOCK_TIMEOUT = '10s';
+
+export interface AtomicDrop {
+  readonly name: string;
+  readonly oid: number;
+  readonly owner: string;
+  readonly cascade: boolean;
+}
+
+/** The whole atomic drop: lock → re-verify → refuse or drop. Pure text, no client. */
+export const buildAtomicDropSql = (drop: AtomicDrop): string => {
+  const body = `DECLARE
+  v_name text := ${quoteStringLiteral(drop.name)};
+  v_oid oid := ${String(Math.trunc(drop.oid))};
+  v_owner text := ${quoteStringLiteral(drop.owner)};
+  v_cascade boolean := ${drop.cascade ? 'true' : 'false'};
+  v_ns oid;
+  v_count bigint;
+  v_comment text;
+  v_rel text;
+BEGIN
+  SELECT n.oid INTO v_ns FROM pg_catalog.pg_namespace n WHERE n.nspname = v_name;
+  IF v_ns IS NULL THEN RETURN; END IF;
+  PERFORM pg_catalog.set_config('lock_timeout', '${LOCK_TIMEOUT}', true);
+  PERFORM pg_catalog.pg_advisory_xact_lock(v_ns::pg_catalog.int8);
+  v_comment := pg_catalog.obj_description(v_ns, 'pg_namespace');
+  EXECUTE pg_catalog.format('COMMENT ON SCHEMA %I IS %L', v_name, v_comment);
+  SELECT n.oid INTO v_ns FROM pg_catalog.pg_namespace n
+    WHERE n.nspname = v_name AND n.oid = v_oid
+      AND pg_catalog.pg_get_userbyid(n.nspowner) = v_owner;
+  IF v_ns IS NULL THEN
+    RAISE EXCEPTION 'schema identity changed' USING ERRCODE = '${IDENTITY_CHANGED}';
+  END IF;
+  IF NOT v_cascade THEN
+    IF NOT (${emptyPredicate('v_ns')}) THEN
+      RAISE EXCEPTION 'schema not empty' USING ERRCODE = '${NOT_EMPTY}';
+    END IF;
+  ELSE
+    SELECT count(*) INTO v_count FROM pg_catalog.pg_class c
+      WHERE c.relnamespace = v_ns AND c.relkind = 'S';
+    IF v_count > 0 THEN
+      RAISE EXCEPTION 'cascade sequences: %', v_count USING ERRCODE = '${CASCADE_SEQUENCES}';
+    END IF;
+    FOR v_rel IN SELECT c.oid::pg_catalog.regclass::pg_catalog.text FROM pg_catalog.pg_class c
+        WHERE c.relnamespace = v_ns AND c.relkind IN ('r', 'p', 'v', 'm', 'f') ORDER BY c.oid LOOP
+      EXECUTE pg_catalog.format('LOCK TABLE %s IN ACCESS EXCLUSIVE MODE', v_rel);
+    END LOOP;
+    ${OUTSIDE_DEPENDENTS_SQL};
+    IF v_count > 0 THEN
+      RAISE EXCEPTION 'cross-schema dependents: %', v_count USING ERRCODE = '${CROSS_SCHEMA_DEPENDENTS}';
+    END IF;
+  END IF;
+  PERFORM 1 FROM pg_catalog.pg_namespace n WHERE n.oid = v_oid AND n.nspname = v_name;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'schema identity changed' USING ERRCODE = '${IDENTITY_CHANGED}';
+  END IF;
+  EXECUTE ${quoteStringLiteral(buildDropSchemaSql(drop.name, drop.cascade))};
+END`;
+  return `DO ${quoteStringLiteral(body)}`;
+};
+
+/** The server's SQLSTATE on a failed statement, whichever transport raised it. */
+export const sqlStateOf = (error: SqlError): string | undefined => {
+  const cause = error.reason.cause;
+  const code =
+    typeof cause === 'object' && cause !== null ? (cause as { code?: unknown }).code : '';
+  return typeof code === 'string' ? code : undefined;
+};
+
+/** The dependents COUNT out of an `HF003` error. An unreadable message still refuses: it
+ * answers 1, never 0 — the refusal is the fail-closed answer. */
+export const dependentsCount = (error: SqlError): number => {
+  const cause = error.reason.cause;
+  const message = typeof cause === 'object' && cause !== null ? (cause as Error).message : '';
+  const parsed = /dependents:\s*(\d+)/.exec(message ?? '')?.[1];
+  return Math.max(1, Number(parsed ?? 1));
+};

package/src/postgres/schema-drop.test.ts

@@ -0,0 +1,241 @@
+/**
+ * `Postgres.Schema`'s atomic drop (`schema-drop-sql.ts`) against `fake-sql.ts`: one `DO`
+ * statement that re-verifies identity under a lock, refuses a non-empty schema or cross-schema
+ * dependents, and only then drops. The Opus read of PR 334 (2026-10-02) found the old
+ * three-autocommit drop racy, and `cascade: true` reaching other stacks' objects.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { SqlError, UnknownError } from 'effect/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+import { makeFakeSql } from './fake-sql.ts';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+import { buildAtomicDropSql } from './schema-drop-sql.ts';
+import {
+  PostgresSchemaCascadeCrossSchemaRefused,
+  PostgresSchemaDeleteForeignRefused,
+  PostgresSchemaDropNotEmptyError,
+} from './schema-errors.ts';
+import { PostgresSchemaCascadeSequencesRefused } from './schema-sequence-error.ts';
+import { deleteWithClient, dropWithClient } from './schema.ts';
+
+const run = <A, E>(eff: Effect.Effect<A, E>): Promise<A> => Effect.runPromise(eff);
+const fails = <A, E>(eff: Effect.Effect<A, E>): Promise<E> => Effect.runPromise(Effect.flip(eff));
+
+const baseProps: PostgresSchemaProps = { name: 'ledger', database: 'postgres', owner: 'tim' };
+const liveRow = (over: Partial<PostgresSchemaAttributes> = {}): PostgresSchemaAttributes => ({
+  name: 'ledger',
+  database: 'postgres',
+  oid: 30000,
+  owner: 'tim',
+  comment: null,
+  ...over,
+});
+const drops = (fake: ReturnType<typeof makeFakeSql>) =>
+  fake.statements.filter((s) => s.text.startsWith('DO '));
+
+describe('drop: the proof and the DROP are one statement', () => {
+  test('an empty schema is dropped by ONE DO carrying the proven oid and owner', async () => {
+    const fake = makeFakeSql({ schemas: [liveRow()] });
+    await run(dropWithClient(fake, baseProps));
+    expect(drops(fake).map((s) => s.text)).toEqual([
+      buildAtomicDropSql({ name: 'ledger', oid: 30000, owner: 'tim', cascade: false }),
+    ]);
+    // No bare DROP and no separate emptiness probe reached the server.
+    expect(fake.statements.some((s) => s.text.startsWith('DROP SCHEMA'))).toBe(false);
+    expect(fake.statements.some((s) => s.text.includes('AS empty'))).toBe(false);
+    expect(fake.schemas.get('ledger')).toBeUndefined();
+  });
+
+  test('the block locks BEFORE it re-verifies, re-verifies oid + owner, and drops last', () => {
+    const sql = buildAtomicDropSql({ name: 'ledger', oid: 30000, owner: 'tim', cascade: false });
+    const at = (needle: string): number => sql.indexOf(needle);
+    expect(at('pg_advisory_xact_lock')).toBeGreaterThan(-1);
+    expect(at('pg_advisory_xact_lock')).toBeLessThan(at('n.oid = v_oid'));
+    expect(at('pg_get_userbyid(n.nspowner) = v_owner')).toBeGreaterThan(-1);
+    // The DDL-conflicting lock (a no-op COMMENT on the schema object) precedes the re-verify too.
+    expect(at('COMMENT ON SCHEMA %I')).toBeGreaterThan(-1);
+    expect(at('COMMENT ON SCHEMA %I')).toBeLessThan(at('n.oid = v_oid'));
+    expect(at("''lock_timeout''")).toBeLessThan(at('pg_advisory_xact_lock'));
+    expect(at('n.oid = v_oid')).toBeLessThan(sql.lastIndexOf('EXECUTE'));
+  });
+
+  test('a schema replaced between the read and the drop is refused, nothing dropped (HF001)', async () => {
+    const fake = makeFakeSql({ schemas: [liveRow()] });
+    // The read sees oid 30000; before the DO runs another role drops and recreates the name.
+    const racing: PgExecutor = {
+      ...fake,
+      unsafe: (text, params) => {
+        if (text.startsWith('DO ')) {
+          fake.schemas.set('ledger', liveRow({ oid: 30001, owner: 'intruder' }));
+        }
+        return fake.unsafe(text, params);
+      },
+    };
+    const error = await fails(deleteWithClient(racing, baseProps, liveRow()));
+    expect(error).toBeInstanceOf(PostgresSchemaDeleteForeignRefused);
+    expect(error).toMatchObject({ liveOid: 30001, liveOwner: 'intruder', lastOid: 30000 });
+    expect(fake.schemas.get('ledger')).toMatchObject({ oid: 30001 });
+  });
+
+  test('a schema that vanished between the read and the drop is idempotent success', async () => {
+    const fake = makeFakeSql({ schemas: [liveRow()] });
+    const racing: PgExecutor = {
+      ...fake,
+      unsafe: (text, params) => {
+        if (text.startsWith('DO ')) fake.schemas.delete('ledger');
+        return fake.unsafe(text, params);
+      },
+    };
+    await run(dropWithClient(racing, baseProps));
+  });
+});
+
+describe('drop: emptiness', () => {
+  test('refuses a non-empty schema with cascade false (HF002 → typed tag)', async () => {
+    const fake = makeFakeSql({ schemas: [liveRow()], schemasWithRelations: ['ledger'] });
+    expect(await fails(dropWithClient(fake, baseProps))).toBeInstanceOf(
+      PostgresSchemaDropNotEmptyError,
+    );
+    expect(fake.schemas.get('ledger')).not.toBeUndefined();
+  });
+
+  test('drops a non-empty schema with cascade true when nothing outside depends on it', async () => {
+    const fake = makeFakeSql({ schemas: [liveRow()], schemasWithRelations: ['ledger'] });
+    await run(dropWithClient(fake, { ...baseProps, cascade: true }));
+    expect(fake.schemas.get('ledger')).toBeUndefined();
+    expect(drops(fake)[0]?.text).toContain(`'DROP SCHEMA IF EXISTS "ledger" CASCADE'`);
+  });
+
+  test("the server's own 2BP01 (an object kind the four catalogs miss) is the same typed tag", async () => {
+    const refusing: PgExecutor = {
+      unsafe: <A extends object>(text: string) =>
+        text.startsWith('SELECT current_database()')
+          ? Effect.succeed([{ database: 'postgres' }] as unknown as ReadonlyArray<A>)
+          : !text.startsWith('DO ') && text.includes('FROM pg_catalog.pg_namespace')
+            ? Effect.succeed([liveRow()] as unknown as ReadonlyArray<A>)
+            : Effect.fail(
+                new SqlError({
+                  reason: new UnknownError({
+                    cause: Object.assign(new Error('ERROR:  2BP01: dependent objects'), {
+                      code: '2BP01',
+                    }),
+                    message: 'dependent_objects_still_exist',
+                    operation: 'DO',
+                  }),
+                }),
+              ),
+      transaction: () => Effect.void,
+    };
+    expect(await fails(dropWithClient(refusing, baseProps))).toBeInstanceOf(
+      PostgresSchemaDropNotEmptyError,
+    );
+  });
+});
+
+describe('drop: cascade never reaches another schema', () => {
+  test('refuses cascade when objects in other schemas depend on this one — count only (HF003)', async () => {
+    const fake = makeFakeSql({
+      schemas: [liveRow()],
+      schemasWithRelations: ['ledger'],
+      dependentsOutside: { ledger: 3 },
+    });
+    const error = await fails(dropWithClient(fake, { ...baseProps, cascade: true }));
+    expect(error).toBeInstanceOf(PostgresSchemaCascadeCrossSchemaRefused);
+    expect(error).toMatchObject({ schema: 'ledger', dependents: 3 });
+    // The message names a count and this schema — never another owner's object.
+    expect((error as Error).message).toContain('3 dependent object(s)');
+    expect(fake.schemas.get('ledger')).not.toBeUndefined();
+    expect(fake.relationsIn.has('ledger')).toBe(true);
+  });
+
+  test('refuses cascade over a schema holding a sequence — count only (HF004), nothing dropped', async () => {
+    const fake = makeFakeSql({
+      schemas: [liveRow()],
+      schemasWithRelations: ['ledger'],
+      sequencesIn: { ledger: 2 },
+    });
+    const error = await fails(dropWithClient(fake, { ...baseProps, cascade: true }));
+    expect(error).toBeInstanceOf(PostgresSchemaCascadeSequencesRefused);
+    expect(error).toMatchObject({ schema: 'ledger', sequences: 2 });
+    expect((error as Error).message).toContain('2 sequence(s)');
+    expect(fake.schemas.get('ledger')).not.toBeUndefined();
+    expect(fake.relationsIn.has('ledger')).toBe(true);
+  });
+
+  test('the sequence check precedes every table lock in the generated block', () => {
+    const sql = buildAtomicDropSql({ name: 'ledger', oid: 1, owner: 'tim', cascade: true });
+    expect(sql).toContain("c.relkind = ''S''");
+    expect(sql.indexOf("c.relkind = ''S''")).toBeLessThan(sql.indexOf('LOCK TABLE'));
+  });
+
+  test('cascade false never runs the dependents check: the emptiness refusal comes first', async () => {
+    const fake = makeFakeSql({
+      schemas: [liveRow()],
+      schemasWithRelations: ['ledger'],
+      dependentsOutside: { ledger: 3 },
+    });
+    expect(await fails(dropWithClient(fake, baseProps))).toBeInstanceOf(
+      PostgresSchemaDropNotEmptyError,
+    );
+  });
+
+  test('the dependents query counts per catalog class and treats an unknown class as foreign', () => {
+    const sql = buildAtomicDropSql({ name: 'ledger', oid: 1, owner: 'tim', cascade: true });
+    expect(sql).toContain('pg_catalog.pg_depend');
+    // A class the CASE does not know yields NULL; IS DISTINCT FROM counts NULL as foreign, so an
+    // unclassifiable dependent refuses the cascade instead of slipping through.
+    expect(sql).toContain('IS NOT DISTINCT FROM v_ns');
+    // The walk follows every deptype except the pin (`p`): n a i P S e x each cascade or attribute.
+    expect(sql).toContain("d.deptype <> ''p''");
+    for (const catalog of [
+      'pg_collation',
+      'pg_conversion',
+      'pg_opclass',
+      'pg_opfamily',
+      'pg_ts_config',
+      'pg_statistic_ext',
+      'pg_extension',
+      'pg_constraint',
+      'pg_trigger',
+      'pg_rewrite',
+      'pg_attrdef',
+      'pg_policy',
+    ]) {
+      // Inside the body's `E'…'` literal every quote is doubled.
+      expect(sql).toContain(`''pg_catalog.${catalog}''::pg_catalog.regclass`);
+    }
+  });
+});
+
+describe('drop: the generated text cannot be broken out of by a name', () => {
+  test('a schema name holding quotes, backslashes and a dollar-quote tag stays inside its literal', () => {
+    const name = `x$$; DROP TABLE t; --'\\"`;
+    const sql = buildAtomicDropSql({ name, oid: 1, owner: `o'wn\\er`, cascade: false });
+    expect(sql.startsWith("DO E'")).toBe(true);
+    expect(sql.endsWith("'")).toBe(true);
+    // No unescaped quote before the final one: every `'` inside is doubled by the quoter.
+    expect(sql.slice(5, -1).replace(/''/g, '')).not.toContain("'");
+  });
+
+  test('applyAtomicDrop reads such a name and owner back exactly (fake parses its own output)', async () => {
+    const name = `x$$; DROP TABLE t; --'\\"`;
+    const owner = `o'wn\\er$tag$`;
+    const fake = makeFakeSql({ schemas: [liveRow({ name, owner })] });
+    await run(dropWithClient(fake, { name, database: 'postgres' }));
+    expect(fake.schemas.get(name)).toBeUndefined();
+    // A different owner with the same tricky name is a refusal, not a by-name drop.
+    const other = makeFakeSql({ schemas: [liveRow({ name, owner: 'someone' })] });
+    const racing: PgExecutor = {
+      ...other,
+      unsafe: (text, params) => {
+        if (text.startsWith('DO ')) other.schemas.set(name, liveRow({ name, owner }));
+        return other.unsafe(text, params);
+      },
+    };
+    await fails(
+      deleteWithClient(racing, { name, database: 'postgres' }, liveRow({ name, owner: 'someone' })),
+    );
+    expect(other.schemas.get(name)).toBeDefined();
+  });
+});