@homeflare/alchemy 0.23.0 → 0.24.0

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

@@ -0,0 +1,118 @@
+/**
+ * Provenance: every `PostgresDatabaseProps` field traces to a real `CREATE DATABASE` synopsis
+ * option AND a real `pg_database` column, and every synopsis option this family does NOT expose
+ * as a prop is named with a reason. Both fixtures are parsed, not eyeballed — deleting a fixture
+ * line, or adding a prop with no mapping, fails this file (S38, the house's provenance rule).
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const FIXTURES = join(import.meta.dir, 'fixtures');
+const synopsis = readFileSync(join(FIXTURES, 'pg-REL_18_6-create-database-synopsis.txt'), 'utf8');
+const struct = readFileSync(join(FIXTURES, 'pg-REL_18_6-pg_database.h.txt'), 'utf8');
+
+const SYNOPSIS_BLOB = '4da8aeebb50a29e89bd9f68a8deac4b1a3ec7b18';
+const STRUCT_BLOB = '54f0d38c9c9e1cd4d419b05b296b8f84875e9768';
+
+const synopsisOptions = (): readonly string[] => {
+  const re = /\[\s*([A-Z][A-Z_ ]*?)\s*(?:\[=\]|=)\s*<replaceable/g;
+  const found: string[] = [];
+  for (const m of synopsis.matchAll(re)) found.push(m[1] as string);
+  return found;
+};
+
+const structColumns = (): readonly string[] => {
+  const re = /^\t[A-Za-z_][A-Za-z0-9_]*\s+(\w+)(?:\[\d+\])?\b/;
+  const found: string[] = [];
+  for (const line of struct.split('\n')) {
+    const m = re.exec(line);
+    if (m !== null) found.push(m[1] as string);
+  }
+  return found;
+};
+
+/** Every asserted prop except `name`, which is the mandatory `CREATE DATABASE <name>` token, not
+ * a bracketed `WITH` option — checked separately below. */
+const PROP_MAPPING: Readonly<Record<string, { readonly option: string; readonly column: string }>> =
+  {
+    owner: { option: 'OWNER', column: 'datdba' },
+    encoding: { option: 'ENCODING', column: 'encoding' },
+    localeProvider: { option: 'LOCALE_PROVIDER', column: 'datlocprovider' },
+    lcCollate: { option: 'LC_COLLATE', column: 'datcollate' },
+    lcCtype: { option: 'LC_CTYPE', column: 'datctype' },
+    allowConnections: { option: 'ALLOW_CONNECTIONS', column: 'datallowconn' },
+    connectionLimit: { option: 'CONNECTION LIMIT', column: 'datconnlimit' },
+    isTemplate: { option: 'IS_TEMPLATE', column: 'datistemplate' },
+    tablespace: { option: 'TABLESPACE', column: 'dattablespace' },
+  };
+
+/** Every synopsis option this family does NOT declare as a prop, and why. */
+const EXCLUDED: Readonly<Record<string, string>> = {
+  TEMPLATE: 'consumed only at create time to copy from; pg_database has no column recording it',
+  STRATEGY: 'consumed only at create time (WAL_LOG vs FILE_COPY copy method); not stored',
+  LOCALE:
+    'a shorthand that sets LC_COLLATE/LC_CTYPE (or BUILTIN_LOCALE); this family declares lcCollate/lcCtype directly instead',
+  BUILTIN_LOCALE:
+    "only meaningful when localeProvider='builtin'; folds into datcollate/datctype like LOCALE, no column of its own",
+  ICU_LOCALE:
+    "only meaningful when localeProvider='icu' (datlocale column exists); deferred — measured 2026-09-23, all 24 live databases are locale provider 'c' (libc)",
+  ICU_RULES:
+    'stored in daticurules, but this family has no ICU-provider consumer yet (see ICU_LOCALE)',
+  COLLATION_VERSION:
+    'intended for pg_upgrade only; normally omitted so PostgreSQL computes it from the OS',
+  OID: 'primarily for pg_upgrade\'s internal use (docs: "only pg_upgrade can specify a value less than 16384"); not something a stack should assert',
+};
+
+describe('postgres provenance', () => {
+  test('fixture headers name the measured blob shas', () => {
+    expect(synopsis).toContain(SYNOPSIS_BLOB);
+    expect(synopsis).toContain('doc/src/sgml/ref/create_database.sgml');
+    expect(struct).toContain(STRUCT_BLOB);
+    expect(struct).toContain('src/include/catalog/pg_database.h');
+  });
+
+  test('the name token is documented and backed by datname', () => {
+    expect(synopsis).toContain('CREATE DATABASE <replaceable class="parameter">name</replaceable>');
+    expect(structColumns()).toContain('datname');
+  });
+
+  test('every declared prop maps to a real synopsis option', () => {
+    const options = synopsisOptions();
+    for (const [prop, { option }] of Object.entries(PROP_MAPPING)) {
+      expect(options, `prop "${prop}" claims synopsis option "${option}"`).toContain(option);
+    }
+  });
+
+  test('every declared prop maps to a real pg_database column', () => {
+    const columns = structColumns();
+    for (const [prop, { column }] of Object.entries(PROP_MAPPING)) {
+      expect(columns, `prop "${prop}" claims column "${column}"`).toContain(column);
+    }
+  });
+
+  test('every synopsis option is either a declared prop or a documented exclusion', () => {
+    const declaredOptions = new Set(Object.values(PROP_MAPPING).map((m) => m.option));
+    for (const option of synopsisOptions()) {
+      const accounted = declaredOptions.has(option) || option in EXCLUDED;
+      expect(accounted, `synopsis option "${option}" is neither a prop nor in EXCLUDED`).toBe(true);
+    }
+  });
+
+  test('no excluded option is silently also a declared prop', () => {
+    const declaredOptions = new Set(Object.values(PROP_MAPPING).map((m) => m.option));
+    for (const option of Object.keys(EXCLUDED)) {
+      expect(declaredOptions.has(option), `"${option}" is both excluded and declared`).toBe(false);
+    }
+  });
+
+  test('every excluded option actually exists in the synopsis (no stale entries)', () => {
+    const options = new Set(synopsisOptions());
+    for (const option of Object.keys(EXCLUDED)) {
+      expect(
+        options.has(option),
+        `EXCLUDED names "${option}", which the synopsis no longer has`,
+      ).toBe(true);
+    }
+  });
+});

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

