@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.1

package/src/postgres/entity-types.ts

@@ -0,0 +1,18 @@
+/**
+ * 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",
+  domain: "Postgres::Domain",
+  extension: "Postgres::Extension",
+} as const;
+
+export type PostgresEntityType = (typeof POSTGRES_ENTITY_TYPES)[keyof typeof POSTGRES_ENTITY_TYPES];

package/src/postgres/import/generator.ts

@@ -0,0 +1,176 @@
+/**
+ * The import IR as TypeScript: one `schema.ts` holding every imported object
+ * as a `schema`, `table`, `index`, `view`, `sequence`, `type`, `domain` or
+ * `extension` 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` names the schema's export.
+ *
+ * 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 type { GeneratedFile, TypeScriptGenerator } from "@intentius/chant/import/generator";
+import type { TemplateIR } from "@intentius/chant/import/parser";
+import { isTrivia, tokenizeText, type Token } from "../tokens";
+import { identValue } from "../parser";
+import { POSTGRES_ENTITY_TYPES } from "../entity-types";
+
+interface Item {
+  exportName: string;
+  type: string;
+  schema?: string;
+  name: string;
+  ddl: string;
+}
+
+const TAG: Record<string, string> = {
+  [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.domain]: "domain",
+  [POSTGRES_ENTITY_TYPES.extension]: "extension",
+};
+
+/** Text that sits inside a template literal: a backquote and `${` escaped. */
+const templateSafe = (s: string) => s.replace(/\\(?=`|\$\{)/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+
+const isName = (t: Token | undefined) => t !== undefined && (t.kind === "ident" || t.kind === "qident");
+
+/** `'app.invoice_seq'` as the qualified name it holds. */
+function regclassName(t: Token): string | undefined {
+  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 ? `public.${pieces[0]}` : undefined;
+}
+
+function templateBody(item: Item, byQualified: Map<string, Item>, schemaExport: Map<string, string>): { body: string; refs: string[] } {
+  const tokens = tokenizeText(item.ddl, 0);
+  const sig: number[] = [];
+  tokens.forEach((t, i) => {
+    if (!isTrivia(t)) sig.push(i);
+  });
+  const replace = new Map<number, { to: number; text: string; ref: string }>();
+  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 target = byQualified.get(regclassName(a) ?? "");
+      if (target && target !== item) {
+        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, text: `\${${target.exportName}}`, 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`.
+      if (item.type === POSTGRES_ENTITY_TYPES.extension && 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, text: `\${${s}}`, ref: s });
+      }
+      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 && target !== item) {
+      replace.set(sig[k]!, { to: sig[k + 2]! + 1, text: `\${${target.exportName}}`, ref: target.exportName });
+      k += 2;
+    } else if (self && schemaExport.has(schema)) {
+      replace.set(sig[k]!, { to: sig[k]! + 1, text: `\${${schemaExport.get(schema)}}`, ref: schemaExport.get(schema)! });
+      k += 2;
+    }
+  }
+  let body = "";
+  const refs: string[] = [];
+  for (let i = 0; i < tokens.length; ) {
+    const r = replace.get(i);
+    if (r) {
+      body += r.text;
+      refs.push(r.ref);
+      i = r.to;
+      continue;
+    }
+    body += templateSafe(tokens[i]!.text);
+    i++;
+  }
+  return { body, refs };
+}
+
+const indent = (body: string) =>
+  body
+    .split("\n")
+    .map((l, i) => (i === 0 || l.length === 0 ? l : `  ${l}`))
+    .join("\n");
+
+export class PostgresGenerator implements TypeScriptGenerator {
+  readonly ownsLayout = true;
+
+  constructor(private readonly header?: string) {}
+
+  generate(ir: TemplateIR): GeneratedFile[] {
+    const items: Item[] = ir.resources
+      .filter((r) => TAG[r.type])
+      .map((r) => ({
+        exportName: r.logicalId,
+        type: r.type,
+        schema: r.properties.schema as string | undefined,
+        name: String(r.properties.name),
+        ddl: String(r.properties.ddl),
+      }));
+    if (items.length === 0) return [];
+
+    const byQualified = new Map<string, Item>();
+    const schemaExport = new Map<string, string>();
+    for (const it of items) {
+      if (it.type === POSTGRES_ENTITY_TYPES.schema) schemaExport.set(it.name, it.exportName);
+      // An index is never referenced by name in another object's DDL.
+      else if (it.schema && it.type !== POSTGRES_ENTITY_TYPES.index) byQualified.set(`${it.schema}.${it.name}`, it);
+    }
+
+    const bodies = new Map(items.map((it) => [it.exportName, templateBody(it, byQualified, schemaExport)]));
+    const order: Item[] = [];
+    const done = new Set<string>();
+    const visiting = new Set<string>();
+    const byExport = new Map(items.map((it) => [it.exportName, it]));
+    const visit = (it: Item) => {
+      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);
+
+    const tags = [...new Set(order.map((it) => TAG[it.type]!))].sort();
+    const lines: string[] = [];
+    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]}\`\n  ${indent(bodies.get(it.exportName)!.body)}\`;`, "");
+    return [{ path: "schema.ts", content: `${lines.join("\n").trimEnd()}\n` }];
+  }
+}

