@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/fake-grants-write.ts

@@ -0,0 +1,90 @@
+/**
+ * The write-semantics half of the `Postgres.Grants` test fake, extracted from
+ * `fake-grants-sql.ts` (the factory and the statement parser) to keep both files under the
+ * cap: how one `GRANT`/`REVOKE` edits the in-memory ACL with the server's rule that a
+ * superuser, the owner itself, or a member of the owning role performs the command AS the
+ * owner (`select_best_grantor`, acl.c@REL_18_6; `revoke.sgml@REL_18_6`).
+ *
+ * ★ THE EFFECTIVE GRANTOR. `effectiveGrantor` names the role a write is recorded as: the
+ *   owner when the executor acts as owner, otherwise the executor. A relation (table, column)
+ *   is owned by its `relowner`; a schema by its `nspowner`; a default ACL has no owner, so the
+ *   executor's own grants are the only ones its writes touch.
+ * ★ `GRANT` records the words on the effective grantor's entry, upgrading a base word to its
+ *   `*` (WITH GRANT OPTION) form rather than keeping both — one `aclitem` per pair.
+ * ★ `REVOKE ALL` removes the effective grantor's entry only: a third grantor's grant to the
+ *   same grantee SURVIVES silently (the survival `PostgresGrantsRepairRefused` surfaces), and
+ *   a grantee that re-granted onward fails like the server without CASCADE (`2BP01`).
+ */
+import { SqlError, SqlSyntaxError } from 'effect/unstable/sql/SqlError';
+import type { AclObject } from './fake-grants-parse.ts';
+import { type FakeGrantsModel, revokesAsOwner } from './fake-grants-read.ts';
+
+const sameObject = (a: AclObject, b: AclObject): boolean =>
+  a.schema === b.schema &&
+  a.table === b.table &&
+  a.column === b.column &&
+  a.defaultFor === b.defaultFor;
+
+/** The role a `GRANT`/`REVOKE` from the executor on `object` is performed AS (see the header). */
+export const effectiveGrantor = (model: FakeGrantsModel, object: AclObject): string => {
+  if (object.table !== undefined) {
+    const owner = model.tableOwners.get(`${object.schema}\u0000${object.table}`) ?? model.executor;
+    return revokesAsOwner(model, owner) ? owner : model.executor;
+  }
+  if (object.defaultFor === undefined) {
+    const owner = model.schemaOwners.get(object.schema) ?? model.executor;
+    return revokesAsOwner(model, owner) ? owner : model.executor;
+  }
+  return model.executor;
+};
+
+/** Add words to the (object, grantee, effective-grantor) entry, upgrading a base word to its
+ * `*` form rather than keeping both. */
+export const grantWords = (
+  model: FakeGrantsModel,
+  object: AclObject,
+  grantee: string,
+  words: ReadonlyArray<string>,
+  option: boolean,
+): void => {
+  const grantor = effectiveGrantor(model, object);
+  const acl = model.acl;
+  let entry = acl.find(
+    (e) => sameObject(e.object, object) && e.grantee === grantee && e.grantor === grantor,
+  );
+  if (entry === undefined) {
+    entry = { object, grantee, grantor, words: [] };
+    acl.push(entry);
+  }
+  for (const word of words) {
+    const base = word.replace(/\*$/, '');
+    entry.words = entry.words.filter((w) => w.replace(/\*$/, '') !== base);
+    entry.words.push(option ? `${word}*` : word);
+  }
+};
+
+/** Remove the effective grantor's grants for (object, grantee); a third grantor's entry
+ * survives by the keying, and a grantee that re-granted onward fails without CASCADE. */
+export const revoke = (
+  model: FakeGrantsModel,
+  object: AclObject,
+  grantee: string,
+  operation: string,
+): SqlError | undefined => {
+  const grantor = effectiveGrantor(model, object);
+  const acl = model.acl;
+  const own = acl.filter(
+    (e) => sameObject(e.object, object) && e.grantee === grantee && e.grantor === grantor,
+  );
+  if (own.length > 0 && acl.some((e) => sameObject(e.object, object) && e.grantor === grantee)) {
+    return new SqlError({
+      reason: new SqlSyntaxError({
+        cause: Object.assign(new Error('dependent privileges exist'), { code: '2BP01' }),
+        message: 'dependent privileges exist',
+        operation,
+      }),
+    });
+  }
+  for (const entry of own) acl.splice(acl.indexOf(entry), 1);
+  return undefined;
+};

