@homeflare/alchemy 0.42.0 → 0.44.0

package/src/postgres/connection.ts

@@ -18,6 +18,8 @@ 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 { PgExecutor } from './database-sql.ts';
+import { type PsqlRunner, makePsqlExecutor } from './psql-executor.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
@@ -31,11 +33,30 @@ export interface PostgresConnectionConfig {
   readonly ssl?: boolean;
 }
 
+/** The runner transport (`psql-executor.ts`): SQL goes through `run` instead of a socket, for a
+ * host whose Postgres is reachable only by a command (CT100: ssh + `podman exec`). `template`
+ * is the `CREATE DATABASE` template — `template0` by default, because CT100's `template1` is
+ * ParadeDB's and would copy postgis/pg_ivm/paradedb objects into every new database. */
+export interface PostgresRunnerConfig {
+  readonly run: PsqlRunner;
+  readonly database: string;
+  readonly username: string;
+  readonly template?: string;
+}
+
+/** What `withPg`'s callback learns about the transport beyond the client. `database` is the
+ * database the statements run IN: the family connection's, or the override `Postgres.Schema`
+ * and `Postgres.Grants` pass so they open their declared database and then prove it. */
+export interface PgContext {
+  readonly template?: string;
+  readonly database: string;
+}
+
 /** The lazy connection service. Its value is an `Effect` of the config, per S24 — see the file
  * header for why. */
 export class PostgresConnection extends Context.Service<
   PostgresConnection,
-  Effect.Effect<PostgresConnectionConfig>
+  Effect.Effect<PostgresConnectionConfig | PostgresRunnerConfig>
 >()('Postgres.Connection') {}
 
 /** A stack's one-line way to provide a cluster: `Layer.provide(postgresConnection({ … }))` on
@@ -44,6 +65,19 @@ export const postgresConnection = (
   config: PostgresConnectionConfig,
 ): Layer.Layer<PostgresConnection> => Layer.succeed(PostgresConnection, Effect.succeed(config));
 
+/** A stack's one-line way to provide a cluster reached through a command runner. */
+export const postgresRunnerConnection = (
+  config: PostgresRunnerConfig,
+): Layer.Layer<PostgresConnection> => Layer.succeed(PostgresConnection, Effect.succeed(config));
+
+/** Effect-scoped pool factory, like BaoGate: tests override it without process-wide module mocks. */
+export const PostgresPool = Context.Reference<typeof PgClient.layer>('homeflare/postgres/Pool', {
+  defaultValue: () => PgClient.layer,
+});
+
+const isRunner = (c: PostgresConnectionConfig | PostgresRunnerConfig): c is PostgresRunnerConfig =>
+  'run' in c;
+
 /**
  * Run one operation against a freshly built, freshly closed connection pool.
  *
@@ -51,12 +85,47 @@ export const postgresConnection = (
  * operation — never once per statement — so a reconcile that runs a `SELECT`, then a `CREATE`,
  * then a re-read shares one pool and closes it once, while a plan-only `read` still opens and
  * closes its own.
+ *
+ * `database` overrides which database of the SAME cluster the pool opens — the declared
+ * database of `Postgres.Schema` and `Postgres.Grants`. The family connection is pointed at a
+ * maintenance database (a brand-new database cannot be connected to on a cold plan), so those
+ * resources pass their declared database here: the runner transport swaps the `psql -d` target,
+ * the socket path swaps the pool's `database`. The swap is proven, not trusted: schema rows
+ * carry `current_database()` (`schema-sql.ts`) and grants calls the same function before writing.
  */
 export const withPg = <A, E>(
-  build: (pg: PgClient.PgClient) => Effect.Effect<A, E>,
+  build: (pg: PgExecutor, context: PgContext) => Effect.Effect<A, E>,
+  database?: string,
 ): Effect.Effect<A, E | SqlError, PostgresConnection> =>
   Effect.gen(function* () {
     const resolveConfig = yield* PostgresConnection;
     const config = yield* resolveConfig;
-    return yield* Effect.provide(Effect.flatMap(PgClient.PgClient, build), PgClient.layer(config));
+    const target: PostgresConnectionConfig | PostgresRunnerConfig =
+      database === undefined ? config : { ...config, database };
+    if (isRunner(target)) {
+      return yield* build(makePsqlExecutor(target.run, target), {
+        template: target.template ?? 'template0',
+        database: target.database,
+      });
+    }
+    const pool = yield* PostgresPool;
+    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 },
+        ),
+      ),
+      pool(target),
+    );
   });

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