package/src/postgres/import/import.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "vitest";
+import { exportNames, objectsToIR, type ImportedPgObject } from "./ir";
+import { PostgresGenerator } from "./generator";
+import { sqlTemplateGenerator } from "../../import-generator";
+
+/** What Postgres 18.6 prints for the getting-started example (`../live/catalog.ts`). */
+const PRINTED: ImportedPgObject[] = [
+  { type: "Postgres::Schema", name: "app", ddl: "CREATE SCHEMA app;\nCOMMENT ON SCHEMA app IS 'The shop'" },
+  { type: "Postgres::Enum", schema: "app", name: "order_status", ddl: "CREATE TYPE app.order_status AS ENUM ('placed', 'paid')" },
+  { type: "Postgres::Sequence", schema: "app", name: "invoice_seq", ddl: "CREATE SEQUENCE app.invoice_seq START WITH 1000" },
+  {
+    type: "Postgres::Table",
+    schema: "app",
+    name: "orders",
+    ddl: `CREATE TABLE app.orders (
+    id bigint GENERATED ALWAYS AS IDENTITY,
+    user_id bigint NOT NULL,
+    invoice_no bigint DEFAULT nextval('app.invoice_seq'::regclass) NOT NULL,
+    status app.order_status DEFAULT 'placed'::app.order_status NOT NULL,
+    CONSTRAINT orders_pkey PRIMARY KEY (id),
+    CONSTRAINT orders_user_id_fkey FOREIGN KEY (user_id) REFERENCES app.users(id) ON DELETE CASCADE
+);
+COMMENT ON TABLE app.orders IS 'Placed'`,
+  },
+  {
+    type: "Postgres::Table",
+    schema: "app",
+    name: "users",
+    ddl: "CREATE TABLE app.users (\n    id bigint GENERATED ALWAYS AS IDENTITY,\n    CONSTRAINT users_pkey PRIMARY KEY (id)\n);\nCOMMENT ON COLUMN app.users.id IS 'The key'",
+  },
+  { type: "Postgres::Index", schema: "app", name: "orders_user_id_idx", ddl: "CREATE INDEX orders_user_id_idx ON app.orders USING btree (user_id)" },
+  { type: "Postgres::View", schema: "app", name: "order_totals", ddl: "CREATE VIEW app.order_totals AS\nSELECT u.id,\n    count(o.id) AS n\n   FROM app.users u\n     LEFT JOIN app.orders o ON o.user_id = u.id\n  GROUP BY u.id" },
+  { type: "Postgres::Extension", name: "citext", ddl: "CREATE EXTENSION citext WITH SCHEMA app" },
+];
+
+describe("importing a Postgres server", () => {
+  const content = new PostgresGenerator().generate(objectsToIR(PRINTED))[0]!.content;
+
+  test("export names are camel case, a schema's and an extension's marked as such", () => {
+    expect(exportNames(PRINTED)).toEqual(["appSchema", "orderStatus", "invoiceSeq", "orders", "users", "ordersUserIdIdx", "orderTotals", "citextExtension"]);
+  });
+
+  test("references to imported objects are interpolated, and the file is in dependency order", () => {
+    expect(content).toContain('import { extension, index, schema, sequence, table, type, view } from "@intentius/chant-lexicon-sql/postgres";');
+    expect(content).toContain("CREATE TABLE ${appSchema}.orders (");
+    expect(content).toContain("DEFAULT nextval(${invoiceSeq}) NOT NULL");
+    expect(content).toContain("status ${orderStatus} DEFAULT 'placed'::${orderStatus} NOT NULL");
+    expect(content).toContain("REFERENCES ${users}(id) ON DELETE CASCADE");
+    expect(content).toContain("COMMENT ON TABLE ${appSchema}.orders IS 'Placed'");
+    expect(content).toContain("COMMENT ON COLUMN ${appSchema}.users.id IS 'The key'");
+    expect(content).toContain("CREATE INDEX orders_user_id_idx ON ${orders} USING btree (user_id)");
+    expect(content).toContain("FROM ${users} u");
+    expect(content).toContain("CREATE EXTENSION citext WITH SCHEMA ${appSchema}");
+    const at = (n: string) => content.indexOf(`export const ${n} `);
+    expect(at("users")).toBeLessThan(at("orders"));
+    expect(at("invoiceSeq")).toBeLessThan(at("orders"));
+    expect(at("orders")).toBeLessThan(at("ordersUserIdIdx"));
+    expect(at("appSchema")).toBeLessThan(at("citextExtension"));
+  });
+
+  test("the sql generator sends a Postgres IR to the Postgres generator", () => {
+    expect(sqlTemplateGenerator.generate(objectsToIR(PRINTED))[0]!.content).toBe(content);
+  });
+
+  test("a backquote and ${ in the DDL are escaped for the template", () => {
+    const out = new PostgresGenerator().generate(
+      objectsToIR([{ type: "Postgres::Table", schema: "app", name: "t", ddl: "CREATE TABLE app.t (\n    a text DEFAULT '${x} `y`'::text\n)" }]),
+    )[0]!.content;
+    expect(out).toContain("DEFAULT '\\${x} \\`y\\`'::text");
+  });
+});

