@homeflare/alchemy 0.42.0 → 0.44.0

package/src/postgres/index.ts

@@ -1,16 +1,28 @@
 /**
- * PostgreSQL providers for Alchemy — `Postgres.Database`, create-and-assert over a self-hosted
- * cluster, walked against PostgreSQL 18.6. See `docs/postgres.md`.
+ * PostgreSQL providers for Alchemy — `Postgres.Database` (create-and-assert over one
+ * self-hosted cluster), `Postgres.Schema` (create-and-assert over one schema inside one),
+ * `Postgres.Role` (create / adopt / alter / drop of a LOGIN or NOLOGIN role whose password is a
+ * reference) and `Postgres.Grants` (declarative grant set diffed against the catalogs), walked
+ * against PostgreSQL 18.6. See `docs/postgres.md`, `docs/postgres-schema.md`,
+ * `docs/postgres-role.md` and `docs/postgres-grants.md`.
  *
- * ⛔ THIS BARREL IS THE PUBLIC API, deliberately smaller than the directory: `fake-sql.ts` is a
- *   test double, not something a consuming stack should import.
+ * ⛔ THIS BARREL IS THE PUBLIC API, deliberately smaller than the directory: `fake-sql.ts` and
+ *   `fake-grants-sql.ts` are test doubles, not something a consuming stack should import.
  */