@@ -0,0 +1,135 @@
+/**
+ * Every plan-time refusal, checked without a client: name-byte precision, identifier and string
+ * quoting, the rename refusal, a full sweep proving `diff` never answers `replace`, and `delete`.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import * as Effect from 'effect/Effect';
+import { POSTGRES_NAME_MAX_BYTES, nameByteRefusal, utf8ByteLength } from './database-attrs.ts';
+import { buildCreateDatabaseSql, quoteIdent, quoteStringLiteral } from './database-sql.ts';
+import { diffPostgresDatabase, postgresDatabaseHandlers } from './database.ts';
+import { PostgresDatabaseDropRefused, PostgresDatabaseRenameRefused } from './errors.ts';
+import type { PostgresDatabaseAttributes, PostgresDatabaseProps } from './database-attrs.ts';
+
+describe('name byte length', () => {
+  test('a 63-byte ASCII name is accepted', () => {
+    const name = 'a'.repeat(63);
+    expect(utf8ByteLength(name)).toBe(63);
+    expect(nameByteRefusal(name)).toBeUndefined();
+  });
+
+  test('a 64-byte ASCII name is refused', () => {
+    const name = 'a'.repeat(64);
+    const refusal = nameByteRefusal(name);
+    expect(refusal).toEqual({ byteLength: 64, limit: POSTGRES_NAME_MAX_BYTES });
+  });
+
+  test('a 63-byte multibyte name (21 three-byte characters) is accepted, though .length is 21', () => {
+    // U+4E2D ("中") is 3 UTF-8 bytes. 21 * 3 = 63 bytes exactly — the last size that survives.
+    const name = '中'.repeat(21);
+    expect(name.length).toBe(21);
+    expect(utf8ByteLength(name)).toBe(63);
+    expect(nameByteRefusal(name)).toBeUndefined();
+  });
+
+  test('one more multibyte character (64 bytes) is refused', () => {
+    const name = `${'中'.repeat(21)}a`;
+    expect(utf8ByteLength(name)).toBe(64);
+    expect(nameByteRefusal(name)).toEqual({ byteLength: 64, limit: POSTGRES_NAME_MAX_BYTES });
+  });
+});
+
+describe('quoting', () => {
+  test('quoteIdent doubles an embedded double quote and leaves a hyphen alone', () => {
+    expect(quoteIdent('a"b-c')).toBe('"a""b-c"');
+  });
+
+  test('quoteIdent does not split a dot the way a qualified-name escaper would', () => {
+    // The hazard this file exists to avoid — see database-sql.ts's header.
+    expect(quoteIdent('my.app')).toBe('"my.app"');
+  });
+
+  test('quoteStringLiteral doubles an embedded single quote', () => {
+    expect(quoteStringLiteral("en_US.UTF-8'; DROP")).toBe("'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\'');
+  });
+});
+
+const sampleOutput: PostgresDatabaseAttributes = {
+  name: 'widgets',
+  oid: 1,
+  owner: 'tim',
+  encoding: 'UTF8',
+  localeProvider: 'libc',
+  collate: 'C',
+  ctype: 'C',
+  allowConnections: true,
+  connectionLimit: -1,
+  isTemplate: false,
+  tablespace: 'pg_default',
+};
+const base: PostgresDatabaseProps = { name: 'widgets', owner: 'tim' };
+
+describe('diff', () => {
+  const output = sampleOutput;
+
+  test('a rename is refused at plan, before reconcile ever runs', async () => {
+    const error = await Effect.runPromise(
+      Effect.flip(diffPostgresDatabase({ ...base, name: 'gadgets' }, output)),
+    );
+    expect(error).toBeInstanceOf(PostgresDatabaseRenameRefused);
+  });
+
+  test('an unchanged declaration answers noop', async () => {
+    const result = await Effect.runPromise(diffPostgresDatabase(base, output));
+    expect(result).toEqual({ action: 'noop' });
+  });
+
+  test('a change in any single prop answers update, and NEVER replace — swept across every prop', async () => {
+    const variants: ReadonlyArray<Partial<PostgresDatabaseProps>> = [
+      { owner: 'someone-else' },
+      { encoding: 'LATIN1' },
+      { localeProvider: 'icu' },
+      { lcCollate: 'en_US.UTF-8' },
+      { lcCtype: 'en_US.UTF-8' },
+      { allowConnections: false },
+      { connectionLimit: 5 },
+      { isTemplate: true },
+      { tablespace: 'fast_ssd' },
+    ];
+    for (const variant of variants) {
+      const result = await Effect.runPromise(diffPostgresDatabase({ ...base, ...variant }, output));
+      expect(result?.action, `variant ${JSON.stringify(variant)}`).toBe('update');
+      expect(result).not.toEqual({ action: 'replace' });
+    }
+  });
+});
+
+describe('delete', () => {
+  test('the real handler refuses with PostgresDatabaseDropRefused naming the database', async () => {
+    const error = await Effect.runPromise(
+      Effect.flip(
+        postgresDatabaseHandlers.delete({
+          id: 'x',
+          fqn: 'x',
+          instanceId: 'x',
+          olds: base,
+          output: sampleOutput,
+          session: undefined as never,
+          bindings: [] as never,
+        }),
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresDatabaseDropRefused);
+    expect((error as PostgresDatabaseDropRefused).database).toBe('widgets');
+  });
+
+  test('defaultRemovalPolicy is retain (declared alongside PostgresDatabase, checked in source)', () => {
+    const source = readFileSync(new URL('./database.ts', import.meta.url), 'utf8');
+    expect(source).toContain("defaultRemovalPolicy: 'retain'");
+  });
+});

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);