@intentius/chant-lexicon-sql 0.118.0 → 0.120.0

package/src/core/foreign-tables.ts

@@ -0,0 +1,28 @@
+/**
+ * Tables another tool keeps its migration history in, by name, with the tool.
+ *
+ * Both dialects' catalog readers mark a table by one of these names as
+ * foreign: import leaves it out with a warning, and a plan names it in a hint
+ * instead of proposing a drop, since chant changing it would change what that
+ * tool owns (#3047 question 10, #3676). golang-migrate, dbmate, goose and
+ * Flyway keep the same tables on ClickHouse as on Postgres.
+ */
+export const FOREIGN_TABLES: Readonly<Record<string, string>> = {
+  _prisma_migrations: "Prisma Migrate",
+  schema_migrations: "a migration runner (Rails, golang-migrate, dbmate)",
+  ar_internal_metadata: "Rails",
+  django_migrations: "Django",
+  alembic_version: "Alembic",
+  __drizzle_migrations: "drizzle-kit",
+  flyway_schema_history: "Flyway",
+  goose_db_version: "goose",
+  knex_migrations: "Knex",
+  knex_migrations_lock: "Knex",
+  SequelizeMeta: "Sequelize",
+  pgmigrations: "node-pg-migrate",
+};
+
+/** The tool that keeps a table by this name, or undefined when none does. */
+export function foreignTool(name: string): string | undefined {
+  return Object.prototype.hasOwnProperty.call(FOREIGN_TABLES, name) ? FOREIGN_TABLES[name] : undefined;
+}

package/src/files/build-root.ts

@@ -8,7 +8,11 @@
  * git-ignored paths, child projects and the project's `exclude` globs are
  * left out. A file whose first lines carry `-- chant-discovery-skip` (or the
  * `/* chant-discovery-skip *\/` form) is not read, for SQL that is not schema:
