@intentius/chant-lexicon-sql 0.116.0 → 0.118.0

package/src/sql-files.ts

@@ -0,0 +1,218 @@
+/**
+ * Plain `.sql` files as a schema source (#3646): DDL read into the same
+ * declarations the tagged templates make. Also at the package root.
+ *
+ * - {@link readSqlFile}: the objects a file of DDL declares, each with its
+ *   export name, type, qualified name and DDL.
+ * - {@link sqlFileDeclarations}: the same file as TypeScript, one `schema.ts`
+ *   of `table`, `view`, ... templates, as `chant import <file>.sql` writes it.
+ * - {@link sqlFileEntities}: the declarations themselves, with the references
+ *   between the files' objects, and to objects declared elsewhere, as
+ *   interpolations, so dependency order comes from the graph. The build uses
+ *   it for every `.sql` file in the source directory.
+ *
+ * Postgres reads each `CREATE`, `GRANT`, `REVOKE` and `ALTER DEFAULT
+ * PRIVILEGES` as an object, with `COMMENT ON`, `ALTER TABLE ... ROW LEVEL
+ * SECURITY` and `ALTER TABLE ... ADD <table constraint>` folded into the
+ * object they finish; ClickHouse reads `CREATE DATABASE`, `TABLE`, `VIEW`,
+ * `MATERIALIZED VIEW`, `DICTIONARY` and `FUNCTION`. Any other statement, and any
+ * statement that does not parse, throws a {@link SqlFileError} naming every
+ * such statement: none is left out.
+ *
+ * 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 of an enum type) and an object declared without a schema has it.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import type { SqlDialect } from "./dialects";
+import { SqlFileError, type ReadOptions } from "./files/common";
+import { postgresTag, readPostgres, templateStrings } from "./files/postgres";
+import { clickhouseTag, readClickHouse } from "./files/clickhouse";
+import { exportNames as pgExportNames, objectsToIR as pgObjectsToIR, type ImportedPgObject } from "./postgres/import/ir";
+import { exportNames as chExportNames, objectsToIR as chObjectsToIR, type ImportedObject } from "./clickhouse/import/ir";
+import { PostgresGenerator, postgresTemplates, type PgTemplateItem, type TemplateBody } from "./postgres/import/generator";
+import { ClickHouseGenerator, clickhouseTemplates } from "./clickhouse/import/generator";
+import { isPostgresObject } from "./postgres/entities";
+import { isClickHouseObject } from "./clickhouse/entities";
+
+export { SqlFileError };
+export type { ReadOptions as SqlFileOptions };
+
+/** One object a file of DDL declares. */
+export interface SqlFileObject {
+  /** The export it is declared as. */
+  export: string;
+  /** Its entity type, `Postgres::Table`. */
+  type: string;
+  /** `schema.name` (Postgres), `database.name` (ClickHouse); the name alone when the DDL does not qualify it. */
+  name: string;
+  /** Its statements: the CREATE, then what was folded into it. */
+  ddl: string;
+  /** The file it came from, the `origin` it was read under. */
+  origin: string;
+}
+
+/** A file to read: its DDL and the name errors give it. */
+export interface SqlFileSource extends ReadOptions {
+  ddl: string;
+}
+
+type Imported = ImportedPgObject | ImportedObject;
+
+const qualifierOf = (o: Imported): string | undefined => ("schema" in o ? o.schema : "database" in o ? o.database : undefined);
+const qualifiedName = (o: Imported): string => (qualifierOf(o) ? `${qualifierOf(o)}.${o.name}` : o.name);
+
+function readObjects(dialect: SqlDialect, sources: readonly SqlFileSource[]): Array<Imported & { origin: string }> {
+  const out: Array<Imported & { origin: string }> = [];
+  for (const source of sources) {
+    const problems: string[] = [];
+    const objects = dialect === "postgres" ? readPostgres(source.ddl, source, problems) : readClickHouse(source.ddl, source, problems);
+    if (problems.length > 0) throw new SqlFileError(source.origin, problems);
+    out.push(...objects.map((o) => ({ ...o, origin: source.origin })));
+  }
+  return out;
+}
+
+/** Export names for objects read from files, unique across them. */
+function namesFor(dialect: SqlDialect, objects: readonly Imported[]): string[] {
+  return dialect === "postgres" ? pgExportNames(objects as ImportedPgObject[]) : chExportNames(objects as ImportedObject[]);
+}
+
+/** The objects a file of DDL declares. Throws a {@link SqlFileError} naming each statement it cannot read. */
+export function readSqlFile(dialect: SqlDialect, ddl: string, options: ReadOptions): SqlFileObject[] {
+  const objects = readObjects(dialect, [{ ...options, ddl }]);
+  const names = namesFor(dialect, objects);
+  return objects.map((o, i) => ({ export: names[i]!, type: o.type, name: qualifiedName(o), ddl: o.ddl, origin: o.origin }));
+}
+
+/**
+ * A file of DDL as TypeScript declarations: the `schema.ts` `chant import`
+ * writes, with `header` as comment lines at its top, and the objects in it.
+ */
+export function sqlFileDeclarations(dialect: SqlDialect, ddl: string, options: ReadOptions & { header?: string }): { content: string; objects: SqlFileObject[] } {
+  const objects = readObjects(dialect, [{ ...options, ddl }]);
+  if (objects.length === 0) throw new SqlFileError(options.origin, ["the DDL creates no objects"]);
+  const ir = dialect === "postgres" ? pgObjectsToIR(objects as ImportedPgObject[]) : chObjectsToIR(objects as ImportedObject[]);
+  const files = dialect === "postgres" ? new PostgresGenerator(options.header).generate(ir) : new ClickHouseGenerator(options.header).generate(ir);
+  const [file] = files;
+  if (!file) throw new SqlFileError(options.origin, ["the DDL creates no objects"]);
+  return {
+    content: file.content,
+    objects: ir.resources.map((r, i) => ({ export: r.logicalId, type: r.type, name: qualifiedName(objects[i]!), ddl: objects[i]!.ddl, origin: options.origin })),
+  };
+}
+
+/** Where an entity read from a `.sql` file came from: its `origin`. Undefined for any other entity. */
+export function sqlFileOf(entity: unknown): string | undefined {
+  return typeof entity === "object" && entity !== null ? ((entity as Record<symbol, unknown>)[FROM_FILE] as string | undefined) : undefined;
+}
+
+const FROM_FILE = Symbol.for("chant.sql.fromFile");
+
+/** A declared entity as a template target: its export, type and name. */
+function targetOf(dialect: SqlDialect, exportName: string, entity: Declarable): PgTemplateItem | undefined {
+  const p = (entity as unknown as { props: { schema?: string; database?: string; name?: string; ddl?: string } }).props;
+  if (typeof p.name !== "string") return undefined;
+  const qualifier = dialect === "postgres" ? p.schema : p.database;
+  return {
+    exportName,
+    type: entity.entityType,
+    ...(qualifier ? (dialect === "postgres" ? { schema: qualifier } : { database: qualifier }) : {}),
+    name: p.name,
+    ddl: typeof p.ddl === "string" ? p.ddl : "",
+  } as PgTemplateItem;
+}
+
+function templates(dialect: SqlDialect, items: readonly PgTemplateItem[], targets: readonly PgTemplateItem[]): { order: PgTemplateItem[]; bodies: Map<string, TemplateBody> } {
+  return dialect === "postgres" ? postgresTemplates(items, targets) : (clickhouseTemplates(items, targets) as { order: PgTemplateItem[]; bodies: Map<string, TemplateBody> });
+}
+
+/** The entities of one dialect in a set, by export name. */
+function ofDialect(dialect: SqlDialect, entities: ReadonlyMap<string, Declarable> | undefined): Map<string, Declarable> {
+  const is = dialect === "postgres" ? isPostgresObject : isClickHouseObject;
+  return new Map([...(entities ?? new Map<string, Declarable>())].filter(([, e]) => is(e)));
+}
+
+/**
+ * The declarations the files make, by export name. `known` holds the
+ * entities declared elsewhere (the project's tagged templates): a file's
+ * reference to one of them is an interpolation of it, as an import would
+ * write it, and an export name or an object one of them already declares is
+ * an error naming both.
+ */
+export function sqlFileEntities(dialect: SqlDialect, sources: readonly SqlFileSource[], options: { known?: ReadonlyMap<string, Declarable> } = {}): Map<string, Declarable> {
+  const objects = readObjects(dialect, sources);
+  const names = namesFor(dialect, objects);
+  const known = ofDialect(dialect, options.known);
+  const problems: string[] = [];
+
+  const items: PgTemplateItem[] = objects.map((o, i) => ({ exportName: names[i]!, type: o.type, ...("schema" in o && o.schema ? { schema: o.schema } : {}), ...("database" in o && o.database ? { database: o.database } : {}), name: o.name, ddl: o.ddl }) as PgTemplateItem);
+  const origin = new Map(objects.map((o, i) => [names[i]!, o.origin]));
+  const knownItems = [...known].map(([n, e]) => targetOf(dialect, n, e)).filter((t): t is PgTemplateItem => t !== undefined);
+  const declared = new Map(knownItems.map((t) => [`${t.type} ${qualifiedName(t as Imported)}`, t.exportName]));
+  const seen = new Map<string, string>();
+  const where = (at: string | undefined) => (sources.length > 1 && at ? `${at}: ` : "");
+  const label = sources.length === 1 ? sources[0]!.origin : "the .sql files";
+  for (const [i, it] of items.entries()) {
+    const what = `${it.type} ${qualifiedName(it as Imported)}`;
+    const at = objects[i]!.origin;
+    const q = qualifiedName(it as Imported);
+    if (options.known?.has(it.exportName)) problems.push(`${where(at)}${q} is exported as ${it.exportName}, a name another declaration already has; rename that one`);
+    const other = declared.get(what);
+    if (other) problems.push(`${where(at)}${q} is declared twice, here and as ${other}; leave it to one of them`);
+    const again = seen.get(what);
+    if (again) problems.push(`${where(at)}${q} is declared twice, here and in ${again}; leave it to one of them`);
+    seen.set(what, at);
+  }
+  if (problems.length > 0) throw new SqlFileError(label, problems);
+
+  const { order, bodies } = templates(dialect, items, [...items, ...knownItems]);
+  const built = new Map<string, Declarable>();
+  const failed = new Set<string>();
+  const tagOf = dialect === "postgres" ? postgresTag : clickhouseTag;
+  for (const it of order) {
+    const body = bodies.get(it.exportName)!;
+    const values = body.refs.map((r) => built.get(r) ?? known.get(r));
+    const missing = body.refs.find((_, i) => values[i] === undefined);
+    if (missing !== undefined) {
+      failed.add(it.exportName);
+      // What references an object that failed is not reported again.
+      if (failed.has(missing)) continue;
+      problems.push(`${where(origin.get(it.exportName))}${qualifiedName(it as Imported)} and ${missing} reference each other, which no declaration can; break the cycle`);
+      continue;
+    }
+    try {
+      const entity = tagOf(it.type)!(templateStrings(body.parts), ...values);
+      Object.defineProperty(entity, FROM_FILE, { value: origin.get(it.exportName), enumerable: false });
+      built.set(it.exportName, entity);
+    } catch (e) {
+      failed.add(it.exportName);
+      problems.push(`${where(origin.get(it.exportName))}${qualifiedName(it as Imported)}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+  if (problems.length > 0) throw new SqlFileError(label, problems);
+  // In the files' order, not the dependency order.
+  return new Map(items.filter((it) => built.has(it.exportName)).map((it) => [it.exportName, built.get(it.exportName)!]));
+}
+
+/**
+ * The objects read from `.sql` files that each other object names in its
+ * DDL as text, by export name: a tagged template cannot import a file's
+ * object, so it names it, and this is the edge the dependency order needs.
+ * Empty when no object came from a file.
+ */
+export function sqlFileReferences(dialect: SqlDialect, objects: ReadonlyMap<string, Declarable>): Map<string, string[]> {
+  const fromFiles = [...objects].filter(([, e]) => sqlFileOf(e) !== undefined);
+  const out = new Map<string, string[]>();
+  if (fromFiles.length === 0) return out;
+  const targets = fromFiles.map(([n, e]) => targetOf(dialect, n, e)).filter((t): t is PgTemplateItem => t !== undefined);
+  for (const [name, entity] of objects) {
+    if (sqlFileOf(entity) !== undefined) continue;
+    const item = targetOf(dialect, name, entity);
+    if (!item || !item.ddl) continue;
+    const refs = templates(dialect, [item], targets).bodies.get(name)?.refs ?? [];
+    if (refs.length > 0) out.set(name, [...new Set(refs)]);
+  }
+  return out;
+}

package/src/token-source.e2e.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Token sources against a live server (#3685). A `command` source stands in
+ * for the token endpoint: it prints a password from a file, and the test
+ * rotates the role's password and the file together, as a cloud rotates its
+ * tokens. A profile with that source connects; after the token's lifetime a
+ * new one is minted and the next connection uses it; a token the server
+ * refuses is forgotten, so the next attempt mints again.
+ *
+ * Postgres: `CHANT_SQL_E2E_POSTGRES_URL` (with
+ * `CHANT_SQL_E2E_POSTGRES_PASSWORD`) names a running server, else a
+ * throwaway one, skipped when Docker is not available. ClickHouse:
+ * `CHANT_SQL_E2E_CLICKHOUSE_URL` (as `default`, with
+ * `CHANT_SQL_E2E_CLICKHOUSE_PASSWORD`), skipped when not set. The test makes
+ * only the user `chant_e2e_3685` on each, dropped afterwards.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { dockerAvailable, startTestPostgres, type TestPostgres } from "./postgres/testing/server";
+import { connectPostgres, PostgresQueryError, type PostgresClient, type PostgresEndpoint } from "./postgres/live/client";
+import { resolveBoundTarget } from "./postgres/live/bind";
+import { bindClickHouse } from "./clickhouse/live/bind";
+import { clickhouseQuery, ClickHouseQueryError, type ClickHouseEndpoint } from "./clickhouse/http";
+
+const ROLE = "chant_e2e_3685";
+const dir = mkdtempSync(join(tmpdir(), "chant-token-"));
+const tokenFile = join(dir, "token");
+const mint = (password: string) => writeFileSync(tokenFile, password);
+const command = ["cat", tokenFile];
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+const pgGiven = process.env.CHANT_SQL_E2E_POSTGRES_URL;
+const pgEnabled = pgGiven ? true : await dockerAvailable();
+let server: TestPostgres | undefined;
+let admin: PostgresClient;
+let pgUrl: string;
+
+describe.skipIf(!pgEnabled)("a Postgres profile with a command token source", () => {
+  beforeAll(async () => {
+    let endpoint: PostgresEndpoint;
+    if (pgGiven) endpoint = { url: pgGiven, password: process.env.CHANT_SQL_E2E_POSTGRES_PASSWORD ?? "" };
+    else {
+      server = await startTestPostgres();
+      endpoint = server.endpoint();
+    }
+    admin = await connectPostgres(endpoint);
+    await admin.query(`DROP ROLE IF EXISTS ${ROLE}`);
+    await admin.query(`CREATE ROLE ${ROLE} LOGIN PASSWORD 'first-token'`);
+    const url = new URL(endpoint.url);
+    url.username = "";
+    url.password = "";
+    pgUrl = url.toString();
+  }, 600_000);
+
+  afterAll(async () => {
+    await admin?.query(`DROP ROLE IF EXISTS ${ROLE}`).catch(() => undefined);
+    await admin?.end();
+    await server?.stop();
+  });
+
+  const whoami = async (endpoint: PostgresEndpoint) => {
+    const client = await connectPostgres(endpoint);
+    try {
+      const [row] = await client.query<{ u: string }>("SELECT current_user AS u");
+      return row?.u;
+    } finally {
+      await client.end();
+    }
+  };
+
+  test("connects with the minted token, mints again after its lifetime, and forgets a refused one", async () => {
+    mint("first-token");
+    const config = { sql: { profiles: { e2e: { url: pgUrl, user: { env: "E2E_USER" }, password: { token: "command" as const, command, ttlSeconds: 1 } } } } };
+    const target = await resolveBoundTarget({ environment: "e2e", config, env: { ...process.env, E2E_USER: ROLE } });
+    expect(await whoami(target.endpoint)).toBe(ROLE);
+
+    // Rotated: the cached token has expired by the next connect, so the new one is minted.
+    await admin.query(`ALTER ROLE ${ROLE} PASSWORD 'second-token'`);
+    mint("second-token");
+    await sleep(1_000);
+    expect(await whoami(target.endpoint)).toBe(ROLE);
+
+    // Rotated before the cached token's lifetime is up: the server refuses it, and the retry mints.
+    const long = await resolveBoundTarget({
+      environment: "e2e",
+      config: { sql: { profiles: { e2e: { ...config.sql.profiles.e2e, password: { token: "command" as const, command, ttlSeconds: 3600 } } } } },
+      env: { ...process.env, E2E_USER: ROLE },
+    });
+    expect(await whoami(long.endpoint)).toBe(ROLE);
+    await admin.query(`ALTER ROLE ${ROLE} PASSWORD 'third-token'`);
+    mint("third-token");
+    const refused = await whoami(long.endpoint).catch((e: unknown) => e);
+    expect(refused).toBeInstanceOf(PostgresQueryError);
+    expect((refused as PostgresQueryError).code).toBe("28P01");
+    expect(await whoami(long.endpoint)).toBe(ROLE);
+  }, 60_000);
+});
+
+const chGiven = process.env.CHANT_SQL_E2E_CLICKHOUSE_URL;
+
+describe.skipIf(!chGiven)("a ClickHouse profile with a command token source", () => {
+  const admin: ClickHouseEndpoint = { url: chGiven ?? "", user: "default", password: process.env.CHANT_SQL_E2E_CLICKHOUSE_PASSWORD ?? "" };
+
+  beforeAll(async () => {
+    await clickhouseQuery(admin, `DROP USER IF EXISTS ${ROLE}`);
+    await clickhouseQuery(admin, `CREATE USER ${ROLE} IDENTIFIED BY 'first-token'`);
+  });
+
+  afterAll(async () => {
+    await clickhouseQuery(admin, `DROP USER IF EXISTS ${ROLE}`).catch(() => undefined);
+  });
+
+  test("each request carries a valid token; a refused one is minted again", async () => {
+    mint("first-token");
+    const config = { sql: { profiles: { e2e: { url: chGiven!, user: { env: "E2E_USER" }, password: { token: "command" as const, command, ttlSeconds: 1 } } } } };
+    const target = await bindClickHouse({ environment: "e2e", config, env: { ...process.env, E2E_USER: ROLE } });
+    const whoami = async () => (await clickhouseQuery<{ u: string }>(target.endpoint, "SELECT currentUser() AS u"))[0]?.u;
+    expect(await whoami()).toBe(ROLE);
+
+    await clickhouseQuery(admin, `ALTER USER ${ROLE} IDENTIFIED BY 'second-token'`);
+    mint("second-token");
+    await sleep(1_000);
+    expect(await whoami()).toBe(ROLE);
+
+    // Rotated before the cached token's lifetime is up: refused once, then minted again.
+    const long = await bindClickHouse({
+      environment: "e2e",
+      config: { sql: { profiles: { e2e: { ...config.sql.profiles.e2e, password: { token: "command" as const, command, ttlSeconds: 3600 } } } } },
+      env: { ...process.env, E2E_USER: ROLE },
+    });
+    const longWhoami = async () => (await clickhouseQuery<{ u: string }>(long.endpoint, "SELECT currentUser() AS u"))[0]?.u;
+    expect(await longWhoami()).toBe(ROLE);
+    await clickhouseQuery(admin, `ALTER USER ${ROLE} IDENTIFIED BY 'third-token'`);
+    mint("third-token");
+    await expect(longWhoami()).rejects.toBeInstanceOf(ClickHouseQueryError);
+    expect(await longWhoami()).toBe(ROLE);
+  }, 60_000);
+});
+
+afterAll(() => rmSync(dir, { recursive: true, force: true }));

package/src/token-source.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, test } from "vitest";
+import { sqlProfileSchema } from "./config";
+import { credentialSource, tokenCommand, TokenSourceError, type RunCommand } from "./token-source";
+import { resolvePostgresTarget, classifyPostgresFailure, isUnresolvedTarget } from "./postgres/live/bind";
+import { resolveClickHouseTarget, classifyClickHouseFailure } from "./clickhouse/live/bind";
+
+const RDS_URL = "postgres://db.abc123.eu-west-1.rds.amazonaws.com:5433/shop";
+
+describe("tokenCommand", () => {
+  test("rds-iam runs aws rds generate-db-auth-token for the URL's host and port and the profile's user", () => {
+    expect(tokenCommand({ token: "rds-iam" }, { url: RDS_URL, user: "app", env: {} })).toEqual([
+      "aws", "rds", "generate-db-auth-token", "--hostname", "db.abc123.eu-west-1.rds.amazonaws.com", "--port", "5433", "--username", "app", "--region", "eu-west-1",
+    ]);
+  });
+
+  test("rds-iam takes the region from the config, then AWS_REGION, then the host name", () => {
+    const region = (argv: readonly string[]) => argv[argv.indexOf("--region") + 1];
+    expect(region(tokenCommand({ token: "rds-iam", region: "us-east-2" }, { url: RDS_URL, user: "app", env: { AWS_REGION: "ap-south-1" } }))).toBe("us-east-2");
+    expect(region(tokenCommand({ token: "rds-iam" }, { url: RDS_URL, user: "app", env: { AWS_REGION: "ap-south-1" } }))).toBe("ap-south-1");
+    const proxy = tokenCommand({ token: "rds-iam" }, { url: "postgres://db.internal/shop", user: "app", env: {} });
+    expect(proxy).not.toContain("--region");
+    expect(proxy[proxy.indexOf("--port") + 1]).toBe("5432");
+  });
+
+  test("rds-iam needs a user", () => {
+    expect(() => tokenCommand({ token: "rds-iam" }, { url: RDS_URL, env: {} })).toThrow(TokenSourceError);
+  });
+
+  test("cloud-sql-iam, entra and command", () => {
+    expect(tokenCommand({ token: "cloud-sql-iam" }, { url: "postgres://10.0.0.3/shop", env: {} })).toEqual(["gcloud", "sql", "generate-login-token"]);
+    expect(tokenCommand({ token: "entra" }, { url: "postgres://x.postgres.database.azure.com/shop", env: {} })).toEqual([
+      "az", "account", "get-access-token", "--resource-type", "oss-rdbms", "--query", "accessToken", "--output", "tsv",
+    ]);
+    expect(tokenCommand({ token: "command", command: ["./mint.sh", "prod"] }, { url: "http://ch:8123", env: {} })).toEqual(["./mint.sh", "prod"]);
+  });
+});
+
+describe("credentialSource", () => {
+  const counting = (outputs: string[]) => {
+    const calls: (readonly string[])[] = [];
+    const run: RunCommand = async (argv) => {
+      calls.push(argv);
+      return outputs[Math.min(calls.length - 1, outputs.length - 1)]!;
+    };
+    return { calls, run };
+  };
+
+  test("mints once, reuses the token, and mints again after most of its lifetime", async () => {
+    let now = 0;
+    const { calls, run } = counting(["one\n", "two\n"]);
+    const src = credentialSource({ token: "command", command: ["mint"], ttlSeconds: 100 }, { url: "http://ch:8123", env: {}, source: "sql.profiles.ci.password", run, now: () => now });
+    expect(src.source).toBe("sql.profiles.ci.password (command)");
+    expect(calls).toHaveLength(0);
+    expect(await src.get()).toBe("one");
+    now = 79_000;
+    expect(await src.get()).toBe("one");
+    now = 80_000;
+    expect(await src.get()).toBe("two");
+    expect(calls).toHaveLength(2);
+  });
+
+  test("invalidate forgets the token; requests at once share one mint", async () => {
+    const { calls, run } = counting(["a", "b"]);
+    const src = credentialSource({ token: "command", command: ["mint"] }, { url: "http://ch:8123", env: {}, source: "s", run });
+    expect(await Promise.all([src.get(), src.get(), src.get()])).toEqual(["a", "a", "a"]);
+    src.invalidate();
+    expect(await src.get()).toBe("b");
+    expect(calls).toHaveLength(2);
+  });
+
+  test("a failed or empty mint names the program, never its output", async () => {
+    const failing: RunCommand = async () => {
+      throw Object.assign(new Error("secret-ish stderr"), { code: 2 });
+    };
+    const missing: RunCommand = async () => {
+      throw Object.assign(new Error("spawn"), { code: "ENOENT" });
+    };
+    const opts = { url: RDS_URL, user: "app", env: {}, source: "sql.profiles.prod.password" };
+    const err = (await credentialSource({ token: "rds-iam" }, { ...opts, run: failing }).get().catch((e: unknown) => e)) as Error;
+    expect(err).toBeInstanceOf(TokenSourceError);
+    expect(err.message).toBe("sql.profiles.prod.password (rds-iam) could not mint a token: `aws` failed, it exited with 2");
+    await expect(credentialSource({ token: "entra" }, { ...opts, run: missing }).get()).rejects.toThrow("`az` failed, az is not installed");
+    await expect(credentialSource({ token: "command", command: ["x"] }, { ...opts, run: async () => "  \n" }).get()).rejects.toThrow("printed nothing");
+    expect(classifyPostgresFailure(err)).toEqual({ reason: "no-credentials", detail: err.message });
+    expect(classifyClickHouseFailure(err).reason).toBe("no-credentials");
+  });
+});
+
+describe("profiles with a token source", () => {
+  test("the schema takes a token source or an env reference, and refuses an unknown one", () => {
+    expect(sqlProfileSchema.safeParse({ url: RDS_URL, password: { token: "rds-iam", region: "eu-west-1" } }).success).toBe(true);
+    expect(sqlProfileSchema.safeParse({ url: RDS_URL, password: { token: "command", command: ["./mint.sh"], ttlSeconds: 60 } }).success).toBe(true);
+    expect(sqlProfileSchema.safeParse({ url: RDS_URL, password: { env: "PW" } }).success).toBe(true);
+    expect(sqlProfileSchema.safeParse({ url: RDS_URL, password: { token: "vault" } }).success).toBe(false);
+    expect(sqlProfileSchema.safeParse({ url: RDS_URL, password: { token: "command", command: [] } }).success).toBe(false);
+  });
+
+  test("a Postgres profile binds a token source with the resolved user, and mints nothing yet", () => {
+    const config = { sql: { profiles: { prod: { url: RDS_URL, user: { env: "PG_USER" }, password: { token: "rds-iam" as const } } } } };
+    const target = resolvePostgresTarget({ environment: "prod", config, env: { PG_USER: "app" } });
+    if (isUnresolvedTarget(target)) throw new Error(target.detail);
+    expect(target.endpoint.user).toBe("app");
+    expect(target.endpoint.password).toBeUndefined();
+    expect(target.endpoint.token?.source).toBe("sql.profiles.prod.password (rds-iam)");
+  });
+
+  test("rds-iam with no user is no-credentials", () => {
+    const config = { sql: { profiles: { prod: { url: RDS_URL, password: { token: "rds-iam" as const } } } } };
+    expect(resolvePostgresTarget({ environment: "prod", config, env: {} })).toMatchObject({ reason: "no-credentials" });
+  });
+
+  test("ClickHouse takes a command source and refuses a cloud one", () => {
+    const command = { sql: { profiles: { ci: { url: "http://ch:8123", password: { token: "command" as const, command: ["mint"] } } } } };
+    const target = resolveClickHouseTarget({ environment: "ci", config: command, env: {} });
+    expect("endpoint" in target && target.endpoint.token?.source).toBe("sql.profiles.ci.password (command)");
+    const cloud = { sql: { profiles: { ci: { url: "http://ch:8123", password: { token: "cloud-sql-iam" as const } } } } };
+    expect(resolveClickHouseTarget({ environment: "ci", config: cloud, env: {} })).toMatchObject({ reason: "no-credentials" });
+  });
+});

package/src/token-source.ts

@@ -0,0 +1,189 @@
+/**
+ * Short-lived database credentials (#3685): a profile's `password` can name a
+ * token source instead of an environment variable, and the token is minted
+ * when a connection needs it.
+ *
+ * ```ts
+ * profiles: {
+ *   prod: { url: "postgres://db.abc.us-east-1.rds.amazonaws.com:5432/shop", user: { env: "PG_USER" }, password: { token: "rds-iam" } },
+ *   ci: { url: "postgres://db.internal:5432/shop", password: { token: "command", command: ["./mint-token.sh"], ttlSeconds: 600 } },
+ * }
+ * ```
+ *
+ * Each cloud source runs that cloud's own command line, which reads the job's
+ * ambient identity (an OIDC-federated role in CI, a workload identity, a
+ * logged-in developer), so chant holds no cloud SDK and no long-lived secret:
+ *
+ * - `rds-iam`: `aws rds generate-db-auth-token`, for RDS and Aurora. The host
+ *   and port come from the profile's URL, the user from its `user`, the region
+ *   from `region`, else `AWS_REGION`, else the RDS host name.
+ * - `cloud-sql-iam`: `gcloud sql generate-login-token`.
+ * - `entra`: `az account get-access-token` for Azure Database for PostgreSQL.
+ * - `command`: any command that prints a password on its standard output.
+ *
+ * A token is reused until most of its lifetime has passed and minted again
+ * after, so a long apply, whose ClickHouse requests each carry the password
+ * and whose Postgres connections each authenticate when opened, never sends
+ * an expired one. A token is never written to a message, an outcome or a log.
+ */
+
+import { execFile } from "node:child_process";
+import { z } from "zod";
+
+const ttl = z.number().int().positive().optional();
+
+/** The token sources a profile's `password` can name. */
+export const tokenSourceSchema = z.discriminatedUnion("token", [
+  z.strictObject({
+    token: z.literal("rds-iam"),
+    /** The AWS region. `AWS_REGION`, `AWS_DEFAULT_REGION`, else the RDS host name's, when omitted. */
+    region: z.string().min(1).optional(),
+    /** How long a token is valid, in seconds. 900, the RDS lifetime, when omitted. */
+    ttlSeconds: ttl,
+  }),
+  z.strictObject({
+    token: z.literal("cloud-sql-iam"),
+    /** How long a token is valid, in seconds. 3600 when omitted. */
+    ttlSeconds: ttl,
+  }),
+  z.strictObject({
+    token: z.literal("entra"),
+    /** How long a token is valid, in seconds. 3600 when omitted. */
+    ttlSeconds: ttl,
+  }),
+  z.strictObject({
+    token: z.literal("command"),
+    /** The program and its arguments, run without a shell; its standard output, trimmed, is the password. */
+    command: z.array(z.string().min(1)).min(1),
+    /** How long a token is valid, in seconds. 300 when omitted. */
+    ttlSeconds: ttl,
+  }),
+]);
+
+export type TokenSourceConfig = z.infer<typeof tokenSourceSchema>;
+
+/** The cloud sources, which mint for a Postgres server only. */
+export const POSTGRES_ONLY_TOKEN_SOURCES: ReadonlySet<string> = new Set(["rds-iam", "cloud-sql-iam", "entra"]);
+
+const DEFAULT_TTL_SECONDS: Record<TokenSourceConfig["token"], number> = {
+  "rds-iam": 900,
+  "cloud-sql-iam": 3600,
+  entra: 3600,
+  command: 300,
+};
+
+/** A token reused past this share of its lifetime is minted again. */
+const REUSE_FRACTION = 0.8;
+
+/** A token source that could not mint. The message names the source and the command, never what it printed. */
+export class TokenSourceError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TokenSourceError";
+  }
+}
+
+/** Runs a program without a shell and returns its standard output. */
+export type RunCommand = (argv: readonly string[], env: Record<string, string | undefined>) => Promise<string>;
+
+const runCommand: RunCommand = (argv, env) =>
+  new Promise((resolve, reject) => {
+    execFile(argv[0]!, argv.slice(1), { env: env as NodeJS.ProcessEnv, timeout: 60_000, maxBuffer: 1 << 20 }, (err, stdout) => {
+      if (err) reject(err);
+      else resolve(String(stdout));
+    });
+  });
+
+/** Where a token is minted, and the cached token. */
+export interface CredentialSource {
+  /** What the token is minted by, for a message: `sql.profiles.prod.password (rds-iam)`. */
+  readonly source: string;
+  /** A valid token: the cached one, or a new one when it has expired. */
+  get(): Promise<string>;
+  /** Forget the cached token, so the next `get()` mints again. */
+  invalidate(): void;
+}
+
+/** The program a source runs. Pure, for tests. */
+export function tokenCommand(
+  config: TokenSourceConfig,
+  input: { url: string; user?: string; env: Record<string, string | undefined> },
+): readonly string[] {
+  switch (config.token) {
+    case "command":
+      return config.command;
+    case "cloud-sql-iam":
+      return ["gcloud", "sql", "generate-login-token"];
+    case "entra":
+      return ["az", "account", "get-access-token", "--resource-type", "oss-rdbms", "--query", "accessToken", "--output", "tsv"];
+    case "rds-iam": {
+      const url = new URL(input.url);
+      if (input.user === undefined) throw new TokenSourceError("rds-iam mints a token for one database user; the profile names no user");
+      const region = config.region ?? input.env.AWS_REGION ?? input.env.AWS_DEFAULT_REGION ?? /\.([a-z]{2}(?:-[a-z]+)+-\d+)\.rds\.amazonaws\.com$/.exec(url.hostname)?.[1];
+      return [
+        "aws",
+        "rds",
+        "generate-db-auth-token",
+        "--hostname",
+        url.hostname,
+        "--port",
+        url.port || "5432",
+        "--username",
+        input.user,
+        ...(region !== undefined ? ["--region", region] : []),
+      ];
+    }
+  }
+}
+
+/**
+ * A source that mints with `config` when asked. Nothing runs until `get()`.
+ * `now` and `run` are for tests.
+ */
+export function credentialSource(
+  config: TokenSourceConfig,
+  input: {
+    url: string;
+    user?: string;
+    env: Record<string, string | undefined>;
+    source: string;
+    run?: RunCommand;
+    now?: () => number;
+  },
+): CredentialSource {
+  const run = input.run ?? runCommand;
+  const now = input.now ?? Date.now;
+  const lifetimeMs = (config.ttlSeconds ?? DEFAULT_TTL_SECONDS[config.token]) * 1000 * REUSE_FRACTION;
+  const source = `${input.source} (${config.token})`;
+  let cached: { token: string; until: number } | undefined;
+  let pending: Promise<string> | undefined;
+  const mint = async (): Promise<string> => {
+    const argv = tokenCommand(config, input);
+    let out: string;
+    try {
+      out = await run(argv, input.env);
+    } catch (err) {
+      const e = err as { code?: unknown; stderr?: unknown };
+      const why = e.code === "ENOENT" ? `${argv[0]} is not installed` : `it exited with ${String(e.code ?? "an error")}`;
+      throw new TokenSourceError(`${source} could not mint a token: \`${argv[0]}\` failed, ${why}`);
+    }
+    const token = out.trim();
+    if (token === "") throw new TokenSourceError(`${source} could not mint a token: \`${argv[0]}\` printed nothing`);
+    cached = { token, until: now() + lifetimeMs };
+    return token;
+  };
+  return {
+    source,
+    async get() {
+      if (cached && now() < cached.until) return cached.token;
+      // Requests that ask at once share one mint.
+      pending ??= mint().finally(() => {
+        pending = undefined;
+      });
+      return pending;
+    },
+    invalidate() {
+      cached = undefined;
+    },
+  };
+}