@homeflare/alchemy 0.46.0 → 0.47.0

package/src/postgres/connection.ts

@@ -17,9 +17,10 @@ import * as PgClient from '@effect/sql-pg/PgClient';
 import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
-import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { SqlError } from 'effect/sql/SqlError';
 import type { PgExecutor } from './database-sql.ts';
 import { type PsqlRunner, makePsqlExecutor } from './psql-executor.ts';
+import { pinnedSocketExecutor } from './search-path.ts';
 
 /** What a stack passes to reach one cluster. `host` may be a socket directory (one beginning
  * with `/` expands to `${host}/.s.PGSQL.${port}` — measured in
@@ -109,21 +110,16 @@ export const withPg = <A, E>(
       });
     }
     const pool = yield* PostgresPool;
+    // ⛔ ONE RESERVED, PINNED CONNECTION FOR THE WHOLE OPERATION (`search-path.ts`): the pin is a
+    // session setting, so a pool checkout per statement would run most statements unpinned — and
+    // would autocommit CREATE before GRANT. `Effect.scoped` releases the reservation; the pool
+    // layer below closes the pool after.
     return yield* Effect.provide(
-      Effect.flatMap(PgClient.PgClient, (pg) =>
-        build(
-          {
-            unsafe: (sql, params) => pg.unsafe(sql, params),
-            // One reserved connection (`SqlClient.withTransaction`). A pool checkout per
-            // statement would autocommit CREATE before GRANT.
-            transaction: (statements) =>
-              pg.withTransaction(
-                Effect.gen(function* () {
-                  for (const sql of statements) yield* pg.unsafe(sql).pipe(Effect.asVoid);
-                }),
-              ),
-          },
-          { database: target.database },
+      Effect.scoped(
+        Effect.flatMap(PgClient.PgClient, (pg) =>
+          Effect.flatMap(pinnedSocketExecutor(pg), (executor) =>
+            build(executor, { database: target.database }),
+          ),
         ),
       ),
       pool(target),

package/src/postgres/database-bigint-serialization.test.ts

@@ -18,7 +18,7 @@ import { describe, expect, test } from 'bun:test';
 import * as Effect from 'effect/Effect';
 import * as Result from 'effect/Result';
 import * as PgTypes from '@effect/sql-pg/PgTypes';
-import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { SqlError } from 'effect/sql/SqlError';
 import { encodeState } from 'alchemy/State/StateEncoding';
 import { reconcileWithClient } from './database.ts';
 import { PostgresDatabaseDrift } from './errors.ts';
@@ -76,10 +76,10 @@ const wireAccuratePg = (seed?: {
   return {
     unsafe: <A extends object>(text: string, params: ReadonlyArray<unknown> = []) =>
       Effect.suspend(() => {
-        if (text.startsWith('SELECT 1 AS present FROM pg_roles')) {
+        if (text.startsWith('SELECT 1 AS present FROM pg_catalog.pg_roles')) {
           return Effect.succeed([{ present: 1 }] as unknown as ReadonlyArray<A>);
         }
-        if (text.includes('FROM pg_database')) {
+        if (text.includes('FROM pg_catalog.pg_database')) {
           if (created === undefined) return Effect.succeed([] as unknown as ReadonlyArray<A>);
           const row = wireAccurateRow(text, created.oid, created.connectionLimit);
           return Effect.succeed([row] as unknown as ReadonlyArray<A>);

package/src/postgres/database-sql.ts

@@ -24,7 +24,7 @@
  *   Measured 2026-10-01: the former quote-only escaper allowed comment SQL injection when
  *   that setting was off; an input backslash escaped the first quote of a doubled pair.
  */
-import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { SqlError } from 'effect/sql/SqlError';
 import * as Effect from 'effect/Effect';
 import type { PostgresDatabaseAttributes, PostgresDatabaseProps } from './database-attrs.ts';
 
@@ -103,7 +103,7 @@ export const isDuplicateDatabaseRace = (error: SqlError): boolean => {
   );
 };
 
