@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/postgres/entity-types.js

@@ -0,0 +1,28 @@
+/**
+ * The Postgres entity types, apart from the tags so generation can name them
+ * before the generated tables the tags read exist.
+ */
+export const POSTGRES_ENTITY_TYPES = {
+    schema: "Postgres::Schema",
+    table: "Postgres::Table",
+    index: "Postgres::Index",
+    view: "Postgres::View",
+    materializedView: "Postgres::MaterializedView",
+    sequence: "Postgres::Sequence",
+    enum: "Postgres::Enum",
+    composite: "Postgres::CompositeType",
+    range: "Postgres::RangeType",
+    domain: "Postgres::Domain",
+    aggregate: "Postgres::Aggregate",
+    collation: "Postgres::Collation",
+    cast: "Postgres::Cast",
+    eventTrigger: "Postgres::EventTrigger",
+    extension: "Postgres::Extension",
+    function: "Postgres::Function",
+    procedure: "Postgres::Procedure",
+    trigger: "Postgres::Trigger",
+    policy: "Postgres::Policy",
+    role: "Postgres::Role",
+    grant: "Postgres::Grant",
+    defaultPrivileges: "Postgres::DefaultPrivileges",
+};

package/dist/postgres/import/generator.js

@@ -0,0 +1,283 @@
+/**
+ * The import IR as TypeScript: one `schema.ts` holding every imported object
+ * as a `schema`, `table`, `index`, `view`, `sequence`, `type`, `domain`,
+ * `extension`, `func`, `aggregate`, `collation`, `cast`, `eventTrigger` (and
+ * the rest of the tags) declaration, in dependency order, with the references between
+ * them interpolated, so the build orders them as the server did:
+ *
+ * - a qualified name of another imported object becomes `${export}`
+ *   (`REFERENCES app.users(id)` is `REFERENCES ${users}(id)`, a type
+ *   `app.order_status` is `${orderStatus}`);
+ * - a sequence named in a `regclass` literal becomes the reference
+ *   (`nextval('app.invoice_seq'::regclass)` is `nextval(${invoiceSeq})`);
+ * - the schema part of the object's own name, wherever the name appears,
+ *   becomes the schema's export (`CREATE TABLE ${appSchema}.users`);
+ * - an extension's `WITH SCHEMA`, a grant's `ON SCHEMA` and default
+ *   privileges' `IN SCHEMA` name the schema's export;
+ * - a grant's object becomes the object's export (`GRANT SELECT ON TABLE
+ *   ${orders} TO reader`), a policy's table its table's.
+ *
+ * Columns stay text, as they do for ClickHouse (#3236): which relation a bare
+ * column belongs to is the server's to resolve. One file, because the
+ * references cross schemas freely.
+ */
+import { relationKey } from "../../core/typed.js";
+import { isTrivia, tokenizeText } from "../tokens.js";
+import { identValue, parseStatements } from "../parser.js";
+import { POSTGRES_ENTITY_TYPES } from "../entity-types.js";
+const TAG = {
+    [POSTGRES_ENTITY_TYPES.schema]: "schema",
+    [POSTGRES_ENTITY_TYPES.table]: "table",
+    [POSTGRES_ENTITY_TYPES.index]: "index",
+    [POSTGRES_ENTITY_TYPES.view]: "view",
+    [POSTGRES_ENTITY_TYPES.materializedView]: "view",
+    [POSTGRES_ENTITY_TYPES.sequence]: "sequence",
+    [POSTGRES_ENTITY_TYPES.enum]: "type",
+    [POSTGRES_ENTITY_TYPES.composite]: "type",
+    [POSTGRES_ENTITY_TYPES.range]: "type",
+    [POSTGRES_ENTITY_TYPES.domain]: "domain",
+    [POSTGRES_ENTITY_TYPES.aggregate]: "aggregate",
+    [POSTGRES_ENTITY_TYPES.collation]: "collation",
+    [POSTGRES_ENTITY_TYPES.cast]: "cast",
+    [POSTGRES_ENTITY_TYPES.eventTrigger]: "eventTrigger",
+    [POSTGRES_ENTITY_TYPES.extension]: "extension",
+    [POSTGRES_ENTITY_TYPES.function]: "func",
+    [POSTGRES_ENTITY_TYPES.procedure]: "procedure",
+    [POSTGRES_ENTITY_TYPES.trigger]: "trigger",
+    [POSTGRES_ENTITY_TYPES.policy]: "policy",
+    [POSTGRES_ENTITY_TYPES.role]: "role",
+    [POSTGRES_ENTITY_TYPES.grant]: "grant",
+    [POSTGRES_ENTITY_TYPES.defaultPrivileges]: "grant",
+};
+/** The kinds no other object's DDL names. */
+const UNREFERENCED = new Set([
+    POSTGRES_ENTITY_TYPES.index,
+    POSTGRES_ENTITY_TYPES.trigger,
+    POSTGRES_ENTITY_TYPES.policy,
+    POSTGRES_ENTITY_TYPES.grant,
+    POSTGRES_ENTITY_TYPES.defaultPrivileges,
+    POSTGRES_ENTITY_TYPES.role,
+    POSTGRES_ENTITY_TYPES.extension,
+    POSTGRES_ENTITY_TYPES.cast,
+    POSTGRES_ENTITY_TYPES.eventTrigger,
+]);
+/** The tag each entity type is declared with (`table`, `func`, ...). */
+export const POSTGRES_TAG_OF = TAG;
+/** Text that sits inside a template literal: a backquote and `${` escaped. */
+const templateSafe = (s) => s.replace(/\\(?=`|\$\{)/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+const isName = (t) => t !== undefined && (t.kind === "ident" || t.kind === "qident");
+/** `'app.invoice_seq'` as the qualified name it holds, or the bare name when unqualified. */
+function regclassName(t) {
+    if (t.kind !== "string" || !/^'.*'$/s.test(t.text))
+        return undefined;
+    const inner = t.text.slice(1, -1).replace(/''/g, "'");
+    const pieces = inner.match(/"(?:[^"]|"")*"|[^.]+/g)?.map((p) => identValue(p)) ?? [];
+    return pieces.length === 2 ? `${pieces[0]}.${pieces[1]}` : pieces.length === 1 ? pieces[0] : undefined;
+}
+/** Words after which a bare name is a relation: `FROM t`, `JOIN t`, `REFERENCES t`. */
+const RELATION_WORDS = new Set(["FROM", "JOIN", "REFERENCES"]);
+/**
+ * The tokens where a bare (unqualified) name is another object's: a column's
+ * or a domain's type, the table of an index, trigger or policy, a trigger's
+ * function, a grant's objects. A `FROM`, `JOIN` or `REFERENCES` before a
+ * name is read off the tokens directly.
+ */
+function bareSpots(tokens) {
+    const out = new Set();
+    let nodes;
+    try {
+        nodes = parseStatements(tokens);
+    }
+    catch {
+        return out;
+    }
+    const first = (from, to) => {
+        for (let i = from; i < to; i++)
+            if (!isTrivia(tokens[i]))
+                return out.add(i);
+        return out;
+    };
+    const name = (n) => n && n.span.to - n.span.from > 0 && first(n.span.from, n.span.to);
+    for (const node of nodes) {
+        if (node.statement === "table")
+            for (const c of node.columns)
+                if (c.type)
+                    first(c.type.from, c.type.to);
+        if (node.statement === "domain")
+            first(node.type.from, node.type.to);
+        if (node.statement === "composite")
+            for (const a of node.attributes)
+                first(a.type.from, a.type.to);
+        if (node.statement === "cast") {
+            first(node.source.from, node.source.to);
+            first(node.target.from, node.target.to);
+            name(node.function);
+        }
+        if (node.statement === "eventTrigger")
+            name(node.function);
+        if (node.statement === "index" || node.statement === "policy")
+            name(node.table);
+        if (node.statement === "trigger") {
+            name(node.table);
+            name(node.function);
+        }
+        if (node.statement === "grant")
+            for (const o of node.objects)
+                name(o.name);
+    }
+    return out;
+}
+function templateBody(item, byQualified, schemaExport) {
+    const tokens = tokenizeText(item.ddl, 0);
+    const sig = [];
+    tokens.forEach((t, i) => {
+        if (!isTrivia(t))
+            sig.push(i);
+    });
+    const spots = bareSpots(tokens);
+    const replace = new Map();
+    const isSelf = (target) => target === item || (target.exportName === item.exportName && target.type === item.type);
+    for (let k = 0; k < sig.length; k++) {
+        const a = tokens[sig[k]];
+        const prev = tokens[sig[k - 1] ?? -1];
+        if (prev?.kind === "punct" && prev.text === ".")
+            continue;
+        // A regclass literal: nextval('app.seq'::regclass) or 'app.t'::regclass.
+        if (a.kind === "string" && tokens[sig[k + 1] ?? -1]?.text === "::" && tokens[sig[k + 2] ?? -1]?.text.toLowerCase() === "regclass") {
+            const held = regclassName(a) ?? "";
+            // An unqualified name is the object in `public`, as the server's own printing has it, else the unqualified object of that name.
+            const target = (!held.includes(".") ? byQualified.get(`public.${held}`) : undefined) ?? byQualified.get(held);
+            if (target && !isSelf(target)) {
+                const fn = tokens[sig[k - 2] ?? -1];
+                const inCall = prev?.text === "(" && fn?.kind === "ident" && /^(nextval|currval|setval)$/i.test(fn.text);
+                replace.set(sig[k], { to: inCall ? sig[k + 2] + 1 : sig[k] + 1, ref: target.exportName });
+                k += inCall ? 2 : 0;
+                continue;
+            }
+        }
+        const dot = tokens[sig[k + 1] ?? -1];
+        const b = tokens[sig[k + 2] ?? -1];
+        if (!isName(a) || dot?.kind !== "punct" || dot.text !== "." || !isName(b)) {
+            // An extension's `WITH SCHEMA app`, a grant's `ON SCHEMA app`, default privileges' `IN SCHEMA app`.
+            const bySchemaWord = item.type === POSTGRES_ENTITY_TYPES.extension || item.type === POSTGRES_ENTITY_TYPES.grant || item.type === POSTGRES_ENTITY_TYPES.defaultPrivileges;
+            if (bySchemaWord && isName(a) && prev?.kind === "ident" && prev.text.toUpperCase() === "SCHEMA") {
+                const s = schemaExport.get(identValue(a));
+                if (s)
+                    replace.set(sig[k], { to: sig[k] + 1, ref: s });
+                continue;
+            }
+            // A bare name where an object is named: `REFERENCES users`, `ON users`, a column of type `status`.
+            const bare = isName(a) && (spots.has(sig[k]) || (prev?.kind === "ident" && RELATION_WORDS.has(prev.text.toUpperCase())));
+            const target = bare ? byQualified.get(identValue(a)) : undefined;
+            if (target && !isSelf(target))
+                replace.set(sig[k], { to: sig[k] + 1, ref: target.exportName });
+            continue;
+        }
+        const schema = identValue(a);
+        const name = identValue(b);
+        const self = schema === item.schema && name === item.name;
+        const target = byQualified.get(`${schema}.${name}`);
+        if (!self && target && !isSelf(target)) {
+            replace.set(sig[k], { to: sig[k + 2] + 1, ref: target.exportName });
+            k += 2;
+        }
+        else if (self && schemaExport.has(schema)) {
+            replace.set(sig[k], { to: sig[k] + 1, ref: schemaExport.get(schema) });
+            k += 2;
+        }
+    }
+    const parts = [""];
+    const refs = [];
+    for (let i = 0; i < tokens.length;) {
+        const r = replace.get(i);
+        if (r) {
+            refs.push(r.ref);
+            parts.push("");
+            i = r.to;
+            continue;
+        }
+        parts[parts.length - 1] += templateSafe(tokens[i].text);
+        i++;
+    }
+    return { parts, refs };
+}
+/** A template body as the text between the backquotes. */
+export const bodyText = (body) => body.parts.map((p, i) => (i === 0 ? p : `\${${body.refs[i - 1]}}${p}`)).join("");
+/**
+ * The template of each object in `items`, with the references to `targets`
+ * (the items themselves, and any object declared elsewhere that they may
+ * name) interpolated, and the items in the order a file declares them: each
+ * after what it references.
+ *
+ * A name is a reference where it is qualified (`app.users`), or bare where an
+ * object is named (`REFERENCES users`, `FROM users`, an index's table, a
+ * column's type) and an unqualified object has that name.
+ */
+export function postgresTemplates(items, targets = items) {
+    const byQualified = new Map();
+    const schemaExport = new Map();
+    for (const it of targets) {
+        if (it.type === POSTGRES_ENTITY_TYPES.schema)
+            schemaExport.set(it.name, it.exportName);
+        // An index, a trigger, a cast or an event trigger is never referenced by name in another object's DDL.
+        else if (!UNREFERENCED.has(it.type)) {
+            byQualified.set(it.schema ? `${it.schema}.${it.name}` : it.name, it);
+        }
+    }
+    const bodies = new Map(items.map((it) => [it.exportName, templateBody(it, byQualified, schemaExport)]));
+    const order = [];
+    const done = new Set();
+    const visiting = new Set();
+    const byExport = new Map(items.map((it) => [it.exportName, it]));
+    const visit = (it) => {
+        if (done.has(it.exportName) || visiting.has(it.exportName))
+            return;
+        visiting.add(it.exportName);
+        for (const ref of bodies.get(it.exportName).refs) {
+            const dep = byExport.get(ref);
+            if (dep)
+                visit(dep);
+        }
+        visiting.delete(it.exportName);
+        done.add(it.exportName);
+        order.push(it);
+    };
+    for (const it of items)
+        visit(it);
+    return { order, bodies };
+}
+const indent = (body) => body
+    .split("\n")
+    .map((l, i) => (i === 0 || l.length === 0 ? l : `  ${l}`))
+    .join("\n");
+const RELATIONS = new Set([POSTGRES_ENTITY_TYPES.table, POSTGRES_ENTITY_TYPES.view, POSTGRES_ENTITY_TYPES.materializedView]);
+/** A table's or view's qualified name as its tag's type argument (#3751), so its columns are typed once `chant sql types` has run. */
+const typeArgument = (it) => (RELATIONS.has(it.type) ? `<${JSON.stringify(relationKey(it))}>` : "");
+export class PostgresGenerator {
+    constructor(header) {
+        this.header = header;
+        this.ownsLayout = true;
+    }
+    generate(ir) {
+        const items = ir.resources
+            .filter((r) => TAG[r.type])
+            .map((r) => ({
+            exportName: r.logicalId,
+            type: r.type,
+            schema: r.properties.schema,
+            name: String(r.properties.name),
+            ddl: String(r.properties.ddl),
+        }));
+        if (items.length === 0)
+            return [];
+        const { order, bodies } = postgresTemplates(items);
+        const tags = [...new Set(order.map((it) => TAG[it.type]))].sort();
+        const lines = [];
+        if (this.header)
+            lines.push(...this.header.split("\n").map((l) => `// ${l}`), "");
+        lines.push(`import { ${tags.join(", ")} } from "@intentius/chant-lexicon-sql/postgres";`, "");
+        for (const it of order)
+            lines.push(`export const ${it.exportName} = ${TAG[it.type]}${typeArgument(it)}\`\n  ${indent(bodyText(bodies.get(it.exportName)))}\`;`, "");
+        return [{ path: "schema.ts", content: `${lines.join("\n").trimEnd()}\n` }];
+    }
+}

