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

package/src/lint/rules/sqlch002.ts

@@ -0,0 +1,115 @@
+import type { LintContext, LintDiagnostic, LintRule } from "@intentius/chant/lint/rule";
+import { parseCreate, unquote, type ColumnNode, type CreateNode, type Span } from "../../clickhouse/parser";
+import { isTrivia, SqlSyntaxError, type Token } from "../../clickhouse/tokens";
+import { findTemplates, tokenPosition, tokensOf } from "./templates";
+
+/** The column's type, as written, reads `Nullable(...)`, also inside `LowCardinality(...)`. */
+function isNullable(tokens: Token[], c: ColumnNode): boolean {
+  if (c.nullable === true) return true;
+  if (!c.type) return false;
+  const words = tokens.slice(c.type.from, c.type.to).filter((t) => t.kind === "ident").map((t) => t.text.toLowerCase());
+  return words[0] === "nullable" || (words[0] === "lowcardinality" && words[1] === "nullable");
+}
+
+/**
+ * The column names a key names as a key part: bare, or inside the key's tuple
+ * parentheses, not an argument of a function (`ifNull(a, '')` makes a
+ * non-Nullable key part of a Nullable column) and not a qualified part.
+ */
+function keyColumns(tokens: Token[], span: Span): Array<{ name: string; token: Token }> {
+  const sig = tokens.slice(span.from, span.to).filter((t) => !isTrivia(t));
+  const out: Array<{ name: string; token: Token }> = [];
+  const frames: boolean[] = []; // true for a function call's parentheses
+  sig.forEach((t, i) => {
+    const prev = sig[i - 1];
+    if (t.kind === "punct" && t.text === "(") {
+      frames.push(prev !== undefined && (prev.kind === "ident" || prev.kind === "qident"));
+      return;
+    }
+    if (t.kind === "punct" && t.text === ")") {
+      frames.pop();
+      return;
+    }
+    if (t.kind !== "ident" && t.kind !== "qident") return;
+    if (frames.includes(true)) return;
+    const next = sig[i + 1];
+    if (next?.kind === "punct" && next.text === "(") return;
+    if (prev?.kind === "punct" && prev.text === ".") return;
+    out.push({ name: unquote(t.text), token: t });
+  });
+  return out;
+}
+
+function allowsNullableKey(tokens: Token[], node: CreateNode): boolean {
+  if (node.statement === "database" || !node.settings) return false;
+  const s = node.settings.find((x) => x.key === "allow_nullable_key");
+  if (!s) return false;
+  const v = tokens.slice(s.value.from, s.value.to).map((t) => t.text).join("").trim().toLowerCase().replace(/'/g, "");
+  return v === "1" || v === "true";
+}
+
+/**
+ * SQLCH002: a `Nullable` column in a table's sort key or primary key.
+ *
+ * ClickHouse refuses to create the table ("Sorting key contains nullable
+ * columns") unless the table sets `allow_nullable_key = 1`, and with it a
+ * `NULL` sorts as a value of its own. The rule reads the types written in the
+ * column list; a key over a column of an inferred type is left to the server.
+ */
+export const sqlch002: LintRule = {
+  id: "SQLCH002",
+  severity: "error",
+  category: "correctness",
+  description: "A Nullable column in a ClickHouse sort key or primary key",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const source = context.sourceFile;
+    const out: LintDiagnostic[] = [];
+    for (const found of findTemplates(source)) {
+      const tokens = tokensOf(found);
+      let node: CreateNode;
+      try {
+        node = parseCreate(tokens);
+      } catch (err) {
+        if (err instanceof SqlSyntaxError) continue; // SQLCH001 reports it
+        throw err;
+      }
+      if (node.statement === "database" || allowsNullableKey(tokens, node)) continue;
+      const nullable = new Set(node.columns.filter((c) => c.name && isNullable(tokens, c)).map((c) => c.name));
+      if (nullable.size === 0) continue;
+      const reported = new Set<string>();
+      for (const [clause, span] of [
+        ["sort key", node.orderBy],
+        ["primary key", node.primaryKey],
+      ] as const) {
+        if (!span) continue;
+        for (const { name, token } of keyColumns(tokens, span)) {
+          if (!nullable.has(name) || reported.has(`${clause}:${name}`)) continue;
+          reported.add(`${clause}:${name}`);
+          out.push({
+            ruleId: "SQLCH002",
+            severity: "error",
+            message:
+              `column "${name}" is Nullable and is in the ${clause}; ClickHouse refuses this unless the table ` +
+              "sets allow_nullable_key = 1. Make the column non-Nullable (a default such as '' or 0 in place of NULL), " +
+              "or drop it from the key",
+            file: context.filePath,
+            ...tokenPosition(source, found, token),
+          });
+        }
+      }
+      for (const c of node.columns) {
+        if (c.primaryKey && nullable.has(c.name)) {
+          out.push({
+            ruleId: "SQLCH002",
+            severity: "error",
+            message: `column "${c.name}" is Nullable and is declared PRIMARY KEY; ClickHouse refuses this unless the table sets allow_nullable_key = 1`,
+            file: context.filePath,
+            ...tokenPosition(source, found, tokens[c.nameSpan.from]!),
+          });
+        }
+      }
+    }
+    return out;
+  },
+};

