@homeflare/alchemy 0.43.0 → 0.45.0

package/src/postgres/fake-sql.ts

@@ -1,19 +1,25 @@
 /**
  * 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.
+ * every lifecycle test in this family. No socket, no `@effect/sql-pg` client — it matches the
+ * statement shapes this family issues, by text, against an in-memory `pg_database` map. The
+ * role catalog is `fake-role-sql.ts`; the schema catalog is `fake-schema-sql.ts`.
  *
- * ⛔ IT PARSES ITS OWN OUTPUT, NOT SQL IN GENERAL. `parseCreate` below understands exactly the
- *   text `buildCreateDatabaseSql` (`database-sql.ts`) produces — quoted with `quoteIdent` /
+ * ⛔ IT PARSES ITS OWN OUTPUT, NOT SQL IN GENERAL. `parseCreate` (`fake-sql-parse.ts`) understands
+ *   exactly the text `buildCreateDatabaseSql` 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.
+ *   general SQL parser would hide a quoting bug instead of tripping over it. The role and schema
+ *   halves live in their own files under the same rule.
  */
 import * as Effect from 'effect/Effect';
-import { SqlError, SqlSyntaxError } from 'effect/unstable/sql/SqlError';
+import { SqlError, SqlSyntaxError, UnknownError } from 'effect/unstable/sql/SqlError';
 import type { PostgresDatabaseAttributes } from './database-attrs.ts';
 import type { PgExecutor } from './database-sql.ts';