package/dist/postgres/import/ir.js

@@ -0,0 +1,53 @@
+/**
+ * Postgres objects into the import IR: one resource per object, the
+ * statements that create it as the server prints them (`../live/catalog.ts`),
+ * and an export name.
+ */
+import { POSTGRES_ENTITY_TYPES } from "../entity-types.js";
+const JS_RESERVED = new Set("break case catch class const continue debugger default delete do else enum export extends false finally for function if import in instanceof new null return super switch this throw true try typeof var void while with yield let static implements interface package private protected public await".split(" "));
+function camel(name) {
+    const words = name.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    if (words.length === 0)
+        return "object";
+    const s = words.map((w, i) => (i === 0 ? w[0].toLowerCase() + w.slice(1) : w[0].toUpperCase() + w.slice(1))).join("");
+    return /^[0-9]/.test(s) ? `o${s}` : s;
+}
+/**
+ * Export names: an object's name in camel case, prefixed with its schema when
+ * two schemas hold the same name; a schema's name with `Schema` after it and
+ * an extension's with `Extension`, so `app` the schema and `app` a table do
+ * not collide.
+ */
+export function exportNames(objects) {
+    const count = new Map();
+    for (const o of objects)
+        if (o.schema)
+            count.set(o.name, (count.get(o.name) ?? 0) + 1);
+    const used = new Set();
+    return objects.map((o) => {
+        let base = o.type === POSTGRES_ENTITY_TYPES.schema
+            ? `${camel(o.name)}Schema`
+            : o.type === POSTGRES_ENTITY_TYPES.extension
+                ? `${camel(o.name)}Extension`
+                : (count.get(o.name) ?? 0) > 1 && o.schema
+                    ? camel(`${o.schema}_${o.name}`)
+                    : camel(o.name);
+        if (JS_RESERVED.has(base))
+            base = `${base}Object`;
+        let name = base;
+        for (let i = 2; used.has(name); i++)
+            name = `${base}${i}`;
+        used.add(name);
+        return name;
+    });
+}
+/** The IR for a set of objects. */
+export function objectsToIR(objects, warnings = []) {
+    const names = exportNames(objects);
+    const resources = objects.map((o, i) => ({
+        logicalId: names[i],
+        type: o.type,
+        properties: { ...(o.schema ? { schema: o.schema } : {}), name: o.name, ddl: o.ddl },
+    }));
+    return { resources, parameters: [], ...(warnings.length ? { warnings } : {}) };
+}

