@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/postgres/entities.js

@@ -0,0 +1,1390 @@
+/**
+ * The Postgres entities: `schema`, `table`, `index`, `view`, `sequence`,
+ * `type` (enum, composite and range), `domain`, `extension`, `func`,
+ * `procedure`, `aggregate`, `trigger`, `eventTrigger`, `collation`, `cast`,
+ * `policy`, `role` and `grant` tagged templates that parse their DDL at fold
+ * time into one Declarable each (chant #3278, #3279, #3680, #3681, #3911).
+ *
+ * ```ts
+ * import { schema, table, index } from "@intentius/chant-lexicon-sql/postgres";
+ *
+ * export const app = schema`CREATE SCHEMA app`;
+ * export const users = table`
+ *   CREATE TABLE ${app}.users (
+ *     id    bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+ *     email text NOT NULL UNIQUE
+ *   );
+ *   COMMENT ON TABLE ${app}.users IS 'One row per account'`;
+ * export const usersEmail = index`CREATE INDEX users_email_idx ON ${users} (lower(${users.columns.email}))`;
+ * ```
+ *
+ * The export name is the object's identity in chant; the name in the SQL is
+ * its name in the database. An unquoted name folds to lower case, as Postgres
+ * folds it, so `CREATE TABLE Users` is `users` and `.columns` is keyed by the
+ * folded name.
+ *
+ * What an interpolation means is decided by its value, as for ClickHouse
+ * (#3235):
+ *
+ * - a Postgres entity is a reference to that object and renders as its
+ *   schema-qualified name; a schema renders as its name, so `${app}.users`
+ *   reads `app.users`;
+ * - `entity.columns.<name>` is a reference to one column, and renders as the
+ *   column's name (write `u.${users.columns.id}` in a join);
+ * - a sequence inside `nextval(...)`, `currval(...)` or `setval(...)`, and any
+ *   object followed by `::regclass`, renders as a `regclass` literal:
+ *   `DEFAULT nextval(${ticketSeq})` reads `nextval('app.ticket_seq'::regclass)`,
+ *   which is also how the catalog prints it, and the table depends on the
+ *   sequence;
+ * - a string is SQL text, spliced into the statement before it is parsed;
+ * - a number or bigint is a numeric literal, a boolean `true`/`false`, `null`
+ *   is `NULL`;
+ * - `literal(value)` is a quoted string literal (`'` doubled; a backslash is an
+ *   ordinary character, since standard_conforming_strings is on).
+ *
+ * A function's or procedure's body is a string constant (`AS $$ ... $$`), kept
+ * verbatim. An interpolation inside it renders as text (an object as its
+ * schema-qualified name, a column reference as the column's name) and is
+ * recorded as a reference, so the routine is created after what its body
+ * names: `` func`... AS $$ SELECT count(*) FROM ${users} $$` ``.
+ *
+ * Postgres has no inline comment clause, so a template may follow its CREATE
+ * with `COMMENT ON` statements for the same object, its columns and its
+ * constraints. They fold into the entity's `comment`, each column's and each
+ * constraint's, and stay in the DDL.
+ */
+import { setInterpolationFields } from "@intentius/chant/provenance";
+import { isTrivia, POSTGRES_LEXICAL, SqlSyntaxError, untokenize } from "./tokens.js";
+import { identValue, parseStatements } from "./parser.js";
+import { keywordCategory, quoteIdent } from "./keywords.js";
+import { feed, lineage, spanText as text, splice as spliceWith, templateSyntaxError, unparsedClauses } from "../core/interpolation.js";
+import { SqlObject, isColumnRefOf, isSqlObjectOf, makeSqlEntity } from "../core/entity.js";
+import { SqlLiteral, SqlTemplateError, describeValue as describe, stripUnset, templateParts } from "../core/template.js";
+import { setTypedSlots } from "../core/typed.js";
+export { SQL_LEXICON } from "../core/entity.js";
+export { SqlLiteral, SqlTemplateError } from "../core/template.js";
+export { quoteIdent } from "./keywords.js";
+export { POSTGRES_ENTITY_TYPES } from "./entity-types.js";
+import { POSTGRES_ENTITY_TYPES } from "./entity-types.js";
+/**
+ * A string as a quoted Postgres string literal: `'` doubled, a backslash left
+ * as written (standard_conforming_strings is on). An interpolated plain string
+ * is SQL text; wrap it in `literal()` when it is a value.
+ */
+export function literal(value) {
+    if (value === null)
+        return new SqlLiteral("NULL");
+    if (typeof value !== "string")
+        return new SqlLiteral(String(value));
+    return new SqlLiteral(`'${value.replace(/'/g, "''")}'`);
+}
+// ── Entities ───────────────────────────────────────────────────────────
+/** The members a Postgres entity has besides its props (the shared core's {@link SqlObject}). */
+export class PostgresObject extends SqlObject {
+}
+export function isPostgresObject(value) {
+    return isSqlObjectOf(value, "Postgres::");
+}
+/** A column reference: an AttrRef whose parent is a Postgres table or view. */
+export function isColumnRef(value) {
+    return isColumnRefOf(value, isPostgresObject);
+}
+// ── Rendering interpolations ───────────────────────────────────────────
+function renderReference(value) {
+    if (isPostgresObject(value))
+        return value.sqlName;
+    if (isColumnRef(value))
+        return quoteIdent(value.attribute);
+    throw new TypeError(`not a reference: ${describe(value)}`);
+}
+/** A name as a `regclass` literal's text: `'app.ticket_seq'`. */
+const regclassText = (sqlName) => `'${sqlName.replace(/'/g, "''")}'`;
+/** Functions whose first argument is a `regclass`, written as a string (`nextval('s')`). */
+const REGCLASS_FUNCTIONS = ["NEXTVAL", "CURRVAL", "SETVAL"];
+/**
+ * Interpolations that stand where Postgres wants a `regclass` literal: the
+ * first argument of `nextval`, `currval` or `setval`, rendered
+ * `'name'::regclass`; and an object followed by `::regclass`, rendered
+ * `'name'`. By value index.
+ */
+function regclassPositions(tokens, values) {
+    const out = new Map();
+    const sig = tokens.filter((t) => !isTrivia(t));
+    sig.forEach((t, k) => {
+        if (t.kind !== "ref" || !isPostgresObject(values[t.part]))
+            return;
+        const prev = sig[k - 1];
+        const fn = sig[k - 2];
+        const next = sig[k + 1];
+        if (prev?.kind === "punct" && prev.text === "(" &&
+            fn?.kind === "ident" && REGCLASS_FUNCTIONS.includes(fn.text.toUpperCase()) &&
+            next?.kind === "punct" && (next.text === ")" || next.text === ",")) {
+            out.set(t.part, "call");
+        }
+        else if (next?.kind === "op" && next.text === "::" && sig[k + 2]?.kind === "ident" && sig[k + 2].text.toLowerCase() === "regclass") {
+            out.set(t.part, "cast");
+        }
+    });
+    return out;
+}
+/**
+ * The output name Postgres gives a select-list item with no alias
+ * (`FigureColname` in the parser): a column's name, a function's name, a
+ * cast's operand's name, `case` for a CASE, else `?column?`.
+ */
+function outputOf(items, valueOf) {
+    const sig = items.filter((t) => !isTrivia(t));
+    if (sig.length === 0)
+        return undefined;
+    // `x::type` names its output after `x`.
+    const cast = sig.findIndex((t) => t.kind === "op" && t.text === "::");
+    const head = cast > 0 ? sig.slice(0, cast) : sig;
+    const name = (t) => {
+        if (t.kind === "ident" || t.kind === "qident")
+            return identValue(t);
+        const v = valueOf(t);
+        return isColumnRef(v) ? v.attribute : undefined;
+    };
+    const first = head[0];
+    const last = head[head.length - 1];
+    // A column, bare or qualified: `x`, `t.x`, `${t.columns.x}`, `t.${t.columns.x}`.
+    if (head.length === 1 || (head.length === 3 && head[1].kind === "punct" && head[1].text === ".")) {
+        const n = name(last);
+        if (n !== undefined)
+            return n;
+    }
+    if (first.kind === "ident" && first.text.toUpperCase() === "CASE")
+        return "case";
+    if (first.kind === "ident" && head[1]?.kind === "punct" && head[1].text === "(")
+        return identValue(first);
+    return "?column?";
+}
+/** Postgres as the shared template machinery reads it (`../core/interpolation.ts`). */
+export const POSTGRES_TEMPLATES = {
+    lexical: POSTGRES_LEXICAL,
+    isObject: isPostgresObject,
+    isColumnRef,
+    renderReference,
+    identValue: (t) => identValue(t),
+    unnamedOutput: () => "?column?",
+    lineage: {
+        aliasWithoutAs: true,
+        keyword: (t) => {
+            const k = keywordCategory(t.text);
+            return k === undefined ? undefined : k === "R" ? "reserved" : "keyword";
+        },
+        distinctOn: true,
+        qualifiedRefs: true,
+        outputOf,
+    },
+};
+/** The statements each tag holds. */
+export const STATEMENTS_OF = {
+    schema: ["schema"],
+    table: ["table"],
+    index: ["index"],
+    view: ["view"],
+    sequence: ["sequence"],
+    type: ["enum", "composite", "range"],
+    domain: ["domain"],
+    extension: ["extension"],
+    func: ["function"],
+    procedure: ["procedure"],
+    aggregate: ["aggregate"],
+    trigger: ["trigger"],
+    eventTrigger: ["eventTrigger"],
+    collation: ["collation"],
+    cast: ["cast"],
+    policy: ["policy"],
+    role: ["role"],
+    grant: ["grant"],
+};
+const TAG_OF = {
+    schema: "schema",
+    table: "table",
+    index: "index",
+    view: "view",
+    sequence: "sequence",
+    enum: "type",
+    composite: "type",
+    range: "type",
+    domain: "domain",
+    extension: "extension",
+    function: "func",
+    procedure: "procedure",
+    aggregate: "aggregate",
+    trigger: "trigger",
+    eventTrigger: "eventTrigger",
+    collation: "collation",
+    cast: "cast",
+    policy: "policy",
+    role: "role",
+    grant: "grant",
+    rowSecurity: undefined,
+    comment: undefined,
+};
+/** What each statement kind is called in a message. */
+export const STATEMENT_NAMES = {
+    schema: "CREATE SCHEMA",
+    table: "CREATE TABLE",
+    index: "CREATE INDEX",
+    view: "CREATE VIEW",
+    sequence: "CREATE SEQUENCE",
+    enum: "CREATE TYPE",
+    composite: "CREATE TYPE",
+    range: "CREATE TYPE",
+    domain: "CREATE DOMAIN",
+    extension: "CREATE EXTENSION",
+    function: "CREATE FUNCTION",
+    procedure: "CREATE PROCEDURE",
+    aggregate: "CREATE AGGREGATE",
+    trigger: "CREATE TRIGGER",
+    eventTrigger: "CREATE EVENT TRIGGER",
+    collation: "CREATE COLLATION",
+    cast: "CREATE CAST",
+    policy: "CREATE POLICY",
+    role: "CREATE ROLE",
+    grant: "GRANT",
+    rowSecurity: "ALTER TABLE",
+    comment: "COMMENT ON",
+};
+/** Props without their unset fields and empty optional lists, so props hold only what the DDL says. */
+const strip = (o, keep = []) => Object.fromEntries(Object.entries(stripUnset(o)).filter(([k, v]) => keep.includes(k) || !(Array.isArray(v) && v.length === 0)));
+const req = (s) => s ?? "";
+/** A string constant's value: `'...'`, `E'...'`, `$tag$...$tag$`. */
+export function stringValue(s) {
+    if (s === undefined)
+        return undefined;
+    let m = /^'(.*)'$/s.exec(s);
+    if (m)
+        return m[1].replace(/''/g, "'");
+    m = /^[Ee]'(.*)'$/s.exec(s);
+    if (m)
+        return m[1].replace(/''/g, "'").replace(/\\(.)/gs, (_, c) => ({ n: "\n", t: "\t", r: "\r", b: "\b", f: "\f" })[c] ?? c);
+    m = /^\$([A-Za-z_\u0080-￿][A-Za-z0-9_\u0080-￿]*)?\$(.*)\$\1\$$/s.exec(s);
+    if (m)
+        return m[2];
+    return s;
+}
+/** A definition list's values, by option name: each value as written, interpolations rendered; an option with no value is `true`. */
+function definitionValues(ctx, elems, path) {
+    const out = {};
+    for (const e of elems)
+        out[e.name] = e.value ? req(text(ctx, e.value, path)) : "true";
+    return out;
+}
+/** A qualified name's schema and name. An interpolated schema names the schema; an interpolated object gives both. */
+function qualified(ctx, n) {
+    const pieces = [];
+    const splices = [];
+    for (const t of ctx.tokens.slice(n.span.from, n.span.to)) {
+        if (isTrivia(t) || (t.kind === "punct" && t.text === "."))
+            continue;
+        if (t.kind === "ref") {
+            const v = ctx.values[t.part];
+            if (isPostgresObject(v)) {
+                const p = v.props;
+                if (v.entityType !== POSTGRES_ENTITY_TYPES.schema && v.entityType !== POSTGRES_ENTITY_TYPES.extension && p.schema) {
+                    pieces.push(p.schema);
+                    splices.push(undefined);
+                }
+                pieces.push(p.name);
+                splices.push(undefined);
+            }
+            else {
+                pieces.push(renderReference(v));
+                splices.push(undefined);
+            }
+        }
+        else {
+            pieces.push(identValue(t));
+            splices.push(t.splice);
+        }
+    }
+    const last = pieces.length - 1;
+    splices.forEach((splice, i) => {
+        if (splice !== undefined)
+            ctx.fed[splice].add(i === last ? "name" : "schema");
+    });
+    return pieces.length >= 2 ? { schema: pieces[pieces.length - 2], name: pieces[pieces.length - 1] } : { name: pieces[0] ?? "" };
+}
+const sqlNameOf = (q) => (q.schema ? `${quoteIdent(q.schema)}.${quoteIdent(q.name)}` : quoteIdent(q.name));
+/** The object a name refers to: the entity when the whole name is one interpolation, else its SQL name. */
+function target(ctx, n) {
+    const sig = ctx.tokens.slice(n.span.from, n.span.to).filter((t) => !isTrivia(t));
+    if (sig.length === 1 && sig[0].kind === "ref") {
+        const v = ctx.values[sig[0].part];
+        if (isPostgresObject(v))
+            return v;
+    }
+    return sqlNameOf(qualified(ctx, n));
+}
+/** The SQL name of what a name refers to. */
+const targetName = (ctx, n) => {
+    const t = target(ctx, n);
+    return typeof t === "string" ? t : t.sqlName;
+};
+/** The name of a column in a key or reference list; an interpolated column reference gives its attribute. */
+function columnName(ctx, c) {
+    if (c.name)
+        return c.name;
+    const t = ctx.tokens[c.span.from];
+    const v = t?.kind === "ref" ? ctx.values[t.part] : undefined;
+    return isColumnRef(v) ? v.attribute : req(text(ctx, c.span));
+}
+function columnDef(ctx, c) {
+    for (const span of [c.nameSpan, c.type, c.default, c.collate, c.compression, c.storage, c.generated?.expr, c.generated?.options])
+        feed(ctx, span, "columns");
+    const def = { name: columnName(ctx, { name: c.name, span: c.nameSpan }) };
+    const set = (k, v) => {
+        if (v !== undefined)
+            def[k] = v;
+    };
+    set("type", text(ctx, c.type));
+    set("notNull", c.notNull);
+    set("notNullName", c.notNullName);
+    set("default", text(ctx, c.default));
+    if (c.generated) {
+        def.generated = stripUnset({
+            kind: c.generated.kind,
+            expr: text(ctx, c.generated.expr),
+            always: c.generated.always,
+            options: text(ctx, c.generated.options),
+        });
+        // `always` false is meaningful for an identity column (BY DEFAULT).
+        def.generated.always = c.generated.always;
+    }
+    set("collate", text(ctx, c.collate));
+    set("compression", text(ctx, c.compression));
+    set("storage", text(ctx, c.storage));
+    return def;
+}
+function deferral(c) {
+    return stripUnset({ deferrable: c.deferrable, initiallyDeferred: c.initiallyDeferred });
+}
+function keyDef(ctx, c, columns, path) {
+    return strip({
+        name: c.name,
+        columns,
+        nullsNotDistinct: c.nullsNotDistinct,
+        include: text(ctx, c.include, path),
+        with: text(ctx, c.with, path),
+        ...deferral(c),
+    }, ["columns"]);
+}
+function checkDef(ctx, c) {
+    return stripUnset({
+        name: c.name,
+        expr: req(text(ctx, c.expr, "checks")),
+        noInherit: c.noInherit,
+        notValid: c.notValid,
+        notEnforced: c.notEnforced,
+    });
+}
+function foreignKeyDef(ctx, c, columns) {
+    const r = c.references;
+    feed(ctx, r.table.span, "foreignKeys");
+    for (const x of r.columns)
+        feed(ctx, x.span, "foreignKeys");
+    return strip({
+        name: c.name,
+        columns,
+        references: target(ctx, r.table),
+        refTable: targetName(ctx, r.table),
+        refColumns: r.columns.map((x) => columnName(ctx, x)),
+        match: r.match,
+        onDelete: text(ctx, r.onDelete),
+        onUpdate: text(ctx, r.onUpdate),
+        notValid: c.notValid,
+        notEnforced: c.notEnforced,
+        ...deferral(c),
+    }, ["columns", "refColumns"]);
+}
+/**
+ * The `${}` in a foreign key's referenced column list that each name one
+ * column, paired with the referencing column at the same position (#3751).
+ * `chant sql types` types each as a column comparing like that one.
+ */
+function referenceSlots(ctx, c, columns) {
+    const out = [];
+    c.references.columns.forEach((x, n) => {
+        const column = columns[n];
+        if (x.name || column === undefined)
+            return;
+        const sig = ctx.tokens.slice(x.span.from, x.span.to).filter((t) => !isTrivia(t));
+        const t = sig[0];
+        if (sig.length === 1 && t?.kind === "ref" && isColumnRef(ctx.values[t.part]))
+            out.push({ index: t.part, kind: "references", column });
+    });
+    return out;
+}
+function exclusionDef(ctx, c) {
+    return stripUnset({
+        name: c.name,
+        using: c.using,
+        elements: req(text(ctx, c.expr, "exclusions")),
+        where: text(ctx, c.where, "exclusions"),
+        include: text(ctx, c.include, "exclusions"),
+        with: text(ctx, c.with, "exclusions"),
+        ...deferral(c),
+    });
+}
+/**
+ * Fold the COMMENT ON statements after the CREATE into the object they name:
+ * the object itself, one of its columns, or one of its named constraints.
+ * Anything else is refused, since a template declares one object.
+ */
+function applyComments(tag, ctx, comments, self, objectTypes, parts = {}) {
+    let comment;
+    const isSelf = (q) => q.name === self.name && (q.schema === undefined || self.schema === undefined || q.schema === self.schema);
+    const refuse = (c, why) => {
+        throw new SqlTemplateError(tag, `COMMENT ON ${c.objectType} ${c.target.pieces.filter(Boolean).join(".") || "${...}"} ${why}`, 0, 0);
+    };
+    for (const c of comments) {
+        const value = c.text ? stringValue(text(ctx, c.text, "comment")) : undefined;
+        if (c.objectType === "COLUMN") {
+            // `table.column` or `schema.table.column`: the last piece is the column, the rest its relation.
+            const all = ctx.tokens.slice(c.target.span.from, c.target.span.to).filter((t) => !isTrivia(t) && !(t.kind === "punct" && t.text === "."));
+            const last = all[all.length - 1];
+            const col = last === undefined ? "" : last.kind === "ref" ? columnName(ctx, { name: "", span: { from: c.target.span.to - 1, to: c.target.span.to, refs: [] } }) : identValue(last);
+            if (all.length < 2)
+                refuse(c, "needs the relation: COMMENT ON COLUMN table.column");
+            const owner = qualified(ctx, { pieces: c.target.pieces.slice(0, -1), span: { from: c.target.span.from, to: lastDot(ctx, c.target.span), refs: c.target.span.refs } });
+            if (!isSelf(owner))
+                refuse(c, `is not a column of ${sqlNameOf(self)}`);
+            if (parts.columnComments) {
+                if (value !== undefined)
+                    parts.columnComments[col] = value;
+                continue;
+            }
+            const column = parts.columns?.get(col);
+            if (!column)
+                refuse(c, `names no column of ${sqlNameOf(self)}`);
+            if (value !== undefined)
+                column.comment = value;
+            else
+                delete column.comment;
+        }
+        else if (c.objectType === "CONSTRAINT") {
+            if (!c.on || !isSelf(qualified(ctx, c.on)))
+                refuse(c, `is not on ${sqlNameOf(self)}`);
+            const name = qualified(ctx, c.target).name;
+            const constraint = parts.constraints?.get(name);
+            if (!constraint)
+                refuse(c, `names no constraint of ${sqlNameOf(self)}; a constraint commented on needs CONSTRAINT ${name} in the definition`);
+            if (value !== undefined)
+                constraint.comment = value;
+        }
+        else {
+            if (!objectTypes.includes(c.objectType))
+                refuse(c, `does not comment on the ${tag} this template declares`);
+            if (c.objectType === "CAST") {
+                // `COMMENT ON CAST (source AS target)`: the two types, as the CREATE CAST writes them.
+                const loose = (x) => x.toLowerCase().replace(/\s+/g, " ").replace(/\s*([(),.])\s*/g, "$1");
+                const named = `(${req(text(ctx, c.cast.source))} AS ${req(text(ctx, c.cast.target))})`;
+                if (loose(named) !== loose(self.name))
+                    refuse(c, `names another cast than ${self.name}`);
+            }
+            else if (c.objectType === "TRIGGER" || c.objectType === "POLICY") {
+                // `COMMENT ON TRIGGER name ON table`: the name is the trigger's, the table its own.
+                if (qualified(ctx, c.target).name !== self.name || !c.on || !isSelf({ ...qualified(ctx, c.on), name: self.name }))
+                    refuse(c, `names another ${c.objectType.toLowerCase()} than ${self.name}`);
+            }
+            else if (!isSelf(qualified(ctx, c.target)))
+                refuse(c, `names another object than ${sqlNameOf(self)}`);
+            comment = value;
+        }
+    }
+    return comment;
+}
+/** The token index of the last `.` in a span, so `a.b.c` without its last piece is `a.b`. */
+function lastDot(ctx, span) {
+    for (let i = span.to - 1; i >= span.from; i--) {
+        const t = ctx.tokens[i];
+        if (t.kind === "punct" && t.text === ".")
+            return i;
+    }
+    return span.from;
+}
+/**
+ * The first statement after the CREATE that its template may not hold: a
+ * template is one object, then COMMENT ON statements for it; a table's may
+ * also turn row-level security on or off (`ALTER TABLE ... ENABLE ROW LEVEL
+ * SECURITY`), as `pg_dump` prints it. A grant is one statement.
+ */
+export function followOnStray(tag, rest) {
+    if (tag === "grant")
+        return rest[0];
+    return rest.find((n) => n.statement !== "comment" && !(tag === "table" && n.statement === "rowSecurity"));
+}
+/**
+ * The interpolations that sit inside a string constant (a routine's
+ * `AS $$ ... $$` body), rendered into the text around them: a string
+ * constant is one token, so the template is joined there before it is
+ * tokenized. Returns the joined parts and values, the original index of each
+ * value kept, and the objects the inlined interpolations name.
+ */
+function inlineQuoted(parts, values) {
+    let state = { kind: "none" };
+    const insideAt = [];
+    parts.forEach((src, part) => {
+        for (let i = 0; i < src.length; i++) {
+            const c = src[i];
+            const rest = src.slice(i);
+            switch (state.kind) {
+                case "none": {
+                    if (c === "'")
+                        state = { kind: "single", escapes: /[Ee]$/.test(src.slice(0, i)) && !/[A-Za-z0-9_$][Ee]$/.test(src.slice(0, i)) };
+                    else if (c === '"')
+                        state = { kind: "dquote" };
+                    else if (rest.startsWith("--"))
+                        state = { kind: "line" };
+                    else if (rest.startsWith("/*")) {
+                        state = { kind: "block", depth: 1 };
+                        i++;
+                    }
+                    else if (c === "$" && !/[A-Za-z0-9_$]$/.test(src.slice(0, i))) {
+                        const m = /^\$([A-Za-z_\u0080-\uffff][A-Za-z0-9_\u0080-\uffff]*)?\$/.exec(rest);
+                        if (m) {
+                            state = { kind: "dollar", tag: m[0] };
+                            i += m[0].length - 1;
+                        }
+                    }
+                    break;
+                }
+                case "single":
+                    if (state.escapes && c === "\\")
+                        i++;
+                    else if (c === "'") {
+                        if (src[i + 1] === "'")
+                            i++;
+                        else
+                            state = { kind: "none" };
+                    }
+                    break;
+                case "dquote":
+                    if (c === '"') {
+                        if (src[i + 1] === '"')
+                            i++;
+                        else
+                            state = { kind: "none" };
+                    }
+                    break;
+                case "dollar":
+                    if (rest.startsWith(state.tag)) {
+                        i += state.tag.length - 1;
+                        state = { kind: "none" };
+                    }
+                    break;
+                case "line":
+                    if (c === "\n")
+                        state = { kind: "none" };
+                    break;
+                case "block":
+                    if (rest.startsWith("/*")) {
+                        state.depth++;
+                        i++;
+                    }
+                    else if (rest.startsWith("*/")) {
+                        i++;
+                        state = state.depth === 1 ? { kind: "none" } : { kind: "block", depth: state.depth - 1 };
+                    }
+                    break;
+            }
+        }
+        if (part < parts.length - 1)
+            insideAt.push(state.kind === "single" ? "single" : state.kind === "dollar" ? "dollar" : undefined);
+    });
+    if (!insideAt.some(Boolean))
+        return { parts: [...parts], values: [...values], original: values.map((_, i) => i), inlined: [], refs: [] };
+    const out = [parts[0]];
+    const outValues = [];
+    const original = [];
+    const inlined = [];
+    const refs = [];
+    values.forEach((v, i) => {
+        if (!insideAt[i]) {
+            outValues.push(v);
+            original.push(i);
+            out.push(parts[i + 1]);
+            return;
+        }
+        let text;
+        if (isPostgresObject(v) || isColumnRef(v)) {
+            text = renderReference(v);
+            refs.push(v);
+        }
+        else if (v instanceof SqlLiteral)
+            text = v.sql;
+        else if (v === null)
+            text = "NULL";
+        else if (typeof v === "string" || typeof v === "number" || typeof v === "bigint" || typeof v === "boolean")
+            text = String(v);
+        else
+            throw new SqlTemplateError("func", `the interpolation inside the body is ${describe(v)}; a body takes an object, a column reference, a string or a number`, i, parts[i].length);
+        // Inside a '...' string a quote is doubled.
+        out[out.length - 1] += (insideAt[i] === "single" ? text.replace(/'/g, "''") : text) + parts[i + 1];
+        inlined.push(i);
+    });
+    return { parts: out, values: outValues, original, inlined, refs };
+}
+/** A role named where one is granted to: an interpolated role entity gives its name. */
+function roleName(ctx, r) {
+    if (r.name)
+        return r.name;
+    const t = ctx.tokens[r.span.from];
+    const v = t?.kind === "ref" ? ctx.values[t.part] : undefined;
+    if (isPostgresObject(v))
+        return v.props.name;
+    return identValue(req(text(ctx, r.span)));
+}
+/** A GRANT's, REVOKE's or ALTER DEFAULT PRIVILEGES's props. */
+function grantProps(ctx, node, ddl, source) {
+    const action = node.revoke ? "revoke" : "grant";
+    const grantees = node.grantees.map((g) => roleName(ctx, g));
+    if (node.defaults) {
+        if (node.privileges.some((p) => p.columns.length > 0))
+            throw new SqlTemplateError("grant", "default privileges are on whole objects; a column list is for a grant on one table", 0, 0);
+        const on = (node.on === "ROUTINES" ? "functions" : node.on.toLowerCase());
+        const forRoles = node.forRoles?.map((r) => roleName(ctx, r));
+        const inSchemas = node.inSchemas?.map((s) => columnName(ctx, s));
+        if (on === "schemas" && inSchemas)
+            throw new SqlTemplateError("grant", "default privileges on schemas cannot be limited to a schema (IN SCHEMA)", 0, 0);
+        const privileges = node.privileges.map((p) => p.privilege.toLowerCase());
+        return stripUnset({
+            name: `default privileges ${action === "grant" ? "grant" : "revoke"} ${privileges.join(", ")} on ${on}${inSchemas ? ` in ${inSchemas.join(", ")}` : ""}${forRoles ? ` for ${forRoles.join(", ")}` : ""} ${action === "grant" ? "to" : "from"} ${grantees.join(", ")}`,
+            action,
+            grantOptionFor: node.grantOptionFor || undefined,
+            forRoles,
+            inSchemas,
+            privileges,
+            on,
+            grantees,
+            withGrantOption: node.withGrantOption || undefined,
+            ddl,
+            source,
+        });
+    }
+    const on = (node.on === "TABLE" ? "table" : node.on.toLowerCase());
+    const routine = on === "function" || on === "procedure" || on === "routine";
+    const objects = [];
+    const objectNames = [];
+    for (const o of node.objects) {
+        const t = target(ctx, o.name);
+        objects.push(t);
+        let sqlName = typeof t === "string" ? t : on === "schema" ? t.props.name : t.sqlName;
+        if (routine) {
+            if (o.args)
+                sqlName += `(${req(text(ctx, o.args, "objects")) ?? ""})`;
+            else if (typeof t !== "string" && (t.entityType === POSTGRES_ENTITY_TYPES.function || t.entityType === POSTGRES_ENTITY_TYPES.procedure)) {
+                // An interpolated routine is named by its own parameter types.
+                sqlName += `(${routineArgTypes(t.props)})`;
+            }
+            else
+                throw new SqlTemplateError("grant", `${sqlName}: name the parameter types (${sqlName}(...)), or interpolate the routine, since overloads share a name`, 0, 0);
+        }
+        objectNames.push(sqlName);
+    }
+    const privileges = node.privileges.map((p) => stripUnset({ privilege: p.privilege.toLowerCase(), columns: p.columns.length > 0 ? p.columns.map((c) => columnName(ctx, c)) : undefined }));
+    if (on !== "table" && privileges.some((p) => p.columns))
+        throw new SqlTemplateError("grant", "a column list is for privileges on a table", 0, 0);
+    const verb = action === "grant" ? "to" : "from";
+    return stripUnset({
+        name: `${action} ${privileges.map((p) => `${p.privilege}${p.columns ? `(${p.columns.join(", ")})` : ""}`).join(", ")} on ${on} ${objectNames.join(", ")} ${verb} ${grantees.join(", ")}`,
+        action,
+        grantOptionFor: node.grantOptionFor || undefined,
+        privileges,
+        on,
+        objects,
+        objectNames,
+        grantees,
+        withGrantOption: node.withGrantOption || undefined,
+        ddl,
+        source,
+    });
+}
+/** A routine's parameter types, as `GRANT ... ON FUNCTION f(...)` names it: the `OUT` ones left out. */
+const routineArgTypes = (props) => props.args.filter((a) => a.mode !== "out").map((a) => a.type).join(", ");
+/** The interpolated functions and procedures not followed by their own `(...)`: the ones a grant's statement writes with the parameter types (#3707). */
+function bareRoutineSplices(tokens, values) {
+    const out = new Set();
+    tokens.forEach((t, k) => {
+        if (t.kind !== "ref")
+            return;
+        const v = values[t.part];
+        if (!isPostgresObject(v) || (v.entityType !== POSTGRES_ENTITY_TYPES.function && v.entityType !== POSTGRES_ENTITY_TYPES.procedure))
+            return;
+        const next = tokens.slice(k + 1).find((x) => !isTrivia(x));
+        if (!(next?.kind === "punct" && next.text === "("))
+            out.add(t.part);
+    });
+    return out;
+}
+function build(tag, strings, rawValues) {
+    const rawParts = templateParts(strings);
+    const routine = tag === "func" || tag === "procedure";
+    const joined = routine ? inlineQuoted(rawParts, rawValues) : undefined;
+    const parts = joined ? joined.parts : rawParts;
+    const values = joined ? joined.values : rawValues;
+    const tokens = spliceWith(POSTGRES_TEMPLATES, tag, parts, values);
+    let nodes;
+    try {
+        nodes = parseStatements(tokens);
+    }
+    catch (err) {
+        if (!(err instanceof SqlSyntaxError))
+            throw err;
+        throw templateSyntaxError(tag, parts, err);
+    }
+    const [node, ...rest] = nodes;
+    if (!STATEMENTS_OF[tag].includes(node.statement)) {
+        const holds = STATEMENT_NAMES[node.statement];
+        const use = TAG_OF[node.statement];
+        throw new SqlTemplateError(tag, use
+            ? `holds a ${holds}; use the ${use} tag`
+            : node.statement === "rowSecurity"
+                ? "holds an ALTER TABLE ... ROW LEVEL SECURITY before any CREATE; it goes after the table's CREATE TABLE, in the table's template"
+                : `holds a ${holds} before any CREATE; a COMMENT ON goes after the CREATE it comments on`, 0, 0);
+    }
+    const stray = followOnStray(tag, rest);
+    if (stray) {
+        throw new SqlTemplateError(tag, `holds a second statement (${STATEMENT_NAMES[stray.statement]}); a template declares one object, followed only by COMMENT ON statements for it${tag === "table" ? " and ALTER TABLE ... ROW LEVEL SECURITY" : ""}`, 0, 0);
+    }
+    const comments = rest.filter((n) => n.statement === "comment");
+    const rowSecurity = rest.filter((n) => n.statement === "rowSecurity");
+    const positions = regclassPositions(tokens, values);
+    const bareRoutines = tag === "grant" ? bareRoutineSplices(tokens, values) : new Set();
+    const render = (v, i) => {
+        const at = i === undefined ? undefined : positions.get(i);
+        if (at && isPostgresObject(v))
+            return at === "call" ? `${regclassText(v.sqlName)}::regclass` : regclassText(v.sqlName);
+        // #3707: a routine a grant interpolates is written with its parameter types, so the statement names it on its own.
+        if (i !== undefined && bareRoutines.has(i) && isPostgresObject(v))
+            return `${renderReference(v)}(${routineArgTypes(v.props)})`;
+        return renderReference(v);
+    };
+    const ctx = { d: { ...POSTGRES_TEMPLATES, renderReference: render }, tokens, values, fed: values.map(() => new Set()) };
+    for (const t of tokens)
+        if (t.splice !== undefined)
+            ctx.fed[t.splice].add("ddl");
+    const ddl = untokenize(tokens, (i) => render(values[i], i)).trim().replace(/;\s*$/, "");
+    const source = { strings: rawParts };
+    const dependsOn = [...new Set([...values, ...(joined?.refs ?? [])].filter((v) => isPostgresObject(v) || isColumnRef(v)))];
+    const slots = [];
+    const unparsed = unparsedClauses(ctx, nodes.flatMap((n) => ("unknown" in n && n.unknown ? n.unknown : [])));
+    const make = (type, q, props, columnNames, sqlName = sqlNameOf(q)) => {
+        if (unparsed)
+            props.unparsed = unparsed;
+        const entity = makeSqlEntity(PostgresObject.prototype, type, sqlName, props, columnNames, dependsOn);
+        const fed = ctx.fed.map((paths) => [...paths].sort());
+        if (!joined)
+            setInterpolationFields(entity, fed);
+        else {
+            // Back to the template's own interpolations: one inlined into the body feeds the body.
+            const byOriginal = rawValues.map(() => ["body", "ddl"]);
+            joined.original.forEach((orig, i) => (byOriginal[orig] = fed[i]));
+            setInterpolationFields(entity, byOriginal);
+        }
+        setTypedSlots(entity, slots);
+        return entity;
+    };
+    switch (node.statement) {
+        case "schema": {
+            const q = node.name ? qualified(ctx, node.name) : { name: identValue(req(text(ctx, node.authorization))) };
+            if (q.schema !== undefined)
+                throw new SqlTemplateError(tag, `a schema name is not qualified (${sqlNameOf(q)})`, 0, 0);
+            const comment = applyComments(tag, ctx, comments, q, ["SCHEMA"]);
+            const props = stripUnset({ name: q.name, ifNotExists: node.ifNotExists, authorization: text(ctx, node.authorization, "authorization"), comment, ddl, source });
+            return make(POSTGRES_ENTITY_TYPES.schema, q, props);
+        }
+        case "extension": {
+            const q = qualified(ctx, node.name);
+            const comment = applyComments(tag, ctx, comments, { name: q.name }, ["EXTENSION"]);
+            const schemaRef = node.schema ? text(ctx, node.schema, "schema") : undefined;
+            const props = stripUnset({
+                name: q.name,
+                schema: schemaRef === undefined ? undefined : identValue(schemaRef),
+                version: stringValue(text(ctx, node.version, "version")),
+                cascade: node.cascade,
+                ifNotExists: node.ifNotExists,
+                comment,
+                ddl,
+                source,
+            });
+            return make(POSTGRES_ENTITY_TYPES.extension, { name: q.name }, props);
+        }
+        case "enum": {
+            const q = qualified(ctx, node.name);
+            const comment = applyComments(tag, ctx, comments, q, ["TYPE"]);
+            const props = stripUnset({ ...q, labels: node.labels.map((l) => req(stringValue(text(ctx, l, "labels")))), comment, ddl, source });
+            return make(POSTGRES_ENTITY_TYPES.enum, q, props);
+        }
+        case "composite": {
+            const q = qualified(ctx, node.name);
+            const comment = applyComments(tag, ctx, comments, q, ["TYPE"]);
+            const attributes = node.attributes.map((a) => {
+                feed(ctx, a.nameSpan, "attributes");
+                return stripUnset({ name: columnName(ctx, { name: a.name, span: a.nameSpan }), type: req(text(ctx, a.type, "attributes")), collate: text(ctx, a.collate, "attributes") });
+            });
+            const props = strip({ ...q, attributes, comment, ddl, source }, ["attributes"]);
+            return make(POSTGRES_ENTITY_TYPES.composite, q, props);
+        }
+        case "range": {
+            const q = qualified(ctx, node.name);
+            const comment = applyComments(tag, ctx, comments, q, ["TYPE"]);
+            const opt = definitionValues(ctx, node.options, "options");
+            const props = stripUnset({
+                ...q,
+                subtype: req(opt.subtype),
+                subtypeOpclass: opt.subtype_opclass,
+                collation: opt.collation,
+                canonical: opt.canonical,
+                subtypeDiff: opt.subtype_diff,
+                multirangeTypeName: opt.multirange_type_name,
+                comment,
+                ddl,
+                source,
+            });
+            return make(POSTGRES_ENTITY_TYPES.range, q, props);
+        }
+        case "aggregate": {
+            const q = qualified(ctx, node.name);
+            const comment = applyComments(tag, ctx, comments, q, ["AGGREGATE"]);
+            const arg = (a) => stripUnset({ mode: (a.mode?.toLowerCase() ?? "in"), name: a.name, type: req(text(ctx, a.type, "args")) });
+            const props = strip({
+                ...q,
+                orReplace: node.orReplace || undefined,
+                args: node.args.map(arg),
+                orderBy: node.orderBy?.map(arg),
+                options: definitionValues(ctx, node.options, "options"),
+                comment,
+                ddl,
+                source,
+            }, ["args"]);
+            return make(POSTGRES_ENTITY_TYPES.aggregate, q, props);
+        }
+        case "collation": {
+            const q = qualified(ctx, node.name);
+            const comment = applyComments(tag, ctx, comments, q, ["COLLATION"]);
+            const props = stripUnset({ ...q, ifNotExists: node.ifNotExists || undefined, options: definitionValues(ctx, node.options, "options"), comment, ddl, source });
+            return make(POSTGRES_ENTITY_TYPES.collation, q, props);
+        }
+        case "cast": {
+            const sourceType = req(text(ctx, node.source, "sourceType"));
+            const targetType = req(text(ctx, node.target, "targetType"));
+            const name = `(${sourceType} AS ${targetType})`;
+            const comment = applyComments(tag, ctx, comments, { name }, ["CAST"]);
+            const props = stripUnset({
+                name,
+                sourceType,
+                targetType,
+                method: node.method,
+                function: node.function ? target(ctx, node.function) : undefined,
+                functionName: node.function ? targetName(ctx, node.function) : undefined,
+                functionArgs: node.functionArgs ? text(ctx, node.functionArgs, "functionArgs") : undefined,
+                context: node.context,
+                comment,
+                ddl,
+                source,
+            });
+            return make(POSTGRES_ENTITY_TYPES.cast, { name }, props, undefined, name);
+        }
+        case "eventTrigger": {
+            const name = node.name.pieces[0] || identValue(req(text(ctx, node.name.span)));
+            feed(ctx, node.name.span, "name");
+            const comment = applyComments(tag, ctx, comments, { name }, ["EVENT TRIGGER"]);
+            const tags = node.filters.flatMap((f) => f.values.map((v) => req(stringValue(text(ctx, v, "tags")))));
+            const props = strip({
+                name,
+                event: node.event.name || identValue(req(text(ctx, node.event.span, "event"))),
+                tags: tags.length > 0 ? tags : undefined,
+                function: target(ctx, node.function),
+                functionName: targetName(ctx, node.function),
+                comment,
+                ddl,
+                source,
+            }, []);
+            return make(POSTGRES_ENTITY_TYPES.eventTrigger, { name }, props);
+        }
+        case "domain": {
+            const q = qualified(ctx, node.name);
+            const checks = node.checks.map((c) => stripUnset({ name: c.name, expr: req(text(ctx, c.expr, "checks")), notValid: c.notValid }));
+            const constraints = new Map(checks.filter((c) => c.name !== undefined).map((c) => [c.name, c]));
+            const comment = applyComments(tag, ctx, comments.map((c) => (c.objectType === "DOMAIN CONSTRAINT" ? { ...c, objectType: "CONSTRAINT" } : c)), q, ["DOMAIN", "TYPE"], { constraints });
+            const props = strip({
+                ...q,
+                dataType: req(text(ctx, node.type, "dataType")),
+                collate: text(ctx, node.collate, "collate"),
+                default: text(ctx, node.default, "default"),
+                notNull: node.notNull,
+                checks,
+                comment,
+                ddl,
+                source,
+            }, ["checks"]);
+            return make(POSTGRES_ENTITY_TYPES.domain, q, props);
+        }
+        case "sequence": {
+            const q = qualified(ctx, node.name);
+            const comment = applyComments(tag, ctx, comments, q, ["SEQUENCE"]);
+            const opt = {};
+            for (const o of node.options) {
+                const v = text(ctx, o.value, "options");
+                switch (o.option) {
+                    case "AS":
+                        opt.dataType = v;
+                        break;
+                    case "INCREMENT":
+                        opt.increment = v;
+                        break;
+                    case "MINVALUE":
+                        opt.minValue = v;
+                        break;
+                    case "MAXVALUE":
+                        opt.maxValue = v;
+                        break;
+                    case "NO MINVALUE":
+                        opt.minValue = null;
+                        break;
+                    case "NO MAXVALUE":
+                        opt.maxValue = null;
+                        break;
+                    case "START":
+                        opt.start = v;
+                        break;
+                    case "CACHE":
+                        opt.cache = v;
+                        break;
+                    case "CYCLE":
+                        opt.cycle = true;
+                        break;
+                    case "NO CYCLE":
+                        opt.cycle = false;
+                        break;
+                    case "OWNED BY":
+                        opt.ownedBy = v;
+                        break;
+                    case "LOGGED":
+                    case "UNLOGGED":
+                        break;
+                }
+            }
+            const props = { ...stripUnset({ ...q, persistence: node.persistence, ifNotExists: node.ifNotExists }), ...opt, ...stripUnset({ comment, ddl, source }) };
+            if (opt.cycle === false)
+                props.cycle = false;
+            return make(POSTGRES_ENTITY_TYPES.sequence, q, props);
+        }
+        case "table": {
+            const q = qualified(ctx, node.name);
+            const columns = node.columns.map((c) => columnDef(ctx, c));
+            let primaryKey;
+            const uniques = [];
+            const checks = [];
+            const foreignKeys = [];
+            const exclusions = [];
+            const file = (c, cols) => {
+                if (c.kind === "FOREIGN KEY") {
+                    foreignKeys.push(foreignKeyDef(ctx, c, cols));
+                    slots.push(...referenceSlots(ctx, c, cols));
+                }
+                else if (c.kind === "PRIMARY KEY") {
+                    if (primaryKey)
+                        throw new SqlTemplateError(tag, `${sqlNameOf(q)} declares more than one primary key`, 0, 0);
+                    primaryKey = keyDef(ctx, c, cols, "primaryKey");
+                }
+                else if (c.kind === "UNIQUE")
+                    uniques.push(keyDef(ctx, c, cols, "uniques"));
+                else if (c.kind === "CHECK")
+                    checks.push(checkDef(ctx, c));
+                else if (c.kind === "EXCLUDE")
+                    exclusions.push(exclusionDef(ctx, c));
+                else if (c.kind === "NOT NULL") {
+                    const col = columns.find((x) => x.name === cols[0]);
+                    if (!col)
+                        throw new SqlTemplateError(tag, `NOT NULL ${cols[0]} names no column of ${sqlNameOf(q)}`, 0, 0);
+                    col.notNull = true;
+                    if (c.name)
+                        col.notNullName = c.name;
+                }
+            };
+            node.columns.forEach((c, i) => c.constraints.forEach((k) => file(k, [columns[i].name])));
+            node.constraints.forEach((k) => {
+                // Text spliced into a key's column list feeds the key's columns.
+                const path = k.kind === "PRIMARY KEY" ? "primaryKey.columns" : k.kind === "UNIQUE" ? "uniques" : k.kind === "FOREIGN KEY" ? "foreignKeys" : undefined;
+                if (path)
+                    for (const x of k.columns)
+                        feed(ctx, x.span, path);
+                file(k, k.columns.map((x) => columnName(ctx, x)));
+            });
+            const named = new Map();
+            for (const c of [primaryKey, ...uniques, ...checks, ...foreignKeys, ...exclusions])
+                if (c?.name)
+                    named.set(c.name, c);
+            const comment = applyComments(tag, ctx, comments, q, ["TABLE"], { columns: new Map(columns.map((c) => [c.name, c])), constraints: named });
+            let rls;
+            let force;
+            for (const r of rowSecurity) {
+                const t = qualified(ctx, r.table);
+                if (t.name !== q.name || (t.schema !== undefined && q.schema !== undefined && t.schema !== q.schema)) {
+                    throw new SqlTemplateError(tag, `ALTER TABLE ${sqlNameOf(t)} ... ROW LEVEL SECURITY names another table than ${sqlNameOf(q)}`, 0, 0);
+                }
+                if (r.action === "ENABLE" || r.action === "DISABLE")
+                    rls = r.action === "ENABLE";
+                else
+                    force = r.action === "FORCE";
+            }
+            const props = strip({
+                ...q,
+                persistence: node.persistence,
+                ifNotExists: node.ifNotExists,
+                partitionOf: node.partitionOf ? target(ctx, node.partitionOf) : undefined,
+                partitionBound: text(ctx, node.partitionBound, "partitionBound"),
+                ofType: node.ofType ? target(ctx, node.ofType) : undefined,
+                columns,
+                primaryKey,
+                uniques,
+                checks,
+                foreignKeys,
+                exclusions,
+                like: node.like.map((l) => req(text(ctx, l, "like"))),
+                inherits: (node.inherits ?? []).map((n) => target(ctx, n)),
+                partitionBy: text(ctx, node.partitionBy, "partitionBy"),
+                using: text(ctx, node.using, "using"),
+                with: text(ctx, node.with, "with"),
+                onCommit: text(ctx, node.onCommit),
+                tablespace: text(ctx, node.tablespace, "tablespace"),
+                rowSecurity: rls,
+                forceRowSecurity: force,
+                comment,
+                ddl,
+                source,
+            }, ["columns", "uniques", "checks", "foreignKeys", "exclusions", "like", "inherits"]);
+            if (rls === false)
+                props.rowSecurity = false;
+            if (force === false)
+                props.forceRowSecurity = false;
+            return make(POSTGRES_ENTITY_TYPES.table, q, props, columns.map((c) => c.name));
+        }
+        case "index": {
+            if (!node.name) {
+                throw new SqlTemplateError(tag, "an index needs a name: the name is its identity on the server, and an unnamed index gets a generated one", 0, 0);
+            }
+            const tableTarget = target(ctx, node.table);
+            const tq = qualified(ctx, node.table);
+            const name = node.name.pieces[0] || identValue(req(text(ctx, node.name.span)));
+            feed(ctx, node.name.span, "name");
+            // An index lives in its table's schema.
+            const q = { schema: tq.schema, name };
+            const comment = applyComments(tag, ctx, comments, q, ["INDEX"]);
+            const props = strip({
+                ...q,
+                table: tableTarget,
+                tableName: sqlNameOf(tq),
+                unique: node.unique,
+                concurrently: node.concurrently,
+                ifNotExists: node.ifNotExists,
+                only: node.only,
+                method: node.using,
+                elements: node.elements.map((e) => {
+                    const sig = tokens.slice(e.span.from, e.span.to).filter((t) => !isTrivia(t));
+                    const ref = sig[0]?.kind === "ref" ? values[sig[0].part] : undefined;
+                    const byRef = isColumnRef(ref) && sig.slice(1).every((t) => t.kind === "ident" || t.kind === "qident") ? ref.attribute : undefined;
+                    return stripUnset({ expr: req(text(ctx, e.span, "elements")), column: e.column ?? byRef });
+                }),
+                include: text(ctx, node.include, "include"),
+                nullsNotDistinct: node.nullsNotDistinct,
+                with: text(ctx, node.with, "with"),
+                tablespace: text(ctx, node.tablespace, "tablespace"),
+                where: text(ctx, node.where, "where"),
+                comment,
+                ddl,
+                source,
+            }, ["elements"]);
+            if (node.nullsNotDistinct === false)
+                props.nullsNotDistinct = false;
+            return make(POSTGRES_ENTITY_TYPES.index, q, props);
+        }
+        case "view": {
+            const q = qualified(ctx, node.name);
+            const lin = lineage(ctx, node.query);
+            const declared = node.columnNames.map((c) => columnName(ctx, c));
+            // A declared column list renames the outputs, by position.
+            const edges = lin.edges.map((e, i) => ({ ...e, output: declared[i] ?? e.output }));
+            const outputs = declared.length > 0 ? declared : edges.map((e) => e.output);
+            const columnComments = {};
+            const comment = applyComments(tag, ctx, comments, q, node.materialized ? ["MATERIALIZED VIEW"] : ["VIEW"], { columnComments });
+            const props = strip({
+                ...q,
+                orReplace: node.orReplace,
+                recursive: node.recursive,
+                temporary: node.temporary,
+                ifNotExists: node.ifNotExists,
+                columns: declared,
+                with: text(ctx, node.with, "with"),
+                using: text(ctx, node.using, "using"),
+                tablespace: text(ctx, node.tablespace, "tablespace"),
+                query: req(text(ctx, node.query, "query")),
+                checkOption: text(ctx, node.checkOption, "checkOption"),
+                withData: node.withData,
+                reads: lin.reads,
+                lineage: edges,
+                columnComments: Object.keys(columnComments).length > 0 ? columnComments : undefined,
+                comment,
+                ddl,
+                source,
+            }, ["columns", "reads", "lineage"]);
+            if (node.withData === false)
+                props.withData = false;
+            feed(ctx, node.query, "lineage");
+            return make(node.materialized ? POSTGRES_ENTITY_TYPES.materializedView : POSTGRES_ENTITY_TYPES.view, q, props, outputs);
+        }
+        case "function":
+        case "procedure": {
+            const q = qualified(ctx, node.name);
+            const comment = applyComments(tag, ctx, comments, q, node.statement === "function" ? ["FUNCTION", "ROUTINE"] : ["PROCEDURE", "ROUTINE"]);
+            const flag = (o) => node.options.find((x) => x.option === o)?.flag;
+            const value = (o, path) => {
+                const x = node.options.find((y) => y.option === o);
+                return x?.value ? text(ctx, x.value, path) : undefined;
+            };
+            const set = {};
+            for (const s of node.set)
+                set[s.name] = req(text(ctx, s.value, "set"));
+            const [def, link] = node.body.map((b) => stringValue(text(ctx, b, "body")));
+            const lang = text(ctx, node.language, "language");
+            const props = strip({
+                ...q,
+                orReplace: node.orReplace || undefined,
+                args: node.args.map((a) => stripUnset({
+                    mode: (a.mode?.toLowerCase() ?? "in"),
+                    name: a.name,
+                    type: req(text(ctx, a.type, "args")),
+                    default: text(ctx, a.default, "args"),
+                })),
+                returns: node.returns ? `${node.returns.setof ? "SETOF " : ""}${req(text(ctx, node.returns.type, "returns"))}` : undefined,
+                returnsTable: node.returnsTable?.map((c) => ({ name: c.name, type: req(text(ctx, c.type, "returns")) })),
+                language: lang === undefined ? undefined : lang.startsWith("'") ? stringValue(lang) : identValue(lang),
+                volatility: value("VOLATILITY", "volatility")?.toLowerCase(),
+                strict: flag("STRICT"),
+                securityDefiner: flag("SECURITY"),
+                leakproof: flag("LEAKPROOF"),
+                parallel: value("PARALLEL", "parallel")?.toLowerCase(),
+                cost: value("COST", "cost"),
+                rows: value("ROWS", "rows"),
+                support: value("SUPPORT", "support"),
+                window: flag("WINDOW"),
+                transform: value("TRANSFORM", "transform"),
+                set: Object.keys(set).length > 0 ? set : undefined,
+                body: req(def),
+                link,
+                reads: (joined?.refs ?? []).filter((v) => isPostgresObject(v)),
+                comment,
+                ddl,
+                source,
+            }, ["args", "reads"]);
+            for (const k of ["strict", "securityDefiner", "leakproof"])
+                if (flag(k === "securityDefiner" ? "SECURITY" : k.toUpperCase()) === false)
+                    props[k] = false;
+            return make(node.statement === "function" ? POSTGRES_ENTITY_TYPES.function : POSTGRES_ENTITY_TYPES.procedure, q, props);
+        }
+        case "trigger": {
+            const tq = qualified(ctx, node.table);
+            const name = node.name.pieces[0] || identValue(req(text(ctx, node.name.span)));
+            feed(ctx, node.name.span, "name");
+            // A trigger is its table's: it is named in the table's schema.
+            const q = { schema: tq.schema, name };
+            const comment = applyComments(tag, ctx, comments, q, ["TRIGGER"]);
+            const referencing = {};
+            for (const r of node.referencing)
+                referencing[r.which === "OLD" ? "old" : "new"] = r.name;
+            const props = strip({
+                ...q,
+                orReplace: node.orReplace || undefined,
+                constraint: node.constraint || undefined,
+                timing: node.timing.toLowerCase(),
+                events: node.events.map((e) => {
+                    for (const c of e.columns)
+                        feed(ctx, c.span, "events");
+                    const columns = e.columns.map((c) => columnName(ctx, c));
+                    return { event: e.event.toLowerCase(), ...(columns.length > 0 ? { columns } : {}) };
+                }),
+                table: target(ctx, node.table),
+                tableName: sqlNameOf(tq),
+                from: node.from ? targetName(ctx, node.from) : undefined,
+                deferrable: node.deferrable,
+                initiallyDeferred: node.initiallyDeferred,
+                referencing: Object.keys(referencing).length > 0 ? referencing : undefined,
+                forEach: (node.forEach ?? "STATEMENT").toLowerCase(),
+                when: text(ctx, node.when, "when"),
+                function: target(ctx, node.function),
+                functionName: targetName(ctx, node.function),
+                args: node.args.map((a) => req(text(ctx, a, "args"))),
+                comment,
+                ddl,
+                source,
+            }, ["events", "args"]);
+            return make(POSTGRES_ENTITY_TYPES.trigger, q, props);
+        }
+        case "policy": {
+            const tq = qualified(ctx, node.table);
+            const name = node.name.pieces[0] || identValue(req(text(ctx, node.name.span)));
+            feed(ctx, node.name.span, "name");
+            // A policy is its table's, named in the table's schema.
+            const q = { schema: tq.schema, name };
+            const comment = applyComments(tag, ctx, comments, q, ["POLICY"]);
+            const props = stripUnset({
+                ...q,
+                table: target(ctx, node.table),
+                tableName: sqlNameOf(tq),
+                permissive: node.permissive !== false,
+                command: (node.command ?? "ALL").toLowerCase(),
+                roles: node.roles.length > 0 ? node.roles.map((r) => roleName(ctx, r)) : ["public"],
+                using: text(ctx, node.using, "using"),
+                check: text(ctx, node.check, "check"),
+                comment,
+                ddl,
+                source,
+            });
+            // AS RESTRICTIVE is a false that means something.
+            props.permissive = node.permissive !== false;
+            return make(POSTGRES_ENTITY_TYPES.policy, q, props);
+        }
+        case "role": {
+            const name = node.name.pieces[0] || identValue(req(text(ctx, node.name.span)));
+            feed(ctx, node.name.span, "name");
+            const comment = applyComments(tag, ctx, comments, { name }, ["ROLE"]);
+            const value = (o) => {
+                const x = node.options.find((y) => y.option === o);
+                return x?.value ? text(ctx, x.value, "options") : undefined;
+            };
+            const props = stripUnset({
+                name,
+                options: node.options.filter((o) => o.value === undefined).map((o) => o.option.toLowerCase()),
+                connectionLimit: value("CONNECTION LIMIT"),
+                comment,
+                ddl,
+                source,
+            });
+            return make(POSTGRES_ENTITY_TYPES.role, { name }, props);
+        }
+        case "grant":
+            return make(node.defaults ? POSTGRES_ENTITY_TYPES.defaultPrivileges : POSTGRES_ENTITY_TYPES.grant, { name: "" }, grantProps(ctx, node, ddl, source));
+        case "rowSecurity":
+            throw new SqlTemplateError(tag, "an ALTER TABLE ... ROW LEVEL SECURITY goes after the table's CREATE TABLE, in the table's template", 0, 0);
+        case "comment":
+            throw new SqlTemplateError(tag, "a COMMENT ON goes after the CREATE it comments on", 0, 0);
+    }
+}
+/**
+ * `` schema`CREATE SCHEMA ...` ``: one Postgres schema, parsed at build time.
+ * Given its name as the type argument (`` schema<"shop">`...` ``), a composite
+ * placed in it types its members' columns (chant#3787).
+ */
+export function schema(strings, ...values) {
+    return build("schema", strings, values);
+}
+/**
+ * `` table`CREATE TABLE ...` ``: one Postgres table with its columns and
+ * constraints, parsed at build time. Given its qualified name as the type
+ * argument (`` table<"shop.orders">`...` ``), its columns are the ones
+ * `chant sql types` declared for that name.
+ */
+export function table(strings, ...values) {
+    return build("table", strings, values);
+}
+/** `` index`CREATE [UNIQUE] INDEX [CONCURRENTLY] name ON ...` ``: one named index. */
+export function index(strings, ...values) {
+    return build("index", strings, values);
+}
+/**
+ * `` view`CREATE [MATERIALIZED] VIEW ...` ``: one view or materialized view,
+ * with what it reads and its column lineage. Takes its qualified name as the
+ * type argument, as {@link table} does.
+ */
+export function view(strings, ...values) {
+    return build("view", strings, values);
+}
+/** `` sequence`CREATE SEQUENCE ...` ``: one sequence. Reference it as `nextval(${seq})`. */
+export function sequence(strings, ...values) {
+    return build("sequence", strings, values);
+}
+/**
+ * `` type`CREATE TYPE name AS ENUM (...)` ``: one enum type; `AS (attribute
+ * type, ...)` a composite type, `AS RANGE (SUBTYPE = ...)` a range type (and
+ * its multirange type, which Postgres creates with it).
+ */
+export function type(strings, ...values) {
+    return build("type", strings, values);
+}
+/** `` domain`CREATE DOMAIN ...` ``: one domain. */
+export function domain(strings, ...values) {
+    return build("domain", strings, values);
+}
+/** `` extension`CREATE EXTENSION ...` ``: one extension. */
+export function extension(strings, ...values) {
+    return build("extension", strings, values);
+}
+/**
+ * `` func`CREATE [OR REPLACE] FUNCTION name(args) RETURNS ... LANGUAGE ... AS $$ ... $$` ``:
+ * one function, its body a string kept verbatim. (`function` is a JavaScript
+ * key word, hence `func`.)
+ */
+export function func(strings, ...values) {
+    return build("func", strings, values);
+}
+/** `` procedure`CREATE [OR REPLACE] PROCEDURE name(args) LANGUAGE ... AS $$ ... $$` ``: one procedure. */
+export function procedure(strings, ...values) {
+    return build("procedure", strings, values);
+}
+/**
+ * `` aggregate`CREATE [OR REPLACE] AGGREGATE name(argtype, ...) (SFUNC = ..., STYPE = ...)` ``:
+ * one aggregate, identified, as a function is, by its argument types.
+ */
+export function aggregate(strings, ...values) {
+    return build("aggregate", strings, values);
+}
+/** `` collation`CREATE COLLATION name (provider = icu, locale = '...')` ``: one collation. */
+export function collation(strings, ...values) {
+    return build("collation", strings, values);
+}
+/**
+ * `` cast`CREATE CAST (source AS target) WITH FUNCTION ${fn}(source) [AS ASSIGNMENT | AS IMPLICIT]` ``:
+ * one cast, named by its two types. Creating one takes owning the source or
+ * the target type.
+ */
+export function cast(strings, ...values) {
+    return build("cast", strings, values);
+}
+/**
+ * `` eventTrigger`CREATE EVENT TRIGGER name ON ddl_command_end WHEN TAG IN ('CREATE TABLE') EXECUTE FUNCTION ${fn}()` ``:
+ * one event trigger, the database's (no schema). Creating one takes a superuser.
+ */
+export function eventTrigger(strings, ...values) {
+    return build("eventTrigger", strings, values);
+}
+/** `` trigger`CREATE [OR REPLACE] [CONSTRAINT] TRIGGER name ... ON ${table} ... EXECUTE FUNCTION ${fn}()` ``: one trigger on its table. */
+export function trigger(strings, ...values) {
+    return build("trigger", strings, values);
+}
+/** `` policy`CREATE POLICY name ON ${table} ... USING (...)` ``: one row-level security policy on its table. */
+export function policy(strings, ...values) {
+    return build("policy", strings, values);
+}
+/**
+ * `` role`CREATE ROLE name [WITH] options` ``: a role the schema needs, created
+ * when it is missing. A password and memberships are the environment's and are
+ * refused; a role the environment provisions is named as text where it is
+ * granted to, never declared.
+ */
+export function role(strings, ...values) {
+    return build("role", strings, values);
+}
+/**
+ * `` grant`GRANT ... ON ... TO ...` ``, `REVOKE ... FROM ...`, or
+ * `ALTER DEFAULT PRIVILEGES ... GRANT|REVOKE ...`: privileges on schemas,
+ * tables, columns, sequences and routines, applied where the profile manages
+ * access (`sql.profiles.<env>.access`).
+ */
+export function grant(strings, ...values) {
+    return build("grant", strings, values);
+}