+import { parseCreate } from './fake-sql-parse.ts';
+import { type FakeRoleState, applyRoleStatement } from './fake-role-sql.ts';
+import { type FakeSchemaState, applySchemaStatement, seedSchemas } from './fake-schema-sql.ts';
+import type { PostgresRoleAttributes } from './role-attrs.ts';
+import type { PostgresSchemaAttributes } from './schema-attrs.ts';
 
 export interface RecordedStatement {
   readonly text: string;
@@ -25,57 +31,93 @@ export interface FakeSql extends PgExecutor {
   /** 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>;
+  /** Mutable on purpose: a test seeds a live role (adoption, drift) or clears one (drop). */
+  readonly roleRows: Map<string, PostgresRoleAttributes>;
+  /** `member\0parent\0grantor` triples backing `pg_auth_members` (a plain `pg_auth_members`
+   * read, a grant, a revoke and a DROP ROLE cascade all go through `fake-role-sql.ts`);
+   * `GRANT`/`REVOKE` mutate it. An empty grantor segment is an inconsistent catalog/test row. */
+  readonly memberships: Set<string>;
+  /** Options on a membership the name alone hides, keyed `member\0parent\0grantor`. Absent
+   * means neither ADMIN, SET nor an explicit per-grant INHERIT. */
+  readonly membershipOptions: Map<
+    string,
+    { readonly admin: boolean; readonly set: boolean; readonly inherit?: boolean }
+  >;
+  /** Mutable on purpose: a test seeds a live schema (adoption, drift) or clears one (drop). */
+  readonly schemas: Map<string, PostgresSchemaAttributes>;
+  /** Mutable on purpose: names of schemas this fake pretends hold at least one relation, so a
+   * `cascade: false` drop refusal has something to refuse. */
+  readonly relationsIn: Set<string>;
 }
 
 export interface FakeSqlOptions {
+  readonly standardConformingStrings?: boolean;
   readonly roles?: ReadonlyArray<string>;
   readonly databases?: ReadonlyArray<PostgresDatabaseAttributes>;
+  readonly roleRows?: ReadonlyArray<PostgresRoleAttributes>;
   /** 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;
+  /** Fail the next statement whose text starts with this prefix, once, without applying it.
+   * A `transaction` that included earlier statements rolls them back. */
+  readonly failNext?: string;
+  readonly schemas?: ReadonlyArray<PostgresSchemaAttributes>;
+  /** Names of schemas the fake answers `schemaIsEmpty` with `false` for. */
+  readonly schemasWithRelations?: ReadonlyArray<string>;
+  /** Accept the NEXT `CREATE SCHEMA` (no error) but record nothing — the S10 case where the
+   * write's own report is a lie and the immediate re-read finds nothing. */
+  readonly swallowNextCreateSchema?: boolean;
+  /** What `current_database()` answers and every schema row is stamped with (a real server
+   * always reports the database its connection opened). Default `postgres`. */
+  readonly database?: string;
+  /** The NEXT `CREATE SCHEMA` races with a row owned by THIS role — a
+   * concurrent creator won between the first `SELECT` and the `IF NOT EXISTS`, which then
+   * does nothing; plain CREATE instead fails with 42P06. Consumed once. */
+  readonly raceNextCreateSchema?: string;
+  /** What `current_user` answers, and the owner a `CREATE SCHEMA` without `AUTHORIZATION`
+   * stores. Default `postgres`. A test that sets this pins the omitted-owner comparison
+   * against the session role, not a hardcoded name. */
+  readonly currentUser?: string;
 }
 
-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 roleNames = new Set(options.roles ?? []);
+  const roleRows = new Map(options.roleRows?.map((r) => [r.name, r] as const) ?? []);
   const databases = new Map(options.databases?.map((d) => [d.name, d] as const) ?? []);
+  const memberships = new Set<string>();
+  const membershipOptions = new Map<
+    string,
+    { readonly admin: boolean; readonly set: boolean; readonly inherit?: boolean }
+  >();
+  const schemas = seedSchemas(options.schemas, options.database ?? 'postgres');
+  const relationsIn = new Set(options.schemasWithRelations ?? []);
   let raceRemaining = options.raceNextCreate === true ? 1 : 0;
+  let failNext = options.failNext;
   let oidCounter = 20000;
+  const nextOid = (): number => {
+    const oid = oidCounter;
+    oidCounter += 1;
+    return oid;
+  };
+  const roleState: FakeRoleState = {
+    roleNames,
+    roleRows,
+    memberships,
+    membershipOptions,
+    nextOid,
+  };
+  const schemaState: FakeSchemaState = {
+    schemas,
+    relationsIn,
+    database: options.database ?? 'postgres',
+    standardConformingStrings: options.standardConformingStrings ?? true,
+    sessionRole: options.currentUser ?? 'postgres',
+    swallowRemaining: options.swallowNextCreateSchema === true ? 1 : 0,
+    raceOwner: options.raceNextCreateSchema,
+    nextOid,
+  };
 
   const unsafe = <A extends object>(
     text: string,
@@ -84,10 +126,35 @@ export const makeFakeSql = (options: FakeSqlOptions = {}): FakeSql => {
     Effect.suspend(() => {
       statements.push({ text, params });
 
+      if (failNext !== undefined && text.startsWith(failNext)) {
+        failNext = undefined;
+        return Effect.fail(
+          new SqlError({
+            reason: new UnknownError({
+              cause: new Error('injected statement failure'),
+              message: 'injected statement failure',
+              operation: text.slice(0, 40),
+            }),
+          }),
+        );
+      }
+
       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>,
+          (roleNames.has(role) || roleRows.has(role)
+            ? [{ present: 1 }]
+            : []) as unknown as ReadonlyArray<A>,
+        );
+      }
+
+      // ⚠️ startsWith, BEFORE the `FROM pg_database` branch: the full-row select also contains
+      //   `FROM pg_database`, but starts with `SELECT d.oid` — only the existence probe starts
+      //   with `SELECT 1 AS present`.
+      if (text.startsWith('SELECT 1 AS present FROM pg_database')) {
+        const name = params[0] as string;
+        return Effect.succeed(
+          (databases.has(name) ? [{ present: 1 }] : []) as unknown as ReadonlyArray<A>,
         );
       }
 
@@ -110,14 +177,67 @@ export const makeFakeSql = (options: FakeSqlOptions = {}): FakeSql => {
             }),
           );
         }
-        const row = { ...parseCreate(text), oid: oidCounter };
-        oidCounter += 1;
+        const row = { ...parseCreate(text), oid: nextOid() };
         databases.set(row.name, row);
         return Effect.succeed([] as unknown as ReadonlyArray<A>);
       }
 