package/src/postgres/fake-role-sql.ts

@@ -0,0 +1,240 @@
+/**
+ * The `Postgres.Role` half of `fake-sql.ts`: the in-memory `pg_roles` / `pg_auth_members` catalog
+ * and every statement branch that touches it, split out so each fake file serves one family.
+ *
+ * ⛔ IT PARSES ITS OWN OUTPUT, NOT SQL IN GENERAL (the rule `fake-sql.ts` documents). Every
+ *   parser here understands exactly the text `role-sql.ts` produces — quoted with `quoteIdent` /
+ *   `quoteStringLiteral` — because that is the only `CREATE ROLE`, per-field `ALTER ROLE`,
+ *   `GRANT`, `REVOKE` and `DROP ROLE` this family ever issues. A general SQL parser would hide a
+ *   quoting bug instead of tripping over it.
+ * ★ THE DEDICATED PASSWORD `ALTER ROLE … WITH PASSWORD` IS RECORDED, NEVER PARSED: `pg_roles`
+ *   answers no password value (S25), so the fake stores none either — the seal lives only in the
+ *   attributes a test seeds or a reconcile returns.
+ */
+import * as Effect from 'effect/Effect';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { PostgresRoleAttributes } from './role-attrs.ts';
+import { unquoteIdent, unquoteLiteral } from './fake-sql-quote.ts';
+
+/** The role catalog `fake-sql.ts` constructs and shares with its callers: seeded by a test, then
+ * mutated by the statements this module applies. */
+export interface FakeRoleState {
+  /** Bare role names, backing the `roleExists` check the database family's owner probe uses. */
+  readonly roleNames: Set<string>;
+  readonly roleRows: Map<string, PostgresRoleAttributes>;
+  /** `member\0parent\0grantor` triples backing `pg_auth_members` (`''` grantor = unresolvable
+   * grantor); `GRANT`/`REVOKE` mutate it. */
+  readonly memberships: Set<string>;
+  /** Options a name-only compare would hide, keyed `member\0parent\0grantor`. */
+  readonly membershipOptions: Map<
+    string,
+    { readonly admin: boolean; readonly set: boolean; readonly inherit?: boolean }
+  >;
+  /** Hands out the next `oid` a real cluster would assign. */
+  nextOid(): number;
+}
+
+type RoleRow = Omit<PostgresRoleAttributes, 'memberOf' | 'passwordSeal'>;
+
+/** Pull every field back out of exactly the text `buildCreateRoleSql` writes. The password never
+ * rides a `CREATE ROLE`, so this parses no secret. */
+const parseCreateRole = (text: string): RoleRow => {
+  const name = /^CREATE ROLE "((?:[^"]|"")*)" WITH /.exec(text);
+  const login = /(?:^| )(NOLOGIN|LOGIN)(?: |$)/.exec(text);
+  const inherit = /(?:^| )(NOINHERIT|INHERIT)(?: |$)/.exec(text);
+  const limit = /CONNECTION LIMIT (-?\d+)/.exec(text);
+  const until = /VALID UNTIL E'((?:[^']|'')*)'/.exec(text);
+  if (name === null) {
+    throw new Error(`fake-sql: could not parse a generated CREATE ROLE statement: ${text}`);
+  }
+  return {
+    name: unquoteIdent(name[1] as string),
+    oid: 0,
+    login: login?.[1] !== 'NOLOGIN',
+    inherit: inherit?.[1] !== 'NOINHERIT',
+    connectionLimit: limit === null ? -1 : Number(limit[1]),
+    validUntil: until === null ? null : unquoteLiteral(until[1] as string),
+  };
+};
+
+/** A per-field `ALTER ROLE … WITH …`, parsed back into the one scalar it changes. */
+const parseAlterRole = (text: string): Partial<RoleRow> => {
+  const name = /^ALTER ROLE "((?:[^"]|"")*)" WITH /.exec(text);
+  if (name === null) {
+    throw new Error(`fake-sql: could not parse a generated ALTER ROLE statement: ${text}`);
+  }
+  const who = unquoteIdent(name[1] as string);
+  const until = /VALID UNTIL E'((?:[^']|'')*)'/.exec(text);
+  const limit = /CONNECTION LIMIT (-?\d+)/.exec(text);
+  const login = /(?:^| )(NOLOGIN|LOGIN)(?: |$)/.exec(text);
+  const inherit = /(?:^| )(NOINHERIT|INHERIT)(?: |$)/.exec(text);
+  // The dedicated password statement carries no catalog-visible field; it is recorded by text
+  // only and never parsed back, because pg_roles answers no password value (S25).
+  if (/ PASSWORD /.test(text)) return { name: who };
+  if (until !== null) return { name: who, validUntil: unquoteLiteral(until[1] as string) };
+  if (limit !== null) return { name: who, connectionLimit: Number(limit[1]) };
+  if (login !== null) return { name: who, login: login[1] !== 'NOLOGIN' };
+  if (inherit !== null) return { name: who, inherit: inherit[1] !== 'NOINHERIT' };
+  throw new Error(`fake-sql: unrecognised ALTER ROLE field: ${text}`);
+};
+
+const EMPTY_ROLE: RoleRow = {
+  name: '',
+  oid: 0,
+  login: false,
+  connectionLimit: -1,
+  inherit: true,
+  validUntil: null,
+};
+
+/**
+ * Every `Postgres.Role` statement and both role reads, applied against the fake catalog. Answers
+ * the effect the statement produces — `undefined` when the text belongs to another family, so
+ * `fake-sql.ts` can fall through to its own branches.
+ */
+export const applyRoleStatement = <A extends object>(
+  state: FakeRoleState,
+  text: string,
+  params: ReadonlyArray<unknown>,
+): Effect.Effect<ReadonlyArray<A>, SqlError> | undefined => {
+  if (text.includes('FROM pg_auth_members')) {
+    const member = params[0] as string;
+    const rows = [...state.memberships]
+      .filter((key) => key.split('\0')[0] === member)
+      .map((key) => {
+        const parts = key.split('\0');
+        const options = state.membershipOptions.get(key);
+        return {
+          parent: parts[1] as string,
+          grantor: parts[2] === undefined || parts[2] === '' ? null : (parts[2] as string),
+          admin: options?.admin === true,
+          set: options?.set === true,
+          inherit: options?.inherit === true,
+        };
+      })
+      .sort(
+        (a, b) =>
+          a.parent.localeCompare(b.parent) || (a.grantor ?? '').localeCompare(b.grantor ?? ''),
+      );
+    return Effect.succeed(rows as unknown as ReadonlyArray<A>);
+  }
+
+  if (text.includes('FROM pg_roles r')) {
+    const name = params[0] as string;
+    const row = state.roleRows.get(name);
+    // pg_roles answers no password value (S25): even a seeded seal is not read back — state
+    // holds it, and a reconcile receives it explicitly, the same way the real server answers.
+    if (row === undefined) return Effect.succeed([] as unknown as ReadonlyArray<A>);
+    const { passwordSeal: _stateOnly, ...catalog } = row;
+    return Effect.succeed([catalog] as unknown as ReadonlyArray<A>);
+  }
+
+  if (text.startsWith('CREATE ROLE')) {
+    const parsed = { ...EMPTY_ROLE, ...parseCreateRole(text), oid: state.nextOid() };
+    state.roleRows.set(parsed.name, { ...parsed, memberOf: [], passwordSeal: '' });
+    return Effect.succeed([] as unknown as ReadonlyArray<A>);
+  }
+
+  if (text.startsWith('ALTER ROLE')) {
+    const parsed = parseAlterRole(text);
+    const row = state.roleRows.get(parsed.name ?? '');
+    if (row === undefined) {
+      throw new Error(`fake-sql: ALTER ROLE on absent role "${String(parsed.name)}"`);
+    }
+    state.roleRows.set(row.name, { ...row, ...parsed });
+    return Effect.succeed([] as unknown as ReadonlyArray<A>);
+  }
+
+  if (text.startsWith('GRANT')) {
+    const m =
+      /^GRANT "((?:[^"]|"")*)" TO "((?:[^"]|"")*)"(?: WITH ADMIN FALSE, SET FALSE| WITH SET FALSE)?$/.exec(
+        text,
+      );
+    if (m === null) {
+      throw new Error(`fake-sql: could not parse a generated GRANT statement: ${text}`);
+    }
+    // The session issues the statement as the bootstrap superuser, so the grant it (re)makes
+    // is keyed on grantor `postgres` — `AddRoleMems` updates only that (role, member, grantor)
+    // tuple (`user.c@REL_18_6`). A later `REVOKE … GRANTED BY "postgres"` finds the same row.
+    const parent = unquoteIdent(m[1] as string);
+    const member = unquoteIdent(m[2] as string);
+    if (!state.roleRows.has(parent) && !state.roleNames.has(parent)) {
+      throw new Error(`fake-sql: GRANT parent "${parent}" does not exist`);
+    }
+    if (!state.roleRows.has(member) && !state.roleNames.has(member)) {
+      throw new Error(`fake-sql: GRANT member "${member}" does not exist`);
+    }
+    const key = `${member}\0${parent}\0postgres`;
+    state.memberships.add(key);
+    // `grant.sgml` (REL_18_6): altering an existing membership retains every option the new
+    // GRANT omits, so only the full-options form clears ADMIN; `WITH SET FALSE` alone keeps a
+    // current ADMIN. A bare `GRANT` (never issued by this family) leaves options untouched.
+    const options = state.membershipOptions.get(key) ?? {
+      admin: false,
+      set: false,
+      inherit: state.roleRows.get(member)?.inherit ?? true,
+    };
+    if (text.endsWith('WITH ADMIN FALSE, SET FALSE')) {
+      state.membershipOptions.set(key, { ...options, admin: false, set: false });
+    } else if (text.endsWith('WITH SET FALSE')) {
+      state.membershipOptions.set(key, { ...options, set: false });
+    }
+    return Effect.succeed([] as unknown as ReadonlyArray<A>);
+  }
+
+  if (text.startsWith('REVOKE')) {
+    const option =
+      /^REVOKE (ADMIN|SET|INHERIT) OPTION FOR "((?:[^"]|"")*)" FROM "((?:[^"]|"")*)" GRANTED BY "((?:[^"]|"")*)" RESTRICT$/.exec(
+        text,
+      );
+    if (option !== null) {
+      const key = `${unquoteIdent(option[3] as string)}\0${unquoteIdent(option[2] as string)}\0${unquoteIdent(option[4] as string)}`;
+      const options = state.membershipOptions.get(key) ?? { admin: false, set: false };
+      const next = { ...options, [(option[1] as string).toLowerCase()]: false };
+      if (next.admin || next.set || next.inherit !== undefined)
+        state.membershipOptions.set(key, next);
+      else state.membershipOptions.delete(key);
+      return Effect.succeed([] as unknown as ReadonlyArray<A>);
+    }
+    const granted =
+      /^REVOKE "((?:[^"]|"")*)" FROM "((?:[^"]|"")*)" GRANTED BY "((?:[^"]|"")*)"$/.exec(text);
+    if (granted !== null) {
+      // Only the grantor's own row goes; other grantors' rows for the same parent stand.
+      const key = `${unquoteIdent(granted[2] as string)}\0${unquoteIdent(granted[1] as string)}\0${unquoteIdent(granted[3] as string)}`;
+      state.memberships.delete(key);
+      state.membershipOptions.delete(key);
+      return Effect.succeed([] as unknown as ReadonlyArray<A>);
+    }
+    const plain = /^REVOKE "((?:[^"]|"")*)" FROM "((?:[^"]|"")*)"$/.exec(text);
+    if (plain === null) {
+      throw new Error(`fake-sql: could not parse a generated REVOKE statement: ${text}`);
+    }
+    // `revoke.sgml`: a plain REVOKE removes only grants the session's grantor made and warns
+    // on the rest — a no-op against other grantors' rows. The session's grantor is
+    // `postgres`, so the key it can touch is `member\0parent\0postgres`.
+    const key = `${unquoteIdent(plain[2] as string)}\0${unquoteIdent(plain[1] as string)}\0postgres`;
+    state.memberships.delete(key);
+    state.membershipOptions.delete(key);
+    return Effect.succeed([] as unknown as ReadonlyArray<A>);
+  }
+
+  if (text.startsWith('DROP ROLE')) {
+    const m = /^DROP ROLE IF EXISTS "((?:[^"]|"")*)"$/.exec(text);
+    if (m === null) {
+      throw new Error(`fake-sql: could not parse a generated DROP ROLE statement: ${text}`);
+    }
+    const name = unquoteIdent(m[1] as string);
+    state.roleRows.delete(name);
+    state.roleNames.delete(name);
+    for (const key of state.memberships) {
+      const parts = key.split('\0');
+      if (parts[0] === name || parts[1] === name) {
+        state.memberships.delete(key);
+        state.membershipOptions.delete(key);
+      }
+    }
+    return Effect.succeed([] as unknown as ReadonlyArray<A>);
+  }
+
+  return undefined;
+};