package/src/lint/rules/sqlch003.ts

@@ -0,0 +1,68 @@
+import * as ts from "typescript";
+import type { LintContext, LintDiagnostic, LintRule } from "@intentius/chant/lint/rule";
+import { findTemplates } from "./templates";
+
+/** The entity's own members: an interpolation of one of them is never a column. */
+const OWN_MEMBERS = new Set(["kind", "lexicon", "entityType", "props", "sqlName", "dependsOn"]);
+
+/**
+ * Identifiers that hold a ClickHouse entity, as far as one file can tell:
+ * bound to a sql tag here, or imported from another file of the project.
+ */
+function entityBindings(source: ts.SourceFile, tagged: Set<ts.Node>): Set<string> {
+  const out = new Set<string>();
+  for (const stmt of source.statements) {
+    if (ts.isImportDeclaration(stmt) && ts.isStringLiteral(stmt.moduleSpecifier) && stmt.moduleSpecifier.text.startsWith(".")) {
+      const named = stmt.importClause?.namedBindings;
+      if (named && ts.isNamedImports(named)) for (const el of named.elements) out.add(el.name.text);
+    }
+    if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(d.name) && d.initializer && tagged.has(d.initializer)) out.add(d.name.text);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * SQLCH003: a column written as `${events.kind}` instead of `${events.columns.kind}`.
+ *
+ * Columns are reached through `.columns`. `kind`, `lexicon`, `entityType`,
+ * `props`, `sqlName` and `dependsOn` are the entity's own fields, so
+ * `${events.kind}` is the string `"resource"`, which the tag splices in as SQL
+ * text: the statement builds and means something else. This rule flags it for
+ * an entity the file declares or imports from another project file.
+ */
+export const sqlch003: LintRule = {
+  id: "SQLCH003",
+  severity: "error",
+  category: "correctness",
+  description: "A column interpolated without .columns reads the entity's own field instead",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const source = context.sourceFile;
+    const found = findTemplates(source);
+    if (found.length === 0) return [];
+    const entities = entityBindings(source, new Set(found.map((f) => f.node)));
+    const out: LintDiagnostic[] = [];
+    for (const f of found) {
+      for (const expr of f.expressions) {
+        if (!ts.isPropertyAccessExpression(expr) || !ts.isIdentifier(expr.expression)) continue;
+        const owner = expr.expression.text;
+        const member = expr.name.text;
+        if (!entities.has(owner) || !OWN_MEMBERS.has(member)) continue;
+        const { line, character } = source.getLineAndCharacterOfPosition(expr.getStart(source));
+        out.push({
+          ruleId: "SQLCH003",
+          severity: "error",
+          message: `\${${owner}.${member}} is the entity's own "${member}" field, not a column; write \${${owner}.columns.${member}}`,
+          file: context.filePath,
+          line: line + 1,
+          column: character + 1,
+        });
+      }
+    }
+    return out;
+  },
+};