+      const schemaStatement = applySchemaStatement<A>(schemaState, text, params);
+      if (schemaStatement !== undefined) return schemaStatement;
+
+      const roleStatement = applyRoleStatement<A>(roleState, text, params);
+      if (roleStatement !== undefined) return roleStatement;
+
       throw new Error(`fake-sql: unrecognised statement: ${text}`);
     });
 
-  return { unsafe, statements, databases };
+  const snapshot = () => ({
+    roleRows: new Map(roleRows),
+    roleNames: new Set(roleNames),
+    memberships: new Set(memberships),
+    membershipOptions: new Map(membershipOptions),
+    databases: new Map(databases),
+    schemas: new Map(schemas),
+    relationsIn: new Set(relationsIn),
+    swallowRemaining: schemaState.swallowRemaining,
+    raceOwner: schemaState.raceOwner,
+    oid: oidCounter,
+  });
+  const restore = (snap: ReturnType<typeof snapshot>) => {
+    roleRows.clear();
+    for (const [key, value] of snap.roleRows) roleRows.set(key, value);
+    roleNames.clear();
+    for (const name of snap.roleNames) roleNames.add(name);
+    memberships.clear();
+    for (const key of snap.memberships) memberships.add(key);
+    membershipOptions.clear();
+    for (const [key, value] of snap.membershipOptions) membershipOptions.set(key, value);
+    databases.clear();
+    for (const [key, value] of snap.databases) databases.set(key, value);
+    schemas.clear();
+    for (const [key, value] of snap.schemas) schemas.set(key, value);
+    relationsIn.clear();
+    for (const name of snap.relationsIn) relationsIn.add(name);
+    schemaState.swallowRemaining = snap.swallowRemaining;
+    schemaState.raceOwner = snap.raceOwner;
+    oidCounter = snap.oid;
+  };
+  const transaction = (sqls: readonly string[]): Effect.Effect<void, SqlError> => {
+    const snap = snapshot();
+    return Effect.gen(function* () {
+      for (const sql of sqls) yield* unsafe(sql).pipe(Effect.asVoid);
+    }).pipe(Effect.onError(() => Effect.sync(() => restore(snap))));
+  };
+
+  return {
+    unsafe,
+    transaction,
+    statements,
+    databases,
+    roleRows,
+    memberships,
+    membershipOptions,
+    schemas,
+    relationsIn,
+  };
 };

package/src/postgres/fixtures/pg-REL_18_6-acl.h.txt