package/src/postgres/fake-schema-semantics.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeFakeSql } from './fake-sql.ts';
+
+const row = { name: 'ledger', database: 'postgres', owner: 'old_owner', oid: 42, comment: 'keep' };
+
+test('PG18 IF NOT EXISTS preserves oid, owner, comment and contents', async () => {
+  const fake = makeFakeSql({ schemas: [row], schemasWithRelations: ['ledger'] });
+  await Effect.runPromise(
+    fake.unsafe('CREATE SCHEMA IF NOT EXISTS "ledger" AUTHORIZATION "new_owner"'),
+  );
+  expect(fake.schemas.get('ledger')).toEqual(row);
+  expect(fake.relationsIn.has('ledger')).toBe(true);
+});
+
+test('PG18 plain CREATE on an existing schema raises 42P06', async () => {
+  const fake = makeFakeSql({ schemas: [row] });
+  const error = await Effect.runPromise(Effect.flip(fake.unsafe('CREATE SCHEMA "ledger"')));
+  expect(error.reason.cause).toMatchObject({ code: '42P06' });
+  expect(fake.schemas.get('ledger')).toEqual(row);
+});
+
+test('PG18 nonempty DROP without CASCADE raises 2BP01 without deleting anything', async () => {
+  const fake = makeFakeSql({ schemas: [row], schemasWithRelations: ['ledger'] });
+  const error = await Effect.runPromise(Effect.flip(fake.unsafe('DROP SCHEMA IF EXISTS "ledger"')));
+  expect(error.reason.cause).toMatchObject({ code: '2BP01' });
+  expect(fake.schemas.get('ledger')).toEqual(row);
+  expect(fake.relationsIn.has('ledger')).toBe(true);
+});
+
+test('PG18 bootstrap seeds public owned by pg_database_owner', () => {
+  expect(makeFakeSql().schemas.get('public')).toMatchObject({
+    oid: 2200,
+    owner: 'pg_database_owner',
+  });
+});

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

