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

package/src/postgres/container.ts

@@ -0,0 +1,72 @@
+/**
+ * A throwaway `postgres` server in a container, for catalog generation and the
+ * live tests: started under a unique name with no published port, queried with
+ * `docker exec psql`, and always removed.
+ *
+ * The official image restarts the server once after `initdb`, so the ready
+ * line appears twice in its log; the server is ready on the second.
+ */
+
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { uniqueContainerName } from "../core/container";
+
+export { dockerAvailable } from "../core/container";
+
+const exec = promisify(execFile);
+
+export interface ScratchPostgres {
+  /** The container's name, for a log line. */
+  name: string;
+  /** Run a SQL script with psql as `postgres` (`-qAt`, stop at the first error) and return its stdout. */
+  psql(sql: string): Promise<string>;
+  /** Remove the container. Safe to call twice. */
+  stop(): Promise<void>;
+}
+
+function psqlIn(name: string, sql: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("docker", ["exec", "-i", name, "psql", "-U", "postgres", "-qAt", "-v", "ON_ERROR_STOP=1", "-f", "-"]);
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    child.stdout.on("data", (d: Buffer) => out.push(d));
+    child.stderr.on("data", (d: Buffer) => err.push(d));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) resolve(Buffer.concat(out).toString("utf-8"));
+      else reject(new Error(`psql failed (${code}): ${Buffer.concat(err).toString("utf-8").trim()}`));
+    });
+    child.stdin.end(sql);
+  });
+}
+
+/** Start `image` and wait until the server accepts connections. Pulls the image when it is absent. */
+export async function startScratchPostgres(
+  image: string,
+  options: { namePrefix?: string; readyTimeoutMs?: number } = {},
+): Promise<ScratchPostgres> {
+  const name = uniqueContainerName(options.namePrefix ?? "chant-sql-pg");
+  let removed = false;
+  const stop = async (): Promise<void> => {
+    if (removed) return;
+    removed = true;
+    await exec("docker", ["rm", "-f", "-v", name]).catch(() => undefined);
+  };
+  try {
+    await exec("docker", ["run", "-d", "--name", name, "-e", "POSTGRES_PASSWORD=chant", image], { timeout: 600_000 });
+    const deadline = Date.now() + (options.readyTimeoutMs ?? 120_000);
+    for (;;) {
+      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) break;
+      if (Date.now() > deadline) throw new Error(`${name} did not accept connections within the timeout`);
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    return { name, psql: (sql) => psqlIn(name, sql), stop };
+  } catch (err) {
+    await stop();
+    throw err;
+  }
+}