@@ -0,0 +1,147 @@
+# path: src/include/utils/acl.h
+# blob: 13bb8128747139d9cae66777e4782359ead0a760
+# tag: REL_18_6 (commit 724edf9bde9d356724ad384a2e196edc3c9f80f7)
+# fetched: 2026-09-30 via gh api repos/postgres/postgres/contents/...?ref=724edf9bde9d356724ad384a2e196edc3c9f80f7
+# excerpt: the AclItem struct, the grant-option layout, every ACL_*_CHR letter define and the ACL_ALL_RIGHTS_* sets (lines 40-180 of the full file)
+#
+
+/*
+ * typedef AclMode is declared in parsenodes.h, also the individual privilege
+ * bit meanings are defined there
+ */
+
+#define ACL_ID_PUBLIC	0		/* placeholder for id in a PUBLIC acl item */
+
+/*
+ * AclItem
+ *
+ * Note: must be same size on all platforms, because the size is hardcoded
+ * in the pg_type.h entry for aclitem.
+ */
+typedef struct AclItem
+{
+	Oid			ai_grantee;		/* ID that this item grants privs to */
+	Oid			ai_grantor;		/* grantor of privs */
+	AclMode		ai_privs;		/* privilege bits */
+} AclItem;
+
+/*
+ * The upper 32 bits of the ai_privs field of an AclItem are the grant option
+ * bits, and the lower 32 bits are the actual privileges.  We use "rights"
+ * to mean the combined grant option and privilege bits fields.
+ */
+#define ACLITEM_GET_PRIVS(item)    ((item).ai_privs & 0xFFFFFFFF)
+#define ACLITEM_GET_GOPTIONS(item) (((item).ai_privs >> 32) & 0xFFFFFFFF)
+#define ACLITEM_GET_RIGHTS(item)   ((item).ai_privs)
+
+#define ACL_GRANT_OPTION_FOR(privs) (((AclMode) (privs) & 0xFFFFFFFF) << 32)
+#define ACL_OPTION_TO_PRIVS(privs)	(((AclMode) (privs) >> 32) & 0xFFFFFFFF)
+
+#define ACLITEM_SET_PRIVS(item,privs) \
+  ((item).ai_privs = ((item).ai_privs & ~((AclMode) 0xFFFFFFFF)) | \
+					 ((AclMode) (privs) & 0xFFFFFFFF))
+#define ACLITEM_SET_GOPTIONS(item,goptions) \
+  ((item).ai_privs = ((item).ai_privs & ~(((AclMode) 0xFFFFFFFF) << 32)) | \
+					 (((AclMode) (goptions) & 0xFFFFFFFF) << 32))
+#define ACLITEM_SET_RIGHTS(item,rights) \
+  ((item).ai_privs = (AclMode) (rights))
+
+#define ACLITEM_SET_PRIVS_GOPTIONS(item,privs,goptions) \
+  ((item).ai_privs = ((AclMode) (privs) & 0xFFFFFFFF) | \
+					 (((AclMode) (goptions) & 0xFFFFFFFF) << 32))
+
+
+#define ACLITEM_ALL_PRIV_BITS		((AclMode) 0xFFFFFFFF)
+#define ACLITEM_ALL_GOPTION_BITS	((AclMode) 0xFFFFFFFF << 32)
+
+/*
+ * Definitions for convenient access to Acl (array of AclItem).
+ * These are standard PostgreSQL arrays, but are restricted to have one
+ * dimension and no nulls.  We also ignore the lower bound when reading,
+ * and set it to one when writing.
+ *
+ * CAUTION: as of PostgreSQL 7.1, these arrays are toastable (just like all
+ * other array types).  Therefore, be careful to detoast them with the
+ * macros provided, unless you know for certain that a particular array
+ * can't have been toasted.
+ */
+
+
+/*
+ * Acl			a one-dimensional array of AclItem
+ */
+typedef struct ArrayType Acl;
+
+#define ACL_NUM(ACL)			(ARR_DIMS(ACL)[0])
+#define ACL_DAT(ACL)			((AclItem *) ARR_DATA_PTR(ACL))
+#define ACL_N_SIZE(N)			(ARR_OVERHEAD_NONULLS(1) + ((N) * sizeof(AclItem)))
+#define ACL_SIZE(ACL)			ARR_SIZE(ACL)
+
+/*
+ * fmgr macros for these types
+ */
+#define DatumGetAclItemP(X)		   ((AclItem *) DatumGetPointer(X))
+#define PG_GETARG_ACLITEM_P(n)	   DatumGetAclItemP(PG_GETARG_DATUM(n))
+#define PG_RETURN_ACLITEM_P(x)	   PG_RETURN_POINTER(x)
+
+#define DatumGetAclP(X)			   ((Acl *) PG_DETOAST_DATUM(X))
+#define DatumGetAclPCopy(X)		   ((Acl *) PG_DETOAST_DATUM_COPY(X))
+#define PG_GETARG_ACL_P(n)		   DatumGetAclP(PG_GETARG_DATUM(n))
+#define PG_GETARG_ACL_P_COPY(n)    DatumGetAclPCopy(PG_GETARG_DATUM(n))
+#define PG_RETURN_ACL_P(x)		   PG_RETURN_POINTER(x)
+
+/*
+ * ACL modification opcodes for aclupdate
+ */
+#define ACL_MODECHG_ADD			1
+#define ACL_MODECHG_DEL			2
+#define ACL_MODECHG_EQL			3
+
+/*
+ * External representations of the privilege bits --- aclitemin/aclitemout
+ * represent each possible privilege bit with a distinct 1-character code
+ */
+#define ACL_INSERT_CHR			'a' /* formerly known as "append" */
+#define ACL_SELECT_CHR			'r' /* formerly known as "read" */
+#define ACL_UPDATE_CHR			'w' /* formerly known as "write" */
+#define ACL_DELETE_CHR			'd'
+#define ACL_TRUNCATE_CHR		'D' /* super-delete, as it were */
+#define ACL_REFERENCES_CHR		'x'
+#define ACL_TRIGGER_CHR			't'
+#define ACL_EXECUTE_CHR			'X'
+#define ACL_USAGE_CHR			'U'
+#define ACL_CREATE_CHR			'C'
+#define ACL_CREATE_TEMP_CHR		'T'
+#define ACL_CONNECT_CHR			'c'
+#define ACL_SET_CHR				's'
+#define ACL_ALTER_SYSTEM_CHR	'A'
+#define ACL_MAINTAIN_CHR		'm'
+
+/* string holding all privilege code chars, in order by bitmask position */
+#define ACL_ALL_RIGHTS_STR	"arwdDxtXUCTcsAm"
+
+/*
+ * Bitmasks defining "all rights" for each supported object type
+ */
+#define ACL_ALL_RIGHTS_COLUMN		(ACL_INSERT|ACL_SELECT|ACL_UPDATE|ACL_REFERENCES)
+#define ACL_ALL_RIGHTS_RELATION		(ACL_INSERT|ACL_SELECT|ACL_UPDATE|ACL_DELETE|ACL_TRUNCATE|ACL_REFERENCES|ACL_TRIGGER|ACL_MAINTAIN)
+#define ACL_ALL_RIGHTS_SEQUENCE		(ACL_USAGE|ACL_SELECT|ACL_UPDATE)
+#define ACL_ALL_RIGHTS_DATABASE		(ACL_CREATE|ACL_CREATE_TEMP|ACL_CONNECT)
+#define ACL_ALL_RIGHTS_FDW			(ACL_USAGE)
+#define ACL_ALL_RIGHTS_FOREIGN_SERVER (ACL_USAGE)
+#define ACL_ALL_RIGHTS_FUNCTION		(ACL_EXECUTE)
+#define ACL_ALL_RIGHTS_LANGUAGE		(ACL_USAGE)
+#define ACL_ALL_RIGHTS_LARGEOBJECT	(ACL_SELECT|ACL_UPDATE)
+#define ACL_ALL_RIGHTS_PARAMETER_ACL (ACL_SET|ACL_ALTER_SYSTEM)
+#define ACL_ALL_RIGHTS_SCHEMA		(ACL_USAGE|ACL_CREATE)
+#define ACL_ALL_RIGHTS_TABLESPACE	(ACL_CREATE)
+#define ACL_ALL_RIGHTS_TYPE			(ACL_USAGE)
+
+/* operation codes for pg_*_aclmask */
+typedef enum
+{
+	ACLMASK_ALL,				/* normal case: compute all bits */
+	ACLMASK_ANY,				/* return when result is known nonzero */
+} AclMaskHow;
+
+/* result codes for pg_*_aclcheck */