package/src/lint/rules/sqlpg001.ts

@@ -0,0 +1,88 @@
+import type { LintContext, LintDiagnostic, LintRule } from "@intentius/chant/lint/rule";
+import { parseStatements, SqlSyntaxError } from "../../postgres/parser";
+import { STATEMENT_NAMES, type PostgresTag } from "../../postgres/entities";
+import { findPostgresTemplates, postgresTokensOf, templatePosition, tokenPosition } from "./postgres-templates";
+
+/** The statement each tag holds. */
+const STATEMENT: Record<PostgresTag, string> = {
+  schema: "schema",
+  table: "table",
+  index: "index",
+  view: "view",
+  sequence: "sequence",
+  type: "enum",
+  domain: "domain",
+  extension: "extension",
+};
+
+const TAG_OF: Record<string, PostgresTag> = Object.fromEntries(Object.entries(STATEMENT).map(([tag, statement]) => [statement, tag as PostgresTag]));
+
+/**
+ * SQLPG001: the DDL in a Postgres template does not parse, or does not hold
+ * what its tag declares.
+ *
+ * The same parse runs when the build calls the tag, and fails the build there.
+ * This rule reports it in the editor and in `chant lint`, at the token, as a
+ * line and column of the `.ts` file, before anything is built. It also reports
+ * what the tag refuses after parsing: another statement than the tag's, a
+ * second CREATE in one template, and an index with no name (its name is its
+ * identity on the server). Interpolations are references here, since lint
+ * cannot know their values, so an error inside text a string interpolation
+ * supplies is left to the build.
+ */
+export const sqlpg001: LintRule = {
+  id: "SQLPG001",
+  severity: "error",
+  category: "correctness",
+  description: "Postgres DDL in a tagged template does not parse, or holds another statement than its tag",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const source = context.sourceFile;
+    const out: LintDiagnostic[] = [];
+    const report = (message: string, at: { line: number; column: number }) =>
+      out.push({ ruleId: "SQLPG001", severity: "error", message, file: context.filePath, ...at });
+    for (const found of findPostgresTemplates(source)) {
+      const tokens = (() => {
+        try {
+          return postgresTokensOf(found);
+        } catch (err) {
+          if (!(err instanceof SqlSyntaxError)) throw err;
+          report(`Postgres DDL does not parse: ${err.message}`, templatePosition(source, found, err.part, err.offset));
+          return undefined;
+        }
+      })();
+      if (!tokens) continue;
+      try {
+        const [node, ...rest] = parseStatements(tokens);
+        if (node!.statement !== STATEMENT[found.tag]) {
+          const use = TAG_OF[node!.statement];
+          report(
+            use
+              ? `${found.tag}\`...\` holds a ${STATEMENT_NAMES[node!.statement]}; use the ${use} tag`
+              : `${found.tag}\`...\` starts with a COMMENT ON; it goes after the CREATE it comments on`,
+            templatePosition(source, found, 0, 0),
+          );
+          continue;
+        }
+        const stray = rest.find((n) => n.statement !== "comment");
+        if (stray) {
+          report(
+            `${found.tag}\`...\` holds a second statement (${STATEMENT_NAMES[stray.statement]}); a template declares one object, followed only by COMMENT ON statements for it`,
+            templatePosition(source, found, 0, 0),
+          );
+        }
+        if (node!.statement === "index" && !node!.name) {
+          const on = tokens.find((t) => t.kind === "ident" && t.text.toUpperCase() === "ON");
+          report(
+            "an index needs a name: the name is its identity on the server, and an unnamed index gets a generated one",
+            on ? tokenPosition(source, found, on) : templatePosition(source, found, 0, 0),
+          );
+        }
+      } catch (err) {
+        if (!(err instanceof SqlSyntaxError)) throw err;
+        report(`Postgres DDL does not parse: ${err.message}`, err.token ? tokenPosition(source, found, err.token) : templatePosition(source, found, err.part, err.offset));
+      }
+    }
+    return out;
+  },
+};

