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

package/src/postgres/testing/server.ts

@@ -0,0 +1,58 @@
+/**
+ * A throwaway Postgres server for the live tests: the pinned image on a random
+ * loopback port, a client for it, and a URL for a second database on it.
+ * Always removed with its volume.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { startScratchContainer } from "../../core/container";
+import { postgresImage, POSTGRES_LATEST_MAJOR } from "../../spec/postgres-pin";
+import { connectPostgres, type PostgresClient, type PostgresEndpoint } from "../live/client";
+
+export { dockerAvailable } from "../../core/container";
+
+export interface TestPostgres {
+  name: string;
+  /** The endpoint of database `db` (default `postgres`). */
+  endpoint(db?: string): PostgresEndpoint;
+  /** A client on database `db`, with the catalog-reading session (empty search_path). */
+  connect(db?: string): Promise<PostgresClient>;
+  stop(): Promise<void>;
+}
+
+const PASSWORD = "chant";
+const exec = promisify(execFile);
+
+export async function startTestPostgres(major = POSTGRES_LATEST_MAJOR): Promise<TestPostgres> {
+  let port = "";
+  let name = "";
+  const endpoint = (db = "postgres"): PostgresEndpoint => ({ url: `postgres://postgres@127.0.0.1:${port}/${db}`, password: PASSWORD });
+  const container = await startScratchContainer({
+    image: postgresImage(major),
+    namePrefix: "chant-sql-pg-test",
+    containerPort: 5432,
+    env: { POSTGRES_PASSWORD: PASSWORD },
+    removeVolumes: true,
+    readyTimeoutMs: 120_000,
+    notReady: "did not accept a connection",
+    onStarted: (n: string) => {
+      name = n;
+    },
+    ready: async (p) => {
+      port = p;
+      // The image runs a temporary server for initdb and then restarts it: ready is the second "ready" line.
+      const logs = await exec("docker", ["logs", name]).then((r) => `${r.stdout}${r.stderr}`, () => "");
+      if ((logs.match(/database system is ready to accept connections/g) ?? []).length < 2) return false;
+      try {
+        const c = await connectPostgres(endpoint());
+        await c.query("SELECT 1");
+        await c.end();
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  });
+  return { name: container.name, endpoint, connect: (db) => connectPostgres(endpoint(db)), stop: () => container.stop() };
+}

package/src/postgres/testing/writable-server.ts

@@ -0,0 +1,188 @@
+/**
+ * A fake Postgres server for the applier's unit tests (#3280): a client that
+ * keeps the objects it was sent `CREATE` for, their comments set by
+ * `COMMENT ON`, and drops them on `DROP`, with transactions that roll back;
+ * and a catalog reader over what it keeps, standing in for
+ * `../live/catalog.ts`. What it was sent is recorded, so a test asserts on
+ * the transport.
+ *
+ * It parses statements with the dialect's own parser, so what it stores reads
+ * back as the declaration it came from. It does not model locks, column
+ * changes or dependencies: a test that needs those runs against the pinned
+ * server (`../../op/activities/postgres-apply.e2e.test.ts`).
+ */
+
+import type { PostgresClient } from "../live/client";
+import { PostgresQueryError } from "../live/client";
+import type { LivePgObject } from "../live/catalog";
+import { stripMarker } from "../../core/ownership";
+import { tokenizeText } from "../tokens";
+import { parseStatements, type CommentNode, type NameNode } from "../parser";
+import { POSTGRES_ENTITY_TYPES, type PostgresEntityType } from "../entity-types";
+import { quoteIdent } from "../keywords";
+
+/** One object the fake holds. */
+export interface StoredPgObject {
+  type: PostgresEntityType;
+  schema?: string;
+  name: string;
+  /** The CREATE statement, as sent. */
+  create: string;
+  /** The comment, chant's trailer included. */
+  comment?: string;
+  /** Another tool keeps it (an ORM's revision table). */
+  foreign?: string;
+}
+
+export interface WritablePostgres {
+  client: PostgresClient;
+  /** Reads what the fake holds, as the catalog reader would print it. */
+  readLive: () => Promise<LivePgObject[]>;
+  objects: StoredPgObject[];
+  /** Every statement sent that is not session or transaction control. */
+  writes: string[];
+  /** The DROP statements sent. */
+  deletes: string[];
+  /** Transaction control as sent: BEGIN, COMMIT, ROLLBACK. */
+  control: string[];
+  /** A statement matching this fails with `refuseCode`. */
+  refuse?: RegExp;
+  refuseCode?: string;
+}
+
+const KIND_WORD: 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]: "MATERIALIZED VIEW",
+  [POSTGRES_ENTITY_TYPES.sequence]: "SEQUENCE",
+  [POSTGRES_ENTITY_TYPES.enum]: "TYPE",
+  [POSTGRES_ENTITY_TYPES.domain]: "DOMAIN",
+  [POSTGRES_ENTITY_TYPES.extension]: "EXTENSION",
+};
+
+const flat = (type: string) => type === POSTGRES_ENTITY_TYPES.schema || type === POSTGRES_ENTITY_TYPES.extension;
+const qname = (o: { type: string; schema?: string; name: string }) => (flat(o.type) || !o.schema ? quoteIdent(o.name) : `${quoteIdent(o.schema)}.${quoteIdent(o.name)}`);
+const split = (n: NameNode, defaultSchema = "public"): { schema: string; name: string } =>
+  n.pieces.length > 1 ? { schema: n.pieces[0]!, name: n.pieces[1]! } : { schema: defaultSchema, name: n.pieces[0]! };
+const unquote = (s: string) => s.replace(/^'/, "").replace(/'$/, "").replace(/''/g, "'");
+
+export function writablePostgres(seed: StoredPgObject[] = []): WritablePostgres {
+  let objects = seed.map((o) => ({ ...o }));
+  let snapshot: StoredPgObject[] | undefined;
+  const server: WritablePostgres = {
+    objects,
+    writes: [],
+    deletes: [],
+    control: [],
+    readLive: async () =>
+      server.objects.map((o, i) => {
+        const own = o.comment !== undefined ? stripMarker(o.comment) : "";
+        return {
+          type: o.type,
+          ...(flat(o.type) ? {} : { schema: o.schema }),
+          name: o.name,
+          oid: String(16384 + i),
+          ...(o.comment !== undefined ? { comment: o.comment } : {}),
+          ...(o.foreign ? { foreign: o.foreign } : {}),
+          statement: [o.create, ...(own ? [`COMMENT ON ${KIND_WORD[o.type]} ${qname(o)} IS '${own.replace(/'/g, "''")}'`] : [])].join(";\n"),
+        };
+      }),
+    client: {
+      async query<T>(sql: string): Promise<T[]> {
+        const s = sql.trim();
+        if (/^BEGIN$/i.test(s)) {
+          server.control.push("BEGIN");
+          snapshot = server.objects.map((o) => ({ ...o }));
+          return [];
+        }
+        if (/^COMMIT$/i.test(s)) {
+          server.control.push("COMMIT");
+          snapshot = undefined;
+          return [];
+        }
+        if (/^ROLLBACK$/i.test(s)) {
+          server.control.push("ROLLBACK");
+          if (snapshot) server.objects = objects = snapshot;
+          snapshot = undefined;
+          return [];
+        }
+        if (/^(SET|SELECT|RESET)\b/i.test(s)) return [];
+        if (server.refuse?.test(s)) throw new PostgresQueryError(`refused: ${s.split("\n")[0]}`, server.refuseCode ?? "XX000");
+        server.writes.push(s);
+        const drop = /^DROP\s+(MATERIALIZED VIEW|INDEX(?:\s+CONCURRENTLY)?|TABLE|VIEW|SEQUENCE|TYPE|DOMAIN|EXTENSION|SCHEMA)\s+(.+)$/i.exec(s);
+        if (drop) {
+          server.deletes.push(s);
+          const word = drop[1]!.toUpperCase().replace(/\s+CONCURRENTLY$/, "");
+          const at = server.objects.findIndex((o) => KIND_WORD[o.type] === word && qname(o) === drop[2]!.trim());
+          if (at >= 0) server.objects.splice(at, 1);
+          return [];
+        }
+        let node;
+        try {
+          node = parseStatements(tokenizeText(s, 0))[0];
+        } catch {
+          return []; // ALTER and the rest: recorded, not modelled
+        }
+        if (!node) return [];
+        if (node.statement === "comment") {
+          const c = node as CommentNode;
+          const entry = Object.entries(KIND_WORD).find(([, w]) => w === c.objectType.toUpperCase());
+          if (!entry) return [];
+          const type = entry[0];
+          const n = flat(type) ? { name: c.target.pieces[0]! } : split(c.target);
+          const o = server.objects.find((x) => x.type === type && x.name === n.name && (flat(type) || x.schema === (n as { schema: string }).schema));
+          const text = c.text ? unquote(/IS\s+('(?:[^']|'')*')\s*$/i.exec(s)?.[1] ?? "") : undefined;
+          if (o) {
+            if (text === undefined) delete o.comment;
+            else o.comment = text;
+          }
+          return [];
+        }
+        const add = (type: PostgresEntityType, schema: string | undefined, name: string) => {
+          if (server.objects.some((x) => x.type === type && x.name === name && x.schema === schema)) {
+            throw new PostgresQueryError(`relation "${name}" already exists`, "42P07");
+          }
+          server.objects.push({ type, ...(schema !== undefined ? { schema } : {}), name, create: s.replace(/\bCREATE\s+OR\s+REPLACE\s+/i, "CREATE ") });
+        };
+        switch (node.statement) {
+          case "schema":
+            add(POSTGRES_ENTITY_TYPES.schema, undefined, node.name!.pieces[0]!);
+            break;
+          case "extension":
+            add(POSTGRES_ENTITY_TYPES.extension, undefined, node.name.pieces[0]!);
+            break;
+          case "table":
+          case "sequence":
+          case "enum":
+          case "domain": {
+            const n = split(node.name);
+            const type = { table: POSTGRES_ENTITY_TYPES.table, sequence: POSTGRES_ENTITY_TYPES.sequence, enum: POSTGRES_ENTITY_TYPES.enum, domain: POSTGRES_ENTITY_TYPES.domain }[node.statement];
+            add(type, n.schema, n.name);
+            break;
+          }
+          case "view": {
+            const n = split(node.name);
+            const type = node.materialized ? POSTGRES_ENTITY_TYPES.materializedView : POSTGRES_ENTITY_TYPES.view;
+            if (node.orReplace) {
+              const o = server.objects.find((x) => x.type === type && x.name === n.name && x.schema === n.schema);
+              if (o) {
+                o.create = s.replace(/\bCREATE\s+OR\s+REPLACE\s+/i, "CREATE ");
+                break;
+              }
+            }
+            add(type, n.schema, n.name);
+            break;
+          }
+          case "index":
+            add(POSTGRES_ENTITY_TYPES.index, split(node.table).schema, node.name!.pieces[0]!);
+            break;
+        }
+        return [];
+      },
+      async end() {},
+    },
+  };
+  return server;
+}