-export type { PostgresConnectionConfig } from './connection.ts';
-export { PostgresConnection, postgresConnection, withPg } from './connection.ts';
+export type { PostgresConnectionConfig, PostgresRunnerConfig } from './connection.ts';
+export {
+  PostgresConnection,
+  postgresConnection,
+  postgresRunnerConnection,
+  withPg,
+} from './connection.ts';
+export type { PsqlResult, PsqlRunner } from './psql-executor.ts';
+export { inlineParams, makePsqlExecutor } from './psql-executor.ts';
 export type { PostgresDatabaseAttributes, PostgresDatabaseProps } from './database-attrs.ts';
 export { POSTGRES_NAME_MAX_BYTES, nameByteRefusal, utf8ByteLength } from './database-attrs.ts';
 export {
   buildCreateDatabaseSql,
+  databaseExists,
   firstDrift,
   isDuplicateDatabaseRace,
   quoteIdent,
@@ -19,6 +31,38 @@ export {
   selectDatabase,
 } from './database-sql.ts';
 export { PostgresDatabase, PostgresDatabaseProvider, isPostgresDatabase } from './database.ts';
+export type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+export { normalizedComment, schemaNameByteRefusal } from './schema-attrs.ts';
+export {
+  buildCommentSchemaSql,
+  buildCreateSchemaSql,
+  buildDropSchemaSql,
+  currentDatabase,
+  currentUser,
+  isDependentObjectsError,
+  schemaIsEmpty,
+  selectSchema,
+} from './schema-sql.ts';
+export {
+  PostgresSchema,
+  PostgresSchemaProvider,
+  diffPostgresSchema,
+  isPostgresSchema,
+} from './schema.ts';
+export {
+  PostgresSchemaCreateVanished,
+  PostgresSchemaExistsRefused,
+  PostgresSchemaIdentityRefused,
+  PostgresSchemaDatabaseRefused,
+  PostgresSchemaDeleteForeignRefused,
+  PostgresSchemaDrift,
+  PostgresSchemaDropNotEmptyError,
+  PostgresSchemaNameRefused,
+  PostgresSchemaOwnerMissing,
+  PostgresSchemaRenameRefused,
+  PostgresSchemaWrongDatabase,
+  type PostgresSchemaError,
+} from './schema-errors.ts';
 export {
   PostgresDatabaseDrift,
   PostgresDatabaseDropRefused,
@@ -27,4 +71,90 @@ export {
   PostgresDatabaseRenameRefused,
   type PostgresDatabaseError,
 } from './errors.ts';
-export { postgresProviders } from './providers.ts';
+export type {
+  PostgresGrantsAttributes,
+  PostgresGrantsAttributesColumn,
+  PostgresGrantsAttributesDefault,
+  PostgresGrantsAttributesTable,
+  PostgresGrantsColumn,
+  PostgresGrantsDefault,
+  PostgresGrantsProps,
+  PostgresGrantsTable,
+} from './grants-attrs.ts';
+export {
+  COLUMN_PRIVILEGES,
+  SCHEMA_PRIVILEGES,
+  TABLE_PRIVILEGES,
+  grantsNameByteRefusal,
+  letterForPrivilege,
+} from './grants-attrs.ts';
+export {
+  grantColumnSql,
+  grantDefaultSql,
+  grantSchemaSql,
+  grantTableSql,
+  revokeColumnSql,
+  revokeDefaultSql,
+  revokePublicSchemaSql,
+  revokePublicTablesSql,
+  revokeSchemaSql,
+  revokeTableSql,
+} from './grants-sql.ts';
+export { PostgresGrants, PostgresGrantsProvider, isPostgresGrants } from './grants.ts';
+export {
+  PostgresGrantsDatabaseMismatch,
+  PostgresGrantsDatabaseMissing,
+  PostgresGrantsDuplicateObject,
+  PostgresGrantsNameRefused,
+  PostgresGrantsPrivilegeRefused,
+  PostgresGrantsRepairRefused,
+  PostgresGrantsRetargetRefused,
+  PostgresGrantsRoleMissing,
+  PostgresGrantsSchemaMissing,
+  PostgresGrantsTableMissing,
+  PostgresGrantsColumnMissing,
+  type PostgresGrantsError,
+} from './grants-errors.ts';
+export type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+export { sameValidUntil, validUntilRefusal } from './role-attrs.ts';
+export {
+  buildAlterRoleSql,
+  buildCreateRoleSql,
+  buildDropRoleSql,
+  buildSetPasswordSql,
+  scalarDrift,
+  selectRole,
+} from './role-sql.ts';
+export {
+  buildGrantMembershipSql,
+  buildRepairMembershipSql,
+  buildRevokeGrantorMembershipSql,
+  membershipDrift,
+  selectRoleMemberships,
+  syncMemberships,
+  unsafeMemberships,
+} from './role-membership-sql.ts';
+export type { MembershipRow } from './role-membership-sql.ts';
+export { PostgresRole, isPostgresRole } from './role.ts';
+export { PostgresRoleProvider } from './role-provider.ts';
+export { resolvePassword } from './role-secrets.ts';
+export type { ResolvedPassword } from './role-secrets.ts';
+export type { FromEnv } from '../secrets/write-only.ts';
+export {
+  PostgresRoleCreateVanished,
+  PostgresRoleIdentityRefused,
+  PostgresRoleMembershipUnrepaired,
+  PostgresRoleNameRefused,
+  PostgresRoleParentMissing,
+  PostgresRolePasswordEnvUnsetError,
+  PostgresRolePrivilegedRefused,
+  PostgresRoleRenameRefused,
+  PostgresRoleValidUntilRefused,
+  type PostgresRoleError,
+} from './role-errors.ts';
+export {
+  postgresProviders,
+  postgresRoleProviders,
+  postgresRoleRunnerProviders,
+  postgresRunnerProviders,
+} from './providers.ts';

package/src/postgres/installed-classifier.ts

@@ -0,0 +1,36 @@
+/**
+ * The installed `@effect/sql-pg` classifier, for tests that must pin real driver behavior
+ * instead of a hand-built error shape.
+ *
+ * ⛔ TEST-ONLY, PINNED TO THE INSTALLED DRIVER. `@effect/sql-pg` nulls the `./internal/*`
+ * export, so the public specifier cannot name `src/internal/sqlError.ts`; the file URL is
+ * resolved from the installed package's `package.json` — the same module
+ * `PgConnection.ts#classifyFields` calls. If the driver moves the file, the import fails
+ * loudly in the tests that use it rather than silently asserting a fabricated shape.
+ */
+import { SqlError } from 'effect/unstable/sql/SqlError';
+
+export const classifyInstalled = async (
+  code: string,
+  message = 'dependent objects still exist',
+): Promise<SqlError> => {
+  // `package.json` sets `"./internal/*": null`, so the specifier cannot name this file.
+  // `import.meta.resolve` finds the installed package; `src/internal/sqlError.ts` is the
+  // module `PgConnection.ts#classifyFields` calls.
+  const root = import.meta.resolve('@effect/sql-pg/package.json');
+  const href = new URL('./src/internal/sqlError.ts', root).href;
+  const mod = (await import(href)) as {
+    classifySqlState: (
+      code: string | undefined,
+      constraint: unknown,
+      props: { cause: unknown; message: string; operation: string },
+    ) => SqlError['reason'];
+  };
+  return new SqlError({
+    reason: mod.classifySqlState(code, undefined, {
+      cause: Object.assign(new Error(message), { code, message }),
+      message: `ERROR:  ${code}: ${message}`,
+      operation: 'DROP SCHEMA',
+    }),
+  });
+};

package/src/postgres/providers.ts

@@ -1,16 +1,53 @@
 /**
- * `Postgres.Database`'s provider, pre-wired to one cluster:
+ * `Postgres.*` providers, pre-wired for one cluster:
  *
- *     const providers = postgresProviders({ host: '/opt/homeflare/postgres/sockets', database: 'postgres', username: 'tim' });
+ *     const providers = postgresProviders({ host: '/var/run/postgresql', database: 'postgres', username: 'tim' });
  *
- * ★ THE CLUSTER IS A PARAMETER, NOT A DEFAULT (S15, and `docs/postgres.md#path`). This kit is
- *   PUBLIC; the mini's socket directory, its user and its port are the CONSUMING stack's values,
- *   never baked in here. A stack with more than one cluster calls this more than once and merges
+ * ★ THE CLUSTER IS THE PARAMETER, NOT A DEFAULT (S15, `docs/postgres.md#path`). This kit is
+ *   PUBLIC; mini's socket directory, user and port are the CONSUMING stack's values,
+ *   never baked in here. A stack with more than one cluster calls this once per cluster and merges
  *   the results under whatever logical grouping it wants.
  */
 import * as Layer from 'effect/Layer';
-import { type PostgresConnectionConfig, postgresConnection } from './connection.ts';
+import {
+  type PostgresConnectionConfig,
+  type PostgresRunnerConfig,
+  postgresConnection,
+  postgresRunnerConnection,
+} from './connection.ts';
 import { PostgresDatabaseProvider } from './database.ts';
+import { PostgresGrantsProvider } from './grants.ts';
+import { PostgresRoleProvider } from './role-provider.ts';
+import { PostgresSchemaProvider } from './schema.ts';
 
+// ⚠️ `Layer.provideMerge`, NEVER plain `Layer.provide`: the handlers' `withPg` reads
+//   `PostgresConnection` when the ENGINE later calls `read`/`reconcile`, and plain `provide`
+//   seals it away ("Service not found: Postgres.Connection" — measured for `caddyProviders`,
+//   see `caddy/providers.ts`). Each resource provider merges its own connection in; the three
+//   results are merged per resource (`Layer.mergeAll`, the same shape `unifi/providers.ts`).
 export const postgresProviders = (config: PostgresConnectionConfig) =>
-  PostgresDatabaseProvider().pipe(Layer.provide(postgresConnection(config)));
+  Layer.mergeAll(
+    PostgresDatabaseProvider().pipe(Layer.provideMerge(postgresConnection(config))),
+    PostgresSchemaProvider().pipe(Layer.provideMerge(postgresConnection(config))),
+    PostgresGrantsProvider().pipe(Layer.provideMerge(postgresConnection(config))),
+  );
+
+/** The same providers over a command runner (`psql-executor.ts`) — for loopback-only clusters. */
+export const postgresRunnerProviders = (config: PostgresRunnerConfig) =>
+  Layer.mergeAll(
+    PostgresDatabaseProvider().pipe(Layer.provideMerge(postgresRunnerConnection(config))),
+    PostgresSchemaProvider().pipe(Layer.provideMerge(postgresRunnerConnection(config))),
+    PostgresGrantsProvider().pipe(Layer.provideMerge(postgresRunnerConnection(config))),
+  );
+
+/**
+ * `Postgres.Role`'s provider, over the same socket transport and the same cluster parameter.
+ *
+ *     const providers = postgresRoleProviders({ host: '/opt/homeflare/postgres/sockets', database: 'postgres', username: 'tim' });
+ */
+export const postgresRoleProviders = (config: PostgresConnectionConfig) =>
+  PostgresRoleProvider().pipe(Layer.provideMerge(postgresConnection(config)));
+
+/** `Postgres.Role` over a command runner (`psql-executor.ts`) — for loopback-only clusters. */
+export const postgresRoleRunnerProviders = (config: PostgresRunnerConfig) =>
+  PostgresRoleProvider().pipe(Layer.provideMerge(postgresRunnerConnection(config)));

package/src/postgres/psql-executor-escaping.test.ts

@@ -0,0 +1,67 @@
+/** PG18 lexical §4.1.2.2 regressions: exercise the fake and the executor's actual stdin. */
+import { expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { makeFakeSql } from './fake-sql.ts';
+import { parseLiteral } from './fake-sql-quote.ts';
+import { buildCommentSchemaSql } from './schema-sql.ts';
+import { buildSetPasswordSql } from './role-sql.ts';
+import { makePsqlExecutor, redactPasswordLiterals } from './psql-executor.ts';
+
+const payload = "\\'; CREATE SCHEMA injected; --";
+const target = { database: 'postgres', username: 'postgres' };
+const row = { name: 'ledger', database: 'postgres', owner: 'postgres', oid: 42, comment: null };
+
+for (const on of [true, false]) {
+  test(`fake comment round-trips hostile text with standard_conforming_strings=${String(on)}`, async () => {
+    const fake = makeFakeSql({ schemas: [row], standardConformingStrings: on });
+    await Effect.runPromise(fake.unsafe(buildCommentSchemaSql('ledger', payload)));
+    expect(fake.schemas.get('ledger')?.comment).toBe(payload);
+    expect(fake.schemas.has('injected')).toBe(false);
+  });
+
+  test(`psql executor comment and bound param stay one literal with standard_conforming_strings=${String(on)}`, async () => {
+    const fake = makeFakeSql({ schemas: [row], standardConformingStrings: on });
+    const calls: string[] = [];
+    const pg = makePsqlExecutor(async ({ stdin }) => {
+      calls.push(stdin);
+      if (stdin.startsWith('COMMENT')) {
+        await Effect.runPromise(fake.unsafe(stdin.slice(0, -1)));
+        return { code: 0, stdout: '', stderr: '' };
+      }
+      const prefix = "SELECT coalesce(json_agg(t), '[]'::json)::text FROM (SELECT ";
+      expect(stdin.startsWith(prefix)).toBe(true);
+      const literal = stdin.slice(prefix.length, -' AS value) t;'.length);
+      const value = parseLiteral(literal, on);
+      return { code: 0, stdout: JSON.stringify([{ value }]), stderr: '' };
+    }, target);
+    await Effect.runPromise(pg.unsafe(buildCommentSchemaSql('ledger', payload)));
+    const rows = await Effect.runPromise(
+      pg.unsafe<{ value: string }>('SELECT $1 AS value', [payload]),
+    );
+    expect(rows).toEqual([{ value: payload }]);
+    expect(fake.schemas.get('ledger')?.comment).toBe(payload);
+    expect(fake.schemas.has('injected')).toBe(false);
+    expect(calls[0]).toContain("IS E'\\\\''; CREATE SCHEMA injected; --'");
+  });
+}
+
+test('escape-literal regression oracle rejects the old injection when the setting is off', () => {
+  expect(() => parseLiteral("'\\''; CREATE SCHEMA injected; --'", false)).toThrow('trailing SQL');
+});
+
+test('Role password redaction covers escape strings, including escaped quotes and backslashes', async () => {
+  const statement = buildSetPasswordSql('seat', "verifier\\'tail");
+  expect(redactPasswordLiterals(statement)).toBe('ALTER ROLE "seat" WITH PASSWORD \'[redacted]\'');
+  const pg = makePsqlExecutor(
+    async () => ({
+      code: 3,
+      stdout: '',
+      stderr: `ERROR:  42501: refused\nSTATEMENT: ${statement}`,
+    }),
+    target,
+  );
+  const error = await Effect.runPromise(Effect.flip(pg.unsafe(statement)));
+  expect(JSON.stringify(error)).not.toContain('verifier');
+  expect(JSON.stringify(error)).not.toContain('tail');
+  expect(redactPasswordLiterals("PASSWORD 'legacy'")).toBe("PASSWORD '[redacted]'");
+});

package/src/postgres/psql-executor.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { postgresRunnerProviders } from './providers.ts';
+import { postgresRunnerConnection, withPg } from './connection.ts';
+import { reconcileWithClient } from './database.ts';
+import { buildCreateDatabaseSql, isDuplicateDatabaseRace } from './database-sql.ts';
+import { buildSetPasswordSql } from './role-sql.ts';
+import { scramSha256Verifier } from './role-scram.ts';
+import { type PsqlRunner, inlineParams, makePsqlExecutor } from './psql-executor.ts';
+
+const target = { database: 'postgres', username: 'postgres' };
+const ok = (stdout: string) => Promise.resolve({ code: 0, stdout, stderr: '' });
+
+describe('psql executor', () => {
+  test('inlines string params as literals and refuses non-strings', () => {
+    expect(inlineParams('SELECT $1, $2', ["it's", 'b'])).toBe("SELECT E'it''s', E'b'");
+    expect(() => inlineParams('SELECT $1', [5])).toThrow('must be a string');
+  });
+
+  test('a SELECT is wrapped in json_agg and parsed to rows', async () => {
+    const calls: { argv: readonly string[]; stdin: string }[] = [];
+    const run: PsqlRunner = (call) => {
+      calls.push(call);
+      return ok('[{"oid":"16400","name":"x"}]\n');
+    };
+    const rows = await Effect.runPromise(
+      makePsqlExecutor(run, target).unsafe('SELECT 1 FROM pg_database WHERE datname = $1', ['x']),
+    );
+    expect(rows).toEqual([{ oid: 16400, name: 'x' }]);
+    expect(calls[0]?.argv.slice(0, 1)).toEqual(['psql']);
+    expect(calls[0]?.stdin).toContain('json_agg');
+    expect(calls[0]?.stdin).toContain("datname = E'x'");
+  });
+
+  test('a WITH-led row query is wrapped in json_agg too, not discarded as a write', async () => {
+    // The schema emptiness check is `WITH ns AS (…) SELECT …` — unwrapped, its answer rows
+    // are dropped and the check reads the empty-table fallback ("every schema is empty").
+    const calls: { argv: readonly string[]; stdin: string }[] = [];
+    const run: PsqlRunner = (call) => {
+      calls.push(call);
+      return ok('[{"empty":false}]\n');
+    };
+    const rows = await Effect.runPromise(
+      makePsqlExecutor(run, target).unsafe(
+        'WITH ns AS (SELECT 1 AS oid) SELECT NOT EXISTS (SELECT 1 FROM pg_class) AS empty',
+      ),
+    );
+    expect(rows).toEqual([{ empty: false }]);
+    expect(calls[0]?.stdin).toContain('json_agg');
+  });
+
+  test('a duplicate-database failure stays recognisable as the 42P04 race', async () => {
+    const run: PsqlRunner = () =>
+      Promise.resolve({
+        code: 3,
+        stdout: '',
+        stderr: 'ERROR:  42P04: database "x" already exists\n',
+      });
+    const error = await Effect.runPromise(
+      Effect.flip(makePsqlExecutor(run, target).unsafe('CREATE DATABASE "x"')),
+    );
+    expect(isDuplicateDatabaseRace(error)).toBe(true);
+  });
+
+  test('a failed password statement carries the SCRAM verifier on stdin, never the plain password', async () => {
+    // The red-team finding: the statement text is what the runner inlines into `psql`'s stdin and
+    // what a failed `ALTER` echoes back through stderr into the error. Since the fix the text
+    // holds only the verifier, so both the stdin side and the error side stay secret-free.
+    const placeholder = 'placeholder-password';
+    const statement = buildSetPasswordSql('hf_agent', scramSha256Verifier(placeholder));
+    let stdin = '';
+    const run: PsqlRunner = async (call) => {
+      stdin = call.stdin;
+      return {
+        code: 3,
+        stdout: '',
+        stderr: `ERROR:  42501: permission denied\nSTATEMENT:  ${statement}\n`,
+      };
+    };
+    const error = await Effect.runPromise(
+      Effect.flip(makePsqlExecutor(run, target).unsafe(statement)),
+    );
+    const rendered = `${error.message}\n${String(error.reason.operation ?? '')}\n${JSON.stringify(error)}`;
+    expect(stdin).toContain('SCRAM-SHA-256$');
+    expect(stdin).not.toContain(placeholder);
+    expect(rendered).not.toContain(placeholder);
+    expect(rendered).not.toContain(`PASSWORD E'${placeholder.slice(0, 3)}`);
+  });
+
+  test('a runner that never reached psql is a ConnectionError', async () => {
+    const run: PsqlRunner = () =>
+      Promise.resolve({ code: 255, stdout: '', stderr: 'ssh: refused' });
+    const error = await Effect.runPromise(
+      Effect.flip(makePsqlExecutor(run, target).unsafe('SELECT 1')),
+    );
+    expect(error.reason._tag).toBe('ConnectionError');
+  });
+});
+
+describe('runner transport through withPg', () => {
+  test('create uses template0 by default and the same adopt path on an existing row', async () => {
+    const stdins: string[] = [];
+    const row = {
+      oid: 1,
+      name: 'lite',
+      owner: 'litellm',
+      encoding: 'UTF8',
+      localeProvider: 'libc',
+      collate: 'C',
+      ctype: 'C',
+      allowConnections: true,
+      connectionLimit: -1,
+      isTemplate: false,
+      tablespace: 'pg_default',
+    };
+    let created = false;
+    const run: PsqlRunner = ({ stdin }) => {
+      stdins.push(stdin);
+      if (stdin.includes('pg_roles')) return ok('[{"present":1}]');
+      if (stdin.includes('FROM pg_database')) return ok(created ? JSON.stringify([row]) : '[]');
+      if (stdin.startsWith('CREATE DATABASE')) created = true;
+      return ok('');
+    };
+    const layer = postgresRunnerConnection({ run, ...target });
+    const props = { name: 'lite', owner: 'litellm' };
+    const attrs = await Effect.runPromise(
+      withPg((pg, ctx) => reconcileWithClient(pg, props, ctx.template)).pipe(Effect.provide(layer)),
+    );
+    expect(attrs.name).toBe('lite');
+    expect(stdins.find((s) => s.startsWith('CREATE DATABASE'))).toBe(
+      `${buildCreateDatabaseSql(props, 'template0')};`,
+    );
+    expect(stdins.find((s) => s.startsWith('CREATE DATABASE'))).toContain('TEMPLATE "template0"');
+    const before = stdins.length;
+    await Effect.runPromise(
+      withPg((pg, ctx) => reconcileWithClient(pg, props, ctx.template)).pipe(Effect.provide(layer)),
+    );
+    expect(stdins.slice(before).some((s) => s.startsWith('CREATE DATABASE'))).toBe(false);
+  });
+
+  test('transaction is one psql script from BEGIN through COMMIT', async () => {
+    const calls: string[] = [];
+    const run: PsqlRunner = (call) => {
+      calls.push(call.stdin);
+      return ok('');
+    };
+    await Effect.runPromise(
+      makePsqlExecutor(run, target).transaction([
+        'CREATE ROLE "a" WITH NOLOGIN',
+        'GRANT "p" TO "a" WITH SET FALSE',
+      ]),
+    );
+    expect(calls).toEqual([
+      'BEGIN;\nCREATE ROLE "a" WITH NOLOGIN;\nGRANT "p" TO "a" WITH SET FALSE;\nCOMMIT;',
+    ]);
+  });
+
+  test("postgresRunnerProviders keeps the connection live for the engine's later handler calls", async () => {
+    const run: PsqlRunner = () => ok('[]');
+    const rows = await Effect.runPromise(
+      withPg((pg) => pg.unsafe('SELECT 1')).pipe(
+        Effect.provide(postgresRunnerProviders({ run, ...target })),
+      ),
+    );
+    expect(rows).toEqual([]);
+  });
+});

package/src/postgres/psql-executor.ts

@@ -0,0 +1,170 @@
+/**
+ * A `PgExecutor` that runs SQL through a caller-supplied command runner instead of a socket.
+ *
+ * For a host whose Postgres listens on loopback only inside a container (CT100: rootful podman
+ * container `postgres`, local socket, user `postgres`, no password): the consumer's runner is
+ * `ssh <host> sudo -n podman exec -i postgres <argv…>`, and this file only builds the `psql`
+ * argv and stdin and parses the answer.
+ *
+ * ⛔ NO ESTATE VALUE LIVES HERE (public kit). The ssh destination, container name and sudo
+ *   allowlist are the runner's, in the consuming stack.
+ * ⛔ `psql` HAS NO BIND PARAMETERS OVER STDIN. Every `$n` is replaced by a `quoteStringLiteral`
+ *   literal, and ONLY string params are accepted — this family binds a database or role name,
+ *   nothing else — so a number or object is a refusal, never silently stringified.
+ * ★ ROWS COME BACK AS JSON: a row-returning statement (`SELECT`, or a `WITH` query) is wrapped
+ *   in `json_agg`, so `oid` and `datconnlimit` arrive as JS numbers exactly as the socket client
+ *   decodes them (database-sql.ts, no bigint).
+ * ★ `VERBOSITY=verbose` puts the SQLSTATE in the error line, so `42P04` (duplicate database)
+ *   stays recognisable to `isDuplicateDatabaseRace`.
+ */
+import * as Effect from 'effect/Effect';
+import {
+  ConnectionError,
+  SqlError,
+  SqlSyntaxError,
+  UnknownError,
+} from 'effect/unstable/sql/SqlError';
+import { type PgExecutor, quoteStringLiteral } from './database-sql.ts';
+
+export interface PsqlResult {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/** Runs one `psql` argv (starting with `psql`) with `stdin` and answers its exit. The consumer's
+ * implementation prepends the transport (`ssh … sudo -n podman exec -i <container>`) and owns
+ * the timeout and output bound: the kit sets neither. */
+export type PsqlRunner = (call: {
+  readonly argv: readonly string[];
+  readonly stdin: string;
+}) => Promise<PsqlResult>;
+
+export interface PsqlTarget {
+  readonly database: string;
+  readonly username: string;
+}
+
+/** Replace `$1…$n` with string literals; refuses a non-string param or a missing one. */
+export const inlineParams = (sql: string, params: ReadonlyArray<unknown>): string =>
+  params.length === 0
+    ? sql
+    : sql.replace(/\$(\d+)/g, (_match, index: string) => {
+        const value = params[Number(index) - 1];
+        if (typeof value !== 'string') {
+          throw new Error(`psql executor: param $${index} must be a string, got ${typeof value}`);
+        }
+        return quoteStringLiteral(value);
+      });
+
+/** Postgres `to_json` emits the `oid` type as a string; the socket driver returns a number. */
+const normalizeRow = (row: unknown): unknown =>
+  typeof row === 'object' && row !== null && typeof (row as { oid?: unknown }).oid === 'string'
+    ? { ...row, oid: Number((row as { oid: string }).oid) }
+    : row;
+
+/** Row-returning statements: a plain `SELECT`, or a CTE query (`WITH … SELECT …`). A `WITH`
+ * whose rows were discarded would answer an empty table instead of its result — the emptiness
+ * check is `WITH`-led, so a missing `WITH` here silently claims every schema is empty. */
+const returnsRows = (sql: string): boolean => /^\s*(SELECT|WITH)\b/i.test(sql);
+
+const wrapRows = (sql: string): string =>
+  `SELECT coalesce(json_agg(t), '[]'::json)::text FROM (${sql}) t;`;
+
+/** A password literal must not survive into an error Alchemy logs. `ALTER ROLE … PASSWORD`
+ * inlines the value (Postgres has no bind form), and the runner turns the first 40 characters
+ * of that statement into `operation` and the full `stderr` into `message`. */
+export const redactPasswordLiterals = (text: string): string =>
+  text.replace(
+    /PASSWORD\s+(?:E'(?:[^'\\]|\\[\s\S]|'')*'|'(?:[^']|'')*')/gi,
+    "PASSWORD '[redacted]'",
+  );
+
+const failure = (operation: string, result: PsqlResult): SqlError => {
+  const state = /ERROR:\s+([0-9A-Z]{5}):/.exec(result.stderr)?.[1];
+  const stderr = redactPasswordLiterals(result.stderr.trim());
+  const fields = {
+    cause: Object.assign(new Error(stderr), state === undefined ? {} : { code: state }),
+    message: stderr,
+    operation: redactPasswordLiterals(operation),
+  };
+  const reason =
+    state === undefined
+      ? new ConnectionError(fields)
+      : state.startsWith('42')
+        ? new SqlSyntaxError(fields)
+        : new UnknownError(fields);
+  return new SqlError({ reason });
+};
+
+const runScript = (
+  run: PsqlRunner,
+  target: PsqlTarget,
+  stdin: string,
+  operation: string,
+): Effect.Effect<PsqlResult, SqlError> =>
+  Effect.gen(function* () {
+    const result = yield* Effect.tryPromise({
+      try: () =>
+        run({
+          argv: [
+            'psql',
+            '-X',
+            '-q',
+            '-A',
+            '-t',
+            '-v',
+            'ON_ERROR_STOP=1',
+            '-v',
+            'VERBOSITY=verbose',
+            '-U',
+            target.username,
+            '-d',
+            target.database,
+          ],
+          stdin,
+        }),
+      catch: (cause) =>
+        new SqlError({ reason: new ConnectionError({ cause, operation: 'psql exec' }) }),
+    });
+    if (result.code !== 0) {
+      return yield* Effect.fail(failure(operation, result));
+    }
+    return result;
+  });
+
+export const makePsqlExecutor = (run: PsqlRunner, target: PsqlTarget): PgExecutor => ({
+  unsafe: <A extends object>(sql: string, params: ReadonlyArray<unknown> = []) =>
+    Effect.gen(function* () {
+      const inlined = yield* Effect.try({
+        try: () => inlineParams(sql, params),
+        catch: (cause) =>
+          new SqlError({ reason: new UnknownError({ cause, operation: 'psql inline params' }) }),
+      });
+      const rows = returnsRows(inlined);
+      const result = yield* runScript(
+        run,
+        target,
+        rows ? wrapRows(inlined) : `${inlined};`,
+        redactPasswordLiterals(inlined).slice(0, 40),
+      );
+      if (!rows) return [] as ReadonlyArray<A>;
+      const parsed = yield* Effect.try({
+        try: () => (JSON.parse(result.stdout.trim() || '[]') as unknown[]).map(normalizeRow),
+        catch: (cause) =>
+          new SqlError({ reason: new UnknownError({ cause, operation: 'psql parse output' }) }),
+      });
+      return parsed as ReadonlyArray<A>;
+    }),
+  /**
+   * One `psql` session: `BEGIN` … statements … `COMMIT`. `ON_ERROR_STOP` exits before `COMMIT`
+   * on a failure, and the backend aborts the open transaction when that session drops
+   * (`postgres.c@REL_18_6` `SocketBackend` EOF while `IsTransactionState`). Separate `unsafe`
+   * calls cannot do this — each is its own process and its own autocommit.
+   */
+  transaction: (statements) =>
+    Effect.gen(function* () {
+      const script = ['BEGIN', ...statements, 'COMMIT'].join(';\n');
+      yield* runScript(run, target, `${script};`, 'BEGIN');
+    }),
+});