@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/index.ts

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

package/src/postgres/installed-classifier.ts

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

package/src/postgres/providers.ts

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

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

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

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

@@ -4,6 +4,8 @@ import { postgresRunnerProviders } from './providers.ts';
 import { postgresRunnerConnection, withPg } from './connection.ts';
 import { reconcileWithClient } from './database.ts';
 import { buildCreateDatabaseSql, isDuplicateDatabaseRace } from './database-sql.ts';
+import { buildSetPasswordSql } from './role-sql.ts';
+import { scramSha256Verifier } from './role-scram.ts';
 import { type PsqlRunner, inlineParams, makePsqlExecutor } from './psql-executor.ts';
 
 const target = { database: 'postgres', username: 'postgres' };
@@ -11,7 +13,7 @@ const ok = (stdout: string) => Promise.resolve({ code: 0, stdout, stderr: '' });
 
 describe('psql executor', () => {
   test('inlines string params as literals and refuses non-strings', () => {
-    expect(inlineParams('SELECT $1, $2', ["it's", 'b'])).toBe("SELECT 'it''s', 'b'");
+    expect(inlineParams('SELECT $1, $2', ["it's", 'b'])).toBe("SELECT E'it''s', E'b'");
     expect(() => inlineParams('SELECT $1', [5])).toThrow('must be a string');
   });
 
@@ -27,7 +29,24 @@ describe('psql executor', () => {
     expect(rows).toEqual([{ oid: 16400, name: 'x' }]);
     expect(calls[0]?.argv.slice(0, 1)).toEqual(['psql']);
     expect(calls[0]?.stdin).toContain('json_agg');
-    expect(calls[0]?.stdin).toContain("datname = 'x'");
+    expect(calls[0]?.stdin).toContain("datname = E'x'");
+  });
+
+  test('a WITH-led row query is wrapped in json_agg too, not discarded as a write', async () => {
+    // The schema emptiness check is `WITH ns AS (…) SELECT …` — unwrapped, its answer rows
+    // are dropped and the check reads the empty-table fallback ("every schema is empty").
+    const calls: { argv: readonly string[]; stdin: string }[] = [];
+    const run: PsqlRunner = (call) => {
+      calls.push(call);
+      return ok('[{"empty":false}]\n');
+    };
+    const rows = await Effect.runPromise(
+      makePsqlExecutor(run, target).unsafe(
+        'WITH ns AS (SELECT 1 AS oid) SELECT NOT EXISTS (SELECT 1 FROM pg_class) AS empty',
+      ),
+    );
+    expect(rows).toEqual([{ empty: false }]);
+    expect(calls[0]?.stdin).toContain('json_agg');
   });
 
   test('a duplicate-database failure stays recognisable as the 42P04 race', async () => {
@@ -43,6 +62,31 @@ describe('psql executor', () => {
     expect(isDuplicateDatabaseRace(error)).toBe(true);
   });
 
+  test('a failed password statement carries the SCRAM verifier on stdin, never the plain password', async () => {
+    // The red-team finding: the statement text is what the runner inlines into `psql`'s stdin and
+    // what a failed `ALTER` echoes back through stderr into the error. Since the fix the text
+    // holds only the verifier, so both the stdin side and the error side stay secret-free.
+    const placeholder = 'placeholder-password';
+    const statement = buildSetPasswordSql('hf_agent', scramSha256Verifier(placeholder));
+    let stdin = '';
+    const run: PsqlRunner = async (call) => {
+      stdin = call.stdin;
+      return {
+        code: 3,
+        stdout: '',
+        stderr: `ERROR:  42501: permission denied\nSTATEMENT:  ${statement}\n`,
+      };
+    };
+    const error = await Effect.runPromise(
+      Effect.flip(makePsqlExecutor(run, target).unsafe(statement)),
+    );
+    const rendered = `${error.message}\n${String(error.reason.operation ?? '')}\n${JSON.stringify(error)}`;
+    expect(stdin).toContain('SCRAM-SHA-256$');
+    expect(stdin).not.toContain(placeholder);
+    expect(rendered).not.toContain(placeholder);
+    expect(rendered).not.toContain(`PASSWORD E'${placeholder.slice(0, 3)}`);
+  });
+
   test('a runner that never reached psql is a ConnectionError', async () => {
     const run: PsqlRunner = () =>
       Promise.resolve({ code: 255, stdout: '', stderr: 'ssh: refused' });
@@ -94,6 +138,23 @@ describe('runner transport through withPg', () => {
     expect(stdins.slice(before).some((s) => s.startsWith('CREATE DATABASE'))).toBe(false);
   });
 
+  test('transaction is one psql script from BEGIN through COMMIT', async () => {
+    const calls: string[] = [];
+    const run: PsqlRunner = (call) => {
+      calls.push(call.stdin);
+      return ok('');
+    };
+    await Effect.runPromise(
+      makePsqlExecutor(run, target).transaction([
+        'CREATE ROLE "a" WITH NOLOGIN',
+        'GRANT "p" TO "a" WITH SET FALSE',
+      ]),
+    );
+    expect(calls).toEqual([
+      'BEGIN;\nCREATE ROLE "a" WITH NOLOGIN;\nGRANT "p" TO "a" WITH SET FALSE;\nCOMMIT;',
+    ]);
+  });
+
   test("postgresRunnerProviders keeps the connection live for the engine's later handler calls", async () => {
     const run: PsqlRunner = () => ok('[]');
     const rows = await Effect.runPromise(

package/src/postgres/psql-executor.ts

@@ -11,8 +11,9 @@
  * ⛔ `psql` HAS NO BIND PARAMETERS OVER STDIN. Every `$n` is replaced by a `quoteStringLiteral`
  *   literal, and ONLY string params are accepted — this family binds a database or role name,
  *   nothing else — so a number or object is a refusal, never silently stringified.
- * ★ ROWS COME BACK AS JSON: a `SELECT` is wrapped in `json_agg`, so `oid` and `datconnlimit`
- *   arrive as JS numbers exactly as the socket client decodes them (database-sql.ts, no bigint).
+ * ★ ROWS COME BACK AS JSON: a row-returning statement (`SELECT`, or a `WITH` query) is wrapped
+ *   in `json_agg`, so `oid` and `datconnlimit` arrive as JS numbers exactly as the socket client
+ *   decodes them (database-sql.ts, no bigint).
  * ★ `VERBOSITY=verbose` puts the SQLSTATE in the error line, so `42P04` (duplicate database)
  *   stays recognisable to `isDuplicateDatabaseRace`.
  */
@@ -62,20 +63,30 @@ const normalizeRow = (row: unknown): unknown =>
     ? { ...row, oid: Number((row as { oid: string }).oid) }
     : row;
 
-const isSelect = (sql: string): boolean => /^\s*SELECT\b/i.test(sql);
+/** Row-returning statements: a plain `SELECT`, or a CTE query (`WITH … SELECT …`). A `WITH`
+ * whose rows were discarded would answer an empty table instead of its result — the emptiness
+ * check is `WITH`-led, so a missing `WITH` here silently claims every schema is empty. */
+const returnsRows = (sql: string): boolean => /^\s*(SELECT|WITH)\b/i.test(sql);
 
 const wrapRows = (sql: string): string =>
   `SELECT coalesce(json_agg(t), '[]'::json)::text FROM (${sql}) t;`;
 
+/** A password literal must not survive into an error Alchemy logs. `ALTER ROLE … PASSWORD`
+ * inlines the value (Postgres has no bind form), and the runner turns the first 40 characters
+ * of that statement into `operation` and the full `stderr` into `message`. */
+export const redactPasswordLiterals = (text: string): string =>
+  text.replace(
+    /PASSWORD\s+(?:E'(?:[^'\\]|\\[\s\S]|'')*'|'(?:[^']|'')*')/gi,
+    "PASSWORD '[redacted]'",
+  );
+
 const failure = (operation: string, result: PsqlResult): SqlError => {
   const state = /ERROR:\s+([0-9A-Z]{5}):/.exec(result.stderr)?.[1];
+  const stderr = redactPasswordLiterals(result.stderr.trim());
   const fields = {
-    cause: Object.assign(
-      new Error(result.stderr.trim()),
-      state === undefined ? {} : { code: state },
-    ),
-    message: result.stderr.trim(),
-    operation,
+    cause: Object.assign(new Error(stderr), state === undefined ? {} : { code: state }),
+    message: stderr,
+    operation: redactPasswordLiterals(operation),
   };
   const reason =
     state === undefined
@@ -86,6 +97,42 @@ const failure = (operation: string, result: PsqlResult): SqlError => {
   return new SqlError({ reason });
 };
 
+const runScript = (
+  run: PsqlRunner,
+  target: PsqlTarget,
+  stdin: string,
+  operation: string,
+): Effect.Effect<PsqlResult, SqlError> =>
+  Effect.gen(function* () {
+    const result = yield* Effect.tryPromise({
+      try: () =>
+        run({
+          argv: [
+            'psql',
+            '-X',
+            '-q',
+            '-A',
+            '-t',
+            '-v',
+            'ON_ERROR_STOP=1',
+            '-v',
+            'VERBOSITY=verbose',
+            '-U',
+            target.username,
+            '-d',
+            target.database,
+          ],
+          stdin,
+        }),
+      catch: (cause) =>
+        new SqlError({ reason: new ConnectionError({ cause, operation: 'psql exec' }) }),
+    });
+    if (result.code !== 0) {
+      return yield* Effect.fail(failure(operation, result));
+    }
+    return result;
+  });
+
 export const makePsqlExecutor = (run: PsqlRunner, target: PsqlTarget): PgExecutor => ({
   unsafe: <A extends object>(sql: string, params: ReadonlyArray<unknown> = []) =>
     Effect.gen(function* () {
@@ -94,31 +141,13 @@ export const makePsqlExecutor = (run: PsqlRunner, target: PsqlTarget): PgExecuto
         catch: (cause) =>
           new SqlError({ reason: new UnknownError({ cause, operation: 'psql inline params' }) }),
       });
-      const rows = isSelect(inlined);
-      const result = yield* Effect.tryPromise({
-        try: () =>
-          run({
-            argv: [
-              'psql',
-              '-X',
-              '-q',
-              '-A',
-              '-t',
-              '-v',
-              'ON_ERROR_STOP=1',
-              '-v',
-              'VERBOSITY=verbose',
-              '-U',
-              target.username,
-              '-d',
-              target.database,
-            ],
-            stdin: rows ? wrapRows(inlined) : `${inlined};`,
-          }),
-        catch: (cause) =>
-          new SqlError({ reason: new ConnectionError({ cause, operation: 'psql exec' }) }),
-      });
-      if (result.code !== 0) return yield* Effect.fail(failure(inlined.slice(0, 40), result));
+      const rows = returnsRows(inlined);
+      const result = yield* runScript(
+        run,
+        target,
+        rows ? wrapRows(inlined) : `${inlined};`,
+        redactPasswordLiterals(inlined).slice(0, 40),
+      );
       if (!rows) return [] as ReadonlyArray<A>;
       const parsed = yield* Effect.try({
         try: () => (JSON.parse(result.stdout.trim() || '[]') as unknown[]).map(normalizeRow),
@@ -127,4 +156,15 @@ export const makePsqlExecutor = (run: PsqlRunner, target: PsqlTarget): PgExecuto
       });
       return parsed as ReadonlyArray<A>;
     }),
+  /**
+   * One `psql` session: `BEGIN` … statements … `COMMIT`. `ON_ERROR_STOP` exits before `COMMIT`
+   * on a failure, and the backend aborts the open transaction when that session drops
+   * (`postgres.c@REL_18_6` `SocketBackend` EOF while `IsTransactionState`). Separate `unsafe`
+   * calls cannot do this — each is its own process and its own autocommit.
+   */
+  transaction: (statements) =>
+    Effect.gen(function* () {
+      const script = ['BEGIN', ...statements, 'COMMIT'].join(';\n');
+      yield* runScript(run, target, `${script};`, 'BEGIN');
+    }),
 });

package/src/postgres/role-adopt.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Apply-time ownership for `Postgres.Role`. The review of PR 336: `read` answers `Unowned` when
+ * the stack holds no state, but `reconcile` never called `refuseTakeover`, so a live role found
+ * between plan and apply (or one Alchemy skipped probing because a prop was still an Output) was
+ * altered and then recorded as ours.
+ *
+ * These tests construct `postgresRoleHandlers` — the lifecycle tests drive `reconcileWithClient`
+ * directly and cannot see this hole. The recording fake is reached the way the engine reaches a
+ * real cluster: `withPg` over the runner transport.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { postgresRunnerConnection } from './connection.ts';
+import { parseLiteral } from './fake-sql-quote.ts';
+import { makeFakeSql } from './fake-sql.ts';
+import { type PsqlRunner } from './psql-executor.ts';
+import { postgresRoleHandlers } from './role-provider.ts';
+import type { PostgresRoleAttributes, PostgresRoleProps } from './role-attrs.ts';
+
+const baseProps: PostgresRoleProps = {
+  name: 'seat-observability',
+  login: false,
+  connectionLimit: 10,
+  inherit: true,
+};
+
+const liveRole = (): PostgresRoleAttributes => ({
+  name: 'seat-observability',
+  oid: 20000,
+  login: true,
+  connectionLimit: -1,
+  inherit: false,
+  validUntil: null,
+  memberOf: ['hf_agent'],
+  passwordSeal: '',
+});
+
+/**
+ * A runner that answers the handler's `psql` calls from the recording fake. `withPg` wraps a
+ * `SELECT` in `json_agg` and the executor inlines `$1` before the runner sees it, so this
+ * unwraps that envelope and binds the literal back to the param the fake's catalog read expects.
+ */
+const runnerFor =
+  (fake: ReturnType<typeof makeFakeSql>): PsqlRunner =>
+  async ({ stdin }) => {
+    const wrapped = /^SELECT coalesce\(json_agg\(t\), '\[\]'::json\)::text FROM \((.*)\) t;$/s.exec(
+      stdin,
+    );
+    const body = (wrapped?.[1] ?? stdin).replace(/;\s*$/, '');
+    const bound = /^([\s\S]*) = (E'[\s\S]*')$/.exec(body);
+    const sql = bound === null ? body : `${bound[1]} = $1`;
+    const params = bound === null ? [] : [parseLiteral(bound[2] as string)];
+    const rows = await Effect.runPromise(fake.unsafe(sql, params));
+    return { code: 0, stdout: JSON.stringify(rows), stderr: '' };
+  };
+
+const writes = (fake: ReturnType<typeof makeFakeSql>) =>
+  fake.statements.filter(
+    (s) =>
+      s.text.startsWith('ALTER') ||
+      s.text.startsWith('GRANT') ||
+      s.text.startsWith('REVOKE') ||
+      s.text.startsWith('CREATE'),
+  );
+
+describe('adopt-off takeover', () => {
+  test('a live role and adopt-off produces no statement', async () => {
+    const fake = makeFakeSql({ roleRows: [liveRole()] });
+    fake.memberships.add('seat-observability\0hf_agent');
+    const refused = await Effect.runPromise(
+      postgresRoleHandlers
+        .reconcile({
+          id: 'seat-observability',
+          fqn: 'Postgres.Role/seat-observability',
+          instanceId: 'creating-1',
+          news: baseProps,
+          output: undefined,
+          olds: baseProps,
+          session: {} as never,
+          bindings: [],
+        })
+        .pipe(
+          Effect.provide(
+            postgresRunnerConnection({
+              run: runnerFor(fake),
+              database: 'postgres',
+              username: 'postgres',
+            }),
+          ),
+          Effect.exit,
+        ),
+    );
+    // refuseTakeover dies: a takeover is a defect, not a typed error the engine retries.
+    const rendered = refused._tag === 'Failure' ? String(refused.cause) : JSON.stringify(refused);
+    expect(rendered).toContain('already exists');
+    expect(writes(fake)).toEqual([]);
+  });
+});