- * seed data, a migration, a query.
+ * seed data, a migration, a query. Nor is a file under a `migrations`
+ * directory (#3713): versioned migrations and an ORM's generated migrations
+ * are `ALTER`s and repeated `CREATE`s of objects declared elsewhere, and a
+ * build of the project root, as `chant lifecycle diff` and an ApplyOp's plan
+ * run with no `sourceDir`, walks into them.
  *
  * The dialect is the declarations': a project whose templates are Postgres
  * reads its files as Postgres. With no templates it is `sql.dialect`, and
@@ -16,7 +20,7 @@
  */
 
 import { readFileSync } from "node:fs";
-import { relative, resolve } from "node:path";
+import { relative, resolve, sep } from "node:path";
 import type { Declarable } from "@intentius/chant/declarable";
 import type { BuildRootContext, BuildRootContribution } from "@intentius/chant/lexicon";
 import { findSourceFiles, hasDiscoveryMarkerSync } from "@intentius/chant/discovery/files";
@@ -36,6 +40,14 @@ export function isSqlSourceFile(name: string, full: string): boolean {
   return !SQL_SKIP_MARKER.test(readHead(full, 1024));
 }
 
+/** A directory whose `.sql` files are migrations, never declarations. */
+export const MIGRATIONS_DIR = "migrations";
+
+/** Whether `file` sits under a {@link MIGRATIONS_DIR} directory below `sourceDir`. */
+export function inMigrationsDir(sourceDir: string, file: string): boolean {
+  return relative(sourceDir, file).split(sep).slice(0, -1).includes(MIGRATIONS_DIR);
+}
+
 /** The dialect the project's `.sql` files are read as. */
 export function filesDialect(entities: ReadonlyMap<string, Declarable> | undefined, config: Record<string, unknown>): SqlDialect {
   for (const e of entities?.values() ?? []) {
@@ -54,7 +66,7 @@ export function filesDialect(entities: ReadonlyMap<string, Declarable> | undefin
 /** The `buildRoots` contribution: every `.sql` file's declarations, or nothing when the source directory holds none. */
 export async function sqlFilesBuildRoot(ctx: BuildRootContext): Promise<BuildRootContribution> {
   const sourceDir = ctx.sourceDir ?? resolve(ctx.projectRoot, typeof ctx.config.sourceDir === "string" ? ctx.config.sourceDir : ".");
-  const files = (await findSourceFiles(sourceDir, isSqlSourceFile)).sort();
+  const files = (await findSourceFiles(sourceDir, isSqlSourceFile)).filter((f) => !inMigrationsDir(sourceDir, f)).sort();
   if (files.length === 0) return { entities: new Map() };
   const dialect = filesDialect(ctx.entities, ctx.config);
   const sources = files.map((f) => ({ origin: relative(ctx.projectRoot, f) || f, ddl: readFileSync(f, "utf8") }));

package/src/files/clickhouse.ts

@@ -1,23 +1,79 @@
 /**
  * A file of ClickHouse DDL as the objects it declares: one per `CREATE
  * DATABASE`, `TABLE`, `VIEW`, `MATERIALIZED VIEW`, `DICTIONARY` or `FUNCTION`, as `chant import
- * <file>.sql` reads them. Any other statement, and any statement the parser
- * refuses, is a problem naming it.
+ * <file>.sql` reads them, and one per `CREATE USER`, `CREATE ROLE`, `CREATE
+ * ROW POLICY` and `GRANT` (#3711), each read by its tag, so what the tag
+ * refuses (`IDENTIFIED BY`, a `REVOKE`) is refused with the tag's message.
+ * Any other statement, and any statement the parser refuses, is a problem
+ * naming it.
  *
  * With `schema` (a database), an object's unqualified name is qualified with
- * it; a function belongs to no database and keeps its name.
+ * it, and so is the table a row policy or a grant is on; a function, a user
+ * and a role belong to no database and keep their names.
  */
 
 import type { Declarable } from "@intentius/chant/declarable";
 import { isTrivia, tokenizeText } from "../clickhouse/tokens";
 import { parseCreate } from "../clickhouse/parser";
-import { database, dictionary, func, table, view } from "../clickhouse/entities";
+import { CLICKHOUSE_ENTITY_TYPES, database, dictionary, func, grant, policy, role, table, user, view } from "../clickhouse/entities";
+import { isAccessStatement, parseAccess, type AccessNode } from "../clickhouse/access";
+import type { Token } from "../clickhouse/tokens";
 import { CLICKHOUSE_TAG_OF } from "../clickhouse/import/generator";
 import { describeStatement, type ImportedObject } from "../clickhouse/import/ir";
 import { firstLine, quoteBare, splitTokens, tokensText, type ReadOptions } from "./common";
+import { templateSafe, templateStrings } from "./postgres";
 
 type Tag = (strings: TemplateStringsArray, ...values: unknown[]) => Declarable;
-const TAGS: Record<string, Tag> = { database, table, view, dictionary, func };
+const TAGS: Record<string, Tag> = { database, table, view, dictionary, func, user, role, policy, grant };
+
+/** Tokens with `[db.]name`'s bare name qualified with `schema`. A `*` (all tables) is left alone. */
+function qualifyBare(tokens: Token[], span: { from: number; to: number } | undefined, schema: string): string | undefined {
+  if (!span) return undefined;
+  const name = tokens.slice(span.from, span.to).filter((t) => !isTrivia(t));
+  const [only] = name;
+  if (!only || name.length !== 1 || (only.kind !== "ident" && only.kind !== "qident")) return undefined;
+  const at = tokens.indexOf(only);
+  return tokensText(tokens.slice(0, at)) + `${quoteBare(schema)}.` + tokensText(tokens.slice(at));
+}
+
+/** An access statement as the object its tag declares (#3711), or the tag's refusal. */
+function readAccess(sql: string, options: ReadOptions): ImportedObject | string {
+  let tokens = tokenizeText(sql, 0);
+  let node: AccessNode;
+  try {
+    node = parseAccess(tokens);
+  } catch (e) {
+    // What the tag refuses (a password) is refused in the tag's words.
+    const words = sql.replace(/--[^\n]*\n/g, " ").trim().split(/\s+/, 2).map((w) => w.toUpperCase());
+    const tag = words[0] === "CREATE" ? (words[1] === "USER" ? user : words[1] === "ROLE" ? role : policy) : grant;
+    try {
+      tag(templateStrings([templateSafe(sql)]));
+    } catch (refused) {
+      return refused instanceof Error ? refused.message : String(refused);
+    }
+    throw e;
+  }
+  if (options.schema) {
+    const qualified = qualifyBare(tokens, node.statement === "rowPolicy" ? node.table : node.statement === "grant" ? node.target : undefined, options.schema);
+    if (qualified !== undefined) {
+      sql = qualified;
+      tokens = tokenizeText(sql, 0);
+      node = parseAccess(tokens);
+    }
+  }
+  const tag = node.statement === "user" ? user : node.statement === "role" ? role : node.statement === "rowPolicy" ? policy : grant;
+  let props: { name: string; database?: string; table?: string };
+  try {
+    props = (tag(templateStrings([templateSafe(sql)])) as unknown as { props: typeof props }).props;
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+  if (node.statement === "user") return { type: CLICKHOUSE_ENTITY_TYPES.user, name: props.name, ddl: sql };
+  if (node.statement === "role") return { type: CLICKHOUSE_ENTITY_TYPES.role, name: props.name, ddl: sql };
+  if (node.statement === "rowPolicy") return { type: CLICKHOUSE_ENTITY_TYPES.rowPolicy, ...(props.database ? { database: props.database } : {}), name: props.name, ddl: sql };
+  // A grant has no name of its own: what it grants, on what, to whom.
+  return { type: CLICKHOUSE_ENTITY_TYPES.grant, name: `grant ${tokensText(tokens.slice(tokens.findIndex((t) => !isTrivia(t)) + 1)).replace(/\s+/g, " ").trim().toLowerCase()}`, ddl: sql };
+}
 
 /** The tag that declares an entity type. */
 export function clickhouseTag(type: string): Tag | undefined {
@@ -30,6 +86,16 @@ export function readClickHouse(ddl: string, options: ReadOptions, problems: stri
   const objects: ImportedObject[] = [];
   for (const stmt of splitTokens(tokenizeText(ddl, 0), isTrivia)) {
     let sql = tokensText(stmt);
+    if (isAccessStatement(sql)) {
+      try {
+        const read = readAccess(sql, options);
+        if (typeof read === "string") problems.push(`${read}: ${firstLine(sql)}`);
+        else objects.push(read);
+      } catch (e) {
+        problems.push(`does not parse (${e instanceof Error ? e.message : String(e)}): ${firstLine(sql)}`);
+      }
+      continue;
+    }
     if (!/^CREATE\b/i.test(sql)) {
       problems.push(`not a CREATE statement: ${firstLine(sql)}`);
       continue;

package/src/files/postgres.ts

@@ -45,7 +45,8 @@ const isName = (t: Token | undefined): boolean => t !== undefined && (t.kind ===
 const word = (t: Token | undefined, ...words: string[]): boolean => t !== undefined && t.kind === "ident" && words.includes(t.text.toUpperCase());
 
 /** Text that sits inside a template literal: a backquote and `${` escaped. */
-const templateSafe = (s: string) => s.replace(/\\(?=`|\$\{)/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+/** Text that sits inside a template literal: a backquote and `${` escaped. */
+export const templateSafe = (s: string) => s.replace(/\\(?=`|\$\{)/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
 
 interface PgFileObject {
   node: StatementNode;

package/src/import-parser.ts

@@ -25,6 +25,8 @@ const CLICKHOUSE_ONLY = [
   /^\s*CREATE\s+(?:DATABASE|(?:OR\s+REPLACE\s+)?DICTIONARY)\b/im,
   // A SQL function: CREATE FUNCTION f AS (x) -> ...
   /^\s*CREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\s+[^\s(]+(?:\s+ON\s+CLUSTER\s+\S+)?\s+AS\s*\(/im,
+  // A row policy (#3711): Postgres says CREATE POLICY.
+  /^\s*CREATE\s+(?:OR\s+REPLACE\s+)?ROW\s+POLICY\b/im,
 ];
 const POSTGRES_ONLY = [
   /^\s*CREATE\s+(?:OR\s+REPLACE\s+)?(?:SCHEMA|EXTENSION|TYPE|DOMAIN|SEQUENCE|(?:UNIQUE\s+)?INDEX|(?:CONSTRAINT\s+)?TRIGGER|POLICY|ROLE|FUNCTION|PROCEDURE|(?:UNLOGGED|TEMP|TEMPORARY)\s+TABLE)\b/im,

package/src/migration-statements.test.ts

@@ -111,6 +111,39 @@ describe("ClickHouse", () => {
     expect((d.steps[0] as { detail: string }).detail).toMatch(/drop and create this object instead/);
   });
 
+  test("a user the environment creates gets its declared clauses with ALTER USER, its password left alone (#3717)", () => {
+    const reader: Obj = { export: "reader", type: "ClickHouse::Role", ddl: "CREATE ROLE reader" };
+    const app: Obj = {
+      export: "app",
+      type: "ClickHouse::User",
+      dependsOn: ["reader", "analytics"],
+      ddl: "CREATE USER app HOST LOCAL DEFAULT ROLE reader DEFAULT DATABASE analytics SETTINGS max_memory_usage = 1000000000",
+    };
+    const readerToApp: Obj = { export: "readerToApp", type: "ClickHouse::Grant", dependsOn: ["reader", "app"], ddl: "GRANT reader TO app" };
+    const d = diffStatements(build("clickhouse", [DB]), build("clickhouse", [DB, reader, app, readerToApp]));
+    const sql = sqlOf(d);
+    expect(sql).toEqual([
+      "CREATE ROLE reader",
+      "ALTER USER `app` HOST LOCAL",
+      "ALTER USER `app` DEFAULT DATABASE analytics",
+      "ALTER USER `app` SETTINGS max_memory_usage = 1000000000",
+      "GRANT `reader` TO `app`",
+      // A default role must be held first.
+      "ALTER USER `app` DEFAULT ROLE reader",
+    ]);
+    expect(sql.join("\n")).not.toMatch(/CREATE USER|IDENTIFIED/);
+    expect(d.steps.filter((s) => s.object === "app").map((s) => (s as StatementStep).rule)).toEqual(["SQLCH271", "SQLCH271", "SQLCH271"]);
+
+    // Without grants to it, the default role is set with the rest.
+    const alone = sqlOf(diffStatements(build("clickhouse", [DB, reader]), build("clickhouse", [DB, reader, app])));
+    expect(alone).toEqual([
+      "ALTER USER `app` HOST LOCAL",
+      "ALTER USER `app` DEFAULT DATABASE analytics",
+      "ALTER USER `app` SETTINGS max_memory_usage = 1000000000",
+      "ALTER USER `app` DEFAULT ROLE reader",
+    ]);
+  });
+
   test("two identical builds take no steps", () => {
     expect(diffStatements(CH_BEFORE, CH_BEFORE)).toEqual({ dialect: "clickhouse", defaultDatabase: "default", topology: "single", steps: [], refused: false, hints: [] });
   });

package/src/migration-statements.ts

@@ -112,6 +112,8 @@ function clickhouseStatements(beforeJson: string, afterJson: string, options: Di
     current: new Map(before.map((o) => [o.exportName, o.canonical])),
     keyOf: (o) => o.exportName,
     allowDestructive: true,
+    // A user whose password is the environment's exists by the time a migration runs: the GRANTs to it need it too (#3717).
+    environmentCreatesUsers: true,
     topology,
     ...(options.marker ? { marker: options.marker } : {}),
   });

package/src/op/__snapshots__/watch-pipeline.test.ts.snap

@@ -62,7 +62,7 @@ jobs:
 `;
 
 exports[`generateOpsPipeline renders the sql drift watch (#3642) > GitLab: a schedule-only job with the reader's credentials and no token of its own 1`] = `
-"# chant Ops (#927, #2084, #2293) — one job per Op under stage "ops", each
+"# chant Ops — one job per Op under stage "ops", each
 # selected by its own rules:. A merge_request_event or push job needs no
 # setup; its rule fires on the event itself.
 #

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

@@ -10,9 +10,28 @@
  * `upstreamPin` already tracks the LTS tags (`-lts`).
  */
 
-import { emulatorLifecycle, type EmulatorCapability, type EmulatorSpec } from "@intentius/chant/op";
+import { emulatorLifecycle, type EmulatorCapability, type EmulatorIdentity, type EmulatorSpec } from "@intentius/chant/op";
 import { clickhouseImage } from "../../spec/pin";
 
+/**
+ * The server's UUID (#3673), read in the container and through the endpoint
+ * `status` prints, so a server of another origin on the same port is told
+ * apart from the emulator.
+ */
+export const CLICKHOUSE_EMULATOR_IDENTITY: EmulatorIdentity = {
+  server: "ClickHouse",
+  command: ["clickhouse-client", "-q", "SELECT serverUUID()"],
+  async probe(endpoint) {
+    const url = new URL(endpoint);
+    url.searchParams.set("query", "SELECT serverUUID(), version() FORMAT TSV");
+    const res = await fetch(url, { signal: AbortSignal.timeout(5_000) });
+    const body = (await res.text()).trim();
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${body.split("\n")[0]}`);
+    const [id = "", version = "(unknown version)"] = body.split("\t");
+    return { id, label: `ClickHouse ${version}` };
+  },
+};
+
 export const CLICKHOUSE_EMULATOR_SPEC: EmulatorSpec = {
   name: "chant-clickhouse",
   image: clickhouseImage(),
@@ -21,6 +40,8 @@ export const CLICKHOUSE_EMULATOR_SPEC: EmulatorSpec = {
   // The image disables network access for the passwordless default user
   // unless this is set; a local server is reached as `default` with no password.
   runArgs: ["-e", "CLICKHOUSE_SKIP_USER_SETUP=1"],
+  identity: CLICKHOUSE_EMULATOR_IDENTITY,
+  credentials: "user default, no password",
 };
 
 /** `CLICKHOUSE_URL` is the variable binding reads when no `sql.profiles.<env>` names a server. */

package/src/op/activities/postgres-apply-lock-timeout.e2e.test.ts

@@ -0,0 +1,87 @@
+/**
+ * The applier's catalog read under `lock_timeout` (#3726). One session holds
+ * ACCESS EXCLUSIVE on a table behind a view; `postgresApply` of a build that
+ * declares the view reads its definition first, so it stops after the
+ * profile's `lockTimeoutMs` instead of waiting for the lock, names the table
+ * and the pid holding it, and writes nothing.
+ *
+ * `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. The test makes only the schema `chant_e2e_3726`, 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, type PostgresClient, type PostgresEndpoint } from "../../postgres/live/client";
+import { postgresApply } from "./postgres-apply";
+
+const SCHEMA = "chant_e2e_3726";
+const given = process.env.CHANT_SQL_E2E_POSTGRES_URL;
+const enabled = given ? true : await dockerAvailable();
+const dir = mkdtempSync(join(tmpdir(), "chant-pg-apply-3726-"));
+let server: TestPostgres | undefined;
+let endpoint: PostgresEndpoint;
+let admin: PostgresClient;
+let holder: PostgresClient;
+
+describe.skipIf(!enabled)("an apply whose catalog read is blocked behind ACCESS EXCLUSIVE", () => {
+  beforeAll(async () => {
+    if (given) endpoint = { url: given, password: process.env.CHANT_SQL_E2E_POSTGRES_PASSWORD ?? "" };
+    else {
+      server = await startTestPostgres();
+      endpoint = server.endpoint();
+    }
+    admin = await connectPostgres(endpoint);
+    await admin.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`);
+    await admin.query(`CREATE SCHEMA ${SCHEMA}`);
+    await admin.query(`CREATE TABLE ${SCHEMA}.orders (id bigint PRIMARY KEY)`);
+    await admin.query(`CREATE VIEW ${SCHEMA}.recent AS SELECT id FROM ${SCHEMA}.orders`);
+    holder = await connectPostgres(endpoint, { applicationName: "chant-e2e-3726-holder" });
+    await holder.query("BEGIN");
+    await holder.query(`LOCK TABLE ${SCHEMA}.orders IN ACCESS EXCLUSIVE MODE`);
+  }, 600_000);
+
+  afterAll(async () => {
+    await holder?.query("ROLLBACK").catch(() => undefined);
+    await holder?.end();
+    await admin?.query(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => undefined);
+    await admin?.end();
+    await server?.stop();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("stops after lockTimeoutMs, naming the table and the pid, with nothing written", async () => {
+    const [{ pid }] = await holder.query<{ pid: number }>("SELECT pg_catalog.pg_backend_pid() AS pid");
+    const buildPath = join(dir, "schema.json");
+    writeFileSync(
+      buildPath,
+      JSON.stringify({
+        dialect: "postgres",
+        applyOrder: ["app", "orders", "recent", "audit"],
+        objects: [
+          { export: "app", type: "Postgres::Schema", dependsOn: [], ddl: `CREATE SCHEMA ${SCHEMA}` },
+          { export: "orders", type: "Postgres::Table", dependsOn: ["app"], ddl: `CREATE TABLE ${SCHEMA}.orders (\n  id bigint PRIMARY KEY\n)` },
+          { export: "recent", type: "Postgres::View", dependsOn: ["orders"], ddl: `CREATE VIEW ${SCHEMA}.recent AS SELECT id FROM ${SCHEMA}.orders` },
+          { export: "audit", type: "Postgres::Table", dependsOn: ["app"], ddl: `CREATE TABLE ${SCHEMA}.audit (\n  id bigint\n)` },
+        ],
+      }),
+    );
+    const started = Date.now();
+    const err = (await postgresApply({ buildPath, environment: "e2e" }, undefined, {
+      config: { ownership: { stack: "e2e3726", env: "e2e" }, sql: { profiles: { e2e: { url: endpoint.url, password: { env: "PG_E2E_3726_PASSWORD" }, schemas: [SCHEMA], lockTimeoutMs: 300 } } } },
+      env: { PG_E2E_3726_PASSWORD: endpoint.password ?? "" },
+      log: () => undefined,
+    }).catch((e: unknown) => e)) as Error;
+    expect(Date.now() - started).toBeLessThan(10_000);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.message).toContain("lock timeout: the catalog read waited 300ms for a lock");
+    expect(err.message).toContain(`${SCHEMA}.orders is held in ACCESS EXCLUSIVE by pid ${pid}`);
+    expect(err.message).toContain("chant-e2e-3726-holder");
+    const [audit] = await admin.query<{ n: number }>(`SELECT count(*)::int AS n FROM pg_catalog.pg_tables WHERE schemaname = $1 AND tablename = 'audit'`, [SCHEMA]);
+    expect(audit?.n).toBe(0);
+  }, 60_000);
+});

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

@@ -8,6 +8,7 @@ import { buildMajor, postgresApply, type PostgresApplyArgs, type PostgresApplyDe
 import { toApplyResult } from "./index";
 import { writablePostgres, type StoredPgObject, type WritablePostgres } from "../../postgres/testing/writable-server";
 import { PostgresApplyError } from "../../postgres/apply/apply";
+import { PostgresQueryError } from "../../postgres/live/client";
 
 const dirs: string[] = [];
 afterAll(() => {
@@ -213,6 +214,37 @@ describe("a statement the server refuses", () => {
   });
 });
 
+describe("the catalog read before applying (#3726)", () => {
+  test("runs under the profile's lockTimeoutMs, else 5000 ms, else the argument's", async () => {
+    for (const [profile, arg, expected] of [[undefined, undefined, "5000ms"], [250, undefined, "250ms"], [250, 75, "75ms"]] as const) {
+      const s = writablePostgres();
+      const sent: unknown[][] = [];
+      const config = { ownership: { stack: "shop", env: "prod" }, sql: { profiles: { test: { url: "postgres://fake/shop", ...(profile !== undefined ? { lockTimeoutMs: profile } : {}) } } } };
+      const client = { query: (sql: string, p?: readonly unknown[]) => (sent.push([sql, ...(p ?? [])]), s.client.query(sql)), end: s.client.end };
+      await apply(s, [APP], arg !== undefined ? { lockTimeoutMs: arg } : {}, { config, env: {}, connect: async () => client as never });
+      expect(sent[0]).toEqual(["SELECT pg_catalog.set_config('lock_timeout', $1, false)", expected]);
+    }
+  });
+
+  test("blocked behind ACCESS EXCLUSIVE, it stops before any write, naming the relation and the pid holding it", async () => {
+    const s = writablePostgres();
+    const client = {
+      async query<T>(sql: string): Promise<T[]> {
+        if (sql.includes("pg_get_viewdef")) throw new PostgresQueryError("canceling statement due to lock timeout", "55P03");
+        if (sql.includes("pg_catalog.pg_locks")) return [{ pid: 4242, relation: "app.users", application: "psql", state: "idle in transaction", seconds: 9, query: "LOCK TABLE app.users" }] as T[];
+        return s.client.query<T>(sql);
+      },
+      end: s.client.end,
+    };
+    const err = (await apply(s, ALL, {}, { connect: async () => client as never, readLive: async (c) => (await c.query("SELECT pg_catalog.pg_get_viewdef(1)"), []) }).catch((e: unknown) => e)) as Error;
+    expect(err).toBeInstanceOf(PostgresQueryError);
+    expect(err.message).toContain("canceling statement due to lock timeout: the catalog read waited 5000ms for a lock");
+    expect(err.message).toContain("app.users is held in ACCESS EXCLUSIVE by pid 4242");
+    expect(s.writes).toEqual([]);
+    expect(s.control).toEqual([]);
+  });
+});
+
 describe("the target major", () => {
   test("is the build output's postgresMajor", () => {
     expect(buildMajor(JSON.stringify({ dialect: "postgres", postgresMajor: 16, objects: [] }))).toBe(16);

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

@@ -24,3 +24,23 @@ describe("the Postgres emulator capability (#3280)", () => {
     expect(lc.endpoint(5432)).toBe("postgres://localhost:5432/postgres");
   });
 });
+
+describe("the sql emulators say who they are (#3673)", () => {
+  test("Postgres compares the cluster's system identifier, read over the container's socket", () => {
+    expect(POSTGRES_EMULATOR.spec.identity?.server).toBe("Postgres");
+    expect(POSTGRES_EMULATOR.spec.identity?.command).toEqual(["psql", "-U", "postgres", "-tAc", "select system_identifier from pg_control_system()"]);
+    expect(POSTGRES_EMULATOR.spec.credentials).toBe("user postgres, password chant");
+  });
+
+  test("ClickHouse compares serverUUID(), and signs in as default with no password", () => {
+    expect(CLICKHOUSE_EMULATOR.spec.identity?.server).toBe("ClickHouse");
+    expect(CLICKHOUSE_EMULATOR.spec.identity?.command).toEqual(["clickhouse-client", "-q", "SELECT serverUUID()"]);
+    expect(CLICKHOUSE_EMULATOR.spec.credentials).toBe("user default, no password");
+  });
+
+  test("a server that is not Postgres fails the Postgres probe instead of matching", async () => {
+    // Nothing listens on port 1; the probe rejects, which status reports as "does not answer as the emulator".
+    await expect(POSTGRES_EMULATOR.spec.identity!.probe("postgres://127.0.0.1:1/postgres")).rejects.toThrow();
+  });
+});
+

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

@@ -15,12 +15,50 @@
  * `upstreamPins`, not the emulator freshness check.
  */
 
-import { emulatorLifecycle, type EmulatorCapability, type EmulatorSpec } from "@intentius/chant/op";
+import { emulatorLifecycle, type EmulatorCapability, type EmulatorIdentity, type EmulatorSpec } from "@intentius/chant/op";
 import { POSTGRES_LATEST_MAJOR, postgresImage } from "../../spec/postgres-pin";
+import { connectPostgres } from "../../postgres/live/client";
 
 /** The local server's password. It is a throwaway server on localhost. */
 export const POSTGRES_EMULATOR_PASSWORD = "chant";
 
+/** How long `chant emulator status` waits for the server behind the endpoint. */
+const PROBE_TIMEOUT_MS = 5_000;
+
+/**
+ * The cluster's system identifier, unique per `initdb` (#3673): read in the
+ * container over its socket, and through the endpoint `status` prints. A
+ * native Postgres holding 127.0.0.1:5432 answers with its own, or refuses
+ * the emulator's sign-in.
+ */
+export const POSTGRES_EMULATOR_IDENTITY: EmulatorIdentity = {
+  server: "Postgres",
+  command: ["psql", "-U", "postgres", "-tAc", "select system_identifier from pg_control_system()"],
+  async probe(endpoint) {
+    const client = await withTimeout(
+      connectPostgres({ url: endpoint, user: "postgres", password: POSTGRES_EMULATOR_PASSWORD }, { applicationName: "chant emulator status" }),
+    );
+    try {
+      const [row] = await withTimeout(
+        client.query<{ id: string; version: string }>(
+          "SELECT system_identifier::text AS id, pg_catalog.current_setting('server_version') AS version FROM pg_catalog.pg_control_system()",
+        ),
+      );
+      return { id: row?.id ?? "", label: `PostgreSQL ${row?.version ?? "(unknown version)"}` };
+    } finally {
+      await client.end();
+    }
+  },
+};
+
+function withTimeout<T>(promise: Promise<T>): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`no answer within ${PROBE_TIMEOUT_MS / 1000}s`)), PROBE_TIMEOUT_MS);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
 export const POSTGRES_EMULATOR_SPEC: EmulatorSpec = {
   name: "chant-postgres",
   image: postgresImage(POSTGRES_LATEST_MAJOR),
@@ -28,6 +66,8 @@ export const POSTGRES_EMULATOR_SPEC: EmulatorSpec = {
   readyCommand: ["pg_isready", "-h", "127.0.0.1", "-U", "postgres"],
   endpoint: (port) => `postgres://localhost:${port}/postgres`,
   runArgs: ["-e", `POSTGRES_PASSWORD=${POSTGRES_EMULATOR_PASSWORD}`],
+  identity: POSTGRES_EMULATOR_IDENTITY,
+  credentials: `user postgres, password ${POSTGRES_EMULATOR_PASSWORD}`,
 };
 
 /** `POSTGRES_URL` is the variable binding reads when no `sql.profiles.<env>` names a server. */