package/dist/postgres/import/live-export.js

@@ -0,0 +1,83 @@
+/**
+ * Live export: `chant import --from <env>` writes a Postgres server's schema as
+ * declarations, each object as the statements the catalog's own printers
+ * give for it (`../live/catalog.ts`), the canonical form.
+ *
+ * - `selector.type` is an entity type (`Postgres::Table`); `selector.name` is
+ *   `name` or `schema.name`.
+ * - `owned` keeps the objects whose comment carries chant's ownership marker.
+ * - Another tool's objects (an ORM's revision table, and its sequence and
+ *   indexes) are left out with a warning naming the tool: they are its, and
+ *   a declaration of them would have chant fight it.
+ * - `verbatim` changes nothing yet: the printers already leave out what the
+ *   server would add by itself.
+ * - Where the profile manages access (`sql.profiles.<env>.access`), the
+ *   policies and each table's row-level security come with the objects, and
+ *   the privileges on them and the default privileges are written as `grant`
+ *   declarations: the GRANT and REVOKE statements that take a new object's
+ *   privileges to what the server holds. Roles are the environment's and are
+ *   not imported.
+ * - An object of a kind no declaration holds (an aggregate, a cast, a
+ *   composite type, an event trigger, ...; `../live/undeclarable.ts`) fails
+ *   the import, which names every one of them (#3911). `skipUndeclarable`
+ *   (`--skip-undeclarable`) imports the rest and lists them as warnings. A
+ *   selector or `owned` import asks for objects chant can hold, so it does
+ *   not look.
+ */
+import { bindPostgres } from "../live/bind.js";
+import { markProviderOwned, readLiveSchema } from "../live/catalog.js";
+import { objectsToIR } from "./ir.js";
+import { isChantManaged } from "../../core/ownership.js";
+import { importedAccess } from "../access/import.js";
+import { readUndeclarable } from "../live/undeclarable.js";
+import { describeUndeclarable, refuseUndeclarable } from "../../core/undeclarable.js";
+import { isProviderOwned, providerData } from "../providers/index.js";
+export async function exportResources(options) {
+    const { target, client } = await bindPostgres(options);
+    let live;
+    let access = [];
+    // A selector or an owned import asks only for what chant can hold.
+    const checked = !options.selector && !options.owned;
+    let undeclarable = { objects: [], unread: [] };
+    try {
+        if (checked)
+            undeclarable = await readUndeclarable(client, { schemas: target.schemas });
+        live = markProviderOwned(await readLiveSchema(client, { schemas: target.schemas, access: target.access === true }), target.provider);
+        // Where the profile manages access, the privileges on what is imported, and the default privileges, as grant declarations.
+        if (target.access === true && !options.selector)
+            access = await importedAccess(client, live.filter((o) => !o.foreign && !o.unsupported && (!options.owned || isChantManaged(o.comment))), target.schemas);
+    }
+    finally {
+        await client.end();
+    }
+    const warnings = undeclarable.unread.map((u) => `the server was not checked for objects of one kind chant cannot declare, so some may be left out: ${u}`);
+    // A managed provider's own (in its schemas, or owned by its roles) is the provider's, as for the objects read below.
+    const provider = target.provider;
+    const providers = (o) => provider !== undefined &&
+        ((o.schema !== undefined && isProviderOwned(provider, { kind: "schema", name: o.schema })) || (o.owner !== undefined && isProviderOwned(provider, { kind: "role", name: o.owner })));
+    for (const o of undeclarable.objects.filter(providers))
+        warnings.push(`${describeUndeclarable(o)} is kept by ${providerData(provider).label}; left out`);
+    refuseUndeclarable("postgres", undeclarable.objects.filter((o) => !providers(o)), options.skipUndeclarable, warnings);
+    const objects = [];
+    for (const o of live) {
+        if (options.owned && !isChantManaged(o.comment))
+            continue;
+        if (options.selector?.type && o.type !== options.selector.type)
+            continue;
+        const name = options.selector?.name;
+        if (name !== undefined && name !== o.name && name !== `${o.schema}.${o.name}`)
+            continue;
+        if (o.unsupported) {
+            // When checked, it is among the undeclarable objects above.
+            if (!checked)
+                warnings.push(`${o.schema ? `${o.schema}.` : ""}${o.name}${o.signature ?? ""} is left out: ${o.unsupported}`);
+            continue;
+        }
+        if (o.foreign) {
+            warnings.push(`${o.schema ? `${o.schema}.` : ""}${o.name} is kept by ${o.foreign}; left out, since declaring it would have chant change what that tool owns`);
+            continue;
+        }
+        objects.push({ type: o.type, ...(o.schema ? { schema: o.schema } : {}), name: o.name, ddl: o.statement });
+    }
+    return objectsToIR([...objects, ...access], warnings);
+}