package/src/postgres/import/ir.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 type { ResourceIR, TemplateIR } from "@intentius/chant/import/parser";
+import { POSTGRES_ENTITY_TYPES, type PostgresEntityType } from "../entity-types";
+
+export interface ImportedPgObject {
+  type: PostgresEntityType;
+  schema?: string;
+  name: string;
+  /** The CREATE, then any COMMENT ON statements, separated by `;`. */
+  ddl: string;
+}
+
+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: string): string {
+  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: readonly ImportedPgObject[]): string[] {
+  const count = new Map<string, number>();
+  for (const o of objects) if (o.schema) count.set(o.name, (count.get(o.name) ?? 0) + 1);
+  const used = new Set<string>();
+  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: readonly ImportedPgObject[], warnings: string[] = []): TemplateIR {
+  const names = exportNames(objects);
+  const resources: ResourceIR[] = 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/src/postgres/import/live-export.ts

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+
+import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
+import { bindPostgres, type BindOptions } from "../live/bind";
+import { markProviderOwned, readLiveSchema } from "../live/catalog";
+import { objectsToIR, type ImportedPgObject } from "./ir";
+import { isChantManaged } from "../../core/ownership";
+
+export interface ExportOptions extends Omit<BindOptions, "environment"> {
+  environment: string;
+  stack?: string;
+  region?: string;
+  selector?: ResourceSelector;
+  owned?: boolean;
+  verbatim?: boolean;
+}
+
+export async function exportResources(options: ExportOptions): Promise<ExportedTemplate> {
+  const { target, client } = await bindPostgres(options);
+  let live;
+  try {
+    live = markProviderOwned(await readLiveSchema(client, { schemas: target.schemas }), target.provider);
+  } finally {
+    await client.end();
+  }
+  const warnings: string[] = [];
+  const objects: ImportedPgObject[] = [];
+  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.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, warnings) as ExportedTemplate;
+}

