@homeflare/alchemy 0.23.0 → 0.25.0

package/src/postgres/database-sql.ts

@@ -0,0 +1,174 @@
+/**
+ * The four statements `Postgres.Database` ever issues, and the quoting each one needs.
+ *
+ * ⛔ `CREATE DATABASE` TAKES NO BIND PARAMETERS FOR ANY OF ITS VALUES, INCLUDING `OWNER`.
+ *   Measured at `gram.y@REL_18_6`: `CreatedbStmt: CREATE DATABASE name opt_with
+ *   createdb_opt_list`, and every `createdb_opt_item` value is `NumericOnly`,
+ *   `opt_boolean_or_string` or the bare keyword `DEFAULT` — none of those productions reaches
+ *   `PARAM` (`$n`). `sql\`…\`` cannot help here; every free-form value in this statement is
+ *   escaped by hand, once, in this file, and the assembled text runs through `.unsafe()`.
+ * ⚠️ THE DATABASE NAME AND EFFECT'S OWN `sql(value)` IDENTIFIER HELPER DO NOT MIX. `name` is a
+ *   `ColId` (`gram.y@REL_18_6` line 17327), a single token — but `Statement.defaultEscape('"')`
+ *   (what `sql(value)` compiles to) also rewrites every `.` in the value to `"."`, because it is
+ *   built for a *qualified* name like `schema.table`. A database named `"my.app"` would come out
+ *   as `"my"."app"` — two tokens where `CreatedbStmt` parses exactly one — a syntax error the
+ *   engine would blame on this provider. `quoteIdent` below is the single-token form: it quotes
+ *   and doubles embedded `"`, and nothing else.
+ * ★ EVERY OTHER `WITH` VALUE (`OWNER`, `TABLESPACE`, `ENCODING`, `LOCALE_PROVIDER`,
+ *   `LC_COLLATE`, `LC_CTYPE`) IS A STRING LITERAL, NOT AN IDENTIFIER. Measured at the same tag:
+ *   `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.
+ */
+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)`. */
+export interface PgExecutor {
+  readonly unsafe: <A extends object>(
+    sql: string,
+    params?: ReadonlyArray<unknown>,
+  ) => Effect.Effect<ReadonlyArray<A>, SqlError>;
+}
+
+/** Single-token identifier quoting: wrap in `"`, double any embedded `"`. No dot-splitting —
+ * see the file header. Used for the database name and, since a role or tablespace name is a
+ * `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, "''")}'`;
+
+const withOptions = (props: PostgresDatabaseProps): string => {
+  const parts: string[] = [`OWNER ${quoteIdent(props.owner)}`];
+  if (props.encoding !== undefined) parts.push(`ENCODING ${quoteStringLiteral(props.encoding)}`);
+  if (props.localeProvider !== undefined) {
+    parts.push(`LOCALE_PROVIDER ${quoteStringLiteral(props.localeProvider)}`);
+  }
+  if (props.lcCollate !== undefined)
+    parts.push(`LC_COLLATE ${quoteStringLiteral(props.lcCollate)}`);
+  if (props.lcCtype !== undefined) parts.push(`LC_CTYPE ${quoteStringLiteral(props.lcCtype)}`);
+  if (props.tablespace !== undefined) parts.push(`TABLESPACE ${quoteIdent(props.tablespace)}`);
+  if (props.allowConnections !== undefined) {
+    parts.push(`ALLOW_CONNECTIONS ${props.allowConnections ? 'true' : 'false'}`);
+  }
+  if (props.connectionLimit !== undefined) {
+    parts.push(`CONNECTION LIMIT ${String(Math.trunc(props.connectionLimit))}`);
+  }
+  if (props.isTemplate !== undefined)
+    parts.push(`IS_TEMPLATE ${props.isTemplate ? 'true' : 'false'}`);
+  return parts.join(' ');
+};
+
+/**
+ * Build the exact `CREATE DATABASE` text — a pure function, unit-tested on its own with no
+ * client at all. `CONNECTION LIMIT` and the two booleans are never string-escaped: an integer is
+ * `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)}`;
+
+/** `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
+ * starting `42` — this one included — classifies as `SqlSyntaxError`, the same tag a genuine
+ * syntax error would raise; there is no more specific tag to `catchTag` on. So this reads the
+ * raw code PostgreSQL sent, carried on `reason.cause.code` (`PgConnection.ts#errorFromFields`,
+ * `Object.assign(new Error(...), fields)`), rather than trusting the tag alone. */
+export const isDuplicateDatabaseRace = (error: SqlError): boolean => {
+  if (error.reason._tag !== 'SqlSyntaxError') return false;
+  const cause = error.reason.cause;
+  return (
+    typeof cause === 'object' && cause !== null && (cause as { code?: unknown }).code === '42P04'
+  );
+};
+
+const ROLE_EXISTS_SQL = 'SELECT 1 AS present FROM 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
+ * `ERROR: role "…" does not exist` surfacing as an unclassified statement failure. */
+export const roleExists = (pg: PgExecutor, role: string): Effect.Effect<boolean, SqlError> =>
+  Effect.map(
+    pg.unsafe<{ readonly present: number }>(ROLE_EXISTS_SQL, [role]),
+    (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
+ * for the same codes, so the row never crosses the wire as anything but ordinary `text`.
+ *
+ * ⛔ `oid` AND `datconnlimit` ARE READ AT THEIR NATIVE CATALOG WIDTH — NEVER CAST TO `::int8`.
+ *   `pg_database.h@REL_18_6` types them `Oid oid` (4 bytes, builtin OID 26) and
+ *   `int32 datconnlimit` (4 bytes, builtin OID 23); `@effect/sql-pg`'s codec table
+ *   (`PgTypes.ts@4.0.0-rc.115`) decodes both of those as a plain JS `number`
+ *   (`readUint32`/`readInt32`), matching `PostgresDatabaseAttributes`'s declared `number`
+ *   fields. Casting either to `::int8` changes the WIRE type the server sends, so the same
+ *   codec table decodes it as a JS `bigint` instead (`OID.int8`'s codec calls
+ *   `DataView.getBigInt64`) — and alchemy's `encodeState`
+ *   (`node_modules/alchemy/lib/State/StateEncoding.js`) has no `bigint` branch, so
+ *   `JSON.stringify`ing the persisted state throws `TypeError: Do not know how to serialize a
+ *   BigInt` on every successful reconcile, and a live `bigint` compared against a declared
+ *   `number` in `firstDrift` below is never `===`, so a matching `connectionLimit` reads as
+ *   permanent drift. Measured 2026-09-23; regression test:
+ *   `database-bigint-serialization.test.ts`. */
+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,
+    CASE d.datlocprovider
+      WHEN 'b' THEN 'builtin' WHEN 'i' THEN 'icu' WHEN 'c' THEN 'libc'
+      ELSE 'libc'
+    END AS "localeProvider",
+    d.datcollate AS collate,
+    d.datctype AS ctype,
+    d.datallowconn AS "allowConnections",
+    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
+  WHERE d.datname = $1`;
+
+/** The read: one bound `SELECT` on `pg_database`, joined to the two functions that turn its raw
+ * owner and encoding columns into names (`docs/postgres.md#mapping`). `undefined` when the row
+ * is absent — ownership branding happens one layer up, in `database.ts`, not here. */
+export const selectDatabase = (
+  pg: PgExecutor,
+  name: string,
+): Effect.Effect<PostgresDatabaseAttributes | undefined, SqlError> =>
+  Effect.map(pg.unsafe<PostgresDatabaseAttributes>(SELECT_DATABASE_SQL, [name]), (rows) => rows[0]);
+
+/** Compare every declared, asserted prop against the live row. Returns the name of the first
+ * prop that drifted, or `undefined` when every declared prop matches. `name` and `owner` are
+ * compared by their callers (identity and the create-time assertion), never here. */
+export const firstDrift = (
+  props: PostgresDatabaseProps,
+  live: PostgresDatabaseAttributes,
+): { readonly prop: string; readonly declared: unknown; readonly live: unknown } | undefined => {
+  const checks: ReadonlyArray<readonly [string, unknown, unknown]> = [
+    ['encoding', props.encoding, live.encoding],
+    ['localeProvider', props.localeProvider, live.localeProvider],
+    ['lcCollate', props.lcCollate, live.collate],
+    ['lcCtype', props.lcCtype, live.ctype],
+    ['allowConnections', props.allowConnections, live.allowConnections],
+    ['connectionLimit', props.connectionLimit, live.connectionLimit],
+    ['isTemplate', props.isTemplate, live.isTemplate],
+    ['tablespace', props.tablespace, live.tablespace],
+  ];
+  for (const [prop, declared, liveValue] of checks) {
+    if (declared !== undefined && declared !== liveValue)
+      return { prop, declared, live: liveValue };
+  }
+  return undefined;
+};

package/src/postgres/database.ts

@@ -0,0 +1,193 @@
+/**
+ * `Postgres.Database` — create-and-assert over a self-hosted PostgreSQL 18 cluster.
+ *
+ * ⛔ THIS IS NOT AN ALTER-CAPABLE RESOURCE. Every optional prop is asserted ONCE, at create, and
+ *   compared against the live row on every later plan; a mismatch is a typed
+ *   `PostgresDatabaseDrift` refusal, never an `ALTER DATABASE`. `docs/postgres.md` says why:
+ *   several of these props (`LC_COLLATE`, `LC_CTYPE`, `LOCALE_PROVIDER`) cannot be altered on a
+ *   live database at all without `ALTER … REFRESH COLLATION VERSION` semantics this family does
+ *   not implement, and the rest are left alone on principle rather than by accident.
+ * ⛔ `delete` NEVER DROPS. See `errors.ts#PostgresDatabaseDropRefused` and
+ *   `defaultRemovalPolicy: 'retain'` below — two independent reasons the engine never issues
+ *   `DROP DATABASE` through this provider.
+ * ★ A DATABASE CARRIES NO OWNERSHIP MARK (H1). `read` always answers `Unowned` for a match, the
+ *   same rule `Cloudflare.Snippets.Snippet` uses for a marker-less API — so every one of the
+ *   mini's 19 already-live databases needs `adopt(true)` in the stack that declares it.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+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 { PostgresDatabaseAttributes, PostgresDatabaseProps } from './database-attrs.ts';
+import { nameByteRefusal } from './database-attrs.ts';
+import {
+  buildCreateDatabaseSql,
+  firstDrift,
+  isDuplicateDatabaseRace,
+  roleExists,
+  selectDatabase,
+} from './database-sql.ts';
+import { type PostgresConnection, withPg } from './connection.ts';
+import type { PgExecutor } from './database-sql.ts';
+import {
+  PostgresDatabaseCreateVanished,
+  PostgresDatabaseDrift,
+  PostgresDatabaseDropRefused,
+  PostgresDatabaseNameRefused,
+  PostgresDatabaseOwnerMissing,
+  PostgresDatabaseRenameRefused,
+} from './errors.ts';
+
+export interface PostgresDatabase extends Resource<
+  'Postgres.Database',
+  PostgresDatabaseProps,
+  PostgresDatabaseAttributes,
+  never,
+  PostgresConnection
+> {}
+
+export const PostgresDatabase = Resource<PostgresDatabase>('Postgres.Database', {
+  defaultRemovalPolicy: 'retain',
+});
+
+/** Mirrors `alchemy/Resource`'s own `isResourceOfType`: a resource constructor is a callable
+ * `Object.assign`ed function, not a plain object, so `typeof` must accept both — a bare
+ * `'object'` check (measured live in `scripts/smoke.ts`: it rejects `PostgresDatabase` itself,
+ * matching only an instance) is the regression this comment exists to prevent. */
+export const isPostgresDatabase = (value: unknown): value is PostgresDatabase =>
+  (typeof value === 'object' || typeof value === 'function') &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === 'Postgres.Database';
+
+/** Every asserted-prop mismatch against the LIVE row, owner included — reconcile's own
+ * authoritative check, independent of what `diff` compared at plan time (S10: cloud state is
+ * authoritative). */
+const liveDrift = (props: PostgresDatabaseProps, live: PostgresDatabaseAttributes) => {
+  if (props.owner !== live.owner) {
+    return { prop: 'owner', declared: props.owner, live: live.owner };
+  }
+  return firstDrift(props, live);
+};
+
+/**
+ * The core of `reconcile`, against any {@link PgExecutor} — the real pooled client through
+ * `withPg`, or `fake-sql.ts`'s recording fake in tests. Kept apart from the provider wiring
+ * below so a lifecycle test drives this exact function, not a re-implementation of it.
+ */
+export const reconcileWithClient = (
+  pg: PgExecutor,
+  props: PostgresDatabaseProps,
+): Effect.Effect<
+  PostgresDatabaseAttributes,
+  PostgresDatabaseOwnerMissing | PostgresDatabaseDrift | PostgresDatabaseCreateVanished | SqlError
+> =>
+  Effect.gen(function* () {
+    const observed = yield* selectDatabase(pg, props.name);
+    if (observed === undefined) {
+      const ownerPresent = yield* roleExists(pg, props.owner);
+      if (!ownerPresent) {
+        return yield* Effect.fail(
+          new PostgresDatabaseOwnerMissing({ database: props.name, owner: props.owner }),
+        );
+      }
+      yield* pg.unsafe(buildCreateDatabaseSql(props)).pipe(
+        Effect.asVoid,
+        Effect.catchTag('SqlError', (error) =>
+          isDuplicateDatabaseRace(error) ? Effect.succeed(undefined) : Effect.fail(error),
+        ),
+      );
+      // Never trust the write's own report (S10): re-read what the server actually stored.
+      const created = yield* selectDatabase(pg, props.name);
+      if (created === undefined) {
+        return yield* Effect.fail(new PostgresDatabaseCreateVanished({ database: props.name }));
+      }
+      return created;
+    }
+    const drift = liveDrift(props, observed);
+    if (drift !== undefined) {
+      return yield* Effect.fail(
+        new PostgresDatabaseDrift({
+          database: props.name,
+          prop: drift.prop,
+          declared: drift.declared,
+          live: drift.live,
+        }),
+      );
+    }
+    // Unchanged: the row already read is the authoritative answer. No write, no second round trip.
+    return observed;
+  });
+
+/** The core of `read`: one bound `SELECT`, no ownership branding — the caller (the provider's
+ * `read` below, or a test) decides whether to wrap a match in `Unowned`. */
+export const readWithClient = (pg: PgExecutor, name: string) => selectDatabase(pg, name);
+
+/**
+ * The core of `diff`, entirely offline: `news` (declared) against `output` (last-applied
+ * attributes) — never a live query (that authoritative check is `reconcileWithClient`'s job, per
+ * S10). A rename is a plan-time refusal; over-long names are too, so a bad name never even reaches
+ * `reconcile`; every other change answers `update`, which `reconcileWithClient` then either
+ * applies (create) or refuses (drift on an already-live database).
+ */
+export const diffPostgresDatabase = (
+  news: Input<PostgresDatabaseProps>,
+  output: PostgresDatabaseAttributes | undefined,
+) =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    if (news.name !== output.name) {
+      return yield* Effect.fail(
+        new PostgresDatabaseRenameRefused({ from: output.name, to: news.name }),
+      );
+    }
+    const nameRefusal = nameByteRefusal(news.name);
+    if (nameRefusal !== undefined) {
+      return yield* Effect.fail(
+        new PostgresDatabaseNameRefused({ name: news.name, ...nameRefusal }),
+      );
+    }
+    const changed = news.owner !== output.owner || firstDrift(news, output) !== undefined;
+    return changed ? ({ action: 'update' } as const) : ({ action: 'noop' } as const);
+  });
+
+/**
+ * The five lifecycle handlers, wired to `withPg` for anything that touches a client. Exported
+ * on its own — not only through {@link PostgresDatabaseProvider}'s `Layer` — so a test can call
+ * `postgresDatabaseHandlers.delete(...)` directly, against the real implementation, without
+ * standing up the engine's provider machinery.
+ */
+export const postgresDatabaseHandlers = PostgresDatabase.Provider.of({
+  // ⚠️ EMPTY, NOT A LIVE SWEEP. Enumerating `pg_database` would list every database on the
+  //   cluster, most of which nothing declared — the same reasoning `NetboxPrefix` documents
+  //   for its own marker-less `list`. Adoption for this family is one declaration at a time.
+  list: () => Effect.succeed([]),
+  nuke: { skip: true },
+
+  read: ({ olds, output }) =>
+    Effect.gen(function* () {
+      const name = output?.name ?? olds.name;
+      const live = yield* withPg((pg) => readWithClient(pg, name));
+      return live === undefined ? undefined : Unowned(live);
+    }),
+
+  diff: ({ news, output }) => diffPostgresDatabase(news, output),
+
+  reconcile: ({ news }) =>
+    Effect.gen(function* () {
+      const nameRefusal = nameByteRefusal(news.name);
+      if (nameRefusal !== undefined) {
+        return yield* Effect.fail(
+          new PostgresDatabaseNameRefused({ name: news.name, ...nameRefusal }),
+        );
+      }
+      return yield* withPg((pg) => reconcileWithClient(pg, news));
+    }),
+
+  delete: ({ olds }) => Effect.fail(new PostgresDatabaseDropRefused({ database: olds.name })),
+});
+
+export const PostgresDatabaseProvider = () =>
+  Provider.succeed(PostgresDatabase, postgresDatabaseHandlers);