package/src/lint/rules/sqlpg002.ts

@@ -0,0 +1,68 @@
+import * as ts from "typescript";
+import type { LintContext, LintDiagnostic, LintRule } from "@intentius/chant/lint/rule";
+import { findPostgresTemplates as findTemplates } from "./postgres-templates";
+
+/** The entity's own members: an interpolation of one of them is never a column. */
+const OWN_MEMBERS = new Set(["kind", "lexicon", "entityType", "props", "sqlName", "dependsOn"]);
+
+/**
+ * Identifiers that hold a Postgres entity, as far as one file can tell:
+ * bound to a sql tag here, or imported from another file of the project.
+ */
+function entityBindings(source: ts.SourceFile, tagged: Set<ts.Node>): Set<string> {
+  const out = new Set<string>();
+  for (const stmt of source.statements) {
+    if (ts.isImportDeclaration(stmt) && ts.isStringLiteral(stmt.moduleSpecifier) && stmt.moduleSpecifier.text.startsWith(".")) {
+      const named = stmt.importClause?.namedBindings;
+      if (named && ts.isNamedImports(named)) for (const el of named.elements) out.add(el.name.text);
+    }
+    if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(d.name) && d.initializer && tagged.has(d.initializer)) out.add(d.name.text);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * SQLPG002: a column written as `${events.kind}` instead of `${events.columns.kind}`.
+ *
+ * Columns are reached through `.columns`. `kind`, `lexicon`, `entityType`,
+ * `props`, `sqlName` and `dependsOn` are the entity's own fields, so
+ * `${events.kind}` is the string `"resource"`, which the tag splices in as SQL
+ * text: the statement builds and means something else. This rule flags it for
+ * an entity the file declares or imports from another project file.
+ */
+export const sqlpg002: LintRule = {
+  id: "SQLPG002",
+  severity: "error",
+  category: "correctness",
+  description: "A column interpolated without .columns reads the entity's own field instead",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const source = context.sourceFile;
+    const found = findTemplates(source);
+    if (found.length === 0) return [];
+    const entities = entityBindings(source, new Set(found.map((f) => f.node)));
+    const out: LintDiagnostic[] = [];
+    for (const f of found) {
+      for (const expr of f.expressions) {
+        if (!ts.isPropertyAccessExpression(expr) || !ts.isIdentifier(expr.expression)) continue;
+        const owner = expr.expression.text;
+        const member = expr.name.text;
+        if (!entities.has(owner) || !OWN_MEMBERS.has(member)) continue;
+        const { line, character } = source.getLineAndCharacterOfPosition(expr.getStart(source));
+        out.push({
+          ruleId: "SQLPG002",
+          severity: "error",
+          message: `\${${owner}.${member}} is the entity's own "${member}" field, not a column; write \${${owner}.columns.${member}}`,
+          file: context.filePath,
+          line: line + 1,
+          column: character + 1,
+        });
+      }
+    }
+    return out;
+  },
+};

package/src/lint/rules/sqlpg003.ts

