@homeflare/alchemy 0.42.0 → 0.44.0

package/src/postgres/schema-delete.ts

@@ -0,0 +1,96 @@
+/**
+ * `Postgres.Schema`'s drop path: prove the connection, prove the schema is still ours, then
+ * the guarded `DROP SCHEMA`.
+ *
+ * ⛔ THE ENGINE DOES NOT RE-READ BEFORE A DELETE THAT HAS STATE (alchemy `Apply.ts`). When
+ *   persisted attributes exist, `delete` receives the LAST asserted `oid` + `owner` and no
+ *   fresh row — a schema dropped out of band and recreated under the same name by another role
+ *   would be dropped by name, `CASCADE` included, destroying their objects.
+ *   `deleteWithClient` re-reads `pg_namespace` first: absent is idempotent success, and a live
+ *   row that no longer matches the persisted proof fails with
+ *   `PostgresSchemaDeleteForeignRefused` (`schema-assert.ts#deleteForeignRefusal`) before any
+ *   `DROP` is issued.
+ */
+import * as Effect from 'effect/Effect';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+import { assertDatabase, deleteForeignRefusal } from './schema-assert.ts';
+import {
+  type PostgresSchemaDeleteForeignRefused,
+  PostgresSchemaDropNotEmptyError,
+  type PostgresSchemaWrongDatabase,
+} from './schema-errors.ts';
+import {
+  buildDropSchemaSql,
+  isDependentObjectsError,
+  schemaIsEmpty,
+  selectSchema,
+} from './schema-sql.ts';
+
+/**
+ * The guarded `DROP SCHEMA`, against any {@link PgExecutor}: refuses a non-empty schema
+ * without `cascade`, and classifies the server's own `2BP01` refusal as the same typed tag —
+ * for an object kind the emptiness check's four catalogs do not cover. Callers have already
+ * proven the connected database (`assertDatabase`) and, on the delete path, the schema's
+ * ownership.
+ */
+const dropGuarded = (
+  pg: PgExecutor,
+  props: PostgresSchemaProps,
+): Effect.Effect<void, PostgresSchemaDropNotEmptyError | SqlError> =>
+  Effect.gen(function* () {
+    if (props.cascade !== true) {
+      const empty = yield* schemaIsEmpty(pg, props.name);
+      if (!empty) {
+        return yield* Effect.fail(new PostgresSchemaDropNotEmptyError({ schema: props.name }));
+      }
+    }
+    // The server's own `2BP01` refusal (an object kind the four catalogs miss) is classified
+    // into the same typed tag the emptiness check raises — one fail branch, classified before
+    // the fail, exactly as `database-sql.ts` classifies the `42P04` race.
+    const dropRefusal = (error: SqlError): PostgresSchemaDropNotEmptyError | SqlError =>
+      props.cascade !== true && isDependentObjectsError(error)
+        ? new PostgresSchemaDropNotEmptyError({ schema: props.name })
+        : error;
+    yield* pg.unsafe(buildDropSchemaSql(props.name, props.cascade === true)).pipe(
+      Effect.asVoid,
+      Effect.catchTag('SqlError', (error) => Effect.fail(dropRefusal(error))),
+    );
+  });
+
+/** Prove the connected database, then the guarded drop — the drop core on its own, for the
+ * tests that drive it directly. */
+export const dropWithClient = (
+  pg: PgExecutor,
+  props: PostgresSchemaProps,
+): Effect.Effect<void, PostgresSchemaWrongDatabase | PostgresSchemaDropNotEmptyError | SqlError> =>
+  Effect.gen(function* () {
+    yield* assertDatabase(props, pg);
+    yield* dropGuarded(pg, props);
+  });
+
+/**
+ * The core of `delete`: re-read first (see the file header), refuse a schema the persisted
+ * proof cannot vouch for, then the guarded drop. `output` is the persisted state the engine
+ * hands over — `undefined` is no proof and refuses too.
+ */
+export const deleteWithClient = (
+  pg: PgExecutor,
+  props: PostgresSchemaProps,
+  output: PostgresSchemaAttributes | undefined,
+): Effect.Effect<
+  void,
+  | PostgresSchemaWrongDatabase
+  | PostgresSchemaDeleteForeignRefused
+  | PostgresSchemaDropNotEmptyError
+  | SqlError
+> =>
+  Effect.gen(function* () {
+    yield* assertDatabase(props, pg);
+    const live = yield* selectSchema(pg, props.name);
+    if (live === undefined) return;
+    const refusal = deleteForeignRefusal(props, live, output);
+    if (refusal !== undefined) return yield* Effect.fail(refusal);
+    yield* dropGuarded(pg, props);
+  });

