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

package/src/op/activities/postgres-apply.test.ts

@@ -0,0 +1,304 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { describeApplyConformance } from "@intentius/chant-test-utils";
+import { normalizeApply } from "@intentius/chant/apply";
+import { buildMajor, postgresApply, type PostgresApplyArgs, type PostgresApplyDeps } from "./postgres-apply";
+import { toApplyResult } from "./index";
+import { writablePostgres, type StoredPgObject, type WritablePostgres } from "../../postgres/testing/writable-server";
+import { PostgresApplyError } from "../../postgres/apply/apply";
+
+const dirs: string[] = [];
+afterAll(() => {
+  for (const d of dirs) rmSync(d, { recursive: true, force: true });
+});
+
+interface Obj {
+  export: string;
+  type: string;
+  ddl: string;
+  dependsOn?: string[];
+}
+
+const APP: Obj = { export: "app", type: "Postgres::Schema", ddl: "CREATE SCHEMA app" };
+const USERS: Obj = {
+  export: "users",
+  type: "Postgres::Table",
+  dependsOn: ["app"],
+  ddl: "CREATE TABLE app.users (\n  id bigint PRIMARY KEY,\n  email text NOT NULL\n);\nCOMMENT ON TABLE app.users IS 'Accounts'",
+};
+const EMAIL_IDX: Obj = { export: "usersEmail", type: "Postgres::Index", dependsOn: ["users"], ddl: "CREATE INDEX CONCURRENTLY users_email_idx ON app.users (email)" };
+const EMAILS: Obj = { export: "emails", type: "Postgres::View", dependsOn: ["users"], ddl: "CREATE VIEW app.emails AS SELECT email FROM app.users" };
+const ALL = [APP, USERS, EMAIL_IDX, EMAILS];
+
+function buildOutput(objects: Obj[], extra: Record<string, unknown> = {}): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-postgres-apply-"));
+  dirs.push(dir);
+  const path = join(dir, "schema.json");
+  writeFileSync(path, JSON.stringify({ dialect: "postgres", ...extra, applyOrder: objects.map((o) => o.export), objects: objects.map((o) => ({ dependsOn: [], ...o })) }));
+  return path;
+}
+
+const OURS = "[chant managed-by=chant stack=shop env=prod]";
+const deps = (s: WritablePostgres | undefined, extra: Partial<PostgresApplyDeps> = {}): PostgresApplyDeps => ({
+  config: { ownership: { stack: "shop", env: "prod" } },
+  env: s ? { POSTGRES_URL: "postgres://fake:5432/shop" } : {},
+  log: () => undefined,
+  connect: async () => s!.client,
+  readLive: () => s!.readLive(),
+  serverNormalize: async (_client, o) => o,
+  ...extra,
+});
+
+const apply = (s: WritablePostgres | undefined, objects: Obj[], args: Partial<PostgresApplyArgs> = {}, extra: Partial<PostgresApplyDeps> = {}) =>
+  postgresApply({ buildPath: buildOutput(objects), environment: "test", ...args }, undefined, deps(s, extra));
+const run = async (s: WritablePostgres | undefined, objects: Obj[], args: Partial<PostgresApplyArgs> = {}, extra: Partial<PostgresApplyDeps> = {}) =>
+  toApplyResult(await apply(s, objects, args, extra));
+
+/** What the server holds after a first apply of `objects`. */
+async function applied(objects: Obj[] = ALL): Promise<WritablePostgres> {
+  const s = writablePostgres();
+  await apply(s, objects);
+  s.writes.length = 0;
+  s.deletes.length = 0;
+  s.control.length = 0;
+  return s;
+}
+
+const table = (name: string, comment?: string): StoredPgObject => ({
+  type: "Postgres::Table",
+  schema: "app",
+  name,
+  create: `CREATE TABLE app.${name} (id bigint)`,
+  ...(comment !== undefined ? { comment } : {}),
+});
+
+describe("creating", () => {
+  test("an empty server gets every object, each marked by COMMENT ON, the declared comment kept", async () => {
+    const s = writablePostgres();
+    const r = normalizeApply(await run(s, ALL));
+    expect(r.applied.map((a) => [a.name, a.action])).toEqual([
+      ["app", "created"],
+      ["app.users", "created"],
+      ["app.users_email_idx", "created"],
+      ["app.emails", "created"],
+    ]);
+    expect(s.writes).toContain(`COMMENT ON SCHEMA app IS '${OURS}'`);
+    expect(s.writes).toContain(`COMMENT ON TABLE app.users IS 'Accounts ${OURS}'`);
+    expect(s.writes).not.toContain("COMMENT ON TABLE app.users IS 'Accounts'");
+  });
+
+  test("catalog-only statements share a transaction; CREATE INDEX CONCURRENTLY runs outside one", async () => {
+    const s = writablePostgres();
+    const outcome = await apply(s, ALL);
+    const cic = outcome.statements.find((x) => x.sql.startsWith("CREATE INDEX CONCURRENTLY"))!;
+    expect(cic.transaction).toBeUndefined();
+    expect(outcome.statements.filter((x) => x.object === "app" || x.object === "app.users").every((x) => x.transaction === 0)).toBe(true);
+    expect(outcome.transactions.map((t) => [t.objects, t.result])).toEqual([
+      [["app", "app.users"], "committed"],
+      [["app.users_email_idx", "app.emails"], "committed"],
+    ]);
+  });
+
+  test("every statement runs with the default timeouts, recorded on the outcome", async () => {
+    const lines: string[] = [];
+    const outcome = await apply(writablePostgres(), ALL, {}, { log: (l) => lines.push(l) });
+    expect(outcome.timeouts).toEqual({ lockTimeoutMs: 5000, statementTimeoutMs: 60000, scanTimeoutMs: 0 });
+    expect(lines.slice(0, 4)).toEqual(["BEGIN", "SET LOCAL lock_timeout = '5000ms'", "SET LOCAL statement_timeout = '60000ms'", "CREATE SCHEMA app"]);
+    const cic = lines.indexOf("CREATE INDEX CONCURRENTLY users_email_idx ON app.users (email)");
+    // On a table created in the same apply the build is part of the create.
+    expect(lines.slice(cic - 2, cic)).toEqual(["SET lock_timeout = '5000ms'", "SET statement_timeout = '60000ms'"]);
+  });
+
+  test("an index built on a table that exists runs under the scan timeout, outside a transaction", async () => {
+    const s = await applied([APP, USERS]);
+    const lines: string[] = [];
+    const outcome = await apply(s, [APP, USERS, EMAIL_IDX], {}, { log: (l) => lines.push(l) });
+    expect(lines.slice(0, 3)).toEqual(["SET lock_timeout = '5000ms'", "SET statement_timeout = '0ms'", "CREATE INDEX CONCURRENTLY users_email_idx ON app.users (email)"]);
+    expect(outcome.statements[0]).toMatchObject({ class: "concurrently", statementTimeoutMs: 0 });
+    expect(outcome.statements[0]!.transaction).toBeUndefined();
+  });
+
+  test("the profile's timeouts, overridden by the arguments", async () => {
+    const lines: string[] = [];
+    const config = { ownership: { stack: "shop", env: "prod" }, sql: { profiles: { test: { url: "postgres://fake/shop", lockTimeoutMs: 250, statementTimeoutMs: 1000 } } } };
+    const outcome = await apply(writablePostgres(), [APP], { statementTimeoutMs: 2000 }, { config, env: {}, log: (l) => lines.push(l) });
+    expect(outcome.timeouts).toEqual({ lockTimeoutMs: 250, statementTimeoutMs: 2000, scanTimeoutMs: 0 });
+    expect(lines).toContain("SET LOCAL lock_timeout = '250ms'");
+    expect(outcome.statements[0]).toMatchObject({ lockTimeoutMs: 250, statementTimeoutMs: 2000, transaction: 0 });
+  });
+
+  test("without an ownership stack the marker says managed-by alone", async () => {
+    const s = writablePostgres();
+    await run(s, [APP], {}, { config: {} });
+    expect(s.writes).toContain("COMMENT ON SCHEMA app IS '[chant managed-by=chant]'");
+  });
+});
+
+describe("updating", () => {
+  test("an added column with a default is one ALTER, its table updated", async () => {
+    const s = await applied();
+    const withName = { ...USERS, ddl: USERS.ddl.replace("email text NOT NULL", "email text NOT NULL,\n  name text NOT NULL DEFAULT 'none'") };
+    const r = normalizeApply(await run(s, [APP, withName, EMAIL_IDX, EMAILS]));
+    expect(r.applied.find((a) => a.name === "app.users")?.action).toBe("updated");
+    expect(s.writes).toEqual(["ALTER TABLE app.users ADD COLUMN name text DEFAULT 'none' NOT NULL"]);
+  });
+
+  test("an expand-and-contract change is not attempted, naming the rule and the migration Op", async () => {
+    const s = await applied();
+    const renamed = { ...USERS, ddl: USERS.ddl.replace("email text NOT NULL", "mail text NOT NULL -- previously: email") };
+    const r = normalizeApply(await run(s, [APP, renamed]));
+    const users = r.notAttempted.find((n) => n.name === "app.users");
+    expect(users).toMatchObject({ kind: "Postgres::Table", reason: "unsupported-kind" });
+    expect(users!.detail).toMatch(/SQLPG205 Rename a column/);
+    expect(users!.detail).toMatch(/postgresql\.org\/docs\/18/);
+    expect(users!.detail).toContain('PostgresMigrationOp({ table: "app.users", column: "mail", ... })');
+    expect(s.writes).toEqual([]);
+  });
+
+  test("a column drop is withheld unless the apply may delete", async () => {
+    const s = await applied([APP, USERS]);
+    const without = { ...USERS, ddl: USERS.ddl.replace(",\n  email text NOT NULL", "") };
+    const withheld = normalizeApply(await run(s, [APP, without]));
+    expect(withheld.notAttempted[0]).toMatchObject({ name: "app.users", reason: "filtered" });
+    expect(s.writes).toEqual([]);
+    await run(s, [APP, without], { prune: true });
+    expect(s.writes).toEqual(["ALTER TABLE app.users DROP COLUMN email"]);
+  });
+
+  test("an object whose comment lost the marker is stamped again, its own comment kept", async () => {
+    const s = await applied([APP, USERS]);
+    s.objects.find((o) => o.name === "users")!.comment = "Accounts";
+    const r = normalizeApply(await run(s, [APP, USERS]));
+    expect(r.applied.find((a) => a.name === "app.users")?.action).toBe("updated");
+    expect(s.writes).toEqual([`COMMENT ON TABLE app.users IS 'Accounts ${OURS}'`]);
+  });
+
+  test("an object another tool keeps is left alone", async () => {
+    const s = writablePostgres([{ ...table("_prisma_migrations"), foreign: "Prisma Migrate" }]);
+    const prisma: Obj = { export: "prisma", type: "Postgres::Table", ddl: "CREATE TABLE app._prisma_migrations (id bigint)" };
+    const r = normalizeApply(await run(s, [prisma]));
+    expect(r.notAttempted[0]).toMatchObject({ reason: "filtered" });
+    expect(r.notAttempted[0]!.detail).toMatch(/Prisma Migrate keeps/);
+  });
+});
+
+describe("a statement the server refuses", () => {
+  test("rolls its transaction back: its object fails, the others in it are not attempted with the statement named", async () => {
+    const s = writablePostgres();
+    s.refuse = /^CREATE TABLE/;
+    const err = (await apply(s, ALL).catch((e: unknown) => e)) as PostgresApplyError;
+    expect(err).toBeInstanceOf(PostgresApplyError);
+    expect(err.outcome.failed.map((f) => f.name)).toEqual(["app.users"]);
+    const app = err.outcome.notAttempted.find((n) => n.name === "app")!;
+    expect(app.reason).toBe("dependency-failed");
+    expect(app.detail).toMatch(/transaction that rolled back.*failed at CREATE TABLE app\.users/s);
+    expect(err.outcome.notAttempted.filter((n) => n.name !== "app").map((n) => [n.name, n.reason])).toEqual([
+      ["app.users_email_idx", "dependency-failed"],
+      ["app.emails", "dependency-failed"],
+    ]);
+    expect(s.control).toEqual(["BEGIN", "ROLLBACK"]);
+    expect(s.objects).toEqual([]);
+  });
+
+  test("a lock timeout says which timeout fired", async () => {
+    const s = await applied([APP, USERS]);
+    s.refuse = /^ALTER TABLE/;
+    s.refuseCode = "55P03";
+    const withName = { ...USERS, ddl: USERS.ddl.replace("email text NOT NULL", "email text NOT NULL, name text") };
+    const err = (await apply(s, [APP, withName]).catch((e: unknown) => e)) as PostgresApplyError;
+    expect(err.outcome.failed[0]!.error).toMatch(/lock_timeout 5000ms: another session holds a lock/);
+    expect(err.outcome.transactions[0]).toMatchObject({ result: "rolled-back", failedAt: { sql: "ALTER TABLE app.users ADD COLUMN name text" } });
+  });
+});
+
+describe("the target major", () => {
+  test("is the build output's postgresMajor", () => {
+    expect(buildMajor(JSON.stringify({ dialect: "postgres", postgresMajor: 16, objects: [] }))).toBe(16);
+    expect(buildMajor(JSON.stringify({ sql: { dialect: "postgres", postgresMajor: 15 } }))).toBe(15);
+    expect(buildMajor(JSON.stringify({ dialect: "postgres", objects: [] }))).toBeUndefined();
+  });
+});
+
+const PLAN = [
+  { kind: "Postgres::Schema", name: "app" },
+  { kind: "Postgres::Table", name: "app.users" },
+  { kind: "Postgres::Index", name: "app.users_email_idx" },
+  { kind: "Postgres::View", name: "app.emails" },
+];
+
+describeApplyConformance({
+  lexicon: "sql (postgres)",
+  scenarios: [
+    {
+      name: "a schema, a table, an index and a view on an empty server",
+      plan: PLAN,
+      run: async () => run(writablePostgres(), ALL),
+      expectApplied: PLAN.map((p) => `${p.kind}/${p.name}`),
+    },
+    {
+      name: "a column rename refused as expand and contract beside an unchanged schema",
+      plan: PLAN.slice(0, 2),
+      run: async () => run(await applied([APP, USERS]), [APP, { ...USERS, ddl: USERS.ddl.replace("email text NOT NULL", "mail text NOT NULL -- previously: email") }]),
+      expectApplied: ["Postgres::Schema/app"],
+      expectNotAttempted: ["Postgres::Table/app.users"],
+    },
+    {
+      name: "no server bound",
+      plan: PLAN.slice(0, 2),
+      run: () => run(undefined, [APP, USERS]),
+      expectNotAttempted: ["Postgres::Schema/app", "Postgres::Table/app.users"],
+    },
+    {
+      name: "prune without an ownership stack",
+      plan: [{ kind: "Postgres::Schema", name: "app" }],
+      run: async () => run(writablePostgres([{ type: "Postgres::Schema", name: "app", create: "CREATE SCHEMA app", comment: "[chant managed-by=chant]" }, table("old", "[chant managed-by=chant]")]), [APP], { prune: true }, { config: {} }),
+      expectApplied: ["Postgres::Schema/app"],
+      expectNotAttempted: ["Postgres::Table/app.old"],
+    },
+  ],
+  pruneScenarios: [
+    {
+      name: "an owned orphan table beside one created by hand",
+      ownedOrphan: "app.old",
+      foreign: "app.handmade",
+      run: async () => {
+        const s = await applied([APP]);
+        s.objects.push(table("old", OURS), table("handmade", "made by hand"));
+        return { result: await run(s, [APP], { prune: true }), deletes: s.deletes };
+      },
+    },
+    {
+      name: "an owned orphan table beside another stack's",
+      ownedOrphan: "app.old",
+      foreign: "app.theirs",
+      run: async () => {
+        const s = await applied([APP]);
+        s.objects.push(table("old", OURS), table("theirs", "[chant managed-by=chant stack=other env=prod]"));
+        return { result: await run(s, [APP], { prune: true }), deletes: s.deletes };
+      },
+    },
+  ],
+  idempotenceScenarios: [
+    {
+      name: "the same build applied twice",
+      run: async () => {
+        const s = writablePostgres();
+        const first = await run(s, ALL);
+        const second = await run(s, ALL);
+        return { first, second };
+      },
+    },
+  ],
+});
+
+describe("idempotence", () => {
+  test("the second apply sends nothing and reports every object unchanged", async () => {
+    const s = await applied();
+    const second = normalizeApply(await run(s, ALL));
+    expect(second.applied.map((a) => a.action)).toEqual(["unchanged", "unchanged", "unchanged", "unchanged"]);
+    expect(s.writes).toEqual([]);
+    expect(s.control).toEqual([]);
+  });
+});