package/dist/postgres/keywords.js

@@ -0,0 +1,32 @@
+/**
+ * Postgres key words and their categories at the pinned server, as
+ * `pg_get_keywords()` reports them: what decides whether a bare word can be a
+ * name. The parser refuses an unquoted reserved word (`R`) or type/function
+ * name word (`T`) where a column, table or constraint name goes, as Postgres's
+ * `ColId` does, and quoting reads the same table.
+ */
+import { KEYWORDS as GENERATED_KEYWORDS } from "../generated/postgres.js";
+/** Generated from `pg_get_keywords()` at the latest pinned major (`src/spec/postgres-catalog-18.snapshot.json`). */
+const KEYWORDS = GENERATED_KEYWORDS;
+/** A word's key word category, case-insensitively; undefined when it is not a key word. */
+export function keywordCategory(word) {
+    const w = word.toLowerCase();
+    return Object.prototype.hasOwnProperty.call(KEYWORDS, w) ? KEYWORDS[w] : undefined;
+}
+/** Whether `word` is a key word of any category. */
+export const isKeyword = (word) => keywordCategory(word) !== undefined;
+/**
+ * Whether `name` must be double-quoted to read back as itself: anything but a
+ * lower-case identifier, and every key word that is not unreserved (a
+ * `C` word such as `bigint` is a name only where a column name goes).
+ */
+export function needsQuotes(name) {
+    if (!/^[a-z_][a-z0-9_$]*$/.test(name))
+        return true;
+    const k = keywordCategory(name);
+    return k !== undefined && k !== "U";
+}
+/** A name as Postgres reads it back: bare when it can be, double-quoted otherwise. */
+export function quoteIdent(name) {
+    return needsQuotes(name) ? `"${name.replace(/"/g, '""')}"` : name;
+}