package/src/postgres/fixtures/pg-REL_18_6-aclexplode-func.txt

@@ -0,0 +1,31 @@
+# path: doc/src/sgml/func.sgml
+# blob: b57f161f53c8833c721dede3d48121490dc15f12
+# tag: REL_18_6 (commit 724edf9bde9d356724ad384a2e196edc3c9f80f7)
+# fetched: 2026-09-30 via gh api repos/postgres/postgres/contents/...?ref=724edf9bde9d356724ad384a2e196edc3c9f80f7
+# excerpt: the aclexplode row of "Access Privilege Inquiry Functions" (lines 25843-25867 of the full file)
+#
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>aclexplode</primary>
+        </indexterm>
+        <function>aclexplode</function> ( <type>aclitem[]</type> )
+        <returnvalue>setof record</returnvalue>
+        ( <parameter>grantor</parameter> <type>oid</type>,
+        <parameter>grantee</parameter> <type>oid</type>,
+        <parameter>privilege_type</parameter> <type>text</type>,
+        <parameter>is_grantable</parameter> <type>boolean</type> )
+       </para>
+       <para>
+        Returns the <type>aclitem</type> array as a set of rows.
+        If the grantee is the pseudo-role PUBLIC, it is represented by zero in
+        the <parameter>grantee</parameter> column.  Each granted privilege is
+        represented as <literal>SELECT</literal>, <literal>INSERT</literal>,
+        etc (see <xref linkend="privilege-abbrevs-table"/> for a full list).
+        Note that each privilege is broken out as a separate row, so
+        only one keyword appears in the <parameter>privilege_type</parameter>
+        column.
+       </para></entry>
+      </row>
+
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">