@@ -0,0 +1,146 @@
+/**
+ * The `Postgres.Schema` half of `fake-sql.ts`: the in-memory `pg_namespace` catalog and every
+ * statement branch that touches it, split out so each fake file serves one family.
+ *
+ * ⛔ IT PARSES ITS OWN OUTPUT, NOT SQL IN GENERAL (the rule `fake-sql.ts` documents). Every
+ *   parser understands exactly the text `schema-sql.ts` produces. A general SQL parser would
+ *   hide a quoting bug instead of tripping over it.
+ * ★ Reads answer `current_database()` from this fake's `database` — the same a real server
+ *   answers for the connection it opened — and `schemaIsEmpty` from a seeded relation set.
+ */
+import * as Effect from 'effect/Effect';
+import { SqlError, SqlSyntaxError, UnknownError } from 'effect/unstable/sql/SqlError';
+import { parseCommentSchema, parseCreateSchema, parseDropSchema } from './fake-sql-parse.ts';
+import type { PostgresSchemaAttributes } from './schema-attrs.ts';
+
+/** The schema catalog `fake-sql.ts` constructs and shares with its callers. */
+export interface FakeSchemaState {
+  readonly schemas: Map<string, PostgresSchemaAttributes>;
+  /** Names of schemas this fake pretends hold at least one relation. */
+  readonly relationsIn: Set<string>;
+  /** What `current_database()` answers, and the stamp on every read row. */
+  readonly database: string;
+  /** What `current_user` answers, and the owner of a `CREATE SCHEMA` without `AUTHORIZATION`. */
+  readonly sessionRole: string;
+  readonly standardConformingStrings: boolean;
+  /** Remaining swallowed `CREATE SCHEMA`s (the S10 lie). */
+  swallowRemaining: number;
+  /** Owner a raced `CREATE SCHEMA` stores instead, consumed once. */
+  raceOwner: string | undefined;
+  nextOid(): number;
+}
+
+/**
+ * Every `Postgres.Schema` statement and the reads that back it. `undefined` when the text
+ * belongs to another family, so `fake-sql.ts` can fall through.
+ *
+ * ⚠️ THE EMPTY CHECK BEFORE THE NAMESPACE READ: `SCHEMA_EMPTY_SQL` contains `FROM pg_namespace`,
+ *   so a plain `includes('FROM pg_namespace')` test would swallow it.
+ * ⚠️ `current_database()` is `startsWith`, not `includes`: `SELECT_SCHEMA_SQL` also projects
+ *   `current_database() AS database`.
+ */
+export const applySchemaStatement = <A extends object>(
+  state: FakeSchemaState,
+  text: string,
+  params: ReadonlyArray<unknown>,
+): Effect.Effect<ReadonlyArray<A>, SqlError> | undefined => {
+  if (text.startsWith('SELECT current_database()')) {
+    return Effect.succeed([{ database: state.database }] as unknown as ReadonlyArray<A>);
+  }
+
+  if (text.startsWith('SELECT current_user')) {
+    return Effect.succeed([{ role: state.sessionRole }] as unknown as ReadonlyArray<A>);
+  }
+
+  if (text.includes('AS empty') && text.includes('pg_class')) {
+    const name = params[0] as string;
+    return Effect.succeed([{ empty: !state.relationsIn.has(name) }] as unknown as ReadonlyArray<A>);
+  }
+
+  if (text.includes('FROM pg_namespace')) {
+    const name = params[0] as string;
+    const row = state.schemas.get(name);
+    return Effect.succeed(
+      (row === undefined
+        ? []
+        : [{ ...row, database: state.database }]) as unknown as ReadonlyArray<A>,
+    );
+  }
+
+  if (text.startsWith('CREATE SCHEMA')) {
+    if (state.swallowRemaining > 0) {
+      state.swallowRemaining -= 1;
+      return Effect.succeed([] as unknown as ReadonlyArray<A>);
+    }
+    const parsed = parseCreateSchema(text, state.sessionRole);
+    if (state.raceOwner !== undefined) {
+      state.schemas.set(parsed.name, {
+        ...parsed,
+        database: state.database,
+        oid: state.nextOid(),
+        owner: state.raceOwner,
+      });
+      state.raceOwner = undefined;
+    }
+    // PG18 CREATE SCHEMA docs: IF NOT EXISTS does nothing, even if the owner differs.
+    if (state.schemas.has(parsed.name)) {
+      if (!text.startsWith('CREATE SCHEMA IF NOT EXISTS'))
+        return Effect.fail(schemaSqlError('42P06'));
+    } else {
+      state.schemas.set(parsed.name, { ...parsed, database: state.database, oid: state.nextOid() });
+    }
+    return Effect.succeed([] as unknown as ReadonlyArray<A>);
+  }
+
+  if (text.startsWith('COMMENT ON SCHEMA')) {
+    const parsed = parseCommentSchema(text, state.standardConformingStrings);
+    const existing = state.schemas.get(parsed.name);
+    if (existing === undefined) {
+      throw new Error(`fake-sql: COMMENT ON SCHEMA on absent schema "${parsed.name}"`);
+    }
+    state.schemas.set(parsed.name, { ...existing, comment: parsed.comment });
+    return Effect.succeed([] as unknown as ReadonlyArray<A>);
+  }
+
+  if (text.startsWith('DROP SCHEMA')) {
+    const parsed = parseDropSchema(text);
+    if (!parsed.cascade && state.relationsIn.has(parsed.name))
+      return Effect.fail(schemaSqlError('2BP01'));
+    if (parsed.cascade) state.relationsIn.delete(parsed.name);
+    state.schemas.delete(parsed.name);
+    return Effect.succeed([] as unknown as ReadonlyArray<A>);
+  }
+
+  return undefined;
+};
+
+/** Match the socket/runner SQLSTATE classification, including class 2B as UnknownError. */
+const schemaSqlError = (code: string): SqlError => {
+  const fields = {
+    cause: Object.assign(new Error(code), { code }),
+    message: code,
+    operation: 'schema DDL',
+  };
+  return new SqlError({
+    reason: code.startsWith('42') ? new SqlSyntaxError(fields) : new UnknownError(fields),
+  });
+};
+
+/** REL_18_6 pg_namespace.dat: public exists on bootstrap, owned by pg_database_owner. */
+export const seedSchemas = (
+  rows: readonly PostgresSchemaAttributes[] | undefined,
+  database: string,
+): Map<string, PostgresSchemaAttributes> =>
+  new Map([
+    [
+      'public',
+      {
+        name: 'public',
+        oid: 2200,
+        owner: 'pg_database_owner',
+        comment: 'standard public schema',
+        database,
+      },
+    ],
+    ...(rows?.map((row) => [row.name, row] as const) ?? []),
+  ]);