package/src/postgres/entities.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, test } from "vitest";
+import { isDeclarable } from "@intentius/chant/declarable";
+import { getInterpolationFields } from "@intentius/chant/provenance";
+import { domain, extension, index, isColumnRef, literal, schema, sequence, SqlTemplateError, table, type, view } from "./entities";
+
+const app = schema`CREATE SCHEMA app`;
+const orderStatus = type`CREATE TYPE ${app}.order_status AS ENUM ('placed', 'paid')`;
+const invoiceSeq = sequence`CREATE SEQUENCE ${app}.invoice_seq AS bigint START WITH 1000 NO CYCLE`;
+const users = table`
+  CREATE TABLE ${app}.Users (
+    id    bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    Email text NOT NULL,
+    "DisplayName" text,
+    CONSTRAINT users_email_key UNIQUE (email)
+  );
+  COMMENT ON TABLE ${app}.users IS 'One row per account';
+  COMMENT ON COLUMN ${app}.users.email IS 'Login name';
+  COMMENT ON CONSTRAINT users_email_key ON ${app}.users IS 'One account per address'`;
+const orders = table`
+  CREATE TABLE ${app}.orders (
+    id         bigint PRIMARY KEY,
+    user_id    bigint NOT NULL REFERENCES ${users} (${users.columns.id}) ON DELETE CASCADE,
+    invoice_no bigint NOT NULL DEFAULT nextval(${invoiceSeq}),
+    status     ${orderStatus} NOT NULL DEFAULT 'placed',
+    note       text DEFAULT ${literal("it's")}
+  )`;
+
+describe("the tags", () => {
+  test("each is one declarable entity of its Postgres type, in the sql lexicon", () => {
+    expect(isDeclarable(users)).toBe(true);
+    expect([app, orderStatus, invoiceSeq, users].map((e) => e.entityType)).toEqual([
+      "Postgres::Schema",
+      "Postgres::Enum",
+      "Postgres::Sequence",
+      "Postgres::Table",
+    ]);
+    expect(users.lexicon).toBe("sql");
+  });
+
+  test("unquoted names fold to lower case and quoted ones stay exact", () => {
+    expect(users.props).toMatchObject({ schema: "app", name: "users" });
+    expect(users.sqlName).toBe("app.users");
+    expect(users.props.columns.map((c) => c.name)).toEqual(["id", "email", "DisplayName"]);
+    expect(Object.keys(users.columns)).toEqual(["id", "email", "DisplayName"]);
+    expect(table`CREATE TABLE "Mixed Case" (a int)`.sqlName).toBe('"Mixed Case"');
+  });
+
+  test("columns are references, reached through .columns", () => {
+    expect(isColumnRef(users.columns.email)).toBe(true);
+    expect(users.kind).toBe("resource");
+  });
+
+  test("references render as names and are dependencies", () => {
+    expect(orders.props.foreignKeys).toEqual([
+      { columns: ["user_id"], references: users, refTable: "app.users", refColumns: ["id"], onDelete: "CASCADE" },
+    ]);
+    expect(orders.props.columns.find((c) => c.name === "status")?.type).toBe("app.order_status");
+    expect(orders.dependsOn).toEqual(expect.arrayContaining([app, users, users.columns.id, invoiceSeq, orderStatus]));
+  });
+
+  test("a sequence inside nextval renders as the regclass literal the catalog prints", () => {
+    expect(orders.props.columns.find((c) => c.name === "invoice_no")?.default).toBe("nextval('app.invoice_seq'::regclass)");
+    const t = table`CREATE TABLE t (a regclass DEFAULT ${invoiceSeq}::regclass)`;
+    expect(t.props.columns[0]!.default).toBe("'app.invoice_seq'::regclass");
+    expect(t.dependsOn).toEqual([invoiceSeq]);
+  });
+
+  test("literal() doubles a quote and leaves a backslash alone", () => {
+    expect(orders.props.columns.find((c) => c.name === "note")?.default).toBe("'it''s'");
+    expect(literal("a\\b").sql).toBe("'a\\b'");
+  });
+
+  test("COMMENT ON folds into the table, its column and its named constraint", () => {
+    expect(users.props.comment).toBe("One row per account");
+    expect(users.props.columns.find((c) => c.name === "email")?.comment).toBe("Login name");
+    expect(users.props.uniques[0]).toMatchObject({ name: "users_email_key", comment: "One account per address" });
+    expect(users.props.ddl).toContain("COMMENT ON COLUMN app.users.email IS 'Login name'");
+  });
+
+  test("an identity BY DEFAULT keeps always: false", () => {
+    expect(users.props.columns[0]!.generated).toEqual({ kind: "identity", always: false });
+  });
+
+  test("a sequence's options are its props", () => {
+    expect(invoiceSeq.props).toMatchObject({ dataType: "bigint", start: "1000", cycle: false });
+  });
+});
+
+describe("indexes, views and the rest", () => {
+  const byUser = index`CREATE INDEX CONCURRENTLY orders_user_idx ON ${orders} (${orders.columns.user_id}, lower(${orders.columns.note}) DESC)`;
+
+  test("an index lives in its table's schema, records CONCURRENTLY and its column elements", () => {
+    expect(byUser.sqlName).toBe("app.orders_user_idx");
+    expect(byUser.props).toMatchObject({ table: orders, tableName: "app.orders", concurrently: true });
+    expect(byUser.props.elements).toEqual([{ expr: "user_id", column: "user_id" }, { expr: "lower(note) DESC" }]);
+  });
+
+  test("a view records what it reads and Postgres's own output names", () => {
+    const v = view`
+      CREATE VIEW ${app}.order_counts AS
+      SELECT DISTINCT ON (u.${users.columns.id}) u.${users.columns.id}, u.${users.columns.email} address,
+             count(o.${orders.columns.id}), o.${orders.columns.status}::text, 1 + 1
+      FROM ${users} u JOIN ${orders} o ON o.${orders.columns.user_id} = u.${users.columns.id}
+      GROUP BY 1, 2, 4`;
+    expect(v.props.reads).toEqual([users, orders]);
+    expect(v.props.lineage.map((e) => e.output)).toEqual(["id", "address", "count", "status", "?column?"]);
+    expect(Object.keys(v.columns)).toEqual(["id", "address", "count", "status", "?column?"]);
+    expect(v.props.lineage[1]!.from.map((r) => r.attribute)).toEqual(["email"]);
+  });
+
+  test("a declared column list names a view's outputs, and a materialized view is its own type", () => {
+    const m = view`CREATE MATERIALIZED VIEW counts (n) AS SELECT count(*) FROM ${orders} WITH NO DATA`;
+    expect(m.entityType).toBe("Postgres::MaterializedView");
+    expect(m.props).toMatchObject({ columns: ["n"], withData: false });
+    expect(Object.keys(m.columns)).toEqual(["n"]);
+  });
+
+  test("a domain, an extension and an enum", () => {
+    const d = domain`CREATE DOMAIN ${app}.email AS text CONSTRAINT email_shape CHECK (VALUE ~ '^[^@\s]+@')`;
+    expect(d.props).toMatchObject({ dataType: "text", checks: [{ name: "email_shape", expr: "VALUE ~ '^[^@\\s]+@'" }] });
+    const e = extension`CREATE EXTENSION IF NOT EXISTS citext WITH SCHEMA ${app} VERSION '1.6'`;
+    expect(e.props).toMatchObject({ name: "citext", schema: "app", version: "1.6", ifNotExists: true });
+    expect(e.dependsOn).toEqual([app]);
+    expect(orderStatus.props.labels).toEqual(["placed", "paid"]);
+  });
+});
+
+describe("what a tag refuses", () => {
+  const refuses = (fn: () => unknown, message: RegExp) => {
+    expect(fn).toThrow(SqlTemplateError);
+    expect(fn).toThrow(message);
+  };
+
+  test("another statement than its own", () => {
+    refuses(() => table`CREATE INDEX i ON t (a)`, /holds a CREATE INDEX; use the index tag/);
+    refuses(() => type`CREATE DOMAIN d AS int`, /use the domain tag/);
+  });
+
+  test("a second CREATE, and a comment on another object", () => {
+    refuses(() => table`CREATE TABLE a (x int); CREATE TABLE b (x int)`, /second statement/);
+    refuses(() => table`CREATE TABLE a (x int); COMMENT ON TABLE b IS 'no'`, /names another object/);
+    refuses(() => table`CREATE TABLE a (x int); COMMENT ON COLUMN a.y IS 'no'`, /names no column/);
+  });
+
+  test("an index with no name", () => {
+    refuses(() => index`CREATE INDEX ON t (a)`, /an index needs a name/);
+  });
+
+  test("a parse error, on its template line", () => {
+    refuses(
+      () => table`CREATE TABLE t (
+        a int DEFAULT 1 IN (1, 2)
+      )`,
+      /at 'IN' \(on template line 2\)/,
+    );
+  });
+
+  test("an interpolation with no SQL form, naming .columns", () => {
+    refuses(() => table`CREATE TABLE t (a int REFERENCES ${users} (${(users as unknown as Record<string, unknown>).id}))`, /\.columns/);
+  });
+});
+
+describe("provenance", () => {
+  test("a spliced string records the props it landed in", () => {
+    const name = "events";
+    const ttl = 30;
+    const t = table`CREATE TABLE ${name} (ts timestamptz, keep date GENERATED ALWAYS AS (ts::date + ${ttl}) STORED)`;
+    expect(getInterpolationFields(t)).toEqual([["ddl", "name"], ["columns", "ddl"]]);
+  });
+});