@@ -0,0 +1,59 @@
+import type { LintContext, LintDiagnostic, LintRule } from "@intentius/chant/lint/rule";
+import { isTrivia, SqlSyntaxError } from "../../postgres/tokens";
+import { findPostgresTemplates, postgresTokensOf, tokenPosition } from "./postgres-templates";
+
+const REGCLASS_FUNCTIONS = ["NEXTVAL", "CURRVAL", "SETVAL"];
+
+/**
+ * SQLPG003: an object named in a string where Postgres reads a `regclass`:
+ * `nextval('app.ticket_seq')`, `currval(...)`, `setval(...)`, or
+ * `'app.ticket_seq'::regclass`.
+ *
+ * A name inside a string is text to the build, so it records no reference:
+ * the table does not depend on the sequence, the creation order can put the
+ * table first, and the create fails. Interpolating the object instead,
+ * `nextval(${ticketSeq})`, renders the same `regclass` literal the catalog
+ * prints (`nextval('app.ticket_seq'::regclass)`) and keeps the edge. A
+ * sequence another tool owns is the exception, which is why this is a
+ * warning.
+ */
+export const sqlpg003: LintRule = {
+  id: "SQLPG003",
+  severity: "warning",
+  category: "correctness",
+  description: "A sequence or relation named in a regclass string makes no reference; interpolate the object",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const source = context.sourceFile;
+    const out: LintDiagnostic[] = [];
+    for (const found of findPostgresTemplates(source)) {
+      let tokens;
+      try {
+        tokens = postgresTokensOf(found);
+      } catch (err) {
+        if (err instanceof SqlSyntaxError) continue;
+        throw err;
+      }
+      const sig = tokens.filter((t) => !isTrivia(t));
+      sig.forEach((t, k) => {
+        if (t.kind !== "string" || !t.text.startsWith("'")) return;
+        const prev = sig[k - 1];
+        const fn = sig[k - 2];
+        const inCall =
+          prev?.kind === "punct" && prev.text === "(" && fn?.kind === "ident" && REGCLASS_FUNCTIONS.includes(fn.text.toUpperCase());
+        const cast = sig[k + 1]?.kind === "op" && sig[k + 1]!.text === "::" && sig[k + 2]?.kind === "ident" && sig[k + 2]!.text.toLowerCase() === "regclass";
+        if (!inCall && !cast) return;
+        const named = t.text.slice(1, -1).replace(/''/g, "'");
+        const how = inCall ? `${fn!.text}(\${...})` : "${...}::regclass";
+        out.push({
+          ruleId: "SQLPG003",
+          severity: "warning",
+          message: `'${named}' names an object in a string, which records no reference, so the build can create this object before it; interpolate the declared object instead: ${how}`,
+          file: context.filePath,
+          ...tokenPosition(source, found, t),
+        });
+      });
+    }
+    return out;
+  },
+};

package/src/lint/rules/sqlpg004.ts

@@ -0,0 +1,73 @@
+import type { LintContext, LintDiagnostic, LintRule } from "@intentius/chant/lint/rule";
+import { isTrivia, SqlSyntaxError, type Token } from "../../postgres/tokens";
+import { isPostgresProvider, providerAllowsExtension, providerData } from "../../postgres/providers";
+import type { PostgresProvider } from "../../postgres/providers";
+import { findPostgresTemplates, postgresTokensOf, tokenPosition } from "./postgres-templates";
+
+/**
+ * The provider a lint run is for: `sql.provider`, else the one provider every
+ * profile that names one agrees on. No answer (self-hosted, or profiles that
+ * disagree) leaves the rule silent. The lint engine passes the whole project
+ * config as `projectConfig`.
+ */
+export function providerFromConfig(config: unknown): PostgresProvider | undefined {
+  const sql = (config as { sql?: { provider?: unknown; profiles?: Record<string, { provider?: unknown }> } } | undefined)?.sql;
+  if (!sql) return undefined;
+  if (isPostgresProvider(sql.provider)) return sql.provider;
+  const named = new Set(Object.values(sql.profiles ?? {}).map((p) => p.provider).filter(isPostgresProvider));
+  return named.size === 1 ? [...named][0] : undefined;
+}
+
+const unquote = (t: Token): string => (t.kind === "qident" ? t.text.slice(1, -1).replace(/""/g, '"') : t.text.toLowerCase());
+
+/**
+ * SQLPG004: a declared extension the configured provider does not allow.
+ *
+ * `extension\`CREATE EXTENSION pg_stat_monitor\`` builds, and fails when
+ * applied to a provider whose list lacks it. The lists are the providers'
+ * documentation snapshots (see postgres/providers/types.ts), so a provider
+ * that added an extension since reports it here until the list is refreshed;
+ * disable the rule for that line. When a provider's list is partial, a name
+ * outside it is not reported.
+ */
+export const sqlpg004: LintRule = {
+  id: "SQLPG004",
+  severity: "error",
+  category: "correctness",
+  description: "A declared extension the configured Postgres provider does not allow",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const provider = providerFromConfig(context.projectConfig);
+    if (!provider) return [];
+    const label = providerData(provider).label;
+    const source = context.sourceFile;
+    const out: LintDiagnostic[] = [];
+    for (const found of findPostgresTemplates(source)) {
+      if (found.tag !== "extension") continue;
+      let tokens: Token[];
+      try {
+        tokens = postgresTokensOf(found);
+      } catch (err) {
+        if (err instanceof SqlSyntaxError) continue;
+        throw err;
+      }
+      const sig = tokens.filter((t) => !isTrivia(t));
+      const word = (k: number) => (sig[k]?.kind === "ident" ? sig[k]!.text.toUpperCase() : "");
+      if (word(0) !== "CREATE" || word(1) !== "EXTENSION") continue;
+      let k = 2;
+      if (word(k) === "IF" && word(k + 1) === "NOT" && word(k + 2) === "EXISTS") k += 3;
+      const nameToken = sig[k];
+      if (!nameToken || (nameToken.kind !== "ident" && nameToken.kind !== "qident")) continue;
+      const name = unquote(nameToken);
+      if (providerAllowsExtension(provider, name) !== false) continue;
+      out.push({
+        ruleId: "SQLPG004",
+        severity: "error",
+        message: `${label} does not allow the extension "${name}"; CREATE EXTENSION would fail there. Use an extension it lists, or change sql.provider`,
+        file: context.filePath,
+        ...tokenPosition(source, found, nameToken),
+      });
+    }
+    return out;
+  },
+};