package/src/postgres/fake-sql-parse.ts

@@ -0,0 +1,86 @@
+/**
+ * Parsers for exactly the SQL `fake-sql.ts` records — the text this family's builders emit,
+ * not SQL in general. A general parser would hide a quoting bug instead of tripping over it.
+ */
+import type { PostgresDatabaseAttributes } from './database-attrs.ts';
+import type { PostgresSchemaAttributes } from './schema-attrs.ts';
+
+import { parseLiteral, unquoteIdent, unquoteLiteral } from './fake-sql-quote.ts';
+
+/** Pull every field back out of exactly the text `buildCreateDatabaseSql` writes. */
+export const parseCreate = (text: string): PostgresDatabaseAttributes => {
+  const name = /^CREATE DATABASE "((?:[^"]|"")*)" WITH /.exec(text);
+  const owner = /OWNER "((?:[^"]|"")*)"/.exec(text);
+  const encoding = /ENCODING E'((?:[^']|'')*)'/.exec(text);
+  const localeProvider = /LOCALE_PROVIDER E'((?:[^']|'')*)'/.exec(text);
+  const lcCollate = /LC_COLLATE E'((?:[^']|'')*)'/.exec(text);
+  const lcCtype = /LC_CTYPE E'((?:[^']|'')*)'/.exec(text);
+  const tablespace = /TABLESPACE "((?:[^"]|"")*)"/.exec(text);
+  const allowConnections = /ALLOW_CONNECTIONS (true|false)/.exec(text);
+  const connectionLimit = /CONNECTION LIMIT (-?\d+)/.exec(text);
+  const isTemplate = /IS_TEMPLATE (true|false)/.exec(text);
+  if (name === null || owner === null) {
+    throw new Error(`fake-sql: could not parse a generated CREATE DATABASE statement: ${text}`);
+  }
+  return {
+    name: unquoteIdent(name[1] as string),
+    oid: 0,
+    owner: unquoteIdent(owner[1] as string),
+    encoding: encoding === null ? 'UTF8' : unquoteLiteral(encoding[1] as string),
+    localeProvider:
+      localeProvider === null ? 'libc' : (unquoteLiteral(localeProvider[1] as string) as 'libc'),
+    collate: lcCollate === null ? 'C' : unquoteLiteral(lcCollate[1] as string),
+    ctype: lcCtype === null ? 'C' : unquoteLiteral(lcCtype[1] as string),
+    tablespace: tablespace === null ? 'pg_default' : unquoteIdent(tablespace[1] as string),
+    allowConnections: allowConnections === null ? true : allowConnections[1] === 'true',
+    connectionLimit: connectionLimit === null ? -1 : Number(connectionLimit[1]),
+    isTemplate: isTemplate === null ? false : isTemplate[1] === 'true',
+  };
+};
+
+/** Parse exactly the text `buildCreateSchemaSql` writes. The caller stamps `database` and
+ * `oid`. Absent `AUTHORIZATION`, the owner is `executingRole` — Postgres's own default, the
+ * role `current_user` answers. */
+export const parseCreateSchema = (
+  text: string,
+  executingRole: string,
+): Omit<PostgresSchemaAttributes, 'database' | 'oid'> => {
+  const match =
+    /^CREATE SCHEMA(?: IF NOT EXISTS)? "((?:[^"]|"")*)"(?: AUTHORIZATION "((?:[^"]|"")*)")?$/.exec(
+      text,
+    );
+  if (match === null) {
+    throw new Error(`fake-sql: could not parse a generated CREATE SCHEMA statement: ${text}`);
+  }
+  return {
+    name: unquoteIdent(match[1] as string),
+    owner: match[2] === undefined ? executingRole : unquoteIdent(match[2] as string),
+    comment: null,
+  };
+};
+
+/** Parse exactly the text `buildCommentSchemaSql` writes. */
+export const parseCommentSchema = (
+  text: string,
+  standardConformingStrings = true,
+): { readonly name: string; readonly comment: string } => {
+  const match = /^COMMENT ON SCHEMA "((?:[^"]|"")*)" IS ([\s\S]+)$/.exec(text);
+  if (match === null) {
+    throw new Error(`fake-sql: could not parse a generated COMMENT ON SCHEMA statement: ${text}`);
+  }
+  return {
+    name: unquoteIdent(match[1] as string),
+    comment: parseLiteral(match[2] as string, standardConformingStrings),
+  };
+};
+
+/** Parse exactly the text `buildDropSchemaSql` writes. */
+export const parseDropSchema = (
+  text: string,
+): { readonly name: string; readonly cascade: boolean } => {
+  const match = /^DROP SCHEMA IF EXISTS "((?:[^"]|"")*)"( CASCADE)?$/.exec(text);
+  if (match === null) {
+    throw new Error(`fake-sql: could not parse a generated DROP SCHEMA statement: ${text}`);
+  }
+  return { name: unquoteIdent(match[1] as string), cascade: match[2] !== undefined };
+};