package/src/postgres/fixtures/pg-REL_18_6-alter-default-privileges-synopsis.txt

@@ -0,0 +1,82 @@
+# path: doc/src/sgml/ref/alter_default_privileges.sgml
+# blob: 6acd0f1df914c6926e6d6f5bd28b0599d66d629c
+# tag: REL_18_6 (commit 724edf9bde9d356724ad384a2e196edc3c9f80f7)
+# fetched: 2026-09-30 via gh api repos/postgres/postgres/contents/...?ref=724edf9bde9d356724ad384a2e196edc3c9f80f7
+# excerpt: the <synopsis> block only (lines 23-98 of the full file), cut per house doc-size convention
+#
+<synopsis>
+ALTER DEFAULT PRIVILEGES
+    [ FOR { ROLE | USER } <replaceable>target_role</replaceable> [, ...] ]
+    [ IN SCHEMA <replaceable>schema_name</replaceable> [, ...] ]
+    <replaceable class="parameter">abbreviated_grant_or_revoke</replaceable>
+
+<phrase>where <replaceable class="parameter">abbreviated_grant_or_revoke</replaceable> is one of:</phrase>
+
+GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER | MAINTAIN }
+    [, ...] | ALL [ PRIVILEGES ] }
+    ON TABLES
+    TO { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT { { USAGE | SELECT | UPDATE }
+    [, ...] | ALL [ PRIVILEGES ] }
+    ON SEQUENCES
+    TO { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT { EXECUTE | ALL [ PRIVILEGES ] }
+    ON { FUNCTIONS | ROUTINES }
+    TO { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT { USAGE | ALL [ PRIVILEGES ] }
+    ON TYPES
+    TO { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT { { USAGE | CREATE }
+    [, ...] | ALL [ PRIVILEGES ] }
+    ON SCHEMAS
+    TO { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+GRANT { { SELECT | UPDATE }
+    [, ...] | ALL [ PRIVILEGES ] }
+    ON LARGE OBJECTS
+    TO { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
+
+REVOKE [ GRANT OPTION FOR ]
+    { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER | MAINTAIN }
+    [, ...] | ALL [ PRIVILEGES ] }
+    ON TABLES
+    FROM { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...]
+    [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+    { { USAGE | SELECT | UPDATE }
+    [, ...] | ALL [ PRIVILEGES ] }
+    ON SEQUENCES
+    FROM { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...]
+    [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+    { EXECUTE | ALL [ PRIVILEGES ] }
+    ON { FUNCTIONS | ROUTINES }
+    FROM { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...]
+    [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+    { USAGE | ALL [ PRIVILEGES ] }
+    ON TYPES
+    FROM { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...]
+    [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+    { { USAGE | CREATE }
+    [, ...] | ALL [ PRIVILEGES ] }
+    ON SCHEMAS
+    FROM { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...]
+    [ CASCADE | RESTRICT ]
+
+REVOKE [ GRANT OPTION FOR ]
+    { { SELECT | UPDATE }
+    [, ...] | ALL [ PRIVILEGES ] }
+    ON LARGE OBJECTS
+    FROM { [ GROUP ] <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...]
+    [ CASCADE | RESTRICT ]
+</synopsis>

package/src/postgres/fixtures/pg-REL_18_6-alter_role.sgml.txt

@@ -0,0 +1,44 @@
+# path: doc/src/sgml/ref/alter_role.sgml
+# blob: 7b0a04bc4637c7c08246e597a9acf4466b467fa2
+# tag: REL_18_6 (commit 724edf9bde9d356724ad384a2e196edc3c9f80f7)
+# fetched: 2026-09-29 via gh api repos/postgres/postgres/contents/...?ref=724edf9bde9d356724ad384a2e196edc3c9f80f7
+# excerpt: the <synopsis> block plus the memberships sentence the GRANT/REVOKE design leans on; blob SHA is the full upstream file
+#
+<synopsis>
+ALTER ROLE <replaceable class="parameter">role_specification</replaceable> [ WITH ] <replaceable class="parameter">option</replaceable> [ ... ]
+
+<phrase>where <replaceable class="parameter">option</replaceable> can be:</phrase>
+
+      SUPERUSER | NOSUPERUSER
+    | CREATEDB | NOCREATEDB
+    | CREATEROLE | NOCREATEROLE
+    | INHERIT | NOINHERIT
+    | LOGIN | NOLOGIN
+    | REPLICATION | NOREPLICATION
+    | BYPASSRLS | NOBYPASSRLS
+    | CONNECTION LIMIT <replaceable class="parameter">connlimit</replaceable>
+    | [ ENCRYPTED ] PASSWORD '<replaceable class="parameter">password</replaceable>' | PASSWORD NULL
+    | VALID UNTIL '<replaceable class="parameter">timestamp</replaceable>'
+
+ALTER ROLE <replaceable class="parameter">name</replaceable> RENAME TO <replaceable>new_name</replaceable>
+
+ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="parameter">database_name</replaceable> ] SET <replaceable>configuration_parameter</replaceable> { TO | = } { <replaceable>value</replaceable> | DEFAULT }
+ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="parameter">database_name</replaceable> ] SET <replaceable>configuration_parameter</replaceable> FROM CURRENT
+ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="parameter">database_name</replaceable> ] RESET <replaceable>configuration_parameter</replaceable>
+ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | ALL } [ IN DATABASE <replaceable class="parameter">database_name</replaceable> ] RESET ALL
+
+<phrase>where <replaceable class="parameter">role_specification</replaceable> can be:</phrase>
+
+    <replaceable class="parameter">role_name</replaceable>
+  | CURRENT_ROLE
+  | CURRENT_USER
+  | SESSION_USER
+</synopsis>
+
+The first variant of this command listed in the synopsis can change
+   many of the role attributes that can be specified in
+   <link linkend="sql-createrole"><command>CREATE ROLE</command></link>.
+   (All the possible attributes are covered,
+   except that there are no options for adding or removing memberships; use
+   <link linkend="sql-grant"><command>GRANT</command></link> and
+   <link linkend="sql-revoke"><command>REVOKE</command></link> for that.)

package/src/postgres/fixtures/pg-REL_18_6-create_role.sgml.txt

@@ -0,0 +1,26 @@
+# path: doc/src/sgml/ref/create_role.sgml
+# blob: cee23b1ea6b4dcf2d9d356d07a582e64808c2912
+# tag: REL_18_6 (commit 724edf9bde9d356724ad384a2e196edc3c9f80f7)
+# fetched: 2026-09-29 via gh api repos/postgres/postgres/contents/...?ref=724edf9bde9d356724ad384a2e196edc3c9f80f7
+# excerpt: the <synopsis> block only (the provenance test reads the option list); blob SHA is the full upstream file
+#
+<synopsis>
+CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replaceable class="parameter">option</replaceable> [ ... ] ]
+
+<phrase>where <replaceable class="parameter">option</replaceable> can be:</phrase>
+
+      SUPERUSER | NOSUPERUSER
+    | CREATEDB | NOCREATEDB
+    | CREATEROLE | NOCREATEROLE
+    | INHERIT | NOINHERIT
+    | LOGIN | NOLOGIN
+    | REPLICATION | NOREPLICATION
+    | BYPASSRLS | NOBYPASSRLS
+    | CONNECTION LIMIT <replaceable class="parameter">connlimit</replaceable>
+    | [ ENCRYPTED ] PASSWORD '<replaceable class="parameter">password</replaceable>' | PASSWORD NULL
+    | VALID UNTIL '<replaceable class="parameter">timestamp</replaceable>'
+    | IN ROLE <replaceable class="parameter">role_name</replaceable> [, ...]
+    | ROLE <replaceable class="parameter">role_name</replaceable> [, ...]
+    | ADMIN <replaceable class="parameter">role_name</replaceable> [, ...]
+    | SYSID <replaceable class="parameter">uid</replaceable>
+</synopsis>