@intentius/chant-lexicon-sql 0.124.30 → 0.124.32

package/dist/postgres/plan/commands.js

@@ -0,0 +1,137 @@
+/**
+ * `chant sql diff` and `chant sql plan` for Postgres: the classified change
+ * between two builds, or between a build and a live server.
+ *
+ * `diff` is offline and needs no server. `plan` reads the server
+ * `sql.profiles.<env>` binds, and asks it about expressions the rules leave
+ * different (`./server-normalize.ts`). Both exit 2 when a change can only be
+ * made as expand and contract, which a plan refuses, and 0 otherwise.
+ */
+import { bindPostgres, loadSqlConfig } from "../live/bind.js";
+import { markProviderOwned, readLiveSchema } from "../live/catalog.js";
+import { scopeFor } from "../live/describe-resources.js";
+import { diffPgSchemas } from "./diff.js";
+import { renderPgDiff } from "./report.js";
+import { keyedByQualifiedName, pgBuildFileMajor, pgSchemaFromBuildFile, pgSchemaFromLive } from "./schema.js";
+import { serverNormalized } from "./server-normalize.js";
+import { POSTGRES_ENTITY_TYPES } from "../entity-types.js";
+import { migrationOpSuggestions } from "../migrate/handoff.js";
+import { POSTGRES_LATEST_MAJOR } from "../../spec/postgres-pin.js";
+import { ACCESS_MANAGED_KINDS } from "./normalize.js";
+import { accessChangesAgainst } from "../access/changes.js";
+export function emitPg(diff, json, title) {
+    console.log(json ? JSON.stringify(diff, null, 2) : renderPgDiff(diff, { title }));
+    return diff.refused.length > 0 ? 2 : 0;
+}
+/** The major the project declares (`sql.postgresMajor`); undefined is the newest pinned one. */
+export async function projectMajor(options = {}) {
+    const config = options.config ?? (await loadSqlConfig(options.cwd ?? process.cwd()));
+    return config?.sql?.postgresMajor;
+}
+/**
+ * Offline, the major is the one the builds recorded (`postgresMajor`): the
+ * newer build's, else the older's, so a diff between revisions does not
+ * depend on today's config. `configMajor` (`sql.postgresMajor`) answers for
+ * builds that recorded none.
+ */
+export function diffPgBuildFiles(before, after, configMajor) {
+    const major = pgBuildFileMajor(after) ?? pgBuildFileMajor(before) ?? configMajor;
+    const head = pgSchemaFromBuildFile(after);
+    return withMigrationOps(diffPgSchemas(pgSchemaFromBuildFile(before), head, { major }), head, "<env>");
+}
+/** The diff with the migration Op to run for each refused column rename or type change (`../migrate/handoff.ts`). */
+export function withMigrationOps(diff, declared, env, defaultSchema = "public") {
+    const migrationOps = migrationOpSuggestions(diff.refused, new Map(declared.map((o) => [o.key, o.canonical])), env, defaultSchema);
+    return migrationOps.length > 0 ? { ...diff, migrationOps } : diff;
+}
+/** The live server's major, from `server_version_num` (`180006` is 18). */
+async function serverMajor(client) {
+    const rows = await client.query("select current_setting('server_version_num') as v");
+    const n = Number(rows[0]?.v);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n / 10000) : undefined;
+}
+const differs = (a, b) => JSON.stringify([a.canonical.fields, a.canonical.columns, a.canonical.constraints]) !== JSON.stringify([b.canonical.fields, b.canonical.columns, b.canonical.constraints]);
+/**
+ * The declared objects (a build's, keyed by export name) against what a
+ * connected server holds: read in the declarations' scope, the server asked
+ * about expressions the rules leave different, then diffed. The plan and the
+ * applier (`../apply/`) share it.
+ */
+export async function planAgainstClient(client, target, build, options = {}) {
+    const managed = target.access === true;
+    const { kept, unmanaged } = accessScoped(keyedByQualifiedName(build), managed);
+    const declaredRaw = kept;
+    const scope = scopeFor(target, declaredRaw.filter((o) => o.canonical.kind !== "role" && o.canonical.kind !== "grant" && o.canonical.kind !== "defaultPrivileges").map((o) => ({ type: POSTGRES_ENTITY_TYPES[o.canonical.kind], props: { name: o.canonical.name, ...(o.canonical.schema ? { schema: o.canonical.schema } : {}) } })));
+    const roles = declaredRaw.filter((o) => o.canonical.kind === "role").map((o) => o.canonical.name);
+    const liveObjects = markProviderOwned(await (options.readLive ?? readLiveSchema)(client, { schemas: scope, access: managed, roles }), target.provider);
+    const live = pgSchemaFromLive(liveObjects, target.defaultSchema);
+    const liveByKey = new Map(live.map((o) => [o.key, o]));
+    const declared = [];
+    for (const o of declaredRaw) {
+        const l = liveByKey.get(o.key);
+        if (l && differs(o, l) && (o.canonical.kind === "table" || o.canonical.kind === "view" || o.canonical.kind === "materializedView" || o.canonical.kind === "trigger" || o.canonical.kind === "policy")) {
+            declared.push({ ...o, canonical: { ...o.canonical, ...(await (options.serverNormalize ?? serverNormalized)(client, o.canonical, target.defaultSchema)) } });
+        }
+        else
+            declared.push(o);
+    }
+    // The build's major, else the server's own when it differs, since the server is what takes the locks.
+    const running = await serverMajor(client).catch(() => undefined);
+    const major = running ?? options.major;
+    const diff = diffPgSchemas(live, declared, { major, access: false });
+    if (managed) {
+        const access = await accessChangesAgainst(client, declared, { major: major ?? POSTGRES_LATEST_MAJOR, ...(scope ? { scope } : {}) });
+        if (access.length > 0) {
+            diff.changes.push(...access.map((a) => a.change));
+            diff.access = access;
+        }
+    }
+    else if (unmanaged > 0) {
+        diff.hints.push(`${unmanaged} access declaration${unmanaged === 1 ? " is" : "s are"} not planned: ${options.environment ?? "this environment"}'s profile does not manage access (sql.profiles.<env>.access)`);
+    }
+    if (running !== undefined && options.major !== undefined && running !== options.major) {
+        diff.hints.push(`the build targets Postgres ${options.major} but ${options.environment ?? "the server"} runs Postgres ${running}; changes are classified for ${running}`);
+    }
+    return { declared, live, liveObjects, diff, ...(major !== undefined ? { major } : {}), ...(scope ? { scope } : {}) };
+}
+/**
+ * The declarations a plan compares: all of them where the profile manages
+ * access; otherwise none of the policies, roles, grants and default
+ * privileges, and no table's row-level security, so a project that manages
+ * access elsewhere is not affected. `unmanaged` counts what was left out.
+ */
+export function accessScoped(objects, managed) {
+    if (managed)
+        return { kept: [...objects], unmanaged: 0 };
+    let unmanaged = 0;
+    const kept = [];
+    for (const o of objects) {
+        if (ACCESS_MANAGED_KINDS.has(o.canonical.kind)) {
+            unmanaged++;
+            continue;
+        }
+        if (o.canonical.kind === "table" && (o.canonical.fields.rowSecurity || o.canonical.fields.forceRowSecurity)) {
+            unmanaged++;
+            const { rowSecurity: _r, forceRowSecurity: _f, ...fields } = o.canonical.fields;
+            kept.push({ ...o, canonical: { ...o.canonical, fields } });
+        }
+        else
+            kept.push(o);
+    }
+    return { kept, unmanaged };
+}
+/** The declared objects against the server, keys by qualified name and labels with the export name. */
+export async function planPgAgainstServer(environment, buildFile, options = {}) {
+    const { target, client } = await bindPostgres({ ...options, environment });
+    try {
+        const targeted = pgBuildFileMajor(buildFile) ?? (await projectMajor(options));
+        const { declared, diff } = await planAgainstClient(client, target, pgSchemaFromBuildFile(buildFile, target.defaultSchema), { ...(targeted !== undefined ? { major: targeted } : {}), environment });
+        const { migrationOps } = withMigrationOps(diff, declared, environment, target.defaultSchema);
+        const label = new Map(declared.map((o) => [o.key, `${o.canonical.exportName} (${o.key.slice(o.key.indexOf(" ") + 1)})`]));
+        const changes = diff.changes.map((c) => ({ ...c, object: label.get(c.object) ?? (c.object.startsWith("acl ") ? c.object.slice(4) : c.object) }));
+        return { changes, hints: diff.hints, refused: changes.filter((c) => c.class === "expand"), ...(migrationOps ? { migrationOps } : {}) };
+    }
+    finally {
+        await client.end();
+    }
+}