package/src/postgres/fake-sql-quote.ts

@@ -0,0 +1,36 @@
+/**
+ * The inverse of `quoteIdent` / `quoteStringLiteral` (`database-sql.ts`), for the fakes that
+ * parse their own generated statement text. One place, so the database and role fakes can never
+ * disagree about what a doubled quote means.
+ */
+export const unquoteIdent = (raw: string): string => raw.replace(/""/g, '"');
+
+export const unquoteLiteral = (raw: string): string =>
+  raw.replace(/\\\\/g, '\\').replace(/''/g, "'");
+
+/** Decode one entire literal, rejecting trailing SQL. PG18 §4.1.2.2: only E strings
+ * interpret backslashes when standard_conforming_strings is on. Deliberately tiny:
+ * accepts generated escapes, not the server's octal/hex/unicode grammar. */
+export const parseLiteral = (text: string, standardConformingStrings = true): string => {
+  const escape = text.startsWith("E'") || !standardConformingStrings;
+  const start = text.startsWith("E'") ? 2 : 1;
+  if (text[start - 1] !== "'") throw new Error('fake-sql: expected literal');
+  let value = '';
+  for (let i = start; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === "'") {
+      if (text[i + 1] === "'") {
+        value += "'";
+        i += 1;
+      } else if (i === text.length - 1) return value;
+      else throw new Error('fake-sql: trailing SQL after literal');
+    } else if (char === '\\' && escape) {
+      i += 1;
+      const next = text[i];
+      if (next === undefined) throw new Error('fake-sql: unterminated escape');
+      value +=
+        ({ n: '\n', r: '\r', t: '\t', b: '\b', f: '\f' } as Record<string, string>)[next] ?? next;
+    } else value += char;
+  }
+  throw new Error('fake-sql: unterminated literal');
+};