package/src/op/activities/postgres-apply.ts

@@ -0,0 +1,170 @@
+/**
+ * `postgresApply`, the Op activity for the Postgres applier (#3280), and
+ * `toApplyResult`, its projection onto core's apply envelope (#1446), the
+ * same projection the ClickHouse applier exports.
+ *
+ * It reads a build's output (`chant build -o dist/schema.json`), binds the
+ * environment's server the way observation, import and `chant sql plan` do
+ * (`sql.profiles.<env>`, else `POSTGRES_URL`; ../../postgres/live/bind.ts),
+ * connects with node-postgres (loaded only now), and hands the declarations
+ * to `applyPostgres` (../../postgres/apply/apply.ts), which holds the
+ * decisions.
+ *
+ * The server's major is the build output's `postgresMajor` (#3315), else
+ * `sql.postgresMajor`, else the newest pinned one.
+ *
+ * The ownership marker is the project's: `ownership.stack` and
+ * `ownership.env` from `chant.config.ts`, or `stack` / `ownershipEnv` passed
+ * in. Without a stack the apply still runs, stamping only the managed-by
+ * marker, and a prune declines (as `not-prunable`) rather than drop another
+ * project's objects. The timeouts are the profile's, else the applier's
+ * defaults, and an argument overrides either.
+ */
+
+import { readFileSync } from "node:fs";
+import type { ChantConfig } from "@intentius/chant/config";
+import { notAttemptedOutcome, resolveOwnershipMarker } from "../../core/apply";
+import { classifyPostgresFailure, PostgresBindingError, resolveBoundTarget, type PostgresTarget } from "../../postgres/live/bind";
+import { connectPostgres, type PostgresClient, type PostgresEndpoint } from "../../postgres/live/client";
+import {
+  DEFAULT_POSTGRES_APPLY_TIMEOUTS,
+  applyPostgres,
+  declaredObjects,
+  planRefs,
+  type PostgresApplyOptions,
+  type PostgresApplyOutcome,
+  type PostgresApplyTimeouts,
+} from "../../postgres/apply/apply";
+
+export type { PostgresApplyOutcome } from "../../postgres/apply/apply";
+
+export interface PostgresApplyArgs {
+  /** The build's primary output (`chant build src --lexicon sql -o dist/schema.json`), or a multi-lexicon output holding it under `sql`. */
+  buildPath: string;
+  /** The chant environment, which selects `sql.profiles.<environment>`. */
+  environment?: string;
+  /**
+   * Drop this project's objects the build no longer declares (only those
+   * whose comment carries its marker, stack and env), and allow column drops.
+   * Destructive, so off by default.
+   */
+  prune?: boolean;
+  /** Ownership stack. Default: `ownership.stack` in `chant.config.ts`. */
+  stack?: string;
+  /** Ownership env. Default: `ownership.env` in `chant.config.ts` (a literal; a `{ param }` reference needs this). */
+  ownershipEnv?: string;
+  /** `lock_timeout` for every statement, in ms. Default: the profile's `lockTimeoutMs`, else 5000. */
+  lockTimeoutMs?: number;
+  /** `statement_timeout` for a catalog-only statement, in ms. Default: the profile's `statementTimeoutMs`, else 60000. */
+  statementTimeoutMs?: number;
+  /** `statement_timeout` for a statement that reads or rewrites rows, in ms; 0 is no limit. Default: the profile's `scanTimeoutMs`, else 0. */
+  scanTimeoutMs?: number;
+  /** Project directory for `chant.config.ts`. Default: the working directory. */
+  cwd?: string;
+}
+
+/** What a test (or an embedding caller) may inject instead of the project's config, the process env and node-postgres. */
+export interface PostgresApplyDeps {
+  config?: Pick<ChantConfig, "sql" | "ownership">;
+  env?: Record<string, string | undefined>;
+  log?: (line: string) => void;
+  connect?: (endpoint: PostgresEndpoint) => Promise<PostgresClient>;
+  /** Passed to the applier: a catalog reader and a server-normalization stand-in for a fake server. */
+  readLive?: PostgresApplyOptions["readLive"];
+  serverNormalize?: PostgresApplyOptions["serverNormalize"];
+}
+
+/** The build output's `postgresMajor`, when it carries one. */
+export function buildMajor(json: string): number | undefined {
+  try {
+    const raw = JSON.parse(json) as { postgresMajor?: unknown; sql?: { postgresMajor?: unknown } };
+    const m = raw.sql && typeof raw.sql === "object" ? raw.sql.postgresMajor : raw.postgresMajor;
+    return typeof m === "number" ? m : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function loadConfig(cwd: string): Promise<Pick<ChantConfig, "sql" | "ownership"> | undefined> {
+  try {
+    const { loadChantConfig } = await import("@intentius/chant/config");
+    return (await loadChantConfig(cwd)).config;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Apply a sql build to the environment's Postgres server. A server that
+ * cannot be bound, or refuses the credentials when connecting, returns every
+ * declared object as not attempted, with the reason.
+ */
+export async function postgresApply(args: PostgresApplyArgs, signal?: AbortSignal, deps: PostgresApplyDeps = {}): Promise<PostgresApplyOutcome> {
+  const config = deps.config ?? (await loadConfig(args.cwd ?? process.cwd()));
+  const marker = resolveOwnershipMarker(args, config, "postgres apply");
+  const json = readFileSync(args.buildPath, "utf8");
+  const log = deps.log ?? ((line: string) => console.log(line));
+  const timeouts: Partial<PostgresApplyTimeouts> = {
+    ...(args.lockTimeoutMs !== undefined ? { lockTimeoutMs: args.lockTimeoutMs } : {}),
+    ...(args.statementTimeoutMs !== undefined ? { statementTimeoutMs: args.statementTimeoutMs } : {}),
+    ...(args.scanTimeoutMs !== undefined ? { scanTimeoutMs: args.scanTimeoutMs } : {}),
+  };
+
+  // The major the build targets (#3315): what an apply does can differ by major (SET EXPRESSION from 17, SET STORAGE DEFAULT from 16).
+  const major = buildMajor(json) ?? config?.sql?.postgresMajor;
+
+  let target: PostgresTarget;
+  try {
+    target = await resolveBoundTarget({ ...(args.environment !== undefined ? { environment: args.environment } : {}), config: config ?? {}, ...(deps.env ? { env: deps.env } : {}) });
+  } catch (err) {
+    if (!(err instanceof PostgresBindingError)) throw err;
+    return refused(declaredObjects(json), undefined, err.unresolved.reason, err.unresolved.detail);
+  }
+  const declared = declaredObjects(json, target.defaultSchema);
+
+  let client: PostgresClient;
+  try {
+    client = await (deps.connect ?? ((e) => connectPostgres(e, { applicationName: "chant apply" })))(target.endpoint);
+  } catch (err) {
+    // A server that refused the credentials was not written to at all; one that cannot be reached is an error.
+    const why = classifyPostgresFailure(err);
+    if (why.reason === "no-credentials") return refused(declared, target, "no-credentials", why.detail);
+    throw err;
+  }
+  let outcome: PostgresApplyOutcome;
+  try {
+    outcome = await applyPostgres(client, target, declared, {
+      ...(marker ? { marker } : {}),
+      ...(args.prune ? { prune: true } : {}),
+      timeouts,
+      ...(major !== undefined ? { major } : {}),
+      ...(signal ? { signal } : {}),
+      ...(deps.readLive ? { readLive: deps.readLive } : {}),
+      ...(deps.serverNormalize ? { serverNormalize: deps.serverNormalize } : {}),
+      log,
+    });
+  } catch (err) {
+    // The first read is the catalog read: a refusal there means nothing was written.
+    const why = classifyPostgresFailure(err);
+    if (why.reason === "no-credentials" && !(err instanceof Error && err.name === "PostgresApplyError")) {
+      return refused(declared, target, "no-credentials", why.detail);
+    }
+    throw err;
+  } finally {
+    await client.end();
+  }
+  for (const a of outcome.applied) log(`${a.action}: ${a.kind}/${a.name}`);
+  for (const p of outcome.pruned) log(`pruned: ${p.kind}/${p.name}`);
+  for (const n of outcome.notAttempted) log(`not attempted: ${n.kind}/${n.name}: ${n.reason}${n.detail ? ` (${n.detail})` : ""}`);
+  return outcome;
+
+  function refused(objects: ReturnType<typeof declaredObjects>, t: PostgresTarget | undefined, reason: "no-binding" | "no-credentials", detail: string): PostgresApplyOutcome {
+    return {
+      ...notAttemptedOutcome(planRefs(objects), reason, detail),
+      ...(t ? { target: t.endpoint.url, source: t.source } : {}),
+      timeouts: { ...DEFAULT_POSTGRES_APPLY_TIMEOUTS, ...t?.timeouts, ...timeouts },
+      statements: [],
+      transactions: [],
+    };
+  }
+}

package/src/op/activities/postgres-emulator.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "vitest";
+import { emulatorLifecycle, emulatorsOf, endpointEnvVars } from "@intentius/chant/op";
+import { POSTGRES_EMULATOR } from "./postgres-emulator";
+import { CLICKHOUSE_EMULATOR } from "./clickhouse-emulator";
+import { sqlPlugin } from "../../plugin";
+import { POSTGRES_LATEST_MAJOR, postgresImage } from "../../spec/postgres-pin";
+
+describe("the Postgres emulator capability (#3280)", () => {
+  test("is declared on the plugin beside ClickHouse's, so chant emulator up boots it", () => {
+    expect(emulatorsOf(sqlPlugin.emulator)).toEqual([CLICKHOUSE_EMULATOR, POSTGRES_EMULATOR]);
+  });
+
+  test("runs the newest pinned image by digest, and names POSTGRES_URL as its endpoint", () => {
+    expect(POSTGRES_EMULATOR.spec.image).toBe(postgresImage(POSTGRES_LATEST_MAJOR));
+    expect(POSTGRES_EMULATOR.spec.image).toMatch(/^postgres:18\.6@sha256:/);
+    expect(endpointEnvVars(POSTGRES_EMULATOR)).toEqual(["POSTGRES_URL"]);
+    expect(POSTGRES_EMULATOR.env("postgres://localhost:5432/postgres")).toMatchObject({ POSTGRES_USER: "postgres", POSTGRES_PASSWORD: "chant" });
+  });
+
+  test("is ready when pg_isready answers over TCP, and is reached at a postgres:// URL", () => {
+    const lc = emulatorLifecycle(POSTGRES_EMULATOR.spec);
+    expect(lc.runCommand()).toBe(`docker run -d --rm --name chant-postgres -p 5432:5432 -e POSTGRES_PASSWORD=chant ${postgresImage(POSTGRES_LATEST_MAJOR)}`);
+    expect(lc.readyExecCommand("chant-postgres")).toBe("docker exec chant-postgres pg_isready -h 127.0.0.1 -U postgres");
+    expect(lc.endpoint(5432)).toBe("postgres://localhost:5432/postgres");
+  });
+});

package/src/op/activities/postgres-emulator.ts

@@ -0,0 +1,44 @@
+/**
+ * The sql lexicon's Postgres emulator capability (#3280): the official
+ * `postgres` image at the newest pin, by tag and digest (../../spec/postgres-pin.ts),
+ * the same server generation and the live tests run, so `chant emulator up`
+ * boots a real Postgres rather than a stand-in.
+ *
+ * Postgres has no HTTP health endpoint, so readiness is `pg_isready` run in
+ * the container against 127.0.0.1: the image's first, initdb-time server
+ * listens on its socket only, so the TCP check answers once the real server
+ * is up. The endpoint is a `postgres://` URL, which `POSTGRES_URL` carries;
+ * the user and password are `POSTGRES_USER` and `POSTGRES_PASSWORD`, the
+ * variables binding reads with it.
+ *
+ * `upstream` is left off: the pins move per major through the lexicon's
+ * `upstreamPins`, not the emulator freshness check.
+ */
+
+import { emulatorLifecycle, type EmulatorCapability, type EmulatorSpec } from "@intentius/chant/op";
+import { POSTGRES_LATEST_MAJOR, postgresImage } from "../../spec/postgres-pin";
+
+/** The local server's password. It is a throwaway server on localhost. */
+export const POSTGRES_EMULATOR_PASSWORD = "chant";
+
+export const POSTGRES_EMULATOR_SPEC: EmulatorSpec = {
+  name: "chant-postgres",
+  image: postgresImage(POSTGRES_LATEST_MAJOR),
+  containerPort: 5432,
+  readyCommand: ["pg_isready", "-h", "127.0.0.1", "-U", "postgres"],
+  endpoint: (port) => `postgres://localhost:${port}/postgres`,
+  runArgs: ["-e", `POSTGRES_PASSWORD=${POSTGRES_EMULATOR_PASSWORD}`],
+};
+
+/** `POSTGRES_URL` is the variable binding reads when no `sql.profiles.<env>` names a server. */
+export const POSTGRES_EMULATOR: EmulatorCapability = {
+  spec: POSTGRES_EMULATOR_SPEC,
+  env: (endpoint) => ({ POSTGRES_URL: endpoint, POSTGRES_USER: "postgres", POSTGRES_PASSWORD: POSTGRES_EMULATOR_PASSWORD }),
+};
+
+const lifecycle = emulatorLifecycle(POSTGRES_EMULATOR_SPEC);
+
+/** Boot the pinned Postgres server in Docker and return its endpoint. */
+export const postgresUp = (args: Parameters<typeof lifecycle.up>[0] = {}, signal?: AbortSignal) => lifecycle.up(args, signal);
+/** Stop and remove it (a no-op when it is gone). */
+export const postgresDown = (args: { name?: string } = {}, signal?: AbortSignal) => lifecycle.down(args, signal);