@intentius/chant-lexicon-sql 0.116.0 → 0.118.0

package/src/postgres/plan/server-normalize.ts

@@ -8,7 +8,10 @@
  * (`CREATE TEMP VIEW`, or a `CREATE TEMP TABLE` holding the columns' types,
  * defaults and generated expressions and the checks) inside a transaction
  * that is always rolled back, with a short `lock_timeout`, and read back with
- * the same printers the catalog read uses. Nothing is left behind: Postgres
+ * the same printers the catalog read uses. A trigger's `WHEN` and a policy's
+ * `USING` and `WITH CHECK`, which the server prints with the casts it
+ * resolved, are read back from a trigger or policy on a temporary copy of the
+ * table (`CREATE TEMP TABLE ... (LIKE table)`). Nothing is left behind: Postgres
  * DDL is transactional and a temporary object lives in the session's own
  * schema. A server that refuses (no TEMP privilege, a lock not granted in
  * time, an expression it rejects) leaves the rules' answer standing.
@@ -108,6 +111,27 @@ async function triggerWhen(client: PostgresClient, o: CanonicalPgObject, default
   });
 }
 
+/** A policy's USING and WITH CHECK as the server prints them, canonical, from a policy on a temporary copy of its table. */
+async function policyExpressions(client: PostgresClient, o: CanonicalPgObject, defaultSchema: string): Promise<{ using?: string; check?: string } | undefined> {
+  const using = o.fields.using as string | undefined;
+  const check = o.fields.check as string | undefined;
+  if (using === undefined && check === undefined) return undefined;
+  return rolledBack(client, defaultSchema, async () => {
+    await client.query(`CREATE TEMP TABLE chant_normalize (LIKE ${String(o.fields.table)})`);
+    await client.query(
+      [`CREATE POLICY chant_normalize ON pg_temp.chant_normalize FOR ${String(o.fields.command ?? "all").toUpperCase()}`, using !== undefined ? `USING (${using})` : "", check !== undefined ? `WITH CHECK (${check})` : ""]
+        .filter(Boolean)
+        .join(" "),
+    );
+    await emptyPath(client);
+    const [row] = await client.query<Row>(
+      `SELECT pg_catalog.pg_get_expr(p.polqual, p.polrelid, true) AS qual, pg_catalog.pg_get_expr(p.polwithcheck, p.polrelid, true) AS withcheck
+       FROM pg_catalog.pg_policy p WHERE p.polrelid = 'pg_temp.chant_normalize'::pg_catalog.regclass`,
+    );
+    return { ...(row?.qual ? { using: canonicalExpr(String(row.qual)) } : {}), ...(row?.withcheck ? { check: canonicalExpr(String(row.withcheck)) } : {}) };
+  });
+}
+
 /**
  * The declared object with its expressions in the server's own printing,
  * when the server answers; the object unchanged otherwise. Only the
@@ -119,6 +143,10 @@ export async function serverNormalized<T extends CanonicalPgObject & { outputs?:
     // A declared column list names the outputs; otherwise the server's names do (`SELECT *` expanded).
     return q === undefined ? o : { ...o, fields: { ...o.fields, query: q.query }, ...(o.fields.columns === undefined ? { outputs: q.outputs } : {}) };
   }
+  if (o.kind === "policy") {
+    const e = await policyExpressions(client, o, defaultSchema);
+    return e === undefined ? o : { ...o, fields: { ...o.fields, ...e } };
+  }
   if (o.kind === "trigger") {
     const when = await triggerWhen(client, o, defaultSchema);
     return when === undefined ? o : { ...o, fields: { ...o.fields, when } };

package/src/postgres.ts

@@ -18,6 +18,9 @@ export {
   func,
   procedure,
   trigger,
+  policy,
+  role,
+  grant,
   literal,
   SqlLiteral,
   SqlTemplateError,
@@ -39,6 +42,9 @@ export {
   type PostgresFunction,
   type PostgresProcedure,
   type PostgresTrigger,
+  type PostgresPolicy,
+  type PostgresRole,
+  type PostgresGrant,
   type ColumnDef,
   type KeyDef,
   type CheckDef,
@@ -57,6 +63,11 @@ export {
   type FunctionProps,
   type ProcedureProps,
   type TriggerProps,
+  type PolicyProps,
+  type RoleProps,
+  type GrantProps,
+  type DefaultPrivilegesProps,
+  type PrivilegeDef,
   type LineageEdge,
 } from "./postgres/entities";
 

package/src/serializer.ts

@@ -12,7 +12,8 @@
  *
  * 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
+ * database. An object read from a `.sql` file (`./sql-files.ts`) that a
+ * template names in its text counts as referenced too. 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
@@ -35,6 +36,7 @@ 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";
+import { sqlFileReferences } from "./sql-files";
 
 export { applyOrder } from "./core/references";
 
@@ -44,7 +46,7 @@ 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> {
+function objectJson(name: string, obj: ClickHouseObject, names: Map<Declarable, string>, extra: readonly string[] = []): Record<string, unknown> {
   const props = { ...(obj.props as Record<string, unknown>) };
   delete props.source;
   const ddl = props.ddl;
@@ -54,7 +56,7 @@ function objectJson(name: string, obj: ClickHouseObject, names: Map<Declarable,
   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))];
+  const dependsOn = [...new Set([...obj.dependsOn.map((r) => referenceName(r, names)).filter((n) => n !== undefined), ...extra])];
   return JSON.parse(
     JSON.stringify({ export: name, type: obj.entityType, sqlName: obj.sqlName, ...props, dependsOn, ddl }),
   ) as Record<string, unknown>;
@@ -68,12 +70,12 @@ function postgresJsonValue(v: unknown, names: Map<Declarable, string>): unknown
   return v;
 }
 
-function postgresObjectJson(name: string, obj: PostgresObject, names: Map<Declarable, string>): Record<string, unknown> {
+function postgresObjectJson(name: string, obj: PostgresObject, names: Map<Declarable, string>, extra: readonly 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))];
+  const dependsOn = [...new Set([...obj.dependsOn.map((r) => referenceName(r, names)).filter((n) => n !== undefined), ...extra])];
   return JSON.parse(
     JSON.stringify({ export: name, type: obj.entityType, sqlName: obj.sqlName, ...(postgresJsonValue(props, names) as object), dependsOn, ddl }),
   ) as Record<string, unknown>;
@@ -92,12 +94,14 @@ function serializePostgres(
 ): SerializerResult {
   const names = new Map<Declarable, string>();
   for (const [name, entity] of entities) names.set(entity, name);
-  const order = applyOrder(objects, names);
+  // A template names an object read from a `.sql` file as text: that is an edge too.
+  const extra = sqlFileReferences("postgres", objects);
+  const order = applyOrder(objects, names, extra);
   const doc = {
     dialect: "postgres",
     postgresMajor: targetMajor(config),
     applyOrder: order,
-    objects: order.map((n) => postgresObjectJson(n, objects.get(n)!, names)),
+    objects: order.map((n) => postgresObjectJson(n, objects.get(n)!, names, extra.get(n))),
   };
   const ddl = order.map((n) => `${(objects.get(n)!.props as { ddl: string }).ddl};`).join("\n\n");
   return {
@@ -130,11 +134,12 @@ export const sqlSerializer: Serializer = {
     const names = new Map<Declarable, string>();
     for (const [name, entity] of entities) names.set(entity, name);
 
-    const order = applyOrder(objects, names);
+    const extra = sqlFileReferences("clickhouse", objects);
+    const order = applyOrder(objects, names, extra);
     const doc = {
       dialect: "clickhouse",
       applyOrder: order,
-      objects: order.map((n) => objectJson(n, objects.get(n)!, names)),
+      objects: order.map((n) => objectJson(n, objects.get(n)!, names, extra.get(n))),
     };
     const ddl = order
       .map((n) => `${(objects.get(n)!.props as { ddl: string }).ddl};`)

package/src/skill-defs.ts

@@ -54,7 +54,7 @@ export const sqlSkills = createSkillsLoader(import.meta.url, [
     file: "chant-sql-postgres.md",
     name: "chant-sql-postgres",
     description:
-      "Declare Postgres schemas, tables, constraints, indexes, views, sequences, enum and domain types, extensions, functions, procedures and triggers as SQL-shaped tagged templates, with references, lineage and the SQLPG lint rules",
+      "Declare Postgres schemas, tables, constraints, indexes, views, sequences, enum and domain types, extensions, functions, procedures, triggers, policies, roles and grants as SQL-shaped tagged templates, with references, lineage and the SQLPG lint rules",
     triggers: [
       { type: "context" as const, value: "postgres" },
       { type: "context" as const, value: "postgres schema" },

package/src/skills/chant-sql-postgres-migration.md

@@ -40,6 +40,8 @@ Options besides `name`, `env`, `table`, `column`, `using`:
 - `gate` and `contractGate`: the two approvals, each with `gate` (name), `timeout` and `description`; `gate` also takes `approval` for quorum, roles and a policy, and a policy gets `verifiedRows` and `mismatched` as context;
 - `backfillTimeout` (default `6h`), `output` (default `dist/schema.json`), `path`, `build` (default true runs `chant build` first), `stack`, `ownershipEnv`.
 
+Run as one step of a change approved elsewhere: `gates: "outer"` leaves out the switch gate, the contract gate and the Contract phase (verification still runs; the old column is kept until its retention date), and `onFailure: "keep"` leaves out onFailure, so a failed run's next run resumes the backfill from its receipts. Set them rather than editing the Op's phases.
+
 ## What it does
 
 | Phase | Step |
@@ -103,7 +105,7 @@ or set `replicationLag: false` to run without the check.
 
 ## When something goes wrong
 
-- A failed step (a value the `using` expression cannot convert, a verification mismatch, a refused declaration, an index that cannot be built) runs onFailure: the trigger, its function, the check, the carried indexes and constraints, the new column and the receipts table are dropped, and the plan shows the original change again. The old column was never touched. Fix the declaration or the data and run again. A failed gate or an aborted run does not run onFailure.
+- A failed step (a value the `using` expression cannot convert, a verification mismatch, a refused declaration, an index that cannot be built) runs onFailure, unless the Op sets `onFailure: "keep"`: the trigger, its function, the check, the carried indexes and constraints, the new column and the receipts table are dropped, and the plan shows the original change again. The old column was never touched. Fix the declaration or the data and run again. A failed gate or an aborted run does not run onFailure.
 - A lock timeout means another session holds a lock the step needs (SQLSTATE 55P03). The step retries a few times, then fails. Run again when the blocker has finished.
 - The working objects (new column, trigger, function, check, receipts table) carry chant's comment marker with a `migration=` key, and plans, imports and prunes leave them out, so an `ApplyOp` for the rest of the schema can run beside a migration. An object under one of the working names that is not this migration's stops the run; rename or drop it by hand.
 

package/src/skills/chant-sql-postgres-plan.md

@@ -83,9 +83,9 @@ Every rule has an id in the SQLPG2xx range, names its class and cites the Postgr
 | column type to a binary-coercible type (longer varchar, text, wider numeric) | SQLPG206 | metadata | indexes on the column may still be rebuilt |
 | column type with a rewrite (integer to bigint, a shorter varchar) | SQLPG207 | rewrite | |
 | column type across kinds (text to integer) | SQLPG208 | expand | needs USING and breaks readers |
-| set NOT NULL | SQLPG210 | rewrite | a valid `CHECK (col IS NOT NULL)` already in place makes it metadata |
-| add a CHECK | SQLPG218 | rewrite | declare it `NOT VALID`, then validate |
-| add a foreign key | SQLPG219 | validate | `SHARE ROW EXCLUSIVE` on both tables for the scan; `NOT VALID` first avoids it |
+| set NOT NULL | SQLPG210 | validate | made as a `NOT VALID` check, `VALIDATE`, `SET NOT NULL`, the check dropped; a valid `CHECK (col IS NOT NULL)` already in place makes it metadata |
+| add a CHECK | SQLPG218 | validate | made as `ADD CONSTRAINT ... NOT VALID`, then `VALIDATE` in its own transaction; writes go on during the scan |
+| add a foreign key | SQLPG219 | validate | made as `ADD CONSTRAINT ... NOT VALID`, then `VALIDATE` in its own transaction; writes go on during the scan |
 | add a constraint `NOT VALID` | SQLPG217 | metadata | checks new rows only |
 | validate a constraint | SQLPG220 | validate | `SHARE UPDATE EXCLUSIVE`, so reads and writes go on |
 | add a primary key or unique constraint | SQLPG221 | concurrently | build the unique index CONCURRENTLY, then `ADD CONSTRAINT ... USING INDEX` |

package/src/skills/chant-sql-postgres.md

@@ -1,6 +1,6 @@
 ---
 skill: chant-sql-postgres
-description: Declare Postgres schemas, tables, constraints, indexes, views, sequences, enum and domain types, extensions, functions, procedures and triggers as SQL-shaped tagged templates, with references, lineage and the SQLPG lint rules
+description: Declare Postgres schemas, tables, constraints, indexes, views, sequences, enum and domain types, extensions, functions, procedures, triggers, policies, roles and grants as SQL-shaped tagged templates, with references, lineage and the SQLPG lint rules
 user-invocable: true
 ---
 # Declaring a Postgres schema with chant
@@ -40,6 +40,9 @@ The export name (`users`) is the object's identity in chant. The name in the SQL
 | `func` | `CREATE FUNCTION` | `Postgres::Function` |
 | `procedure` | `CREATE PROCEDURE` | `Postgres::Procedure` |
 | `trigger` | `CREATE TRIGGER` | `Postgres::Trigger` |
+| `policy` | `CREATE POLICY` | `Postgres::Policy` |
+| `role` | `CREATE ROLE` (no password, no memberships) | `Postgres::Role` |
+| `grant` | `GRANT`, `REVOKE`, `ALTER DEFAULT PRIVILEGES` | `Postgres::Grant`, `Postgres::DefaultPrivileges` |
 
 `table` and `view` imported from the package root are ClickHouse's. Import every tag from `@intentius/chant-lexicon-sql/postgres`.
 
@@ -140,6 +143,10 @@ export const ordersTouch = trigger`CREATE TRIGGER orders_touch BEFORE UPDATE ON
 
 The tag is `func` (`function` is a JavaScript key word). Write the body as a string, `AS $$ ... $$`: it is kept and compared verbatim. `${users}` inside the body renders as `app.users` and makes the routine depend on the table. A SQL-standard body (`RETURN ...`, `BEGIN ATOMIC`) and `SET ... FROM CURRENT` are SQLPG001 errors. Overloads are separate objects, identified by their input parameter types. A trigger's name is unqualified; it lives on its table.
 
+## Access
+
+A table's template may end with `ALTER TABLE ... ENABLE ROW LEVEL SECURITY`. `policy`, `role` and `grant` declare policies, the roles the schema needs (never a password or a membership: those are the environment's), privileges on schemas, tables, columns, sequences and routines, and default privileges. They are planned and applied only where `sql.profiles.<env>.access` is true; there, the declared privileges are the whole of them, and one granted by hand is revoked. A role the environment provisions is named as text (`TO support`), never declared. `GRANT ... ON ALL TABLES IN SCHEMA` is refused: grant per table and declare default privileges.
+
 ## Comments
 
 Postgres has no inline comment clause. Follow the `CREATE` with `COMMENT ON` for the object, its columns and its named constraints, separated by `;`:
@@ -178,4 +185,4 @@ chant build src --lexicon sql -o dist/schema.json
 
 ## Not covered
 
-`ALTER`, `CREATE POLICY`, `GRANT`, rules, aggregates, event triggers and the composite and range forms of `CREATE TYPE` are not declared with the tags. Planning a schema change (`chant sql diff`, `chant sql plan`, the lock classes) is the `chant-sql-postgres-plan` skill. Apply and the expand-and-contract migration Op have their own skills, which arrive with the code they describe.
+`ALTER` (other than a table's row-level security), role memberships, rules, aggregates, event triggers and the composite and range forms of `CREATE TYPE` are not declared with the tags. Planning a schema change (`chant sql diff`, `chant sql plan`, the lock classes) is the `chant-sql-postgres-plan` skill. Apply and the expand-and-contract migration Op have their own skills, which arrive with the code they describe.

package/src/skills/chant-sql-rebuild.md

@@ -26,7 +26,7 @@ export const { op } = ClickHouseRebuildOp({
 });
 ```
 
-Options: `name`, `env`, `table`, `dualWrite` (required); `output` (default `dist/schema.json`), `path`, `build` (default true runs `chant build` first), `retain` (default `7d`), `gate` (the swap gate: `gate`, `timeout`, `description`, `approval`), `dropGate`, `writesGate` (app mode), `backfillTimeout` (default `6h`), `mutationTimeout` (default `10m`), `replicaTimeout` (default `2m`, Replicated databases only), `stack`, `ownershipEnv`.
+Options: `name`, `env`, `table`, `dualWrite` (required); `output` (default `dist/schema.json`), `path`, `build` (default true runs `chant build` first), `retain` (default `7d`), `gate` (the swap gate: `gate`, `timeout`, `description`, `approval`), `dropGate`, `writesGate` (app mode), `backfillTimeout` (default `6h`), `mutationTimeout` (default `10m`), `replicaTimeout` (default `2m`, Replicated databases only), `cutoverTimeout` (default `10m`, materialized-view mode only), `stack`, `ownershipEnv`.
 
 On a `cluster:<name>` topology with more than one shard, the backfill and the verification work per shard through the profile's server, with a receipt per shard and partition; each shard needs its own `{shard}` macro.
 
@@ -34,7 +34,7 @@ Run as one step of a change approved elsewhere: `gates: "outer"` leaves out the
 
 Pick the dual-write mode:
 
-- `{ mode: "materialized-view", cutoverColumn: "ts", cutoverDelay?: "1m" }` when the table has a time column rows arrive in order of. Writes keep flowing: a materialized view sends rows at or after the cut-over to the new table, the backfill copies the rows before it.
+- `{ mode: "materialized-view", cutoverColumn: "ts", cutoverDelay?: "5s" }` when the table has a time column rows arrive in order of. Writes keep flowing: a materialized view sends rows at or after the cut-over to the new table, the backfill copies the rows before it. The backfill starts once the server's clock has passed the cut-over and every INSERT into the old table begun before it has finished, asynchronous inserts still in their buffer included; `cutoverTimeout` bounds the second wait. Set `cutoverDelay` longer than the batches of a writer that holds rows before inserting them.
 - `{ mode: "app" }` otherwise. A gate, `<name>-writes-stopped`, waits for someone to confirm the application stopped writing to the table; writes resume after the swap.
 
 ## Run it
@@ -57,6 +57,7 @@ The swap gate is bound to a digest of the plan and the verification (row counts
 - A run stopped during the backfill (Ctrl-C, a killed job) is not a failure. The next run resumes from the receipts in `chant_receipts.receipts` on the same server (in `<db>.__chant_receipts` on a Replicated database), and a partition whose copy was cut off before its receipt is cleared and copied again, so no row is copied twice.
 - A failed step (a failed copy after its retries, a verification mismatch, a refused declaration) runs onFailure: the new table `<t>__chant_new` and the dual-write view `<t>__chant_dual` are dropped, and the next run starts from a new table. With `onFailure: "keep"` they stay, and the next run resumes; drop them by hand to start over. The original table is untouched until the swap.
 - A verification mismatch in materialized-view mode usually means rows arrived with a time before the cut-over later than `cutoverDelay`. Raise the delay and run again.
+- A backfill that stops naming writes "begun before the cut-over" waited `cutoverTimeout` for INSERTs into the old table that were still running. Let them finish, or stop them, and run again.
 - The Op refuses a database that is neither Atomic nor Replicated (`EXCHANGE TABLES` needs one of them), a table whose change is not a rebuild (use the applier), and an object already under one of its working names that is not its own. In a Replicated database it also refuses a table, or a declaration, whose engine is not `Replicated*MergeTree`: a plain MergeTree keeps different rows on each replica and one replica's copy would lose the others'.
 
 ## On a Replicated database

package/src/skills/chant-sql.md

@@ -1,6 +1,6 @@
 ---
 skill: chant-sql
-description: Declare ClickHouse databases, tables, views and materialized views as SQL-shaped tagged templates, with references, lineage and the checks that run on them
+description: Declare ClickHouse databases, tables, views, materialized views, dictionaries and functions as SQL-shaped tagged templates, with references, lineage and the checks that run on them
 user-invocable: true
 ---
 # Declaring a ClickHouse schema with chant
@@ -33,6 +33,12 @@ export const byKind = view`
 
 The export name (`events`) is the object's identity in chant. The name in the SQL (`analytics.events`) is its name in the database. A materialized view is a `view` template holding `CREATE MATERIALIZED VIEW`.
 
+A dictionary is a `dictionary` template holding `CREATE DICTIONARY`, with its attributes, `PRIMARY KEY`, `SOURCE`, `LAYOUT` and `LIFETIME`. Its attributes are columns (`${ratesDict.columns.rate}`). Any change but its comment is SQLCH245, and the applier replaces it with `CREATE OR REPLACE DICTIONARY`. Keep passwords out of `SOURCE`: name a server-side named collection instead.
+
+A SQL user-defined function is a `func` template holding `CREATE FUNCTION name AS (x) -> expr`, with no database in its name. A changed expression is SQLCH260 (`CREATE OR REPLACE FUNCTION`). It carries no ownership marker, so chant never drops one.
+
+Users, roles, row policies and grants are `user`, `role`, `policy` and `grant` templates. Never write a password: `IDENTIFIED BY` is refused, a user declared without `IDENTIFIED` is created by the environment with its password, and chant manages the rest of it. Grants are compared per grantee: every `grant` naming a grantee adds up to its complete list, and anything else it holds is revoked (SQLCH274). None of these is ever dropped by chant.
+
 ## Interpolations
 
 | Value | Means | Renders as |

package/src/sql-files.test.ts

@@ -0,0 +1,188 @@
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { mkdir, realpath, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { build } from "@intentius/chant/build";
+import { readSqlFile, sqlFileDeclarations, SqlFileError } from "./sql-files";
+import { sqlPlugin } from "./plugin";
+import { sqlSerializer } from "./serializer";
+import { guessDialect, SqlFileParser } from "./import-parser";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+
+const PG_DDL = `BEGIN;
+CREATE TYPE app.status AS ENUM ('placed', 'paid');
+CREATE TABLE app.orders (
+  id bigint PRIMARY KEY,
+  user_id bigint NOT NULL,
+  status app.status NOT NULL
+);
+CREATE TABLE app.users (id bigint PRIMARY KEY, email text NOT NULL);
+ALTER TABLE app.orders ADD CONSTRAINT orders_user_fk FOREIGN KEY (user_id) REFERENCES app.users (id);
+CREATE INDEX orders_user_idx ON app.orders (user_id);
+COMMENT ON TABLE app.users IS 'People';
+COMMENT ON COLUMN app.users.email IS 'Login';
+ALTER TABLE app.users ENABLE ROW LEVEL SECURITY;
+COMMIT;
+`;
+
+describe("reading a file of Postgres DDL", () => {
+  test("each CREATE is an object, with its comments, row security and added constraints folded in", () => {
+    const objects = readSqlFile("postgres", PG_DDL, { origin: "schema.sql" });
+    expect(objects.map((o) => [o.export, o.type, o.name])).toEqual([
+      ["status", "Postgres::Enum", "app.status"],
+      ["orders", "Postgres::Table", "app.orders"],
+      ["users", "Postgres::Table", "app.users"],
+      ["ordersUserIdx", "Postgres::Index", "app.orders_user_idx"],
+    ]);
+    expect(objects[1]!.ddl).toContain("CONSTRAINT orders_user_fk FOREIGN KEY (user_id) REFERENCES app.users (id)\n)");
+    expect(objects[2]!.ddl).toBe(
+      "CREATE TABLE app.users (id bigint PRIMARY KEY, email text NOT NULL);\nCOMMENT ON TABLE app.users IS 'People';\nCOMMENT ON COLUMN app.users.email IS 'Login';\nALTER TABLE app.users ENABLE ROW LEVEL SECURITY",
+    );
+  });
+
+  test("a statement that declares nothing or does not parse is an error naming it, and every one is named", () => {
+    const read = () => readSqlFile("postgres", "CREATE TABLE a (id int);\nINSERT INTO a VALUES (1);\nCREATE TABLE b (id int,);\nCOMMENT ON TABLE c IS 'x';", { origin: "db/schema.sql" });
+    expect(read).toThrow(SqlFileError);
+    expect(read).toThrow(/^db\/schema\.sql: 3 statements chant cannot read as declarations/);
+    expect(read).toThrow(/not a statement that declares an object: INSERT INTO a VALUES \(1\)/);
+    expect(read).toThrow(/does not parse \(.*\): CREATE TABLE b \(id int,\)/);
+    expect(read).toThrow(/COMMENT ON TABLE for an object the file does not create: COMMENT ON TABLE c IS 'x'/);
+  });
+
+  test("schema qualifies the names the DDL leaves unqualified", () => {
+    const { content } = sqlFileDeclarations("postgres", "CREATE TYPE s AS ENUM ('a');\nCREATE TABLE u (id int PRIMARY KEY, k s);\nCREATE TABLE o (u int REFERENCES u (id));", { origin: "x", schema: "app" });
+    expect(content).toContain("CREATE TABLE app.u (id int PRIMARY KEY, k ${s})");
+    expect(content).toContain("CREATE TABLE app.o (u int REFERENCES ${u} (id))");
+  });
+});
+
+describe("chant import of a .sql file", () => {
+  test("the dialect is read off the statements, and Postgres DDL imports as Postgres declarations", () => {
+    expect(guessDialect(PG_DDL)).toBe("postgres");
+    expect(guessDialect("CREATE TABLE a.t (x UInt8) ENGINE = Log")).toBe("clickhouse");
+    expect(guessDialect("CREATE VIEW a.v AS SELECT 1")).toBe("clickhouse");
+    expect(guessDialect("CREATE FUNCTION f AS (x) -> x + 1")).toBe("clickhouse");
+    expect(guessDialect("CREATE FUNCTION app.f() RETURNS int LANGUAGE sql AS $$ SELECT 1 $$")).toBe("postgres");
+    expect(new SqlFileParser().parse(PG_DDL).resources.map((r) => r.type)).toEqual(["Postgres::Enum", "Postgres::Table", "Postgres::Table", "Postgres::Index"]);
+  });
+
+  test("a statement it cannot read stops the import, named", () => {
+    expect(() => new SqlFileParser("clickhouse").parse("CREATE DATABASE a;\nINSERT INTO a.t VALUES (1)")).toThrow(/not a CREATE statement: INSERT INTO a\.t VALUES \(1\)/);
+  });
+});
+
+/** A project directory under the repository, so its imports resolve. */
+async function project(name: string, files: Record<string, string>): Promise<string> {
+  const path = join(repoRoot, ".cache", `sql-3646-${name}-${process.pid}`);
+  await rm(path, { recursive: true, force: true });
+  await mkdir(join(path, "src"), { recursive: true });
+  const dir = await realpath(path);
+  for (const [file, content] of Object.entries(files)) await writeFile(join(dir, "src", file), content);
+  return dir;
+}
+
+/** A build document with each DDL's whitespace runs collapsed. */
+const squeeze = (doc: unknown): unknown => JSON.parse(JSON.stringify(doc, (k, v: unknown) => (k === "ddl" && typeof v === "string" ? v.replace(/\s+/g, " ") : v)));
+
+async function buildProject(dir: string, config: Record<string, unknown> = {}) {
+  const result = await build(join(dir, "src"), [sqlSerializer], undefined, {
+    lexicons: ["sql"],
+    intrinsics: sqlPlugin.intrinsics?.() ?? [],
+    buildRoots: [(ctx) => sqlPlugin.buildRoots!({ projectRoot: dir, config, entities: ctx.entities, ...(ctx.sourceDir ? { sourceDir: ctx.sourceDir } : {}) })],
+  });
+  const out = result.outputs.get("sql");
+  const primary = typeof out === "string" ? out : out?.primary;
+  return { errors: result.errors.map((e) => e.message), doc: primary ? (JSON.parse(primary) as { applyOrder: string[]; objects: Array<Record<string, unknown>> }) : undefined };
+}
+
+const CH_DDL = `CREATE DATABASE analytics;
+CREATE TABLE analytics.events (ts DateTime, kind String) ENGINE = MergeTree ORDER BY ts;
+CREATE TABLE analytics.counts (kind String, n UInt64) ENGINE = SummingMergeTree ORDER BY kind;
+CREATE MATERIALIZED VIEW analytics.counts_mv TO analytics.counts AS SELECT kind, count() AS n FROM analytics.events GROUP BY kind;
+CREATE DICTIONARY analytics.kinds (kind String, label String DEFAULT '') PRIMARY KEY kind SOURCE(clickhouse(table 'counts' db 'analytics')) LAYOUT(complex_key_hashed()) LIFETIME(300);
+CREATE FUNCTION kind_label AS (k) -> upper(k);
+`;
+
+describe("chant build reads the .sql files in the source directory", () => {
+  const dirs: string[] = [];
+  afterAll(async () => {
+    for (const d of dirs) await rm(d, { recursive: true, force: true });
+  });
+
+  for (const [dialect, ddl] of [
+    ["postgres", PG_DDL.replace("CREATE TYPE", "CREATE SCHEMA app;\nCREATE TYPE")],
+    ["clickhouse", CH_DDL],
+  ] as const) {
+    test(`${dialect}: the same build as the declarations chant import writes for the file`, async () => {
+      const fromSql = await project(`${dialect}-sql`, { "schema.sql": ddl });
+      const fromTs = await project(`${dialect}-ts`, { "schema.ts": sqlFileDeclarations(dialect, ddl, { origin: "schema.sql" }).content });
+      dirs.push(fromSql, fromTs);
+      const a = await buildProject(fromSql, { sql: { dialect } });
+      const b = await buildProject(fromTs, { sql: { dialect } });
+      expect(a.errors).toEqual([]);
+      expect(b.errors).toEqual([]);
+      // The import indents a template's lines under its declaration; the statements are otherwise the same.
+      expect(squeeze(a.doc)).toEqual(squeeze(b.doc));
+      expect(a.doc!.objects.length).toBeGreaterThan(2);
+    });
+  }
+
+  let mixed: string;
+  beforeAll(async () => {
+    mixed = await project("mixed", {
+      "app.ts": `import { schema, view } from "@intentius/chant-lexicon-sql/postgres";
+export const app = schema\`CREATE SCHEMA app\`;
+export const activeUsers = view\`CREATE VIEW app.active_users AS SELECT id FROM app.users\`;
+`,
+      "users.sql": "CREATE TABLE app.users (id bigint PRIMARY KEY);\nCREATE TABLE app.notes (user_id bigint REFERENCES app.users (id));\n",
+    });
+    dirs.push(mixed);
+  });
+
+  test("a file's object and a template reference each other, and the order comes from the references", async () => {
+    const { errors, doc } = await buildProject(mixed);
+    expect(errors).toEqual([]);
+    const objects = new Map(doc!.objects.map((o) => [o.export as string, o]));
+    // The file's table names the template's schema; the template's view names the file's table as text.
+    expect(objects.get("users")!.dependsOn).toEqual(["app"]);
+    expect(objects.get("notes")!.dependsOn).toEqual(["app", "users"]);
+    expect(objects.get("activeUsers")!.dependsOn).toEqual(["users"]);
+    expect(doc!.applyOrder).toEqual(["app", "users", "activeUsers", "notes"]);
+  });
+
+  test("a statement the build cannot read is a build error naming the file and the statement", async () => {
+    const dir = await project("bad", { "app.ts": `import { schema } from "@intentius/chant-lexicon-sql/postgres";\nexport const app = schema\`CREATE SCHEMA app\`;\n`, "bad.sql": "CREATE TABLE app.t (id int);\nDROP TABLE app.old;\n" });
+    dirs.push(dir);
+    const { errors } = await buildProject(dir);
+    expect(errors.join("\n")).toMatch(/src\/bad\.sql: a statement chant cannot read as declarations:\n {2}- not a statement that declares an object: DROP TABLE app\.old/);
+  });
+
+  test("an object declared in a file and a template both is an error naming both", async () => {
+    const dir = await project("twice", { "app.ts": `import { table } from "@intentius/chant-lexicon-sql/postgres";\nexport const accounts = table\`CREATE TABLE app.users (id int)\`;\n`, "users.sql": "CREATE TABLE app.users (id int);\n" });
+    dirs.push(dir);
+    const { errors } = await buildProject(dir);
+    expect(errors.join("\n")).toMatch(/app\.users is declared twice, here and as accounts/);
+  });
+
+  test("a file marked chant-discovery-skip is not read", async () => {
+    const dir = await project("skip", { "app.ts": `import { schema } from "@intentius/chant-lexicon-sql/postgres";\nexport const app = schema\`CREATE SCHEMA app\`;\n`, "seed.sql": "-- chant-discovery-skip\nINSERT INTO app.t VALUES (1);\n" });
+    dirs.push(dir);
+    const { errors, doc } = await buildProject(dir);
+    expect(errors).toEqual([]);
+    expect(doc!.applyOrder).toEqual(["app"]);
+  });
+});
+
+describe("references between a file's objects", () => {
+  test("a bare name where SQL names an object is a reference, and a cycle is an error", async () => {
+    const { sqlFileEntities } = await import("./sql-files");
+    const entities = sqlFileEntities("postgres", [
+      { origin: "a.sql", ddl: "CREATE TABLE orders (user_id int REFERENCES users (id));\nCREATE TABLE users (id int PRIMARY KEY);\nCREATE VIEW recent AS SELECT * FROM orders JOIN users ON true;" },
+    ]);
+    const deps = (n: string) => ((entities.get(n) as unknown as { dependsOn: Array<{ sqlName: string }> }).dependsOn).map((d) => d.sqlName);
+    expect(deps("orders")).toEqual(["users"]);
+    expect(deps("recent")).toEqual(["orders", "users"]);
+    expect(() => sqlFileEntities("postgres", [{ origin: "b.sql", ddl: "CREATE TABLE a (b int REFERENCES b (id), id int PRIMARY KEY);\nCREATE TABLE b (a int REFERENCES a (id), id int PRIMARY KEY);" }])).toThrow(/reference each other/);
+  });
+});