package/dist/postgres/live/bind.js

@@ -0,0 +1,130 @@
+/**
+ * Which Postgres server a chant environment reads: the config lookup and the
+ * binding, shared by observation, live export and the plan, so all of them
+ * read the same server.
+ */
+import { connectPostgres, DEFAULT_LOCK_TIMEOUT_MS, PostgresQueryError, withCatalogLockTimeout } from "./client.js";
+import { credentialSource, TokenSourceError } from "../../token-source.js";
+export const isUnresolvedTarget = (v) => "reason" in v;
+/** Whether a URL names a Postgres server. */
+export const isPostgresUrl = (url) => /^postgres(ql)?:\/\//i.test(url);
+/** A URL with any password in it taken out, for a message. */
+export const redactUrl = (url) => url.replace(/^(postgres(?:ql)?:\/\/[^:/@]+):[^@]*@/i, "$1:***@");
+/**
+ * The server an environment reads. Pure: `config` and `env` are passed in.
+ *
+ * 1. `sql.profiles.<environment>` with a `postgres://` URL. A profile naming a
+ *    credential variable that is not set is `no-credentials`.
+ * 2. `POSTGRES_URL`, with `POSTGRES_USER` and `POSTGRES_PASSWORD` when set.
+ * 3. Otherwise `no-binding`.
+ */
+export function resolvePostgresTarget(input) {
+    const env = input.env ?? process.env;
+    const profile = input.environment !== undefined ? input.config?.sql?.profiles?.[input.environment] : undefined;
+    const provider = (profile && isPostgresUrl(profile.url) ? profile.provider : undefined) ?? input.config?.sql?.provider;
+    const withProvider = (t) => (provider ? { ...t, provider } : t);
+    if (profile && isPostgresUrl(profile.url)) {
+        const source = `sql.profiles.${input.environment}`;
+        const endpoint = { url: profile.url };
+        if (profile.user) {
+            const value = env[profile.user.env];
+            if (value === undefined)
+                return { reason: "no-credentials", detail: `${source}.user names ${profile.user.env}, which is not set` };
+            endpoint.user = value;
+        }
+        const password = profile.password;
+        if (password && "env" in password) {
+            const value = env[password.env];
+            if (value === undefined)
+                return { reason: "no-credentials", detail: `${source}.password names ${password.env}, which is not set` };
+            endpoint.password = value;
+        }
+        else if (password) {
+            if (password.token === "rds-iam" && endpoint.user === undefined) {
+                return { reason: "no-credentials", detail: `${source}.password is an rds-iam token, which is minted for one user, and ${source}.user is not set` };
+            }
+            endpoint.token = credentialSource(password, { url: profile.url, ...(endpoint.user !== undefined ? { user: endpoint.user } : {}), env, source: `${source}.password` });
+        }
+        const timeouts = Object.fromEntries(["lockTimeoutMs", "statementTimeoutMs", "scanTimeoutMs"].filter((k) => profile[k] !== undefined).map((k) => [k, profile[k]]));
+        return withProvider({
+            endpoint,
+            source,
+            ...(profile.schemas ? { schemas: profile.schemas } : {}),
+            defaultSchema: profile.defaultSchema ?? "public",
+            ...(Object.keys(timeouts).length > 0 ? { timeouts } : {}),
+            ...(profile.access === true ? { access: true } : {}),
+        });
+    }
+    const url = env.POSTGRES_URL;
+    if (!url) {
+        const where = input.environment !== undefined ? `sql.profiles.${input.environment} names no postgres:// server and ` : "";
+        return { reason: "no-binding", detail: `${where}POSTGRES_URL is not set, so there is no Postgres server to read` };
+    }
+    return withProvider({
+        endpoint: {
+            url,
+            ...(env.POSTGRES_USER !== undefined ? { user: env.POSTGRES_USER } : {}),
+            ...(env.POSTGRES_PASSWORD !== undefined ? { password: env.POSTGRES_PASSWORD } : {}),
+        },
+        source: "env POSTGRES_URL",
+        defaultSchema: "public",
+    });
+}
+/** A target that could not be resolved. */
+export class PostgresBindingError extends Error {
+    constructor(unresolved) {
+        super(unresolved.detail);
+        this.unresolved = unresolved;
+        this.name = "PostgresBindingError";
+    }
+}
+export async function loadSqlConfig(cwd) {
+    try {
+        const { loadChantConfig } = await import("@intentius/chant/config");
+        return (await loadChantConfig(cwd)).config;
+    }
+    catch {
+        // No project config: the environment variables still bind.
+        return undefined;
+    }
+}
+/** Resolve the environment's server. Throws {@link PostgresBindingError} when there is none. */
+export async function resolveBoundTarget(options = {}) {
+    const config = options.config ?? (await loadSqlConfig(options.cwd ?? process.cwd()));
+    const target = resolvePostgresTarget({ environment: options.environment, config, env: options.env });
+    if (isUnresolvedTarget(target))
+        throw new PostgresBindingError(target);
+    return target;
+}
+/**
+ * Resolve the environment's server and connect to it. The caller ends the client.
+ *
+ * The session reads under the profile's `lockTimeoutMs` (the applier's 5000 ms
+ * otherwise): a catalog read blocked behind ACCESS EXCLUSIVE fails with the
+ * relation and the pid that holds it, instead of waiting for as long as the
+ * lock is held.
+ */
+export async function bindPostgres(options = {}) {
+    const target = await resolveBoundTarget(options);
+    const raw = await (options.connect ?? connectPostgres)(target.endpoint);
+    try {
+        return { target, client: await withCatalogLockTimeout(raw, target.timeouts?.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS) };
+    }
+    catch (err) {
+        await raw.end();
+        throw err;
+    }
+}
+/** SQLSTATEs that mean the server refused who we are: invalid_authorization_specification, invalid_password, insufficient_privilege. */
+const CREDENTIAL_STATES = new Set(["28000", "28P01", "42501"]);
+/** What a failed bind or read means, in the observation vocabulary. */
+export function classifyPostgresFailure(err) {
+    if (err instanceof PostgresBindingError)
+        return { reason: err.unresolved.reason, detail: err.unresolved.detail };
+    if (err instanceof TokenSourceError)
+        return { reason: "no-credentials", detail: err.message };
+    if (err instanceof PostgresQueryError && err.code && CREDENTIAL_STATES.has(err.code)) {
+        return { reason: "no-credentials", detail: `${err.message} (the server refused the credentials, SQLSTATE ${err.code})` };
+    }
+    return { reason: "read-failed", detail: err instanceof Error ? err.message.split("\n")[0] : String(err) };
+}