@@ -90,6 +90,7 @@ const wireAccuratePg = (seed?: {
         }
         throw new Error(`wireAccuratePg: unrecognised statement: ${text}`);
       }) as Effect.Effect<ReadonlyArray<A>, SqlError>,
+    transaction: () => Effect.void,
   };
 };
 

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

@@ -50,12 +50,12 @@ describe('quoting', () => {
   });
 
   test('quoteStringLiteral doubles an embedded single quote', () => {
-    expect(quoteStringLiteral("en_US.UTF-8'; DROP")).toBe("'en_US.UTF-8''; DROP'");
+    expect(quoteStringLiteral("en_US.UTF-8'; DROP")).toBe("E'en_US.UTF-8''; DROP'");
   });
 
   test('buildCreateDatabaseSql never string-concatenates an unescaped value', () => {
     const sql = buildCreateDatabaseSql({ name: 'db"1', owner: 'ro"le', encoding: "UT'F8" });
-    expect(sql).toBe('CREATE DATABASE "db""1" WITH OWNER "ro""le" ENCODING \'UT\'\'F8\'');
+    expect(sql).toBe('CREATE DATABASE "db""1" WITH OWNER "ro""le" ENCODING E\'UT\'\'F8\'');
   });
 });
 

package/src/postgres/database-sql.ts

@@ -19,23 +19,33 @@
  *   `createdb_opt_item`'s string branch is `opt_boolean_or_string → NonReservedWord_or_Sconst →
  *   NonReservedWord | Sconst`. A locale like `en_US.UTF-8` would hit the same dot-splitting
  *   `quoteIdent` avoids if it were identifier-quoted; a plain `Sconst` (`quoteStringLiteral`) has
- *   no such rule. This rests on `standard_conforming_strings = on` (the PG18 default, and
- *   measured live 2026-09-23 — `docs/postgres.md#measured`); the escaper only ever doubles `'`
- *   and never emits a backslash, so it never depends on which way that setting points.
+ *   no such rule. Use E'…' with doubled backslashes and quotes: PostgreSQL 18 lexical
+ *   section 4.1.2.2 makes escape strings independent of standard_conforming_strings.
+ *   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 * as Effect from 'effect/Effect';
 import type { PostgresDatabaseAttributes, PostgresDatabaseProps } from './database-attrs.ts';
 
 /** What every function in this file needs from a client — real (`PgClient.PgClient`) or fake
- * (`fake-sql.ts`). Deliberately smaller than `SqlClient`: nothing here ever needs the tagged
- * template, transactions or streaming, because every statement is either bound params through
- * `.unsafe(text, params)` or a hand-escaped literal through `.unsafe(text)`. */
+ * (`fake-sql.ts`). Deliberately smaller than `SqlClient`: nothing here needs the tagged template
+ * or streaming. `transaction` is the exception `Postgres.Role`'s create and `Postgres.Grants`'
+ * repair share: role DDL commits per statement unless the statements share a transaction, and
+ * a grants repair's `REVOKE` must not autocommit apart from the `GRANT`s that restore it. */
 export interface PgExecutor {
   readonly unsafe: <A extends object>(
     sql: string,
     params?: ReadonlyArray<unknown>,
   ) => Effect.Effect<ReadonlyArray<A>, SqlError>;
+  /**
+   * Run `statements` in one transaction. `CREATE ROLE`, `ALTER ROLE` and `GRANT`/`REVOKE` of
+   * membership are transactional (`utility.c@REL_18_6`: those cases do not call
+   * `PreventInTransactionBlock`; `CREATE DATABASE` does). The socket client reserves one
+   * connection (`SqlClient.withTransaction`); the runner sends one `psql` script, because each
+   * `unsafe` call is its own session and would autocommit.
+   */
+  readonly transaction: (statements: readonly string[]) => Effect.Effect<void, SqlError>;
 }
 
 /** Single-token identifier quoting: wrap in `"`, double any embedded `"`. No dot-splitting —
@@ -43,12 +53,14 @@ export interface PgExecutor {
  * `NonReservedWord` too, for `OWNER` and `TABLESPACE`. */
 export const quoteIdent = (value: string): string => `"${value.replace(/"/g, '""')}"`;
 