package/src/lint/rules/templates.ts

@@ -0,0 +1,35 @@
+/**
+ * Finding the ClickHouse tags in a source file, for the source-level rules
+ * (and the editor). A rule reads the template's raw parts straight from the
+ * TypeScript AST and parses them the way the tag does, with every
+ * interpolation left a reference: lint cannot know the values. The finder is
+ * the shared core's (`../../core/find-templates.ts`); a tag is ClickHouse's
+ * because of the module it is imported from.
+ */
+
+import type * as ts from "typescript";
+import { tokenize, type Token } from "../../clickhouse/tokens";
+import { findSqlTemplates, type FoundTemplate as SqlFoundTemplate, type TemplateSource } from "../../core/find-templates";
+
+export { templatePosition, tokenPosition } from "../../core/find-templates";
+
+export type SqlTag = "database" | "table" | "view";
+
+/**
+ * The ClickHouse tags, by the modules they are imported from. The package
+ * root still exports them, so it counts as ClickHouse too.
+ */
+export const CLICKHOUSE_TEMPLATE_SOURCE: TemplateSource<SqlTag> = {
+  dialect: "clickhouse",
+  modules: ["@intentius/chant-lexicon-sql", "@intentius/chant-lexicon-sql/clickhouse"],
+  tags: ["database", "table", "view"],
+};
+
+export type FoundTemplate = SqlFoundTemplate<SqlTag>;
+
+/** Every ClickHouse template in the file (the shared core's finder). */
+export function findTemplates(source: ts.SourceFile): FoundTemplate[] {
+  return findSqlTemplates(source, [CLICKHOUSE_TEMPLATE_SOURCE]);
+}
+
+export const tokensOf = (found: FoundTemplate): Token[] => tokenize(found.parts);

package/src/live-dialect.ts