package/dist/postgres/plan/deep.js

@@ -0,0 +1,324 @@
+/**
+ * `observeResourcesDeep()` for the Postgres dialect: each declared object's
+ * live definition as a property tree in the declaration's own shape, so
+ * `chant lifecycle diff --live` reports property drift with no false drift.
+ *
+ * The reader parses what the catalog prints for the object (`../live/catalog.ts`)
+ * with the same tag the declaration used, which gives the same props shape.
+ * A field whose canonical form (`./normalize.ts`) equals the declaration's is
+ * written with the declaration's own value, so `timestamptz` and
+ * `timestamp with time zone`, or a constraint the declaration left unnamed and
+ * the name Postgres gave it, do not read as drift; a field that differs keeps
+ * the server's value. `deepNormalizationHooks` prunes what is not a property
+ * of the object (the DDL text, the template source, lineage, reads).
+ */
+import { deepObservation } from "@intentius/chant/deep-observation";
+import { bindPostgres, classifyPostgresFailure } from "../live/bind.js";
+import { liveKey, readLiveSchema } from "../live/catalog.js";
+import { accessUnobserved, declaredAddress, scopeFor } from "../live/describe-resources.js";
+import * as tags from "../entities.js";
+import { POSTGRES_ENTITY_TYPES } from "../entity-types.js";
+import { canonicalPgObject, columnShape, sameConstraint } from "./normalize.js";
+import { serverNormalized } from "./server-normalize.js";
+import { accessChangesAgainst } from "../access/changes.js";
+import { POSTGRES_LATEST_MAJOR } from "../../spec/postgres-pin.js";
+const TAG = {
+    [POSTGRES_ENTITY_TYPES.schema]: tags.schema,
+    [POSTGRES_ENTITY_TYPES.table]: tags.table,
+    [POSTGRES_ENTITY_TYPES.index]: tags.index,
+    [POSTGRES_ENTITY_TYPES.view]: tags.view,
+    [POSTGRES_ENTITY_TYPES.materializedView]: tags.view,
+    [POSTGRES_ENTITY_TYPES.sequence]: tags.sequence,
+    [POSTGRES_ENTITY_TYPES.enum]: tags.type,
+    [POSTGRES_ENTITY_TYPES.composite]: tags.type,
+    [POSTGRES_ENTITY_TYPES.range]: tags.type,
+    [POSTGRES_ENTITY_TYPES.domain]: tags.domain,
+    [POSTGRES_ENTITY_TYPES.aggregate]: tags.aggregate,
+    [POSTGRES_ENTITY_TYPES.collation]: tags.collation,
+    [POSTGRES_ENTITY_TYPES.cast]: tags.cast,
+    [POSTGRES_ENTITY_TYPES.eventTrigger]: tags.eventTrigger,
+    [POSTGRES_ENTITY_TYPES.extension]: tags.extension,
+    [POSTGRES_ENTITY_TYPES.function]: tags.func,
+    [POSTGRES_ENTITY_TYPES.procedure]: tags.procedure,
+    [POSTGRES_ENTITY_TYPES.trigger]: tags.trigger,
+    [POSTGRES_ENTITY_TYPES.policy]: tags.policy,
+    [POSTGRES_ENTITY_TYPES.role]: tags.role,
+    [POSTGRES_ENTITY_TYPES.grant]: tags.grant,
+    [POSTGRES_ENTITY_TYPES.defaultPrivileges]: tags.grant,
+};
+/** The props of what the server printed, parsed with the declaration's tag. */
+export function liveProps(o) {
+    const strings = Object.assign([o.statement], { raw: [o.statement] });
+    return { ...TAG[o.type](strings).props };
+}
+const PROP_OF_FIELD = {
+    comment: ["comment"],
+    authorization: ["authorization"],
+    schema: ["schema"],
+    version: ["version"],
+    labels: ["labels"],
+    dataType: ["dataType"],
+    collate: ["collate"],
+    default: ["default"],
+    notNull: ["notNull"],
+    options: ["dataType", "increment", "minValue", "maxValue", "start", "cache", "cycle"],
+    unlogged: ["persistence"],
+    ownedBy: ["ownedBy"],
+    table: ["table", "tableName"],
+    unique: ["unique"],
+    method: ["method"],
+    elements: ["elements"],
+    include: ["include"],
+    nullsNotDistinct: ["nullsNotDistinct"],
+    with: ["with"],
+    where: ["where"],
+    tablespace: ["tablespace"],
+    query: ["query"],
+    columns: ["columns"],
+    checkOption: ["checkOption"],
+    withData: ["withData"],
+    columnComments: ["columnComments"],
+    partitionBy: ["partitionBy"],
+    partitionOf: ["partitionOf"],
+    partitionBound: ["partitionBound"],
+    inherits: ["inherits"],
+    using: ["using"],
+    args: ["args"],
+    returns: ["returns", "returnsTable"],
+    language: ["language"],
+    body: ["body"],
+    link: ["link"],
+    securityDefiner: ["securityDefiner"],
+    set: ["set"],
+    transform: ["transform"],
+    volatility: ["volatility"],
+    strict: ["strict"],
+    leakproof: ["leakproof"],
+    parallel: ["parallel"],
+    cost: ["cost"],
+    rows: ["rows"],
+    support: ["support"],
+    window: ["window"],
+    constraint: ["constraint"],
+    timing: ["timing"],
+    events: ["events"],
+    forEach: ["forEach"],
+    when: ["when"],
+    function: ["function", "functionName"],
+    from: ["from"],
+    deferrable: ["deferrable"],
+    initiallyDeferred: ["initiallyDeferred"],
+    referencing: ["referencing"],
+    restrictive: ["permissive"],
+    command: ["command"],
+    roles: ["roles"],
+    check: ["check"],
+    attributes: ["options"],
+    connectionLimit: ["connectionLimit"],
+    rowSecurity: ["rowSecurity"],
+    forceRowSecurity: ["forceRowSecurity"],
+    attributeDefs: ["attributes"],
+    subtype: ["subtype"],
+    subtypeOpclass: ["subtypeOpclass"],
+    collation: ["collation"],
+    canonical: ["canonical"],
+    subtypeDiff: ["subtypeDiff"],
+    multirange: ["multirangeTypeName"],
+    definition: ["options"],
+    castMethod: ["method", "functionArgs"],
+    context: ["context"],
+    event: ["event"],
+    tags: ["tags"],
+};
+/** Props keys that hold constraints, by constraint kind. */
+const CONSTRAINT_PROPS = {
+    "PRIMARY KEY": "primaryKey",
+    UNIQUE: "uniques",
+    CHECK: "checks",
+    "FOREIGN KEY": "foreignKeys",
+    EXCLUDE: "exclusions",
+};
+/** The live props, with each field the declaration means the same as written the declaration's way. */
+export function inDeclaredVocabulary(declared, live, d, l) {
+    const out = { ...live };
+    const adopt = (key) => {
+        if (declared[key] === undefined)
+            delete out[key];
+        else
+            out[key] = declared[key];
+    };
+    if (d.name === l.name)
+        adopt("name");
+    if (d.schema === l.schema)
+        adopt("schema");
+    // An aggregate's argument types and a cast's two types are its identity: the same, they are the declaration's.
+    if (d.kind === "aggregate" && d.signature === l.signature)
+        for (const key of ["args", "orderBy"])
+            adopt(key);
+    if (d.kind === "cast" && d.name === l.name)
+        for (const key of ["sourceType", "targetType"])
+            adopt(key);
+    const fieldKeys = new Set([...Object.keys(d.fields), ...Object.keys(l.fields)]);
+    for (const f of fieldKeys) {
+        if (f === "schema" && d.kind !== "extension")
+            continue;
+        if (JSON.stringify(d.fields[f]) !== JSON.stringify(l.fields[f]))
+            continue;
+        for (const key of PROP_OF_FIELD[f] ?? [])
+            adopt(key);
+    }
+    // Fields neither side's canonical form carries (left at their default) are the declaration's too.
+    for (const [f, keys] of Object.entries(PROP_OF_FIELD)) {
+        if (!fieldKeys.has(f))
+            for (const key of keys)
+                if (f !== "schema" || d.kind === "extension")
+                    adopt(key);
+    }
+    if (d.kind === "table") {
+        const declaredColumns = declared.columns ?? [];
+        const liveColumns = live.columns ?? [];
+        // Columns are matched by name and listed in the declaration's order, the
+        // live columns the declaration does not name after them. Postgres keeps a
+        // table's columns in the order they were added, and no ALTER moves one: a
+        // column renamed by expand and contract is last on the server and where
+        // the old one was in the declaration (INTENTIUS/sql-yodeler#47). The plan
+        // compares columns by name too, so an order the server cannot be brought
+        // to is not drift.
+        const read = liveColumns.map((c, i) => {
+            const lc = l.columns[i];
+            const dc = lc ? d.columns.find((x) => x.name === lc.name) : undefined;
+            return { at: dc?.position, value: lc && dc && columnShape(lc) === columnShape(dc) ? declaredColumns[dc.position] : c };
+        });
+        out.columns = [
+            ...read.filter((c) => c.at !== undefined).sort((a, b) => a.at - b.at),
+            ...read.filter((c) => c.at === undefined),
+        ].map((c) => c.value);
+    }
+    // An aggregate's or a collation's `options` is the declaration's only when every field read from it is the same (a role's `options` shares the key).
+    const optionFields = d.kind === "aggregate" ? ["definition"] : d.kind === "collation" ? ["provider", "lcCollate", "lcCtype", "locale", "nondeterministic", "rules"] : undefined;
+    if (optionFields) {
+        if (optionFields.every((f) => JSON.stringify(d.fields[f]) === JSON.stringify(l.fields[f])))
+            adopt("options");
+        else
+            out.options = live.options;
+    }
+    // A cast's `method` shares its key with an index's.
+    if (d.kind === "cast" && JSON.stringify(d.fields.castMethod) !== JSON.stringify(l.fields.castMethod)) {
+        out.method = live.method;
+        out.functionArgs = live.functionArgs;
+    }
+    if (d.kind === "table" || d.kind === "domain") {
+        // A constraint the declaration says the same as the server is the declaration's (its name included or left out).
+        const kinds = d.kind === "domain" ? ["CHECK"] : Object.keys(CONSTRAINT_PROPS);
+        for (const kind of kinds) {
+            const key = CONSTRAINT_PROPS[kind];
+            const dl = d.constraints.filter((c) => c.kind === kind);
+            const ll = l.constraints.filter((c) => c.kind === kind);
+            const all = dl.length === ll.length && dl.every((c) => ll.some((x) => sameConstraint(c, x) && c.notValid === x.notValid && c.comment === x.comment));
+            if (all)
+                adopt(key);
+        }
+    }
+    return out;
+}
+export async function observeResourcesDeep(options) {
+    const resources = {};
+    const unobserved = {};
+    let target;
+    let live;
+    let client;
+    const declared = options.entityNames.map((name) => ({ name, entity: options.entities.get(name) }));
+    try {
+        const bound = await bindPostgres(options);
+        target = bound.target;
+        client = bound.client;
+        try {
+            live = await readLiveSchema(bound.client, {
+                schemas: scopeFor(target, declared.filter((x) => x.entity?.entityType.startsWith("Postgres::")).map((x) => ({ type: x.entity.entityType, props: x.entity.props }))),
+                access: target.access === true,
+                roles: declared.filter((x) => x.entity?.entityType === POSTGRES_ENTITY_TYPES.role).map((x) => String(x.entity.props.name)),
+            });
+        }
+        catch (err) {
+            await bound.client.end();
+            throw err;
+        }
+    }
+    catch (err) {
+        const why = classifyPostgresFailure(err);
+        for (const { name, entity } of declared)
+            unobserved[name] = { type: entity?.entityType ?? "", reason: why.reason, detail: why.detail };
+        return deepObservation({}, unobserved);
+    }
+    const pending = [];
+    try {
+        if (target.access === true) {
+            // #3706: the privilege changes an apply would make, which no one
+            // declaration's properties show, so the plan digest moves with them.
+            try {
+                pending.push(...(await pendingAccess(client, target.defaultSchema, declared, scopeFor(target, declared.filter((x) => x.entity?.entityType.startsWith("Postgres::")).map((x) => ({ type: x.entity.entityType, props: x.entity.props }))))));
+            }
+            catch (err) {
+                for (const { name, entity } of declared) {
+                    if (entity?.entityType === POSTGRES_ENTITY_TYPES.grant || entity?.entityType === POSTGRES_ENTITY_TYPES.defaultPrivileges) {
+                        unobserved[name] = { type: entity.entityType, reason: "read-failed", detail: `the server's privileges could not be compared: ${err.message}` };
+                    }
+                }
+            }
+        }
+        const byKey = new Map(live.map((o) => [liveKey(o.type, o.schema, o.name, o.signature), o]));
+        for (const { name, entity } of declared) {
+            if (!entity || !entity.entityType.startsWith("Postgres::")) {
+                unobserved[name] = { type: entity?.entityType ?? "", reason: "unsupported-kind" };
+                continue;
+            }
+            const why = accessUnobserved(entity.entityType, target.access === true);
+            if (why) {
+                if (unobserved[name])
+                    continue;
+                unobserved[name] = { type: entity.entityType, ...why };
+                continue;
+            }
+            const { schema, name: objectName, signature } = declaredAddress({ type: entity.entityType, props: entity.props }, target.defaultSchema);
+            const o = byKey.get(liveKey(entity.entityType, schema, objectName, signature));
+            if (!o)
+                continue;
+            try {
+                const lp = liveProps(o);
+                let d = canonicalPgObject(entity.entityType, entity.props, target.defaultSchema);
+                const l = canonicalPgObject(o.type, lp, target.defaultSchema);
+                // A trigger's WHEN and a policy's expressions as the server would print them, when the rules leave them different.
+                if ((d.kind === "trigger" && d.fields.when !== l.fields.when) || (d.kind === "policy" && (d.fields.using !== l.fields.using || d.fields.check !== l.fields.check))) {
+                    d = await serverNormalized(client, d, target.defaultSchema);
+                }
+                resources[name] = { type: o.type, physicalId: o.oid, properties: inDeclaredVocabulary(entity.props, lp, d, l) };
+            }
+            catch (err) {
+                unobserved[name] = { type: entity.entityType, reason: "read-failed", detail: `the server's definition does not parse: ${err.message}` };
+            }
+        }
+    }
+    finally {
+        await client.end();
+    }
+    return deepObservation(resources, unobserved, pending);
+}
+/**
+ * The privilege changes an apply would make (#3706), as `chant sql plan`
+ * computes them, one per object and grantee: the statements, and the
+ * declarations behind them.
+ */
+async function pendingAccess(client, defaultSchema, declared, scope) {
+    const objects = declared
+        .filter((x) => x.entity?.entityType.startsWith("Postgres::"))
+        .map((x) => ({ key: x.name, canonical: canonicalPgObject(x.entity.entityType, x.entity.props, defaultSchema) }));
+    const [row] = await client.query("SELECT current_setting('server_version_num') AS v");
+    const n = Number(row?.v);
+    const major = Number.isFinite(n) && n > 0 ? Math.floor(n / 10000) : POSTGRES_LATEST_MAJOR;
+    const changes = await accessChangesAgainst(client, objects, { major, ...(scope ? { scope } : {}) });
+    return changes.map((c) => ({
+        subject: c.change.object.startsWith("acl ") ? c.change.object.slice(4) : c.change.object,
+        change: c.sql.join("; "),
+        ...(c.exports.length > 0 ? { entities: [...c.exports].sort() } : {}),
+    }));
+}