-/** SQL string-literal quoting: wrap in `'`, double any embedded `'`. Used for every `WITH`
- * value that is locale or encoding text, never for an identifier (see the file header). */
-export const quoteStringLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`;
+/** Escape-string quoting is safe with standard_conforming_strings either on or off.
+ * Double backslashes BEFORE quotes, so caller text cannot escape a closing delimiter. */
+export const quoteStringLiteral = (value: string): string =>
+  `E'${value.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`;
 
-const withOptions = (props: PostgresDatabaseProps): string => {
+const withOptions = (props: PostgresDatabaseProps, template?: string): string => {
   const parts: string[] = [`OWNER ${quoteIdent(props.owner)}`];
+  if (template !== undefined) parts.push(`TEMPLATE ${quoteIdent(template)}`);
   if (props.encoding !== undefined) parts.push(`ENCODING ${quoteStringLiteral(props.encoding)}`);
   if (props.localeProvider !== undefined) {
     parts.push(`LOCALE_PROVIDER ${quoteStringLiteral(props.localeProvider)}`);
@@ -74,8 +86,8 @@ const withOptions = (props: PostgresDatabaseProps): string => {
  * `Math.trunc`ed and stringified, and a boolean is one of exactly two literal words this file
  * writes, so no declared value reaches the statement through string interpolation unescaped.
  */
-export const buildCreateDatabaseSql = (props: PostgresDatabaseProps): string =>
-  `CREATE DATABASE ${quoteIdent(props.name)} WITH ${withOptions(props)}`;
+export const buildCreateDatabaseSql = (props: PostgresDatabaseProps, template?: string): string =>
+  `CREATE DATABASE ${quoteIdent(props.name)} WITH ${withOptions(props, template)}`;
 
 /** `42P04` (`duplicate_database`) is a race: something else created the name between our read
  * and our create. Measured at `internal/sqlError.ts@effect/sql-pg 4.0.0-rc.115`: every SQLSTATE
@@ -102,6 +114,22 @@ 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';
+
+/**
+ * Does one database of the cluster exist? `Postgres.Schema` runs this over the FAMILY
+ * connection (no `withPg` database override) before `read` and `delete`, so a declared
+ * database that does not exist yet answers "schema absent" instead of the transports' untyped
+ * connect failures (`ConnectionError` over psql, `UnknownError` 3D000 over the socket). The
+ * probe targets the maintenance database the family connection already points at, which a
+ * cold plan can always reach.
+ */
+export const databaseExists = (pg: PgExecutor, name: string): Effect.Effect<boolean, SqlError> =>
+  Effect.map(
+    pg.unsafe<{ readonly present: number }>(DATABASE_EXISTS_SQL, [name]),
+    (rows) => rows.length > 0,
+  );
+
 /** `datlocprovider` is Postgres's internal 1-byte `"char"` type, which this client decodes as
  * raw bytes rather than text (measured 2026-09-23 against the live socket — `docs/postgres.md`);
  * the `CASE` maps it to the same three words `pg_collation.h@REL_18_6#collprovider_name` returns

package/src/postgres/database.ts

@@ -80,6 +80,7 @@ const liveDrift = (props: PostgresDatabaseProps, live: PostgresDatabaseAttribute
 export const reconcileWithClient = (
   pg: PgExecutor,
   props: PostgresDatabaseProps,
+  template?: string,
 ): Effect.Effect<
   PostgresDatabaseAttributes,
   PostgresDatabaseOwnerMissing | PostgresDatabaseDrift | PostgresDatabaseCreateVanished | SqlError
@@ -93,7 +94,7 @@ export const reconcileWithClient = (
           new PostgresDatabaseOwnerMissing({ database: props.name, owner: props.owner }),
         );
       }
-      yield* pg.unsafe(buildCreateDatabaseSql(props)).pipe(
+      yield* pg.unsafe(buildCreateDatabaseSql(props, template)).pipe(
         Effect.asVoid,
         Effect.catchTag('SqlError', (error) =>
           isDuplicateDatabaseRace(error) ? Effect.succeed(undefined) : Effect.fail(error),
@@ -183,7 +184,7 @@ export const postgresDatabaseHandlers = PostgresDatabase.Provider.of({
           new PostgresDatabaseNameRefused({ name: news.name, ...nameRefusal }),
         );
       }
-      return yield* withPg((pg) => reconcileWithClient(pg, news));
+      return yield* withPg((pg, ctx) => reconcileWithClient(pg, news, ctx.template));
     }),
 
   delete: ({ olds }) => Effect.fail(new PostgresDatabaseDropRefused({ database: olds.name })),

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

@@ -0,0 +1,189 @@
+/**
+ * The statement parser half of the `Postgres.Grants` test fake: it understands EXACTLY the
+ * ten statement shapes `grants-sql.ts` generates — `quoteIdent`'s quoting, one clause
+ * order — and nothing else, so a quoting or clause-order bug in a builder trips the parser
+ * instead of hiding behind lenient matching. The server-model half (entries, grant/revoke
+ * semantics, the aclexplode-shaped reads) lives in `fake-grants-sql.ts`.
+ *
+ * ⛔ IT PARSES ITS OWN OUTPUT, NOT SQL IN GENERAL (`fake-sql.ts`'s own rule): every value
+ *   the builders `quoteIdent` is read back through the same `"…""…"` unquoting, and every
+ *   statement ends in exactly one of the accepted shapes or the parse refuses.
+ * ⛔ A COLUMN GRANT CARRIES ONE COLUMN LIST PER WORD — `GRANT select ("id"), update ("id")`:
+ *   a single trailing list binds only to the privilege it follows (gram.y@REL_18_6), so
+ *   `GRANT select, update ("id")` is a table-level SELECT on a real server. The parser
+ *   refuses that shape instead of filing it as a column-only grant.
+ */
+export interface AclObject {
+  readonly schema: string;
+  readonly table?: string;
+  readonly column?: string;
+  readonly defaultFor?: string;
+}
+
+/** One parsed write statement, already reduced to what the model applies. */
+export interface ParsedWrite {
+  readonly kind: 'grant' | 'revoke';
+  /** `REVOKE ALL ON ALL TABLES IN SCHEMA … FROM PUBLIC` — applied per known relation. */
+  readonly allTables?: boolean;
+  readonly object: AclObject;
+  /** `'PUBLIC'` or a role name. */
+  readonly grantee: string;
+  /** Declared privilege words, lowercase, no `*` marks (the option clause carries the flag). */
+  readonly words: ReadonlyArray<string>;
+  readonly option: boolean;
+}
+
+const unquote = (raw: string): string => raw.replace(/""/g, '"');
+
+const IDENT = String.raw`"((?:[^"]|"")*)"`;
+const WORDS = String.raw`([a-z]+(?:, [a-z]+)*)`;
+/** One column-grant atom, `word ("col")` — the shape every builder column statement is made of. */
+const SYNOPSIS = String.raw`[a-z]+ \("(?:[^"]|"")*"\)`;
+const GRANTEE = String.raw`(?:"((?:[^"]|"")*)"|PUBLIC)`;
+const OPTION = String.raw`(?:( WITH GRANT OPTION))?`;
+
+interface Pattern {
+  readonly re: RegExp;
+  /** `undefined` when the regex matched but the shape is one no builder emits — the loop
+   * falls through and the parse refuses (a builder regression, not a tolerated statement). */
+  readonly parse: (m: RegExpExecArray) => Omit<ParsedWrite, 'kind'> | undefined;
+}
+
+const role = (raw: string | undefined): string => (raw === undefined ? 'PUBLIC' : unquote(raw));
+
+/** Ordered: a column grant/revoke must be tried before the table form its text starts like,
+ * and the two default-privileges forms before the plain ones they begin as. */
+const PATTERNS: ReadonlyArray<Pattern & { readonly kind: 'grant' | 'revoke' }> = [
+  {
+    kind: 'grant',
+    re: new RegExp(
+      `^ALTER DEFAULT PRIVILEGES FOR ROLE ${IDENT} IN SCHEMA ${IDENT} GRANT ${WORDS} ON TABLES TO ${GRANTEE}${OPTION}$`,
+    ),
+    parse: (m) => ({
+      object: { schema: unquote(m[2] as string), defaultFor: unquote(m[1] as string) },
+      grantee: role(m[4] as string | undefined),
+      words: (m[3] as string).split(', '),
+      option: m[5] !== undefined,
+    }),
+  },
+  {
+    kind: 'revoke',
+    re: new RegExp(
+      `^ALTER DEFAULT PRIVILEGES FOR ROLE ${IDENT} IN SCHEMA ${IDENT} REVOKE ALL ON TABLES FROM ${GRANTEE}$`,
+    ),
+    parse: (m) => ({
+      object: { schema: unquote(m[2] as string), defaultFor: unquote(m[1] as string) },
+      grantee: role(m[3] as string | undefined),
+      words: [],
+      option: false,
+    }),
+  },
+  {
+    kind: 'grant',
+    // ⛔ Every word carries its OWN column list — `GRANT select ("id"), update ("id") …`.
+    // A single trailing list binds only to the privilege it follows (gram.y@REL_18_6), so
+    // `GRANT select, update ("id")` is a table-level SELECT on a real server; the parser
+    // refuses that shape instead of filing it as a column-only grant (a builder that
+    // emits it would over-grant at the table level while the suite stays green).
+    re: new RegExp(
+      `^GRANT (${SYNOPSIS}(?:, ${SYNOPSIS})*) ON ${IDENT}\\.${IDENT} TO ${GRANTEE}${OPTION}$`,
+    ),
+    parse: (m) => {
+      const pairs = [...(m[1] as string).matchAll(/([a-z]+) \("((?:[^"]|"")*)"\)/g)];
+      const first = pairs[0];
+      if (first === undefined) return undefined;
+      const column = unquote(first[2] as string);
+      // One statement grants ONE column: every synopsis pair must name the same one (the
+      // builders emit one column per statement) — mixed columns are a foreign shape.
+      if (pairs.some(([, , raw]) => unquote(raw as string) !== column)) return undefined;
+      return {
+        object: {
+          schema: unquote(m[2] as string),
+          table: unquote(m[3] as string),
+          column,
+        },
+        grantee: role(m[4] as string | undefined),
+        words: pairs.map(([, word]) => word as string),
+        option: m[5] !== undefined,
+      };
+    },
+  },
+  {
+    kind: 'revoke',
+    re: new RegExp(`^REVOKE ALL \\(${IDENT}\\) ON ${IDENT}\\.${IDENT} FROM ${GRANTEE}$`),
+    parse: (m) => ({
+      object: {
+        schema: unquote(m[2] as string),
+        table: unquote(m[3] as string),
+        column: unquote(m[1] as string),
+      },
+      grantee: role(m[4] as string | undefined),
+      words: [],
+      option: false,
+    }),
+  },
+  {
+    kind: 'grant',
+    re: new RegExp(`^GRANT ${WORDS} ON SCHEMA ${IDENT} TO ${GRANTEE}${OPTION}$`),
+    parse: (m) => ({
+      object: { schema: unquote(m[2] as string) },
+      grantee: role(m[3] as string | undefined),
+      words: (m[1] as string).split(', '),
+      option: m[4] !== undefined,
+    }),
+  },
+  {
+    kind: 'grant',
+    re: new RegExp(`^GRANT ${WORDS} ON ${IDENT}\\.${IDENT} TO ${GRANTEE}${OPTION}$`),
+    parse: (m) => ({
+      object: { schema: unquote(m[2] as string), table: unquote(m[3] as string) },
+      grantee: role(m[4] as string | undefined),
+      words: (m[1] as string).split(', '),
+      option: m[5] !== undefined,
+    }),
+  },
+  {
+    kind: 'revoke',
+    re: new RegExp(`^REVOKE ALL ON ${IDENT}\\.${IDENT} FROM ${GRANTEE}$`),
+    parse: (m) => ({
+      object: { schema: unquote(m[1] as string), table: unquote(m[2] as string) },
+      grantee: role(m[3] as string | undefined),
+      words: [],
+      option: false,
+    }),
+  },
+  {
+    kind: 'revoke',
+    re: new RegExp(`^REVOKE ALL ON SCHEMA ${IDENT} FROM ${GRANTEE}$`),
+    parse: (m) => ({
+      object: { schema: unquote(m[1] as string) },
+      grantee: role(m[2] as string | undefined),
+      words: [],
+      option: false,
+    }),
+  },
+  {
+    kind: 'revoke',
+    re: new RegExp(`^REVOKE ALL ON ALL TABLES IN SCHEMA ${IDENT} FROM ${GRANTEE}$`),
+    parse: (m) => ({
+      allTables: true,
+      object: { schema: unquote(m[1] as string) },
+      grantee: role(m[2] as string | undefined),
+      words: [],
+      option: false,
+    }),
+  },
+];
+
+/** `undefined` when the text is no statement this family generates — the model refuses it
+ * rather than guessing (a parse miss on a GRANT-shaped text means a builder regressed). */
+export const parseGrantStatement = (text: string): ParsedWrite | undefined => {
+  for (const pattern of PATTERNS) {
+    const m = pattern.re.exec(text);
+    if (m === null) continue;
+    const parsed = pattern.parse(m);
+    if (parsed === undefined) continue;
+    return { kind: pattern.kind, ...parsed };
+  }
+  return undefined;
+};