-const ROLE_EXISTS_SQL = 'SELECT 1 AS present FROM pg_roles WHERE rolname = $1';
+const ROLE_EXISTS_SQL = 'SELECT 1 AS present FROM pg_catalog.pg_roles WHERE rolname = $1';
 
 /** `OWNER` is checked against `pg_roles` before any `CREATE`, so a missing role is
  * `PostgresDatabaseOwnerMissing` at reconcile time rather than the server's own
@@ -114,7 +114,7 @@ export const roleExists = (pg: PgExecutor, role: string): Effect.Effect<boolean,
     (rows) => rows.length > 0,
   );
 
-const DATABASE_EXISTS_SQL = 'SELECT 1 AS present FROM pg_database WHERE datname = $1';
+const DATABASE_EXISTS_SQL = 'SELECT 1 AS present FROM pg_catalog.pg_database WHERE datname = $1';
 
 /**
  * Does one database of the cluster exist? `Postgres.Schema` runs this over the FAMILY
@@ -152,8 +152,8 @@ export const databaseExists = (pg: PgExecutor, name: string): Effect.Effect<bool
 const SELECT_DATABASE_SQL = `SELECT
     d.oid AS oid,
     d.datname AS name,
-    pg_get_userbyid(d.datdba) AS owner,
-    pg_encoding_to_char(d.encoding) AS encoding,
+    pg_catalog.pg_get_userbyid(d.datdba) AS owner,
+    pg_catalog.pg_encoding_to_char(d.encoding) AS encoding,
     CASE d.datlocprovider
       WHEN 'b' THEN 'builtin' WHEN 'i' THEN 'icu' WHEN 'c' THEN 'libc'
       ELSE 'libc'
@@ -164,8 +164,8 @@ const SELECT_DATABASE_SQL = `SELECT
     d.datconnlimit AS "connectionLimit",
     d.datistemplate AS "isTemplate",
     t.spcname AS tablespace
-  FROM pg_database d
-  JOIN pg_tablespace t ON t.oid = d.dattablespace
+  FROM pg_catalog.pg_database d
+  JOIN pg_catalog.pg_tablespace t ON t.oid = d.dattablespace
   WHERE d.datname = $1`;
 
 /** The read: one bound `SELECT` on `pg_database`, joined to the two functions that turn its raw

package/src/postgres/database.ts

@@ -20,7 +20,7 @@ import { isResolved } from 'alchemy/Diff';
 import type { Input } from 'alchemy/Input';
 import * as Provider from 'alchemy/Provider';
 import * as Effect from 'effect/Effect';
-import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { SqlError } from 'effect/sql/SqlError';
 import type { PostgresDatabaseAttributes, PostgresDatabaseProps } from './database-attrs.ts';
 import { nameByteRefusal } from './database-attrs.ts';
 import {

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

@@ -6,7 +6,7 @@
  * cycle.
  */
 import * as Effect from 'effect/Effect';
-import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { SqlError } from 'effect/sql/SqlError';
 import type { AclObject } from './fake-grants-parse.ts';
 
 /** One `aclitem` as the fake stores it: one (object, grantee, grantor) with the words that
@@ -96,17 +96,17 @@ export const answerRead = <A extends object>(
 ): Effect.Effect<ReadonlyArray<A>, SqlError> | undefined => {
   const { acl, schemas, roles, databases, tables } = model;
 
-  if (text.startsWith('SELECT 1 AS present FROM pg_roles')) {
+  if (text.startsWith('SELECT 1 AS present FROM pg_catalog.pg_roles')) {
     return Effect.succeed(
       (roles.has(params[0] as string) ? [{ present: 1 }] : []) as unknown as ReadonlyArray<A>,
     );
   }
-  if (text.startsWith('SELECT 1 AS present FROM pg_namespace')) {
+  if (text.startsWith('SELECT 1 AS present FROM pg_catalog.pg_namespace')) {
     return Effect.succeed(
       (schemas.has(params[0] as string) ? [{ present: 1 }] : []) as unknown as ReadonlyArray<A>,
     );
   }
-  if (text.startsWith('SELECT 1 AS present FROM pg_database')) {
+  if (text.startsWith('SELECT 1 AS present FROM pg_catalog.pg_database')) {
     return Effect.succeed(
       (databases.has(params[0] as string) ? [{ present: 1 }] : []) as unknown as ReadonlyArray<A>,
     );

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

@@ -15,7 +15,7 @@
  *   `42703`, the way the server refuses a missing object.
  */
 import * as Effect from 'effect/Effect';