package/src/postgres/errors.ts

@@ -0,0 +1,131 @@
+/**
+ * `Postgres.Database`'s failures as typed tags (S21).
+ *
+ * ⛔ NONE OF THESE IS A STATUS-CODE OR MESSAGE MATCH. Every one is raised by this family's own
+ *   code from a fact it already checked (a byte count, a live catalog row, a role lookup) — never
+ *   from sniffing a driver error's text. The one live-SQLSTATE check this family makes —
+ *   `isDuplicateDatabaseRace` in `database-sql.ts`, for the `42P04` create race — reads the raw
+ *   code `@effect/sql-pg` classified onto `SqlSyntaxError.cause.code` (measured in
+ *   `node_modules/@effect/sql-pg/src/internal/sqlError.ts#classifySqlState`: every `42xxx` code,
+ *   `42P04` included, becomes `SqlSyntaxError` — there is no more specific tag for it), and it
+ *   never produces one of these tags: a race converges instead of failing.
+ */
+import * as Data from 'effect/Data';
+
+/**
+ * A declared name would be silently truncated by the server (`NAMEDATALEN` 64, so 63 UTF-8
+ * bytes is the last one that survives whole) — refused at plan, before any statement runs.
+ *
+ * ⛔ WHY THIS IS A PLAN-TIME REFUSAL AND NOT A SERVER ERROR. `truncate_identifier`
+ *   (`scansup.c@REL_18_6` line 93) clips a long name to 63 bytes and raises only a `NOTICE`
+ *   (`errcode(ERRCODE_NAME_TOO_LONG)`), never an error. A create would succeed against the
+ *   TRUNCATED name, so the next plan's read (`WHERE datname = $1`, the name exactly as
+ *   declared) would find nothing and try to create it again — forever. See
+ *   `doc/postgres.md#name`.
+ */
+export class PostgresDatabaseNameRefused extends Data.TaggedError('PostgresDatabaseNameRefused')<{
+  readonly name: string;
+  readonly byteLength: number;
+  readonly limit: number;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Database "${this.name}": ${String(this.byteLength)} UTF-8 bytes, over the ` +
+      `${String(this.limit)}-byte limit (NAMEDATALEN 64, minus the terminator). PostgreSQL would ` +
+      'accept the CREATE and silently truncate the name with only a NOTICE, so this plan refuses ' +
+      'it instead of creating a database no later read will ever find again.'
+    );
+  }
+}
+
+/** A logical id's `name` changed. A database's name is its identity; there is no `ALTER … RENAME`
+ * in this family's vocabulary (see `docs/postgres.md`), and `diff` never turns this into a
+ * `replace` — a replace here is `DROP DATABASE` before `CREATE DATABASE`, on data. */
+export class PostgresDatabaseRenameRefused extends Data.TaggedError(
+  'PostgresDatabaseRenameRefused',
+)<{
+  readonly from: string;
+  readonly to: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Database: the declared name changed from "${this.from}" to "${this.to}". A ` +
+      'rename is refused at plan — this provider never replaces a database (that is DROP then ' +
+      'CREATE) and never runs ALTER … RENAME. Declare a new logical id for the new name, and ' +
+      'remove the old one once its data has moved.'
+    );
+  }
+}
+
+/** `OWNER` names a role `pg_roles` does not have, checked before the `CREATE DATABASE` that
+ * would otherwise fail on it. Postgres itself refuses the same case with `ERROR:  role "…" does
+ * not exist` (`createdb()`, `dbcommands.c`) — this tag exists so the refusal is typed and the
+ * check runs before any statement, not caught from the driver's text. */
+export class PostgresDatabaseOwnerMissing extends Data.TaggedError('PostgresDatabaseOwnerMissing')<{
+  readonly database: string;
+  readonly owner: string;
+}> {
+  override get message(): string {
+    return `Postgres.Database "${this.database}": OWNER "${this.owner}" is not a role in pg_roles.`;
+  }
+}
+
+/** A live, asserted property no longer matches the declaration. `reconcile` never issues an
+ * `ALTER DATABASE` to fix this — see `docs/postgres.md` for why each asserted prop stops at
+ * create. */
+export class PostgresDatabaseDrift extends Data.TaggedError('PostgresDatabaseDrift')<{
+  readonly database: string;
+  readonly prop: string;
+  readonly declared: unknown;
+  readonly live: unknown;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Database "${this.database}": ${this.prop} is declared as ` +
+      `${JSON.stringify(this.declared)} but the live database has ${JSON.stringify(this.live)}. ` +
+      'This provider never issues ALTER DATABASE — update the declaration to match the live ' +
+      'value, or change it by hand and re-plan.'
+    );
+  }
+}
+
+/** `delete` never drops a database. `DROP DATABASE` is destructive and irreversible on data
+ * this family did not create from nothing (most declared databases here are adopted, not
+ * created); the decision to remove one stays a human act on the host. */
+export class PostgresDatabaseDropRefused extends Data.TaggedError('PostgresDatabaseDropRefused')<{
+  readonly database: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Database "${this.database}": delete is refused. This provider never issues DROP ` +
+      'DATABASE. Drop it by hand over the trust socket if you mean to remove it, then remove the ' +
+      'declaration.'
+    );
+  }
+}
+
+/** `CREATE DATABASE` raised no error, but the immediate re-read (S10: never trust the write's
+ * own report) still finds nothing. Measured to have no real trigger in a correctly speaking
+ * client, but S20 forbids `Effect.die` here regardless — an invariant violation is a typed
+ * failure the caller can see and retry, never a defect that crashes the whole engine. */
+export class PostgresDatabaseCreateVanished extends Data.TaggedError(
+  'PostgresDatabaseCreateVanished',
+)<{
+  readonly database: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Database "${this.database}": CREATE DATABASE raised no error, but the database ` +
+      'is still absent on the immediate re-read. Re-plan — this is not a state this provider ' +
+      'expects to reach.'
+    );
+  }
+}
+
+export type PostgresDatabaseError =
+  | PostgresDatabaseNameRefused
+  | PostgresDatabaseRenameRefused
+  | PostgresDatabaseOwnerMissing
+  | PostgresDatabaseDrift
+  | PostgresDatabaseDropRefused
+  | PostgresDatabaseCreateVanished;

package/src/postgres/fake-sql.ts

@@ -0,0 +1,123 @@
+/**
+ * A recording fake `PgExecutor` (S28: "Tests use `bun:test`… a test never trusts the deploy's
+ * own report" — here read back from the fake's own catalog, not from the statement list) for
+ * every lifecycle test in this family. No socket, no `@effect/sql-pg` client — it is small
+ * enough to re-derive the one thing this provider ever asks of a real one: three statement
+ * shapes, matched by text, against an in-memory `pg_roles` set and `pg_database` map.
+ *
+ * ⛔ IT PARSES ITS OWN OUTPUT, NOT SQL IN GENERAL. `parseCreate` below understands exactly the
+ *   text `buildCreateDatabaseSql` (`database-sql.ts`) produces — quoted with `quoteIdent` /
+ *   `quoteStringLiteral` — because that is the only `CREATE DATABASE` this family ever issues. A
+ *   general SQL parser would hide a quoting bug instead of tripping over it.
+ */
+import * as Effect from 'effect/Effect';
+import { SqlError, SqlSyntaxError } from 'effect/unstable/sql/SqlError';
+import type { PostgresDatabaseAttributes } from './database-attrs.ts';
+import type { PgExecutor } from './database-sql.ts';
+
+export interface RecordedStatement {
+  readonly text: string;
+  readonly params: ReadonlyArray<unknown>;
+}
+
+export interface FakeSql extends PgExecutor {
+  readonly statements: ReadonlyArray<RecordedStatement>;
+  /** Mutable on purpose: a test seeds a row a "competing" statement would have produced (the
+   * `42P04` race case) before the fake ever sees it. */
+  readonly databases: Map<string, PostgresDatabaseAttributes>;
+}
+
+export interface FakeSqlOptions {
+  readonly roles?: ReadonlyArray<string>;
+  readonly databases?: ReadonlyArray<PostgresDatabaseAttributes>;
+  /** Fail the NEXT `CREATE DATABASE` with SQLSTATE `42P04` (duplicate_database), once, the way a
+   * concurrent creator racing this reconcile would — classified exactly as
+   * `@effect/sql-pg`'s own driver classifies it (`database-sql.ts`'s header). */
+  readonly raceNextCreate?: boolean;
+}
+
+const unquoteIdent = (raw: string): string => raw.replace(/""/g, '"');
+const unquoteLiteral = (raw: string): string => raw.replace(/''/g, "'");
+
+/** Pull every field back out of exactly the text `buildCreateDatabaseSql` writes. */
+const parseCreate = (text: string): PostgresDatabaseAttributes => {
+  const name = /^CREATE DATABASE "((?:[^"]|"")*)" WITH /.exec(text);
+  const owner = /OWNER "((?:[^"]|"")*)"/.exec(text);
+  const encoding = /ENCODING '((?:[^']|'')*)'/.exec(text);
+  const localeProvider = /LOCALE_PROVIDER '((?:[^']|'')*)'/.exec(text);
+  const lcCollate = /LC_COLLATE '((?:[^']|'')*)'/.exec(text);
+  const lcCtype = /LC_CTYPE '((?:[^']|'')*)'/.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',
+  };
+};
+
+export const makeFakeSql = (options: FakeSqlOptions = {}): FakeSql => {
+  const statements: RecordedStatement[] = [];
+  const roles = new Set(options.roles ?? []);
+  const databases = new Map(options.databases?.map((d) => [d.name, d] as const) ?? []);
+  let raceRemaining = options.raceNextCreate === true ? 1 : 0;
+  let oidCounter = 20000;
+
+  const unsafe = <A extends object>(
+    text: string,
+    params: ReadonlyArray<unknown> = [],
+  ): Effect.Effect<ReadonlyArray<A>, SqlError> =>
+    Effect.suspend(() => {
+      statements.push({ text, params });
+
+      if (text.startsWith('SELECT 1 AS present FROM pg_roles')) {
+        const role = params[0] as string;
+        return Effect.succeed(
+          (roles.has(role) ? [{ present: 1 }] : []) as unknown as ReadonlyArray<A>,
+        );
+      }
+
+      if (text.includes('FROM pg_database')) {
+        const name = params[0] as string;
+        const row = databases.get(name);
+        return Effect.succeed((row === undefined ? [] : [row]) as unknown as ReadonlyArray<A>);
+      }
+
+      if (text.startsWith('CREATE DATABASE')) {
+        if (raceRemaining > 0) {
+          raceRemaining -= 1;
+          return Effect.fail(
+            new SqlError({
+              reason: new SqlSyntaxError({
+                cause: Object.assign(new Error('database "x" already exists'), { code: '42P04' }),
+                message: 'duplicate_database (fake race)',
+                operation: 'CREATE DATABASE',
+              }),
+            }),
+          );
+        }
+        const row = { ...parseCreate(text), oid: oidCounter };
+        oidCounter += 1;
+        databases.set(row.name, row);
+        return Effect.succeed([] as unknown as ReadonlyArray<A>);
+      }
+
+      throw new Error(`fake-sql: unrecognised statement: ${text}`);
+    });
+
+  return { unsafe, statements, databases };
+};

package/src/postgres/fixtures/pg-REL_18_6-create-database-synopsis.txt

@@ -0,0 +1,26 @@
+# path: doc/src/sgml/ref/create_database.sgml
+# blob: 4da8aeebb50a29e89bd9f68a8deac4b1a3ec7b18
+# tag: REL_18_6 (commit 724edf9bde9d356724ad384a2e196edc3c9f80f7)
+# fetched: 2026-09-23 via gh api repos/postgres/postgres/contents/...?ref=724edf9bde9d356724ad384a2e196edc3c9f80f7
+# excerpt: the <synopsis> block only (lines 23-42 of the full file), cut per house doc-size convention
+#
+<synopsis>
+CREATE DATABASE <replaceable class="parameter">name</replaceable>
+    [ WITH ] [ OWNER [=] <replaceable class="parameter">user_name</replaceable> ]
+           [ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ]
+           [ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ]
+           [ STRATEGY [=] <replaceable class="parameter">strategy</replaceable> ]
+           [ LOCALE [=] <replaceable class="parameter">locale</replaceable> ]
+           [ LC_COLLATE [=] <replaceable class="parameter">lc_collate</replaceable> ]
+           [ LC_CTYPE [=] <replaceable class="parameter">lc_ctype</replaceable> ]
+           [ BUILTIN_LOCALE [=] <replaceable class="parameter">builtin_locale</replaceable> ]
+           [ ICU_LOCALE [=] <replaceable class="parameter">icu_locale</replaceable> ]
+           [ ICU_RULES [=] <replaceable class="parameter">icu_rules</replaceable> ]
+           [ LOCALE_PROVIDER [=] <replaceable class="parameter">locale_provider</replaceable> ]
+           [ COLLATION_VERSION = <replaceable>collation_version</replaceable> ]
+           [ TABLESPACE [=] <replaceable class="parameter">tablespace_name</replaceable> ]
+           [ ALLOW_CONNECTIONS [=] <replaceable class="parameter">allowconn</replaceable> ]
+           [ CONNECTION LIMIT [=] <replaceable class="parameter">connlimit</replaceable> ]
+           [ IS_TEMPLATE [=] <replaceable class="parameter">istemplate</replaceable> ]
+           [ OID [=] <replaceable class="parameter">oid</replaceable> ]
+</synopsis>