package/src/postgres/schema-diff.ts

@@ -0,0 +1,44 @@
+/**
+ * `Postgres.Schema`'s plan-time diff — entirely offline: `news` (declared) against `output`
+ * (last-applied attributes) and `olds` (last-applied props), never a live query (that
+ * authoritative check is `reconcileWithClient`'s, per S10). Extracted from `schema.ts` to keep
+ * each file under the house's 250-line cap.
+ *
+ * ⛔ `cascade` COMPARES AGAINST `olds`, NOT `output`. Attributes are the live row (name,
+ *   database, owner, comment, oid) — `cascade` is a prop-only concern no catalog column
+ *   carries. The engine's noop branch (`Apply.ts`) commits the OLD props unchanged, so a
+ *   `cascade` flip must answer `update` to reach the persisted state at all: a schema first
+ *   declared `cascade: true` and later set to `false` would otherwise keep dropping with
+ *   `CASCADE` on every delete, because `delete`'s `olds` are read from those persisted props.
+ */
+import { assertSchemaTarget } from './schema-identity.ts';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Effect from 'effect/Effect';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+import { normalizedComment, schemaNameByteRefusal } from './schema-attrs.ts';
+import { PostgresSchemaNameRefused } from './schema-errors.ts';
+
+/** Plan-time only: rename refused, over-long name refused, a database move refused; a `cascade`
+ * flip answers `update` so the new prop reaches state, and every other change answers `update`
+ * too (which `reconcileWithClient` then applies as create, or refuses as drift on a live
+ * schema). */
+export const diffPostgresSchema = (
+  news: Input<PostgresSchemaProps>,
+  output: PostgresSchemaAttributes | undefined,
+  olds?: PostgresSchemaProps,
+) =>
+  Effect.gen(function* () {
+    if (output === undefined || !isResolved(news)) return undefined;
+    yield* assertSchemaTarget(news, output);
+    const nameRefusal = schemaNameByteRefusal(news.name);
+    if (nameRefusal !== undefined) {
+      return yield* Effect.fail(new PostgresSchemaNameRefused({ name: news.name, ...nameRefusal }));
+    }
+    const comment = normalizedComment(news.comment);
+    const changed =
+      (news.owner !== undefined && news.owner !== output.owner) ||
+      (comment !== undefined && comment !== (output.comment ?? undefined)) ||
+      (news.cascade ?? false) !== (olds?.cascade ?? false);
+    return changed ? ({ action: 'update' } as const) : ({ action: 'noop' } as const);
+  });

package/src/postgres/schema-drop-2bp01.test.ts