-import { SqlError, SqlSyntaxError } from 'effect/unstable/sql/SqlError';
+import { SqlError, SqlSyntaxError } from 'effect/sql/SqlError';
 import type { PgExecutor } from './database-sql.ts';
 import { type AclEntry, type FakeCatalogTable, answerRead } from './fake-grants-read.ts';
 import { parseGrantStatement } from './fake-grants-parse.ts';

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

@@ -15,7 +15,7 @@
  *   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 { SqlError, SqlSyntaxError } from 'effect/sql/SqlError';
 import type { AclObject } from './fake-grants-parse.ts';
 import { type FakeGrantsModel, revokesAsOwner } from './fake-grants-read.ts';
 

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

@@ -12,7 +12,7 @@
  *   attributes a test seeds or a reconcile returns.
  */
 import * as Effect from 'effect/Effect';
-import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { SqlError } from 'effect/sql/SqlError';
 import type { PostgresRoleAttributes } from './role-attrs.ts';
 import { unquoteIdent, unquoteLiteral } from './fake-sql-quote.ts';
 
@@ -97,7 +97,7 @@ export const applyRoleStatement = <A extends object>(
   text: string,
   params: ReadonlyArray<unknown>,
 ): Effect.Effect<ReadonlyArray<A>, SqlError> | undefined => {
-  if (text.includes('FROM pg_auth_members')) {
+  if (text.includes('FROM pg_catalog.pg_auth_members')) {
     const member = params[0] as string;
     const rows = [...state.memberships]
       .filter((key) => key.split('\0')[0] === member)
@@ -119,7 +119,7 @@ export const applyRoleStatement = <A extends object>(
     return Effect.succeed(rows as unknown as ReadonlyArray<A>);
   }
 
-  if (text.includes('FROM pg_roles r')) {
+  if (text.includes('FROM pg_catalog.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

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

@@ -0,0 +1,75 @@
+/**
+ * The fake's reading of the atomic `DO` drop `schema-drop-sql.ts` emits.
+ *
+ * ⛔ IT PARSES ITS OWN OUTPUT (the rule `fake-sql.ts` documents): the four `DECLARE` literals are
+ *   read back out of the generated text and the block's decisions are replayed against the
+ *   in-memory catalog in the same order the SQL makes them — absent → return, identity, empty or
+ *   cross-schema dependents, drop. A changed block shape fails the parse loudly.
+ */
+import * as Effect from 'effect/Effect';
+import { SqlError, UnknownError } from 'effect/sql/SqlError';
+import { parseLiteral } from './fake-sql-quote.ts';
+import { parseDropSchema } from './fake-sql-parse.ts';
+import type { FakeSchemaState } from './fake-schema-sql.ts';
+import {
+  CASCADE_SEQUENCES,
+  CROSS_SCHEMA_DEPENDENTS,
+  IDENTITY_CHANGED,
+  NOT_EMPTY,
+} from './schema-drop-sql.ts';
+
+const refusal = (code: string, message: string): SqlError =>
+  new SqlError({
+    reason: new UnknownError({
+      cause: Object.assign(new Error(message), { code }),
+      message,
+      operation: 'DO',
+    }),
+  });
+
+/** `E'…'` literal at the end of a generated line, decoded. */
+const literalAfter = (body: string, label: string): string => {
+  const match = new RegExp(`${label} [a-z]+ := (E'(?:[^']|'')*');`).exec(body);
+  if (match === null) throw new Error(`fake-sql: could not parse DO block ${label}: ${body}`);
+  return parseLiteral(match[1] as string);
+};
+
+export const applyAtomicDrop = (
+  state: FakeSchemaState,
+  text: string,
+): Effect.Effect<ReadonlyArray<never>, SqlError> => {
+  const body = parseLiteral(text.slice('DO '.length));
+  const name = literalAfter(body, 'v_name');
+  const owner = literalAfter(body, 'v_owner');
+  const oid = Number(/v_oid oid := (\d+);/.exec(body)?.[1]);
+  const cascade = /v_cascade boolean := (true|false);/.exec(body)?.[1] === 'true';
+  const drop = /EXECUTE (E'(?:[^']|'')*');/.exec(body)?.[1];
+  if (drop === undefined || Number.isNaN(oid)) {
+    throw new Error(`fake-sql: could not parse DO block: ${body}`);
+  }
+  if (parseDropSchema(parseLiteral(drop)).name !== name) {
+    throw new Error('fake-sql: DO block drops a different schema than it proves');
+  }
+  const row = state.schemas.get(name);
+  if (row === undefined) return Effect.succeed([]);
+  if (row.oid !== oid || row.owner !== owner) {
+    return Effect.fail(refusal(IDENTITY_CHANGED, 'schema identity changed'));
+  }
+  if (!cascade) {
+    if (state.relationsIn.has(name)) return Effect.fail(refusal(NOT_EMPTY, 'schema not empty'));
+  } else {
+    const sequences = state.sequencesIn.get(name) ?? 0;
+    if (sequences > 0) {
+      return Effect.fail(refusal(CASCADE_SEQUENCES, `cascade sequences: ${String(sequences)}`));
+    }
+    const outside = state.dependentsOutside.get(name) ?? 0;
+    if (outside > 0) {
+      return Effect.fail(
+        refusal(CROSS_SCHEMA_DEPENDENTS, `cross-schema dependents: ${String(outside)}`),
+      );
+    }
+    state.relationsIn.delete(name);
+  }
+  state.schemas.delete(name);
+  return Effect.succeed([]);
+};

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

@@ -9,7 +9,8 @@
  *   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 { SqlError, SqlSyntaxError, UnknownError } from 'effect/sql/SqlError';
+import { applyAtomicDrop } from './fake-schema-drop.ts';
 import { parseCommentSchema, parseCreateSchema, parseDropSchema } from './fake-sql-parse.ts';
 import type { PostgresSchemaAttributes } from './schema-attrs.ts';
 
@@ -18,6 +19,11 @@ export interface FakeSchemaState {
   readonly schemas: Map<string, PostgresSchemaAttributes>;
   /** Names of schemas this fake pretends hold at least one relation. */
   readonly relationsIn: Set<string>;
+  /** Per schema name: how many objects in OTHER schemas depend on it (what the atomic drop's
+   * `pg_depend` count answers). Absent means none. */
+  readonly dependentsOutside: Map<string, number>;
+  /** Per schema name: how many sequences it holds (a cascade drop refuses any: `HF004`). */
+  readonly sequencesIn: Map<string, number>;
   /** 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`. */
@@ -44,6 +50,9 @@ export const applySchemaStatement = <A extends object>(
   text: string,
   params: ReadonlyArray<unknown>,
 ): Effect.Effect<ReadonlyArray<A>, SqlError> | undefined => {
+  // The atomic drop's text contains every marker below; matched first, by its own prefix.
+  if (text.startsWith('DO ')) return applyAtomicDrop(state, text);
+
   if (text.startsWith('SELECT current_database()')) {
     return Effect.succeed([{ database: state.database }] as unknown as ReadonlyArray<A>);
   }
@@ -57,7 +66,7 @@ export const applySchemaStatement = <A extends object>(
     return Effect.succeed([{ empty: !state.relationsIn.has(name) }] as unknown as ReadonlyArray<A>);
   }
 
-  if (text.includes('FROM pg_namespace')) {
+  if (text.includes('FROM pg_catalog.pg_namespace')) {
     const name = params[0] as string;
     const row = state.schemas.get(name);
     return Effect.succeed(

package/src/postgres/fake-sql.ts

@@ -12,7 +12,7 @@
  *   halves live in their own files under the same rule.
  */
 import * as Effect from 'effect/Effect';
-import { SqlError, SqlSyntaxError, UnknownError } from 'effect/unstable/sql/SqlError';
+import { SqlError, SqlSyntaxError, UnknownError } from 'effect/sql/SqlError';
 import type { PostgresDatabaseAttributes } from './database-attrs.ts';
 import type { PgExecutor } from './database-sql.ts';
 import { parseCreate } from './fake-sql-parse.ts';
@@ -65,6 +65,10 @@ export interface FakeSqlOptions {
   readonly schemas?: ReadonlyArray<PostgresSchemaAttributes>;
   /** Names of schemas the fake answers `schemaIsEmpty` with `false` for. */
   readonly schemasWithRelations?: ReadonlyArray<string>;
+  /** Per schema name, how many objects in OTHER schemas depend on it (a cascade would drop
+   * them): what the atomic drop's `pg_depend` count answers. */
+  readonly dependentsOutside?: Readonly<Record<string, number>>;
+  readonly sequencesIn?: Readonly<Record<string, number>>; // per schema: sequences held (HF004)
   /** Accept the NEXT `CREATE SCHEMA` (no error) but record nothing — the S10 case where the
    * write's own report is a lie and the immediate re-read finds nothing. */
   readonly swallowNextCreateSchema?: boolean;
@@ -93,6 +97,7 @@ export const makeFakeSql = (options: FakeSqlOptions = {}): FakeSql => {
   >();
   const schemas = seedSchemas(options.schemas, options.database ?? 'postgres');
   const relationsIn = new Set(options.schemasWithRelations ?? []);
+  const dependentsOutside = new Map(Object.entries(options.dependentsOutside ?? {}));
   let raceRemaining = options.raceNextCreate === true ? 1 : 0;
   let failNext = options.failNext;
   let oidCounter = 20000;
@@ -111,6 +116,8 @@ export const makeFakeSql = (options: FakeSqlOptions = {}): FakeSql => {
   const schemaState: FakeSchemaState = {
     schemas,
     relationsIn,
+    dependentsOutside,
+    sequencesIn: new Map(Object.entries(options.sequencesIn ?? {})),
     database: options.database ?? 'postgres',
     standardConformingStrings: options.standardConformingStrings ?? true,
     sessionRole: options.currentUser ?? 'postgres',
@@ -139,7 +146,7 @@ export const makeFakeSql = (options: FakeSqlOptions = {}): FakeSql => {
         );
       }
 
-      if (text.startsWith('SELECT 1 AS present FROM pg_roles')) {
+      if (text.startsWith('SELECT 1 AS present FROM pg_catalog.pg_roles')) {
         const role = params[0] as string;
         return Effect.succeed(
           (roleNames.has(role) || roleRows.has(role)
@@ -151,14 +158,14 @@ export const makeFakeSql = (options: FakeSqlOptions = {}): FakeSql => {
       // ⚠️ startsWith, BEFORE the `FROM pg_database` branch: the full-row select also contains
       //   `FROM pg_database`, but starts with `SELECT d.oid` — only the existence probe starts
       //   with `SELECT 1 AS present`.
-      if (text.startsWith('SELECT 1 AS present FROM pg_database')) {
+      if (text.startsWith('SELECT 1 AS present FROM pg_catalog.pg_database')) {
         const name = params[0] as string;
         return Effect.succeed(
           (databases.has(name) ? [{ present: 1 }] : []) as unknown as ReadonlyArray<A>,
         );
       }
 
-      if (text.includes('FROM pg_database')) {
+      if (text.includes('FROM pg_catalog.pg_database')) {
         const name = params[0] as string;
         const row = databases.get(name);
         return Effect.succeed((row === undefined ? [] : [row]) as unknown as ReadonlyArray<A>);

package/src/postgres/grants-database.test.ts

@@ -48,7 +48,7 @@ const recording = (probe: string, proof: string) => {
   const run: PsqlRunner = ({ stdin, argv }) => {
     stdins.push(stdin);
     argvs.push(argv);
-    const stdout = stdin.includes('FROM pg_database')
+    const stdout = stdin.includes('FROM pg_catalog.pg_database')
       ? probe
       : stdin.includes('current_database()')
         ? proof
@@ -79,7 +79,7 @@ describe('a missing declared database is absent', () => {
     // current_database()/GRANT/REVOKE ever targeted the (absent) declared database.
     expect(result).toBeUndefined();
     expect(stdins.length).toBe(1);
-    expect(stdins[0]).toContain('FROM pg_database');
+    expect(stdins[0]).toContain('FROM pg_catalog.pg_database');
     expect(stdins[0]).not.toContain('current_database()');
     expect(argvs[0]?.at(-1)).toBe('postgres');
   });
@@ -106,7 +106,7 @@ describe('a present database is opened and proved', () => {
         .pipe(Effect.provide(provide(run))),
     );
     expect(argvs[0]?.at(-1)).toBe('postgres');
-    expect(stdins[0]).toContain('FROM pg_database');
+    expect(stdins[0]).toContain('FROM pg_catalog.pg_database');
     expect(argvs.slice(1).every((argv) => argv.at(-1) === 'agents')).toBe(true);
     expect(stdins[1]).toContain('current_database()');
   });
@@ -129,7 +129,7 @@ describe('a present database is opened and proved', () => {
     // declared database and proves current_database() there.
     expect(argvs.length).toBe(2);
     expect(argvs[0]?.at(-1)).toBe('postgres');
-    expect(stdins[0]).toContain('FROM pg_database');
+    expect(stdins[0]).toContain('FROM pg_catalog.pg_database');
     expect(argvs[1]?.at(-1)).toBe('agents');
     expect(stdins[1]).toContain('current_database()');
   });
@@ -152,7 +152,7 @@ describe('a missing declared database on reconcile is a typed refusal', () => {
     expect(error).toMatchObject({ database: 'agents' });
     // Only the family-connection probe ran; reconcile never opened the declared database.
     expect(stdins.length).toBe(1);
-    expect(stdins[0]).toContain('FROM pg_database');
+    expect(stdins[0]).toContain('FROM pg_catalog.pg_database');
     expect(argvs[0]?.at(-1)).toBe('postgres');
   });
 });

package/src/postgres/grants-existence.ts

@@ -5,7 +5,7 @@
  * row `creating` and the resume failing OwnedBySomeoneElse.
  */
 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 type { DeclaredGrants } from './grants-declare.ts';
 import { PostgresGrantsColumnMissing, PostgresGrantsTableMissing } from './grants-errors.ts';
@@ -15,9 +15,9 @@ import { PostgresGrantsColumnMissing, PostgresGrantsTableMissing } from './grant
  * (`func.sgml@REL_18_6`). */
 const TABLES_PRESENT_SQL = `SELECT
     c.relname AS table
-  FROM pg_class c
-  WHERE c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = $1)
-    AND c.relname::text IN (SELECT json_array_elements_text($2::json))`;
+  FROM pg_catalog.pg_class c
+  WHERE c.relnamespace = (SELECT oid FROM pg_catalog.pg_namespace WHERE nspname = $1)
+    AND c.relname::text IN (SELECT pg_catalog.json_array_elements_text($2::json))`;
 
 const findMissingTable = (
   pg: PgExecutor,
@@ -41,13 +41,13 @@ const findMissingTable = (
 const COLUMNS_PRESENT_SQL = `SELECT
     c.relname AS table,
     a.attname AS column
-  FROM pg_attribute a
-  JOIN pg_class c ON c.oid = a.attrelid
-  WHERE c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = $1)
+  FROM pg_catalog.pg_attribute a
+  JOIN pg_catalog.pg_class c ON c.oid = a.attrelid
+  WHERE c.relnamespace = (SELECT oid FROM pg_catalog.pg_namespace WHERE nspname = $1)
     AND a.attnum > 0
     AND NOT a.attisdropped
     AND (c.relname, a.attname) IN (
-      SELECT x->>0, x->>1 FROM json_array_elements($2::json) x
+      SELECT x->>0, x->>1 FROM pg_catalog.json_array_elements($2::json) x
     )`;
 
 const findMissingColumn = (

package/src/postgres/grants-ops.ts

@@ -44,7 +44,7 @@
 import type { Input } from 'alchemy/Input';
 import * as Effect from 'effect/Effect';
 import { isResolved } from 'alchemy/Diff';
-import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { SqlError } from 'effect/sql/SqlError';
 import type { PostgresGrantsAttributes, PostgresGrantsProps } from './grants-attrs.ts';
 import { roleExists } from './database-sql.ts';
 import type { PgExecutor } from './database-sql.ts';

package/src/postgres/grants-ownership.ts

@@ -11,14 +11,14 @@
  *   queries, still inside the read's one bounded burst.
  */
 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';
 
 /** `pg_namespace.nspowner = <role>` for one schema. No rows when the schema is absent —
  * the caller then reads the fact as `false`. */
 const SCHEMA_OWNER_SQL = `SELECT
-    n.nspowner = (SELECT oid FROM pg_roles WHERE rolname = $2) AS role_owns
-  FROM pg_namespace n
+    n.nspowner = (SELECT oid FROM pg_catalog.pg_roles WHERE rolname = $2) AS role_owns
+  FROM pg_catalog.pg_namespace n
   WHERE n.nspname = $1`;
 
 export const readSchemaOwnership = (
@@ -34,9 +34,9 @@ export const readSchemaOwnership = (
 /** Every relation in the schema the declared role OWNS, all relkinds (the table class is
  * not relkind-filtered, and neither is this). */
 const OWNED_TABLES_SQL = `SELECT c.relname AS table
-  FROM pg_class c
-  WHERE c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = $1)
-    AND c.relowner = (SELECT oid FROM pg_roles WHERE rolname = $2)
+  FROM pg_catalog.pg_class c
+  WHERE c.relnamespace = (SELECT oid FROM pg_catalog.pg_namespace WHERE nspname = $1)
+    AND c.relowner = (SELECT oid FROM pg_catalog.pg_roles WHERE rolname = $2)
   ORDER BY c.relname`;
 
 export const readOwnedTables = (

package/src/postgres/grants-psql-lifecycle.test.ts

@@ -8,6 +8,7 @@ import { describe, expect, test } from 'bun:test';
 import * as Effect from 'effect/Effect';
 import type { PsqlRunner } from './psql-executor.ts';
 import { makePsqlExecutor } from './psql-executor.ts';
+import { stripPin } from './search-path.ts';
 import { reconcileWithClient } from './grants-ops.ts';
 import { requireDeclaredObjectsExist } from './grants-existence.ts';
 import { resolveProps } from './grants-declare.ts';
@@ -26,7 +27,8 @@ const props: PostgresGrantsProps = {
 const runner = (): { run: PsqlRunner; stdins: string[] } => {
   const stdins: string[] = [];
   let granted = false;
-  const run: PsqlRunner = ({ stdin }) => {
+  const run: PsqlRunner = ({ stdin: raw }) => {
+    const stdin = stripPin(raw);
     stdins.push(stdin);
     if (stdin.startsWith('BEGIN')) granted = true;
     return Promise.resolve({ code: 0, stdout: answer(stdin, granted), stderr: '' });
@@ -40,8 +42,10 @@ const answer = (stdin: string, granted: boolean): string => {
   if (stdin.includes('json_array_elements')) {
     return '[{"table":"a","column":"b.c"},{"table":"a.b","column":"c"}]';
   }
-  if (stdin.includes('SELECT 1 AS present FROM pg_roles')) return '[{"present":1}]';
-  if (stdin.includes('SELECT 1 AS present FROM pg_namespace')) return '[{"present":1}]';
+  if (stdin.includes('SELECT 1 AS present FROM pg_catalog.pg_roles')) return '[{"present":1}]';
+  if (stdin.includes('SELECT 1 AS present FROM pg_catalog.pg_namespace')) {
+    return '[{"present":1}]';
+  }
   if (stdin.includes('aclexplode(n.nspacl)')) {
     return granted ? '[{"public":false,"privilege":"usage","grantable":false}]' : '[]';
   }

package/src/postgres/grants-read-defaults.ts

@@ -7,7 +7,7 @@
  * header for the doctrine), never the `aclitem` text.
  */
 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 { type AclRow, encodeWord } from './grants-words.ts';
 
@@ -15,14 +15,14 @@ import { type AclRow, encodeWord } from './grants-words.ts';
  * role's words, whatever role created the entry. Sorted by forRole so two reads of the
  * same state compare equal. */
 const DEFAULTS_SQL = `SELECT
-    pg_get_userbyid(d.defaclrole) AS for_role,
+    pg_catalog.pg_get_userbyid(d.defaclrole) AS for_role,
     a.privilege_type AS privilege,
     a.is_grantable AS grantable
-  FROM pg_default_acl d
-  CROSS JOIN LATERAL aclexplode(d.defaclacl) AS a
-  WHERE d.defaclnamespace = (SELECT oid FROM pg_namespace WHERE nspname = $1)
+  FROM pg_catalog.pg_default_acl d
+  CROSS JOIN LATERAL pg_catalog.aclexplode(d.defaclacl) AS a
+  WHERE d.defaclnamespace = (SELECT oid FROM pg_catalog.pg_namespace WHERE nspname = $1)
     AND d.defaclobjtype = 'r'
-    AND a.grantee = (SELECT oid FROM pg_roles WHERE rolname = $2)
+    AND a.grantee = (SELECT oid FROM pg_catalog.pg_roles WHERE rolname = $2)
   ORDER BY for_role`;
 
 export interface LiveDefault {

package/src/postgres/grants-read.ts

@@ -32,13 +32,13 @@
  *   CASE in `database-sql.ts`, which casts `"char"` columns to text for the same reason.
  */
 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 { readOwnedTables, readSchemaOwnership } from './grants-ownership.ts';
 import { type LiveDefault, readDefaultAcls } from './grants-read-defaults.ts';
 import { type AclRow, encodeWord, wordsOf } from './grants-words.ts';
 
-const SCHEMA_PRESENT_SQL = 'SELECT 1 AS present FROM pg_namespace WHERE nspname = $1';
+const SCHEMA_PRESENT_SQL = 'SELECT 1 AS present FROM pg_catalog.pg_namespace WHERE nspname = $1';
 
 export const schemaExists = (pg: PgExecutor, schema: string): Effect.Effect<boolean, SqlError> =>
   Effect.map(
@@ -52,10 +52,10 @@ const SCHEMA_ACL_SQL = `SELECT
     a.grantee = 0 AS public,
     a.privilege_type AS privilege,
     a.is_grantable AS grantable
-  FROM pg_namespace n
-  CROSS JOIN LATERAL aclexplode(n.nspacl) AS a
+  FROM pg_catalog.pg_namespace n
+  CROSS JOIN LATERAL pg_catalog.aclexplode(n.nspacl) AS a
   WHERE n.nspname = $1
-    AND (a.grantee = 0 OR a.grantee = (SELECT oid FROM pg_roles WHERE rolname = $2))`;
+    AND (a.grantee = 0 OR a.grantee = (SELECT oid FROM pg_catalog.pg_roles WHERE rolname = $2))`;
 
 export interface LiveSchemaAcl {
   readonly role: ReadonlyArray<string>;
@@ -84,10 +84,10 @@ const TABLES_SQL = `SELECT
     a.grantee = 0 AS public,
     a.privilege_type AS privilege,
     a.is_grantable AS grantable
-  FROM pg_class c
-  CROSS JOIN LATERAL aclexplode(c.relacl) AS a
-  WHERE c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = $1)
-    AND (a.grantee = 0 OR a.grantee = (SELECT oid FROM pg_roles WHERE rolname = $2))
+  FROM pg_catalog.pg_class c
+  CROSS JOIN LATERAL pg_catalog.aclexplode(c.relacl) AS a
+  WHERE c.relnamespace = (SELECT oid FROM pg_catalog.pg_namespace WHERE nspname = $1)
+    AND (a.grantee = 0 OR a.grantee = (SELECT oid FROM pg_catalog.pg_roles WHERE rolname = $2))
   ORDER BY c.relname`;
 
 export interface LiveTable {
@@ -146,17 +146,17 @@ const COLUMNS_SQL = `SELECT
     a.grantee = 0 AS public,
     a.privilege_type AS privilege,
     a.is_grantable AS grantable,
-    pg_get_userbyid(a.grantor) AS grantor,
-    pg_get_userbyid(c.relowner) AS owner,
+    pg_catalog.pg_get_userbyid(a.grantor) AS grantor,
+    pg_catalog.pg_get_userbyid(c.relowner) AS owner,
     current_user AS revoker,
-    pg_has_role(current_user, c.relowner, 'USAGE') AS revoker_as_owner
-  FROM pg_attribute v
-  JOIN pg_class c ON c.oid = v.attrelid
-  CROSS JOIN LATERAL aclexplode(v.attacl) AS a
-  WHERE c.relnamespace = (SELECT oid FROM pg_namespace WHERE nspname = $1)
+    pg_catalog.pg_has_role(current_user, c.relowner, 'USAGE') AS revoker_as_owner
+  FROM pg_catalog.pg_attribute v
+  JOIN pg_catalog.pg_class c ON c.oid = v.attrelid
+  CROSS JOIN LATERAL pg_catalog.aclexplode(v.attacl) AS a
+  WHERE c.relnamespace = (SELECT oid FROM pg_catalog.pg_namespace WHERE nspname = $1)
     AND v.attnum > 0
     AND NOT v.attisdropped
-    AND (a.grantee = 0 OR a.grantee = (SELECT oid FROM pg_roles WHERE rolname = $2))
+    AND (a.grantee = 0 OR a.grantee = (SELECT oid FROM pg_catalog.pg_roles WHERE rolname = $2))
   ORDER BY c.relname, v.attname`;
 
 export interface LiveColumn {