@@ -0,0 +1,37 @@
+/**
+ * Which dialect a live read is for. A build holds one dialect, so a read of
+ * declared entities follows their types; a read with nothing declared (import)
+ * follows the binding: the environment's profile URL (`postgres://` is
+ * Postgres), else `sql.dialect`, else whichever of `POSTGRES_URL` and
+ * `CLICKHOUSE_URL` is set, else ClickHouse, the first dialect.
+ */
+
+import type { ChantConfig } from "@intentius/chant/config";
+import type { SqlDialect } from "./dialects";
+import { isPostgresUrl, loadSqlConfig } from "./postgres/live/bind";
+
+export function dialectOfEntities(entities: ReadonlyMap<string, { entityType: string }> | undefined): SqlDialect {
+  for (const e of entities?.values() ?? []) if (e.entityType.startsWith("Postgres::")) return "postgres";
+  return "clickhouse";
+}
+
+export function dialectOfBinding(input: {
+  environment?: string;
+  config?: Pick<ChantConfig, "sql">;
+  env?: Record<string, string | undefined>;
+}): SqlDialect {
+  const env = input.env ?? process.env;
+  const profile = input.environment !== undefined ? input.config?.sql?.profiles?.[input.environment] : undefined;
+  if (profile) return isPostgresUrl(profile.url) ? "postgres" : "clickhouse";
+  const configured = input.config?.sql?.dialect;
+  const named = Array.isArray(configured) ? (configured.length === 1 ? configured[0] : undefined) : configured;
+  if (named) return named;
+  if (env.POSTGRES_URL && !env.CLICKHOUSE_URL) return "postgres";
+  return "clickhouse";
+}
+
+/** The binding's dialect, loading the project config from `cwd` when none is passed. */
+export async function resolveBindingDialect(options: { environment?: string; config?: Pick<ChantConfig, "sql">; cwd?: string; env?: Record<string, string | undefined> }): Promise<SqlDialect> {
+  const config = options.config ?? (await loadSqlConfig(options.cwd ?? process.cwd()));
+  return dialectOfBinding({ environment: options.environment, config, env: options.env });
+}

package/src/lsp/catalog.ts

@@ -0,0 +1,60 @@
+/**
+ * The ClickHouse catalog the editor and the MCP tools read: the committed
+ * snapshot of the pinned server's `system.*` tables, parsed once and indexed
+ * by name. No server is needed; the snapshot is what generation reads too.
+ */
+
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { parseCatalog, type ClickHouseCatalog, type SettingRow } from "../spec/catalog";
+
+const SNAPSHOT = join(dirname(fileURLToPath(import.meta.url)), "..", "spec", "clickhouse-catalog.snapshot.json");
+
+export interface CatalogIndex {
+  catalog: ClickHouseCatalog;
+  /** Name lookups. Names a server treats case-insensitively are also keyed lowercased. */
+  engines: Map<string, ClickHouseCatalog["tableEngines"][number]>;
+  databaseEngines: Map<string, ClickHouseCatalog["databaseEngines"][number]>;
+  types: Map<string, ClickHouseCatalog["typeFamilies"][number]>;
+  codecs: Map<string, ClickHouseCatalog["codecs"][number]>;
+  indexTypes: Map<string, ClickHouseCatalog["skipIndexTypes"][number]>;
+  mergeTreeSettings: Map<string, SettingRow>;
+  querySettings: Map<string, SettingRow>;
+  functions: Map<string, ClickHouseCatalog["functions"][number]>;
+  formats: Map<string, ClickHouseCatalog["formats"][number]>;
+}
+
+let cached: CatalogIndex | null = null;
+
+const byName = <T extends { name: string }>(rows: readonly T[], foldCase?: (row: T) => boolean): Map<string, T> => {
+  const map = new Map<string, T>();
+  for (const row of rows) {
+    map.set(row.name, row);
+    if (foldCase?.(row)) map.set(row.name.toLowerCase(), row);
+  }
+  return map;
+};
+
+/** The catalog, or undefined when the snapshot cannot be read. */
+export function catalogIndex(): CatalogIndex | undefined {
+  if (cached) return cached;
+  try {
+    const catalog = parseCatalog(readFileSync(SNAPSHOT, "utf-8"));
+    cached = {
+      catalog,
+      engines: byName(catalog.tableEngines),
+      databaseEngines: byName(catalog.databaseEngines),
+      types: byName(catalog.typeFamilies, (t) => t.caseInsensitive),
+      codecs: byName(catalog.codecs),
+      indexTypes: byName(catalog.skipIndexTypes),
+      mergeTreeSettings: byName(catalog.mergeTreeSettings),
+      querySettings: byName(catalog.querySettings),
+      functions: byName(catalog.functions, (f) => f.caseInsensitive),
+      formats: byName(catalog.formats),
+    };
+    return cached;
+  } catch {
+    return undefined;
+  }
+}