@@ -0,0 +1,146 @@
+/**
+ * SQLSTATE `2BP01` (`dependent_objects_still_exist`) must become
+ * `PostgresSchemaDropNotEmptyError` on both transports.
+ *
+ * Measured at `@effect/sql-pg@4.0.0-rc.115` `src/internal/sqlError.ts#classifySqlState`:
+ * only class `42` becomes `SqlSyntaxError`. `2BP01` is class `2B`, so the socket client
+ * wraps it as `UnknownError` with the raw code on `reason.cause.code`
+ * (`PgConnection.ts#classifyFields`). The runner transport copies that rule
+ * (`psql-executor.ts#failure`). A test that builds `SqlSyntaxError` by hand pins a shape
+ * neither driver produces.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import type { SqlError } from 'effect/unstable/sql/SqlError';
+import type { PgExecutor } from './database-sql.ts';
+import { classifyInstalled } from './installed-classifier.ts';
+import { postgresRunnerConnection } from './connection.ts';
+import { type PsqlRunner, makePsqlExecutor } from './psql-executor.ts';
+import { isDependentObjectsError } from './schema-sql.ts';
+import { PostgresSchemaDropNotEmptyError } from './schema-errors.ts';
+import { dropWithClient, postgresSchemaHandlers } from './schema.ts';
+import type { PostgresSchemaAttributes, PostgresSchemaProps } from './schema-attrs.ts';
+
+const baseProps: PostgresSchemaProps = { name: 'ledger', database: 'postgres', owner: 'tim' };
+
+const socket2bp01 = (): Promise<SqlError> => classifyInstalled('2BP01');
+
+/** Emptiness check says empty; the following DROP is the server's real `2BP01`. */
+const emptyThenRefuse = (drop: Effect.Effect<ReadonlyArray<object>, SqlError>): PgExecutor => ({
+  unsafe: <A extends object>(text: string) => {
+    if (text.startsWith('SELECT current_database()')) {
+      return Effect.succeed([{ database: 'postgres' }] as unknown as ReadonlyArray<A>);
+    }
+    if (text.includes('AS empty')) {
+      return Effect.succeed([{ empty: true }] as unknown as ReadonlyArray<A>);
+    }
+    return drop as Effect.Effect<ReadonlyArray<A>, SqlError>;
+  },
+  transaction: () => Effect.void,
+});
+
+describe('2BP01 classification', () => {
+  test('the installed socket classifier wraps 2BP01 as UnknownError, not SqlSyntaxError', async () => {
+    const error = await socket2bp01();
+    expect(error.reason._tag).toBe('UnknownError');
+    expect(isDependentObjectsError(error)).toBe(true);
+  });
+
+  test('dropWithClient classifies the socket 2BP01 shape as the typed not-empty tag', async () => {
+    const error = await Effect.runPromise(
+      Effect.flip(dropWithClient(emptyThenRefuse(Effect.fail(await socket2bp01())), baseProps)),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaDropNotEmptyError);
+  });
+
+  test('the runner transport classifies a verbose 2BP01 line as the typed not-empty tag', async () => {
+    const run: PsqlRunner = ({ stdin }) => {
+      if (stdin.includes('current_database()')) {
+        return Promise.resolve({ code: 0, stdout: '[{"database":"postgres"}]', stderr: '' });
+      }
+      if (stdin.includes('AS empty')) {
+        return Promise.resolve({ code: 0, stdout: '[{"empty":true}]', stderr: '' });
+      }
+      return Promise.resolve({
+        code: 3,
+        stdout: '',
+        stderr: 'ERROR:  2BP01: dependent objects still exist\n',
+      });
+    };
+    const produced = await Effect.runPromise(
+      Effect.flip(
+        makePsqlExecutor(run, { database: 'postgres', username: 'postgres' }).unsafe(
+          'DROP SCHEMA IF EXISTS "ledger"',
+        ),
+      ),
+    );
+    expect(produced.reason._tag).toBe('UnknownError');
+    expect(isDependentObjectsError(produced)).toBe(true);
+
+    const error = await Effect.runPromise(
+      Effect.flip(
+        dropWithClient(
+          makePsqlExecutor(run, { database: 'postgres', username: 'postgres' }),
+          baseProps,
+        ),
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaDropNotEmptyError);
+  });
+
+  test('the real delete handler classifies a runner 2BP01 as the typed not-empty tag', async () => {
+    // Order is load-bearing (schema-handlers.test.ts#route): the probe must answer PRESENT so
+    // the absent-database short-circuit does not swallow the test, and the ownership re-read
+    // must answer the row the persisted output vouches for, so the delete reaches the DROP.
+    const run: PsqlRunner = ({ stdin }) => {
+      if (stdin.includes('AS empty')) {
+        return Promise.resolve({ code: 0, stdout: '[{"empty":true}]', stderr: '' });
+      }
+      if (stdin.includes('FROM pg_namespace')) {
+        return Promise.resolve({
+          code: 0,
+          stdout: '[{"name":"ledger","oid":1,"owner":"tim"}]',
+          stderr: '',
+        });
+      }
+      if (stdin.includes('FROM pg_database')) {
+        return Promise.resolve({ code: 0, stdout: '[{"present":1}]', stderr: '' });
+      }
+      if (stdin.includes('current_database()')) {
+        return Promise.resolve({ code: 0, stdout: '[{"database":"postgres"}]', stderr: '' });
+      }
+      return Promise.resolve({
+        code: 3,
+        stdout: '',
+        stderr: 'ERROR:  2BP01: dependent objects still exist\n',
+      });
+    };
+    const output: PostgresSchemaAttributes = {
+      name: 'ledger',
+      database: 'postgres',
+      oid: 1,
+      owner: 'tim',
+      comment: null,
+    };
+    const error = await Effect.runPromise(
+      Effect.flip(
+        postgresSchemaHandlers
+          .delete({
+            id: 'x',
+            fqn: 'x',
+            instanceId: 'x',
+            olds: baseProps,
+            output,
+            session: undefined as never,
+            bindings: [] as never,
+          })
+          .pipe(
+            Effect.provide(
+              postgresRunnerConnection({ run, database: 'postgres', username: 'postgres' }),
+            ),
+          ),
+      ),
+    );
+    expect(error).toBeInstanceOf(PostgresSchemaDropNotEmptyError);
+  });
+});

package/src/postgres/schema-errors.ts

@@ -0,0 +1,209 @@
+/**
+ * `Postgres.Schema`'s failures as typed tags, following the `Postgres.Database` pattern (S21).
+ *
+ * Refusals use checked catalog facts or raw SQLSTATE (42P06 / 2BP01), never driver message text.
+ */
+import * as Data from 'effect/Data';
+
+/** A declared name would be silently truncated (same as `PostgresDatabaseNameRefused`). */
+export class PostgresSchemaNameRefused extends Data.TaggedError('PostgresSchemaNameRefused')<{
+  readonly name: string;
+  readonly byteLength: number;
+  readonly limit: number;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Schema "${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 schema no later read will ever find again.'
+    );
+  }
+}
+
+/** A logical id's `name` changed. A schema's name is its identity; this family has no
+ * `ALTER SCHEMA … RENAME`. */
+export class PostgresSchemaRenameRefused extends Data.TaggedError('PostgresSchemaRenameRefused')<{
+  readonly from: string;
+  readonly to: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Schema: the declared name changed from "${this.from}" to "${this.to}". A ` +
+      'rename is refused during plan or apply — this provider never runs ALTER SCHEMA … RENAME. Declare a new ' +
+      'logical id for the new name and remove the old one once its contents have moved.'
+    );
+  }
+}
+
+/** `owner` names a role `pg_roles` does not have, checked before the `CREATE SCHEMA`. */
+export class PostgresSchemaOwnerMissing extends Data.TaggedError('PostgresSchemaOwnerMissing')<{
+  readonly schema: string;
+  readonly owner: string;
+}> {
+  override get message(): string {
+    return `Postgres.Schema "${this.schema}": AUTHORIZATION "${this.owner}" is not a role in pg_roles.`;
+  }
+}
+
+/** A live asserted prop no longer matches the declaration (`owner` or `comment`). */
+export class PostgresSchemaDrift extends Data.TaggedError('PostgresSchemaDrift')<{
+  readonly schema: string;
+  readonly prop: string;
+  readonly declared: unknown;
+  readonly live: unknown;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Schema "${this.schema}": ${this.prop} is declared as ` +
+      `${JSON.stringify(this.declared)} but the live schema has ${JSON.stringify(this.live)}. ` +
+      'This provider never issues ALTER SCHEMA — update the declaration to match the live value, ' +
+      'or change it by hand and re-plan.'
+    );
+  }
+}
+
+/** `CREATE SCHEMA` raised no error, but the immediate re-read (S10) still finds nothing. */
+export class PostgresSchemaCreateVanished extends Data.TaggedError('PostgresSchemaCreateVanished')<{
+  readonly schema: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Schema "${this.schema}": CREATE SCHEMA raised no error, but the schema is still ` +
+      'absent on the immediate re-read. Re-plan — this is not a state this provider expects to reach.'
+    );
+  }
+}
+
+/**
+ * `delete` with `cascade: false` refuses a schema that still has relations. The same refusal
+ * answers a plain `DROP SCHEMA` the server rejected with SQLSTATE `2BP01`
+ * (`dependent_objects_still_exist`) — an object kind the emptiness check's four catalogs do not
+ * cover (an extension, a collation) — so no "empty" path escapes the typed tag.
+ */
+export class PostgresSchemaDropNotEmptyError extends Data.TaggedError(
+  'PostgresSchemaDropNotEmptyError',
+)<{
+  readonly schema: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Schema "${this.schema}": DROP SCHEMA refused because the schema is not empty and ` +
+      'cascade is false. Declare cascade: true to drop its contents, or empty it by hand first.'
+    );
+  }
+}
+
+/** Every statement this resource issues must run against the DECLARED database. The family
+ * connection points at a maintenance database, so the schema handlers open `props.database`
+ * themselves (`withPg`'s database override); this failure means the server answered
+ * `current_database()` with something else — the override was ignored, and no read or write
+ * ran against the schema's real home. */
+export class PostgresSchemaWrongDatabase extends Data.TaggedError('PostgresSchemaWrongDatabase')<{
+  readonly schema: string;
+  readonly declared: string;
+  readonly connected: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Schema "${this.schema}": declared in database "${this.declared}" but the ` +
+      `connection answers current_database() "${this.connected}". The handlers open the declared ` +
+      'database themselves, so this points at broken provider wiring — fix it before touching any ' +
+      'schema, or the next create would land in the wrong database.'
+    );
+  }
+}
+
+/**
+ * `delete` refuses to drop a live schema that is not the one this resource created. The
+ * engine hands `delete` the persisted state (`output`, with the `oid` and `owner` the last
+ * assert proved), and the provider re-reads `pg_namespace` before any `DROP` — a live row that
+ * no longer matches that proof is someone else's schema wearing the same name (the old row was
+ * dropped out of band and the name recreated), and `DROP SCHEMA` would remove their objects.
+ * Nothing is dropped: clear the out-of-band schema by hand, or adopt it.
+ */
+export class PostgresSchemaDeleteForeignRefused extends Data.TaggedError(
+  'PostgresSchemaDeleteForeignRefused',
+)<{
+  readonly schema: string;
+  readonly database: string;
+  readonly liveOid: number;
+  readonly liveOwner: string;
+  /** The proof the persisted state carries; both `undefined` when no state was handed over. */
+  readonly lastOid: number | undefined;
+  readonly lastOwner: string | undefined;
+}> {
+  override get message(): string {
+    const proof =
+      this.lastOid === undefined || this.lastOwner === undefined
+        ? 'delete carried no persisted oid/owner to prove ownership'
+        : `the persisted proof is oid ${String(this.lastOid)}, owner "${this.lastOwner}"`;
+    return (
+      `Postgres.Schema "${this.schema}": the live schema in database "${this.database}" (oid ` +
+      `${String(this.liveOid)}, owner "${this.liveOwner}") is not the one this resource created — ` +
+      `${proof}. No DROP was issued: a schema with this name was created out of band. Drop it by ` +
+      'hand, or adopt it on a resource whose declared props match it.'
+    );
+  }
+}
+
+/** A logical id's `database` changed. A schema lives in one database and this family never
+ * moves one: `DROP SCHEMA` in the old database plus a new declaration is the only path. */
+export class PostgresSchemaDatabaseRefused extends Data.TaggedError(
+  'PostgresSchemaDatabaseRefused',
+)<{
+  readonly from: string;
+  readonly to: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Schema: the declared database changed from "${this.from}" to "${this.to}". A ` +
+      'schema is never moved across databases — declare a new logical id in the new database and ' +
+      'remove the old one once its contents have moved.'
+    );
+  }
+}
+
+/** No persisted proof: even a same-owner schema needs explicit adoption, including recovery. */
+export class PostgresSchemaExistsRefused extends Data.TaggedError('PostgresSchemaExistsRefused')<{
+  readonly schema: string;
+  readonly database: string;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Schema "${this.schema}" in "${this.database}" already exists. Re-plan with ` +
+      '--adopt (adopt(true)) to adopt it explicitly; crash recovery also requires adoption. ' +
+      'No existing schema was changed.'
+    );
+  }
+}
+
+/** Reconcile must not replace the oid delete relies on with an out-of-band replacement's oid. */
+export class PostgresSchemaIdentityRefused extends Data.TaggedError(
+  'PostgresSchemaIdentityRefused',
+)<{
+  readonly schema: string;
+  readonly storedOid: number;
+  readonly liveOid: number;
+}> {
+  override get message(): string {
+    return (
+      `Postgres.Schema "${this.schema}": live oid ${String(this.liveOid)} differs from stored oid ` +
+      `${String(this.storedOid)}. The schema was dropped and recreated outside this stack. ` +
+      'Remove stale state and explicitly adopt the replacement before managing it.'
+    );
+  }
+}
+
+export type PostgresSchemaError =
+  | PostgresSchemaExistsRefused
+  | PostgresSchemaIdentityRefused
+  | PostgresSchemaNameRefused
+  | PostgresSchemaRenameRefused
+  | PostgresSchemaOwnerMissing
+  | PostgresSchemaDrift
+  | PostgresSchemaCreateVanished
+  | PostgresSchemaDropNotEmptyError
+  | PostgresSchemaDeleteForeignRefused
+  | PostgresSchemaWrongDatabase
+  | PostgresSchemaDatabaseRefused;