package/src/postgres/tokens.ts

@@ -0,0 +1,46 @@
+/**
+ * Postgres's lexical rules over the shared lossless tokenizer
+ * (`../core/tokens.ts`, chant #3278), from the Postgres 18 reference,
+ * "Lexical Structure":
+ *
+ * - `"` quotes an identifier; a backtick is an operator character.
+ * - A backslash is an ordinary character in `'...'` (standard_conforming_strings
+ *   is on by default since 9.1) and escapes only in an `E'...'` string. `B'...'`,
+ *   `X'...'`, `N'...'` and `U&'...'` are strings too, each one token.
+ * - `$$...$$` and `$tag$...$tag$` are strings; `$1` is a parameter.
+ * - Block comments nest.
+ * - `( ) , ; . [ ]` are punctuation; `=` is an operator, so `WITH (a = 1)`
+ *   reads `=` as an `op` token.
+ * - A number never runs into a name: `42`, `3.5`, `.5`, `1e-3`, `0x1F`,
+ *   `0o17`, `0b101`, `1_000`.
+ * - A multi-character operator does not end in `+` or `-` unless it holds
+ *   one of `~ ! @ # % ^ & | \` ?`, so `fillfactor=-30` reads `=` then `-`.
+ */
+
+import { tokenize as tokenizeWith, tokenizeText as tokenizeTextWith, type LexicalRules, type Token } from "../core/tokens";
+
+export { isTrivia, SqlSyntaxError, untokenize, type LexicalRules, type Token, type TokenKind } from "../core/tokens";
+
+export const POSTGRES_LEXICAL: LexicalRules = {
+  identQuotes: '"',
+  backslashEscapes: false,
+  punct: "(),;.[]",
+  // The operator characters (sql-syntax-lexical, "Operators"), and `:` for the `::` cast.
+  opChars: /[+\-*/<>=~!@#%^&|`?:]/,
+  prefixedStrings: true,
+  dollarQuotes: true,
+  nestedComments: true,
+  numbers: "sql",
+  unicodeIdentifiers: true,
+  operatorsEndWithoutSign: true,
+};
+
+/** Tokenize one string with Postgres's rules. `part` is the part index recorded on each token and on an error. */
+export function tokenizeText(src: string, part: number): Token[] {
+  return tokenizeTextWith(src, part, POSTGRES_LEXICAL);
+}
+
+/** Tokenize a template's parts with Postgres's rules, with a `ref` token for each interpolation between them. */
+export function tokenize(parts: readonly string[]): Token[] {
+  return tokenizeWith(parts, POSTGRES_LEXICAL);
+}

package/src/postgres.ts

@@ -0,0 +1,75 @@
+/**
+ * `@intentius/chant-lexicon-sql/postgres`: the Postgres dialect (#3289).
+ *
+ * Everything here is spec-true to Postgres, not a database-agnostic model:
+ * the statements are Postgres's own DDL, parsed at build time into entities,
+ * and the names fold and quote as Postgres folds and quotes them.
+ */
+
+export {
+  schema,
+  table,
+  index,
+  view,
+  sequence,
+  type,
+  domain,
+  extension,
+  literal,
+  SqlLiteral,
+  SqlTemplateError,
+  PostgresObject,
+  POSTGRES_ENTITY_TYPES,
+  isPostgresObject,
+  isColumnRef,
+  quoteIdent,
+  type PostgresEntityType,
+  type PostgresSchema,
+  type PostgresRelation,
+  type PostgresTable,
+  type PostgresView,
+  type PostgresIndex,
+  type PostgresSequence,
+  type PostgresEnum,
+  type PostgresDomain,
+  type PostgresExtension,
+  type ColumnDef,
+  type KeyDef,
+  type CheckDef,
+  type ForeignKeyDef,
+  type ExclusionDef,
+  type SchemaProps,
+  type TableProps,
+  type IndexProps,
+  type ViewProps,
+  type SequenceProps,
+  type EnumProps,
+  type DomainProps,
+  type ExtensionProps,
+  type LineageEdge,
+} from "./postgres/entities";
+
+export {
+  POSTGRES_PROVIDERS,
+  COMMON_REFUSED,
+  providerData,
+  isPostgresProvider,
+  providerAllowsExtension,
+  isProviderOwned,
+  refusedStatement,
+  normalizeStatement,
+  type PostgresProvider,
+  type ProviderData,
+  type ProviderSource,
+  type RefusedStatement,
+  type LiveObjectRef,
+} from "./postgres/providers";
+
+export {
+  PostgresMigrationOp,
+  type PostgresMigrationOpConfig,
+  type PostgresMigrationOpResources,
+  type PostgresMigrationArgs,
+} from "./postgres/migrate/op";
+export { POSTGRES_RECEIPTS_TABLE } from "./postgres/migrate/receipts";
+export * from "./composites/postgres";

package/src/serializer.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Sectioned by the serializer test table in lexicon-authoring/serializer.mdx.
+ * Cases 5, 6, 8 and 9 (a derived name, an explicit name, injected defaults)
+ * do not apply: a schema object's name is the one its DDL gives, and the
+ * serializer adds nothing the DDL does not say.
+ */
+import { describe, expect, test } from "vitest";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { CLICKHOUSE_DDL_FILE, POSTGRES_DDL_FILE, sqlSerializer } from "./serializer";
+import { database, table, view } from "./clickhouse/entities";
+import * as pg from "./postgres/entities";
+
+const analytics = database`CREATE DATABASE analytics ENGINE = Atomic`;
+const events = table`
+  CREATE TABLE ${analytics}.events (user_id UUID, kind LowCardinality(String), ts DateTime)
+  ENGINE = MergeTree ORDER BY (user_id, ts)`;
+const byKind = view`
+  CREATE VIEW ${analytics}.by_kind AS
+  SELECT ${events.columns.kind} AS kind, count() AS n FROM ${events} GROUP BY kind`;
+
+const run = (entries: Array<[string, Declarable]>) => sqlSerializer.serialize(new Map(entries)) as SerializerResult;
+const doc = (r: SerializerResult) =>
+  JSON.parse(r.primary) as { dialect: string; applyOrder: string[]; objects: Array<Record<string, unknown>> };
+
+describe("sql serializer", () => {
+  test("1. its name is the lexicon's", () => {
+    expect(sqlSerializer.name).toBe("sql");
+  });
+
+  test("2. its rule prefix is SQL", () => {
+    expect(sqlSerializer.rulePrefix).toBe("SQL");
+  });
+
+  test("3. an empty build serializes to an empty string", () => {
+    expect(sqlSerializer.serialize(new Map())).toBe("");
+  });
+
+  test("4. one table is filed under its export name, with its DDL", () => {
+    const d = doc(run([["events", events]]));
+    expect(d.dialect).toBe("clickhouse");
+    expect(d.objects[0]).toMatchObject({ export: "events", type: "ClickHouse::Table", name: "events", sqlName: "analytics.events" });
+    expect(d.objects[0]!.ddl).toMatch(/^CREATE TABLE analytics\.events/);
+  });
+
+  test("7. several objects come out in dependency order, the statements beside them in the same order", () => {
+    const r = run([["byKind", byKind], ["events", events], ["analytics", analytics]]);
+    expect(doc(r).applyOrder).toEqual(["analytics", "events", "byKind"]);
+    const sql = r.files![CLICKHOUSE_DDL_FILE]!;
+    expect(sql.indexOf("CREATE DATABASE")).toBeLessThan(sql.indexOf("CREATE TABLE"));
+    expect(sql.indexOf("CREATE TABLE")).toBeLessThan(sql.indexOf("CREATE VIEW"));
+    expect(r.verbatimFiles).toEqual([CLICKHOUSE_DDL_FILE]);
+  });
+
+  test("10. a declarable of another lexicon is not written", () => {
+    const other = { [DECLARABLE_MARKER]: true, lexicon: "k8s", entityType: "K8s::Core::ConfigMap", kind: "resource", props: {} } as unknown as Declarable;
+    expect(doc(run([["events", events], ["cm", other]])).applyOrder).toEqual(["events"]);
+  });
+
+  test("11. the output is the same whatever order the entities arrive in", () => {
+    const a = run([["analytics", analytics], ["events", events], ["byKind", byKind]]);
+    const b = run([["byKind", byKind], ["analytics", analytics], ["events", events]]);
+    expect(a.primary).toBe(b.primary);
+    expect(a.files).toEqual(b.files);
+  });
+
+  test("12. references are written as export names, lineage as export.column", () => {
+    const view = doc(run([["analytics", analytics], ["events", events], ["byKind", byKind]])).objects.find((o) => o.export === "byKind")!;
+    expect(view.reads).toEqual(["events"]);
+    expect(view.dependsOn).toEqual(["analytics", "events.kind", "events"]);
+    expect(view.lineage).toEqual([
+      { output: "kind", expr: "kind", from: ["events.kind"] },
+      { output: "n", expr: "count()", from: [] },
+    ]);
+    expect(view.source).toBeUndefined();
+  });
+
+  test("a reference cycle is an error naming it", () => {
+    const a = table`CREATE TABLE a (x UInt8) ENGINE = Log`;
+    const b = view`CREATE VIEW b AS SELECT * FROM ${a}`;
+    // A cycle cannot be written with tags (a reference must exist first), so make one by hand.
+    (a.dependsOn as unknown[]).push(b);
+    expect(() => run([["a", a], ["b", b]])).toThrow(/reference cycle.*a -> b -> a/);
+  });
+});
+
+describe("sql serializer, Postgres", () => {
+  const app = pg.schema`CREATE SCHEMA app`;
+  const users = pg.table`CREATE TABLE ${app}.users (id bigint PRIMARY KEY, email text NOT NULL)`;
+  const orders = pg.table`
+    CREATE TABLE ${app}.orders (id bigint PRIMARY KEY, user_id bigint REFERENCES ${users} (${users.columns.id}));
+    COMMENT ON TABLE ${app}.orders IS 'Placed orders'`;
+  const byUser = pg.index`CREATE INDEX orders_user_idx ON ${orders} (${orders.columns.user_id})`;
+
+  test("4. a Postgres build is its own document, with postgres.sql beside it", () => {
+    const r = run([["users", users], ["app", app]]);
+    expect(doc(r).dialect).toBe("postgres");
+    expect(doc(r).objects[1]).toMatchObject({ export: "users", type: "Postgres::Table", name: "users", schema: "app", sqlName: "app.users" });
+    expect(r.files![POSTGRES_DDL_FILE]).toBe("CREATE SCHEMA app;\n\nCREATE TABLE app.users (id bigint PRIMARY KEY, email text NOT NULL);\n");
+    expect(r.verbatimFiles).toEqual([POSTGRES_DDL_FILE]);
+  });
+
+  test("a Postgres build records the target major: sql.postgresMajor, else the newest pinned", () => {
+    const entities = new Map<string, never>([["app", app as never]]);
+    const major = (config?: Record<string, unknown>) =>
+      (JSON.parse((sqlSerializer.serialize(entities, undefined, { config }) as SerializerResult).primary) as { postgresMajor?: number }).postgresMajor;
+    expect(major()).toBe(18);
+    expect(major({ sql: { postgresMajor: 14 } })).toBe(14);
+  });
+
+  test("7. an index comes after its table, a table after what it references, comments stay with their object", () => {
+    const r = run([["byUser", byUser], ["orders", orders], ["users", users], ["app", app]]);
+    expect(doc(r).applyOrder).toEqual(["app", "users", "orders", "byUser"]);
+    expect(r.files![POSTGRES_DDL_FILE]).toContain("COMMENT ON TABLE app.orders IS 'Placed orders';\n\nCREATE INDEX");
+  });
+
+  test("12. references nested in props are written as export names", () => {
+    const d = doc(run([["app", app], ["users", users], ["orders", orders], ["byUser", byUser]]));
+    expect(d.objects.find((o) => o.export === "orders")!.foreignKeys).toEqual([
+      { columns: ["user_id"], references: "users", refTable: "app.users", refColumns: ["id"] },
+    ]);
+    expect(d.objects.find((o) => o.export === "byUser")).toMatchObject({ table: "orders", tableName: "app.orders" });
+  });
+
+  test("one build holds one dialect", () => {
+    expect(() => run([["events", events], ["users", users]])).toThrow(/one build holds one dialect.*ClickHouse \(events\) and Postgres \(users\)/);
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,148 @@
+/**
+ * The sql serializer.
+ *
+ * A build writes two things:
+ *
+ * - The primary output, one JSON document: the dialect, the order objects
+ *   must be created in, and each object filed under its export name (its
+ *   identity in chant) with its type, its parsed definition, the references it
+ *   makes and its DDL. Post-synth checks, planning and the applier read this.
+ * - `clickhouse.sql` (or `postgres.sql`) beside it: every statement, in that
+ *   order, as it will be sent. Written verbatim.
+ *
+ * The order is the dependency order of the references: a view after the
+ * tables it reads, a materialized view after its target, a table after its
+ * database. Ties break by export name, so the output is the same however the
+ * files were discovered. A reference cycle is an error naming the cycle.
+ *
+ * One build holds one dialect: the dialect is the document's, and a project
+ * whose declarations are ClickHouse and Postgres both is refused, naming one
+ * of each. Two databases of different dialects are two projects (two
+ * workspace members, #3047 question 1).
+ *
+ * A Postgres document also carries `postgresMajor`, the major the project
+ * targets (`sql.postgresMajor`, else the newest pinned major). Post-synth
+ * checks and the lock classifier read it; ClickHouse output has no such field.
+ *
+ * Rule ids: `SQL` for rules that hold in every dialect, `SQLCH` for the
+ * ClickHouse dialect's (#3199), `SQLPG` for Postgres's (#3289).
+ */
+
+import type { Declarable, Serializer, SerializerResult } from "@intentius/chant";
+import type { SerializeContext } from "@intentius/chant/serializer";
+import { isAttrRefLike } from "@intentius/chant/utils";
+import { isClickHouseObject, type ClickHouseObject } from "./clickhouse/entities";
+import { isPostgresObject, type PostgresObject } from "./postgres/entities";
+import { POSTGRES_LATEST_MAJOR } from "./spec/postgres-pin";
+import { applyOrder, lineageJson, referenceName, type LineageEdge } from "./core/references";
+
+export { applyOrder } from "./core/references";
+
+/** The file the statements are written to, beside the primary output. */
+export const CLICKHOUSE_DDL_FILE = "clickhouse.sql";
+
+/** The Postgres statements' file, beside the primary output. */
+export const POSTGRES_DDL_FILE = "postgres.sql";
+
+function objectJson(name: string, obj: ClickHouseObject, names: Map<Declarable, string>): Record<string, unknown> {
+  const props = { ...(obj.props as Record<string, unknown>) };
+  delete props.source;
+  const ddl = props.ddl;
+  delete props.ddl;
+  if (props.reads) props.reads = (props.reads as unknown[]).map((r) => referenceName(r, names) ?? null);
+  if (props.to !== undefined && typeof props.to !== "string") props.to = referenceName(props.to, names) ?? null;
+  if (props.lineage) {
+    props.lineage = lineageJson(props.lineage as LineageEdge[], names);
+  }
+  const dependsOn = [...new Set(obj.dependsOn.map((r) => referenceName(r, names)).filter((n) => n !== undefined))];
+  return JSON.parse(
+    JSON.stringify({ export: name, type: obj.entityType, sqlName: obj.sqlName, ...props, dependsOn, ddl }),
+  ) as Record<string, unknown>;
+}
+
+/** A props value with every entity and column reference in it written as its export name (`users`, `users.id`). */
+function postgresJsonValue(v: unknown, names: Map<Declarable, string>): unknown {
+  if (isPostgresObject(v) || isAttrRefLike(v)) return referenceName(v, names) ?? null;
+  if (Array.isArray(v)) return v.map((x) => postgresJsonValue(x, names));
+  if (v !== null && typeof v === "object") return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, postgresJsonValue(x, names)]));
+  return v;
+}
+
+function postgresObjectJson(name: string, obj: PostgresObject, names: Map<Declarable, string>): Record<string, unknown> {
+  const props = { ...(obj.props as Record<string, unknown>) };
+  delete props.source;
+  const ddl = props.ddl;
+  delete props.ddl;
+  const dependsOn = [...new Set(obj.dependsOn.map((r) => referenceName(r, names)).filter((n) => n !== undefined))];
+  return JSON.parse(
+    JSON.stringify({ export: name, type: obj.entityType, sqlName: obj.sqlName, ...(postgresJsonValue(props, names) as object), dependsOn, ddl }),
+  ) as Record<string, unknown>;
+}
+
+/** The Postgres major the build targets: `sql.postgresMajor`, else the newest pinned major. */
+function targetMajor(config: Record<string, unknown> | undefined): number {
+  const m = (config?.sql as { postgresMajor?: unknown } | undefined)?.postgresMajor;
+  return typeof m === "number" ? m : POSTGRES_LATEST_MAJOR;
+}
+
+function serializePostgres(
+  objects: Map<string, PostgresObject>,
+  entities: Map<string, Declarable>,
+  config?: Record<string, unknown>,
+): SerializerResult {
+  const names = new Map<Declarable, string>();
+  for (const [name, entity] of entities) names.set(entity, name);
+  const order = applyOrder(objects, names);
+  const doc = {
+    dialect: "postgres",
+    postgresMajor: targetMajor(config),
+    applyOrder: order,
+    objects: order.map((n) => postgresObjectJson(n, objects.get(n)!, names)),
+  };
+  const ddl = order.map((n) => `${(objects.get(n)!.props as { ddl: string }).ddl};`).join("\n\n");
+  return {
+    primary: `${JSON.stringify(doc, null, 2)}\n`,
+    files: { [POSTGRES_DDL_FILE]: `${ddl}\n` },
+    verbatimFiles: [POSTGRES_DDL_FILE],
+  };
+}
+
+export const sqlSerializer: Serializer = {
+  name: "sql",
+  rulePrefix: "SQL",
+
+  serialize(entities: Map<string, Declarable>, _outputs?: unknown, context?: SerializeContext): string | SerializerResult {
+    const objects = new Map<string, ClickHouseObject>();
+    const postgres = new Map<string, PostgresObject>();
+    for (const [name, entity] of entities) {
+      if (isClickHouseObject(entity)) objects.set(name, entity);
+      else if (isPostgresObject(entity)) postgres.set(name, entity);
+    }
+    if (objects.size > 0 && postgres.size > 0) {
+      throw new Error(
+        `sql: one build holds one dialect, and this one declares ClickHouse (${[...objects.keys()][0]}) and Postgres (${[...postgres.keys()][0]}) objects; ` +
+          "declare each database in its own project",
+      );
+    }
+    if (postgres.size > 0) return serializePostgres(postgres, entities, context?.config);
+    if (objects.size === 0) return "";
+
+    const names = new Map<Declarable, string>();
+    for (const [name, entity] of entities) names.set(entity, name);
+
+    const order = applyOrder(objects, names);
+    const doc = {
+      dialect: "clickhouse",
+      applyOrder: order,
+      objects: order.map((n) => objectJson(n, objects.get(n)!, names)),
+    };
+    const ddl = order
+      .map((n) => `${(objects.get(n)!.props as { ddl: string }).ddl};`)
+      .join("\n\n");
+    return {
+      primary: `${JSON.stringify(doc, null, 2)}\n`,
+      files: { [CLICKHOUSE_DDL_FILE]: `${ddl}\n` },
+      verbatimFiles: [CLICKHOUSE_DDL_FILE],
+    };
+  },
+};