package/src/postgres/import/live-warnings.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test, vi } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fakeClient } from "../testing/fake-client";
+import { sqlPlugin } from "../../plugin";
+
+vi.mock("../live/bind", async (orig) => ({
+  ...(await orig<typeof import("../live/bind")>()),
+  bindPostgres: async () => ({
+    target: { endpoint: { url: "postgres://x/db" }, source: "test", defaultSchema: "public" },
+    client: fakeClient({
+      schemas: [{ name: "app" }],
+      tables: [
+        { schema: "public", name: "_prisma_migrations" },
+        { schema: "app", name: "users", columns: [{ name: "id", type: "bigint", notnull: true }] },
+      ],
+    }),
+  }),
+}));
+
+vi.mock("../../live-dialect", async (orig) => ({
+  ...(await orig<typeof import("../../live-dialect")>()),
+  resolveBindingDialect: async () => "postgres",
+}));
+
+describe("a Postgres import prints what it left out (#3336)", () => {
+  test("the ORM table's warning reaches the import result", async () => {
+    const { liveImportFromPlugins } = await import("@intentius/chant/cli/commands/import");
+    const dir = mkdtempSync(join(tmpdir(), "pg-import-warn-"));
+    try {
+      const result = await liveImportFromPlugins([sqlPlugin], {
+        environment: "prod",
+        lexicon: "sql",
+        output: join(dir, "infra"),
+        force: true,
+      });
+      expect(result.error).toBeUndefined();
+      expect(result.success).toBe(true);
+      expect(result.warnings.some((w) => w.includes("_prisma_migrations") && w.includes("Prisma Migrate"))).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/postgres/keywords.ts

@@ -0,0 +1,40 @@
+/**
+ * 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";
+
+/** U unreserved, C column name, T type or function name, R reserved. */
+export type KeywordCategory = "U" | "C" | "T" | "R";
+
+/** Generated from `pg_get_keywords()` at the latest pinned major (`src/spec/postgres-catalog-18.snapshot.json`). */
+const KEYWORDS: Readonly<Record<string, KeywordCategory>> = GENERATED_KEYWORDS;
+
+/** A word's key word category, case-insensitively; undefined when it is not a key word. */
+export function keywordCategory(word: string): KeywordCategory | undefined {
+  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: string): boolean => 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: string): boolean {
+  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: string): string {
+  return needsQuotes(name) ? `"${name.replace(/"/g, '""')}"` : name;
+}

package/src/postgres/live/bind.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 type { ChantConfig } from "@intentius/chant/config";
+import type { UnobservedReason } from "@intentius/chant/observation";
+import { connectPostgres, PostgresQueryError, type PostgresClient, type PostgresEndpoint } from "./client";
+import type { PostgresProvider } from "../providers/types";
+
+export interface PostgresTarget {
+  endpoint: PostgresEndpoint;
+  /** Where the binding came from: `sql.profiles.prod` or `env POSTGRES_URL`. */
+  source: string;
+  /** The schemas in scope; undefined is every schema but the server's own. */
+  schemas?: string[];
+  /** The schema an unqualified declaration lives in. */
+  defaultSchema: string;
+  /** The managed service the server runs on (`sql.profiles.<env>.provider`, else `sql.provider`); its own objects read as foreign. */
+  provider?: PostgresProvider;
+  /** The apply's timeouts the profile sets (`lockTimeoutMs`, `statementTimeoutMs`, `scanTimeoutMs`); the applier's defaults otherwise. */
+  timeouts?: { lockTimeoutMs?: number; statementTimeoutMs?: number; scanTimeoutMs?: number };
+}
+
+export interface UnresolvedTarget {
+  reason: "no-binding" | "no-credentials";
+  detail: string;
+}
+
+export const isUnresolvedTarget = (v: PostgresTarget | UnresolvedTarget): v is UnresolvedTarget => "reason" in v;
+
+/** Whether a URL names a Postgres server. */
+export const isPostgresUrl = (url: string): boolean => /^postgres(ql)?:\/\//i.test(url);
+
+/** A URL with any password in it taken out, for a message. */
+export const redactUrl = (url: string): string => 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: {
+  environment?: string;
+  config?: Pick<ChantConfig, "sql">;
+  env?: Record<string, string | undefined>;
+}): PostgresTarget | UnresolvedTarget {
+  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 extends object>(t: T): T => (provider ? { ...t, provider } : t);
+  if (profile && isPostgresUrl(profile.url)) {
+    const source = `sql.profiles.${input.environment}`;
+    const endpoint: PostgresEndpoint = { url: profile.url };
+    for (const key of ["user", "password"] as const) {
+      const ref = profile[key];
+      if (!ref) continue;
+      const value = env[ref.env];
+      if (value === undefined) return { reason: "no-credentials", detail: `${source}.${key} names ${ref.env}, which is not set` };
+      endpoint[key] = value;
+    }
+    const timeouts = Object.fromEntries(
+      (["lockTimeoutMs", "statementTimeoutMs", "scanTimeoutMs"] as const).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 } : {}),
+    });
+  }
+  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(readonly unresolved: UnresolvedTarget) {
+    super(unresolved.detail);
+    this.name = "PostgresBindingError";
+  }
+}
+
+export interface BindOptions {
+  environment?: string;
+  /** The project's config; loaded from `cwd` when omitted. */
+  config?: Pick<ChantConfig, "sql">;
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  /** Connect with this instead of node-postgres (tests). */
+  connect?: (endpoint: PostgresEndpoint) => Promise<PostgresClient>;
+}
+
+export async function loadSqlConfig(cwd: string): Promise<Pick<ChantConfig, "sql"> | undefined> {
+  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: BindOptions = {}): Promise<PostgresTarget> {
+  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. */
+export async function bindPostgres(options: BindOptions = {}): Promise<{ target: PostgresTarget; client: PostgresClient }> {
+  const target = await resolveBoundTarget(options);
+  const client = await (options.connect ?? connectPostgres)(target.endpoint);
+  return { target, client };
+}
+
+/** 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: unknown): { reason: UnobservedReason; detail: string } {
+  if (err instanceof PostgresBindingError) return { reason: err.unresolved.reason, detail: err.unresolved.detail };
+  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) };
+}