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

package/src/postgres/overlays/columns.ts

@@ -0,0 +1,34 @@
+/** Column clauses: defaults, generated columns and identity. */
+
+import { arg, type Clause } from "./kinds";
+
+export const COLUMN_CLAUSES: Record<string, Clause> = {
+  default: { summary: "DEFAULT expression", args: [arg("expression", "expression")] },
+  generated: {
+    summary: "GENERATED ALWAYS AS (expression) STORED",
+    // VIRTUAL generated columns arrive in 18; before that only STORED is accepted.
+    args: [arg("expression", "expression"), arg("storage", "keyword", { optional: true, values: ["STORED", "VIRTUAL"] })],
+  },
+  identity: {
+    summary: "GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [(sequence options)]",
+    args: [arg("generation", "keyword", { values: ["ALWAYS", "BY DEFAULT"] }), arg("sequence", "identifier", { optional: true })],
+  },
+  collate: { summary: "COLLATE collation", args: [arg("collation", "identifier")] },
+  compression: { summary: "COMPRESSION method", args: [arg("method", "keyword", { values: ["pglz", "lz4"] })] },
+  storage: {
+    summary: "STORAGE mode",
+    args: [arg("mode", "keyword", { values: ["PLAIN", "EXTERNAL", "EXTENDED", "MAIN", "DEFAULT"] })],
+  },
+};
+
+/** The options of an identity column's sequence and of `CREATE SEQUENCE`. */
+export const SEQUENCE_OPTIONS: Record<string, readonly ReturnType<typeof arg>[]> = {
+  asType: [arg("type", "type")],
+  incrementBy: [arg("increment", "number")],
+  minValue: [arg("minimum", "number")],
+  maxValue: [arg("maximum", "number")],
+  start: [arg("start", "number")],
+  cache: [arg("cache", "number", { range: [1, Number.MAX_SAFE_INTEGER] })],
+  cycle: [arg("cycle", "boolean")],
+  ownedBy: [arg("column", "identifier")],
+};

package/src/postgres/overlays/constraints.ts

@@ -0,0 +1,56 @@
+/**
+ * Constraint grammar: the arguments of each table and column constraint.
+ * `MATCH`, `ON DELETE` and `DEFERRABLE` are grammar, not catalog.
+ */
+
+import { arg, type Clause } from "./kinds";
+
+export const REFERENTIAL_ACTIONS = ["NO ACTION", "RESTRICT", "CASCADE", "SET NULL", "SET DEFAULT"] as const;
+
+const deferral = [
+  arg("deferrable", "boolean", { optional: true }),
+  arg("initially", "keyword", { optional: true, values: ["DEFERRED", "IMMEDIATE"] }),
+];
+
+export const CONSTRAINTS: Record<string, Clause> = {
+  primaryKey: {
+    summary: "PRIMARY KEY (columns) [INCLUDE (columns)] [USING INDEX TABLESPACE name]",
+    args: [arg("columns", "column", { repeated: true }), arg("include", "column", { optional: true, repeated: true }), ...deferral],
+  },
+  unique: {
+    summary: "UNIQUE [NULLS [NOT] DISTINCT] (columns) [INCLUDE (columns)]",
+    args: [
+      arg("columns", "column", { repeated: true }),
+      arg("nullsNotDistinct", "boolean", { optional: true }),
+      arg("include", "column", { optional: true, repeated: true }),
+      ...deferral,
+    ],
+    since: 15,
+  },
+  check: {
+    summary: "CHECK (expression) [NO INHERIT]",
+    args: [arg("expression", "expression"), arg("noInherit", "boolean", { optional: true })],
+  },
+  foreignKey: {
+    summary: "FOREIGN KEY (columns) REFERENCES table (columns) [MATCH FULL | SIMPLE] [ON DELETE action] [ON UPDATE action]",
+    args: [
+      arg("columns", "column", { repeated: true }),
+      arg("references", "identifier"),
+      arg("referencedColumns", "column", { optional: true, repeated: true }),
+      arg("match", "keyword", { optional: true, values: ["FULL", "SIMPLE"] }),
+      arg("onDelete", "keyword", { optional: true, values: REFERENTIAL_ACTIONS }),
+      arg("onUpdate", "keyword", { optional: true, values: REFERENTIAL_ACTIONS }),
+      ...deferral,
+    ],
+  },
+  exclude: {
+    summary: "EXCLUDE [USING method] (element WITH operator, ...) [WHERE (predicate)]",
+    args: [
+      arg("using", "keyword", { optional: true, values: ["gist", "spgist", "btree", "hash"] }),
+      arg("elements", "expression", { repeated: true }),
+      arg("where", "expression", { optional: true }),
+      ...deferral,
+    ],
+  },
+  notNull: { summary: "NOT NULL [NO INHERIT]", args: [arg("noInherit", "boolean", { optional: true })], since: 18 },
+};

package/src/postgres/overlays/indexes.ts

@@ -0,0 +1,27 @@
+/**
+ * Index clauses. Which access method supports which of them is in the catalog
+ * (`INDEX_METHOD_PROPERTIES`: `can_include`, `can_unique`, ...); the clause
+ * shapes are here.
+ */
+
+import { arg, type Clause } from "./kinds";
+
+export const INDEX_CLAUSES: Record<string, Clause> = {
+  key: {
+    summary: "{ column | (expression) } [COLLATE collation] [opclass [(parameters)]] [ASC | DESC] [NULLS FIRST | LAST]",
+    args: [
+      arg("key", "expression"),
+      arg("collation", "identifier", { optional: true }),
+      arg("opclass", "identifier", { optional: true }),
+      arg("order", "keyword", { optional: true, values: ["ASC", "DESC"] }),
+      arg("nulls", "keyword", { optional: true, values: ["FIRST", "LAST"] }),
+    ],
+  },
+  using: { summary: "USING method", args: [arg("method", "keyword")] },
+  include: { summary: "INCLUDE (columns)", args: [arg("columns", "column", { repeated: true })] },
+  where: { summary: "WHERE predicate: a partial index", args: [arg("predicate", "expression")] },
+  nullsNotDistinct: { summary: "NULLS [NOT] DISTINCT, on a unique index", args: [arg("notDistinct", "boolean")], since: 15 },
+  tablespace: { summary: "TABLESPACE name", args: [arg("tablespace", "identifier")] },
+  concurrently: { summary: "CREATE INDEX CONCURRENTLY: not inside a transaction block", args: [arg("concurrently", "boolean")] },
+  only: { summary: "ON ONLY parent: an index on a partitioned table's parent without its partitions", args: [arg("only", "boolean")] },
+};

package/src/postgres/overlays/kinds.ts

@@ -0,0 +1,53 @@
+/**
+ * What kind of value a clause argument takes. The catalog lists names (types,
+ * access methods, operator classes); it never says that `varchar`'s one
+ * argument is a length or that `ON DELETE` takes one of five actions. The
+ * overlays say that, with these.
+ */
+export type ArgumentKind =
+  /** A column of the table, by name. */
+  | "column"
+  /** Any expression; in an index key or a check, over the table's columns. */
+  | "expression"
+  /** A schema-qualified or bare object name. */
+  | "identifier"
+  /** A string literal. */
+  | "string"
+  /** A numeric literal. */
+  | "number"
+  /** A boolean. */
+  | "boolean"
+  /** A bare keyword from a fixed set (`values`). */
+  | "keyword"
+  /** A column type. */
+  | "type"
+  /** A query. */
+  | "query";
+
+export interface ClauseArgument {
+  name: string;
+  kind: ArgumentKind;
+  optional?: boolean;
+  /** The argument repeats, comma separated. */
+  repeated?: boolean;
+  /** The legal values of a `keyword`. */
+  values?: readonly string[];
+  /** The inclusive range of a `number`. */
+  range?: readonly [number, number];
+}
+
+/** A clause that is in some majors and not others. A bound outside 14..18 is a mistake generation reports. */
+export interface Versioned {
+  since?: number;
+  until?: number;
+}
+
+export type Clause = { args: readonly ClauseArgument[]; summary: string } & Versioned;
+
+export const arg = (
+  name: string,
+  kind: ArgumentKind,
+  extra: Partial<Omit<ClauseArgument, "name" | "kind">> = {},
+): ClauseArgument => ({ name, kind, ...extra });
+
+export const INT_MAX = 2147483647;

package/src/postgres/overlays/partitioning.ts

@@ -0,0 +1,26 @@
+/** Partitioning: `PARTITION BY`, partition bounds, `DEFAULT` partitions, `ATTACH` and `DETACH`. */
+
+import { arg, type Clause } from "./kinds";
+
+export const PARTITION_STRATEGIES = ["RANGE", "LIST", "HASH"] as const;
+
+export const PARTITIONING: Record<string, Clause> = {
+  partitionBy: {
+    summary: "PARTITION BY { RANGE | LIST | HASH } ({ column | (expression) } [COLLATE c] [opclass], ...)",
+    args: [arg("strategy", "keyword", { values: PARTITION_STRATEGIES }), arg("keys", "expression", { repeated: true })],
+  },
+  forValuesRange: { summary: "FOR VALUES FROM (bounds) TO (bounds); MINVALUE and MAXVALUE stand for unbounded", args: [arg("from", "expression", { repeated: true }), arg("to", "expression", { repeated: true })] },
+  forValuesList: { summary: "FOR VALUES IN (values)", args: [arg("values", "expression", { repeated: true })] },
+  forValuesHash: {
+    summary: "FOR VALUES WITH (MODULUS m, REMAINDER r)",
+    args: [arg("modulus", "number", { range: [1, 2147483647] }), arg("remainder", "number", { range: [0, 2147483646] })],
+  },
+  default: { summary: "DEFAULT partition", args: [] },
+  attach: { summary: "ALTER TABLE parent ATTACH PARTITION child { FOR VALUES ... | DEFAULT }", args: [arg("partition", "identifier")] },
+  detach: {
+    summary: "ALTER TABLE parent DETACH PARTITION child [CONCURRENTLY | FINALIZE]",
+    args: [arg("partition", "identifier"), arg("mode", "keyword", { optional: true, values: ["CONCURRENTLY", "FINALIZE"] })],
+  },
+  mergePartitions: { summary: "ALTER TABLE parent MERGE PARTITIONS (children) INTO child", args: [arg("partitions", "identifier", { repeated: true })], since: 18 },
+  splitPartition: { summary: "ALTER TABLE parent SPLIT PARTITION child INTO (partitions)", args: [arg("partition", "identifier")], since: 18 },
+};

package/src/postgres/overlays/relations.ts

@@ -0,0 +1,29 @@
+/** Table and relation clauses, views, materialized views and sequences. */
+
+import { arg, type Clause } from "./kinds";
+
+export const RELATION_CLAUSES: Record<string, Clause> = {
+  persistence: { summary: "{ TEMPORARY | UNLOGGED } TABLE", args: [arg("persistence", "keyword", { values: ["TEMPORARY", "UNLOGGED"] })] },
+  inherits: { summary: "INHERITS (parents)", args: [arg("parents", "identifier", { repeated: true })] },
+  tablespace: { summary: "TABLESPACE name", args: [arg("tablespace", "identifier")] },
+  using: { summary: "USING access_method", args: [arg("method", "keyword")] },
+  onCommit: { summary: "ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP }, temporary tables only", args: [arg("action", "keyword", { values: ["PRESERVE ROWS", "DELETE ROWS", "DROP"] })] },
+  withParameters: { summary: "WITH (storage_parameter = value, ...)", args: [arg("parameters", "expression", { repeated: true })] },
+  likeSource: { summary: "LIKE source [INCLUDING | EXCLUDING option]", args: [arg("source", "identifier"), arg("options", "keyword", { optional: true, repeated: true, values: ["COMMENTS", "COMPRESSION", "CONSTRAINTS", "DEFAULTS", "GENERATED", "IDENTITY", "INDEXES", "STATISTICS", "STORAGE", "ALL"] })] },
+  ofType: { summary: "OF composite_type: a typed table", args: [arg("type", "identifier")] },
+};
+
+export const VIEW_CLAUSES: Record<string, Clause> = {
+  query: { summary: "AS query", args: [arg("query", "query")] },
+  columns: { summary: "(column_names)", args: [arg("columns", "column", { repeated: true })] },
+  recursive: { summary: "CREATE RECURSIVE VIEW", args: [arg("recursive", "boolean")] },
+  checkOption: { summary: "WITH [CASCADED | LOCAL] CHECK OPTION, on an updatable view", args: [arg("option", "keyword", { values: ["CASCADED", "LOCAL"] })] },
+  securityInvoker: { summary: "WITH (security_invoker = true): check permissions as the caller", args: [arg("securityInvoker", "boolean")], since: 15 },
+  securityBarrier: { summary: "WITH (security_barrier = true)", args: [arg("securityBarrier", "boolean")] },
+  withNoData: { summary: "WITH NO DATA: a materialized view created unpopulated", args: [arg("noData", "boolean")] },
+};
+
+export const SEQUENCE_CLAUSES: Record<string, Clause> = {
+  persistence: { summary: "[ { TEMPORARY | UNLOGGED } ] SEQUENCE", args: [arg("persistence", "keyword", { values: ["TEMPORARY", "UNLOGGED"] })] },
+  options: { summary: "AS type, INCREMENT, MINVALUE, MAXVALUE, START, CACHE, [NO] CYCLE, OWNED BY (see SEQUENCE_OPTIONS)", args: [] },
+};

package/src/postgres/overlays/storage.ts

@@ -0,0 +1,75 @@
+/**
+ * Storage parameters (`WITH (fillfactor = 70)`): the overlay half.
+ *
+ * No catalog table lists them; they are compiled into `reloptions.c`.
+ * Generation probes the server instead: it tries every `pg_settings` name plus
+ * {@link STORAGE_PARAMETER_SEED} as `WITH (name = 1)` on each relation kind
+ * and keeps every name the server does not reject as unrecognized. The probe
+ * yields names only, so the types and ranges are here, and generation fails
+ * when a name the probe found has no entry (a pin move that adds a parameter
+ * has to type it in the same commit) or an entry names nothing the probe found.
+ */
+
+import { INT_MAX } from "./kinds";
+
+/** The reloptions that are not `pg_settings` names, so the probe would never try them. */
+export const STORAGE_PARAMETER_SEED: readonly string[] = [
+  "fillfactor", "toast_tuple_target", "parallel_workers", "user_catalog_table", "autovacuum_enabled",
+  "vacuum_index_cleanup", "vacuum_truncate", "autovacuum_vacuum_threshold", "autovacuum_vacuum_scale_factor",
+  "autovacuum_vacuum_max_threshold", "autovacuum_vacuum_insert_threshold", "autovacuum_vacuum_insert_scale_factor",
+  "autovacuum_analyze_threshold", "autovacuum_analyze_scale_factor", "autovacuum_vacuum_cost_delay",
+  "autovacuum_vacuum_cost_limit", "autovacuum_freeze_min_age", "autovacuum_freeze_max_age",
+  "autovacuum_freeze_table_age", "autovacuum_multixact_freeze_min_age", "autovacuum_multixact_freeze_max_age",
+  "autovacuum_multixact_freeze_table_age", "log_autovacuum_min_duration", "deduplicate_items", "buffering",
+  "fastupdate", "gin_pending_list_limit", "pages_per_range", "autosummarize", "security_barrier",
+  "security_invoker", "check_option", "vacuum_cleanup_index_scale_factor", "vacuum_max_eager_freeze_failure_rate",
+];
+
+export type StorageParameterType =
+  | { kind: "integer"; range: readonly [number, number] }
+  | { kind: "real"; range: readonly [number, number] }
+  | { kind: "boolean" }
+  | { kind: "enum"; values: readonly string[] };
+
+const int = (min: number, max: number): StorageParameterType => ({ kind: "integer", range: [min, max] });
+const real = (min: number, max: number): StorageParameterType => ({ kind: "real", range: [min, max] });
+const bool: StorageParameterType = { kind: "boolean" };
+
+/** Keyed by parameter name; the same name has the same type on every relation kind that accepts it. */
+export const STORAGE_PARAMETER_TYPES: Record<string, StorageParameterType> = {
+  fillfactor: int(10, 100),
+  toast_tuple_target: int(128, 1073741823),
+  parallel_workers: int(0, 1024),
+  user_catalog_table: bool,
+  autovacuum_enabled: bool,
+  vacuum_index_cleanup: { kind: "enum", values: ["auto", "on", "off", "true", "false"] },
+  vacuum_truncate: bool,
+  autovacuum_vacuum_threshold: int(0, INT_MAX),
+  autovacuum_vacuum_scale_factor: real(0, 100),
+  autovacuum_vacuum_max_threshold: int(-1, INT_MAX),
+  autovacuum_vacuum_insert_threshold: int(-1, INT_MAX),
+  autovacuum_vacuum_insert_scale_factor: real(0, 100),
+  autovacuum_analyze_threshold: int(0, INT_MAX),
+  autovacuum_analyze_scale_factor: real(0, 100),
+  autovacuum_vacuum_cost_delay: real(-1, 100),
+  autovacuum_vacuum_cost_limit: int(-1, 10000),
+  autovacuum_freeze_min_age: int(0, 1000000000),
+  autovacuum_freeze_max_age: int(100000, 2000000000),
+  autovacuum_freeze_table_age: int(0, 2000000000),
+  autovacuum_multixact_freeze_min_age: int(0, 1000000000),
+  autovacuum_multixact_freeze_max_age: int(10000, 2000000000),
+  autovacuum_multixact_freeze_table_age: int(0, 2000000000),
+  log_autovacuum_min_duration: int(-1, INT_MAX),
+  vacuum_max_eager_freeze_failure_rate: real(0, 1),
+  security_barrier: bool,
+  security_invoker: bool,
+  check_option: { kind: "enum", values: ["local", "cascaded"] },
+  deduplicate_items: bool,
+  // Accepted and ignored since 14, which removed the feature; kept so a dump from 13 still restores.
+  vacuum_cleanup_index_scale_factor: real(0, 10000000000),
+  buffering: { kind: "enum", values: ["on", "off", "auto"] },
+  fastupdate: bool,
+  gin_pending_list_limit: int(64, INT_MAX),
+  pages_per_range: int(1, 131072),
+  autosummarize: bool,
+};

package/src/postgres/overlays/type-ddl.ts

@@ -0,0 +1,38 @@
+/**
+ * `CREATE TYPE` and `CREATE DOMAIN`: the forms for new types. The catalog lists
+ * the built-ins; the grammar for declaring more is not in it.
+ */
+
+import { arg, type Clause } from "./kinds";
+
+export const TYPE_DDL: Record<string, Clause> = {
+  enum: {
+    summary: "CREATE TYPE name AS ENUM ('label', ...)",
+    args: [arg("labels", "string", { repeated: true })],
+  },
+  composite: {
+    summary: "CREATE TYPE name AS (attribute type [COLLATE c], ...)",
+    args: [arg("attributes", "type", { repeated: true })],
+  },
+  domain: {
+    summary: "CREATE DOMAIN name [AS] type [COLLATE c] [DEFAULT expression] [NOT NULL] [CHECK (expression)]",
+    args: [
+      arg("type", "type"),
+      arg("collation", "identifier", { optional: true }),
+      arg("default", "expression", { optional: true }),
+      arg("notNull", "boolean", { optional: true }),
+      arg("check", "expression", { optional: true, repeated: true }),
+    ],
+  },
+  range: {
+    summary: "CREATE TYPE name AS RANGE (SUBTYPE = type [, SUBTYPE_OPCLASS, COLLATION, CANONICAL, SUBTYPE_DIFF, MULTIRANGE_TYPE_NAME])",
+    args: [
+      arg("subtype", "type"),
+      arg("subtypeOpclass", "identifier", { optional: true }),
+      arg("collation", "identifier", { optional: true }),
+      arg("canonical", "identifier", { optional: true }),
+      arg("subtypeDiff", "identifier", { optional: true }),
+      arg("multirangeTypeName", "identifier", { optional: true }),
+    ],
+  },
+};

package/src/postgres/overlays/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Column type parameters and spellings: the overlay half.
+ *
+ * `pg_type` lists the types and `format_type()` gives each one's SQL spelling
+ * (`int4` is `integer`). The parameters (`varchar(n)`, `numeric(p, s)`,
+ * `timestamp(p)`, `interval` fields) and the spellings no catalog row carries
+ * (`int`, `decimal`, `serial`) are in no catalog table. A type missing here
+ * takes no parameters; generation fails when a key here is not a type at the
+ * pins.
+ */
+
+import { arg, type ClauseArgument } from "./kinds";
+
+/** Keyed by the canonical SQL name `format_type()` gives. */
+export const COLUMN_TYPE_PARAMETERS: Record<string, readonly ClauseArgument[]> = {
+  "character varying": [arg("length", "number", { optional: true, range: [1, 10485760] })],
+  character: [arg("length", "number", { optional: true, range: [1, 10485760] })],
+  bit: [arg("length", "number", { optional: true, range: [1, 83886080] })],
+  "bit varying": [arg("length", "number", { optional: true, range: [1, 83886080] })],
+  numeric: [arg("precision", "number", { optional: true, range: [1, 1000] }), arg("scale", "number", { optional: true, range: [-1000, 1000] })],
+  "timestamp without time zone": [arg("precision", "number", { optional: true, range: [0, 6] })],
+  "timestamp with time zone": [arg("precision", "number", { optional: true, range: [0, 6] })],
+  "time without time zone": [arg("precision", "number", { optional: true, range: [0, 6] })],
+  "time with time zone": [arg("precision", "number", { optional: true, range: [0, 6] })],
+  interval: [
+    arg("fields", "keyword", {
+      optional: true,
+      values: ["YEAR", "MONTH", "DAY", "HOUR", "MINUTE", "SECOND", "YEAR TO MONTH", "DAY TO HOUR", "DAY TO MINUTE", "DAY TO SECOND", "HOUR TO MINUTE", "HOUR TO SECOND", "MINUTE TO SECOND"],
+    }),
+    arg("precision", "number", { optional: true, range: [0, 6] }),
+  ],
+};
+
+/** Spellings that are not `format_type()` output, and the canonical name each stands for. */
+export const TYPE_SPELLINGS: Record<string, string> = {
+  int: "integer",
+  decimal: "numeric",
+  float: "double precision",
+  varchar: "character varying",
+  char: "character",
+  varbit: "bit varying",
+  timestamp: "timestamp without time zone",
+  timestamptz: "timestamp with time zone",
+  time: "time without time zone",
+  timetz: "time with time zone",
+};
+
+/** Pseudo-types that declare a sequence-backed column; each stands for a type plus a default and a sequence. */
+export const SERIAL_TYPES: Record<string, string> = {
+  smallserial: "smallint",
+  serial: "integer",
+  bigserial: "bigint",
+};
+
+/** An array suffix: `integer[]`, `text[3]`, `ARRAY`. Dimensions are documentation only to the server. */
+export const ARRAY_SUFFIX = { brackets: "[]", dimensioned: "[n]", keyword: "ARRAY" } as const;

package/src/postgres/parser.test.ts

@@ -0,0 +1,214 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { parseStatements, type IndexNode, type SequenceNode, type TableNode, type ViewNode } from "./parser";
+import { SqlSyntaxError, tokenize, tokenizeText, untokenize } from "./tokens";
+
+const parse = (sql: string) => parseStatements(tokenizeText(sql, 0));
+const one = <T>(sql: string) => parse(sql)[0] as T;
+const kinds = (sql: string) => tokenizeText(sql, 0).filter((t) => t.kind !== "ws").map((t) => `${t.kind}:${t.text}`);
+const fails = (sql: string): SqlSyntaxError => {
+  try {
+    parse(sql);
+  } catch (err) {
+    if (err instanceof SqlSyntaxError) return err;
+    throw err;
+  }
+  throw new Error(`parsed: ${sql}`);
+};
+/** The text an error is located at. */
+const at = (sql: string) => {
+  const err = fails(sql);
+  return sql.slice(err.offset, err.offset + (err.token?.text.length ?? 1));
+};
+
+describe("Postgres's lexical rules", () => {
+  test("are lossless: tokens give the raw text back, comments and spacing included", () => {
+    const parts = ["CREATE TABLE t (\n  a int, -- the key\n  /* outer /* inner */ still */ b ", " DEFAULT $$it's -- not$$\n)"];
+    expect(untokenize(tokenize(parts), (i) => "${" + i + "}")).toBe(parts.join("${0}"));
+  });
+
+  test("a backslash is ordinary in '...' and escapes only in E'...'", () => {
+    expect(kinds(String.raw`'a\'`)).toEqual([String.raw`string:'a\'`]);
+    expect(kinds(String.raw`E'a\'b'`)).toEqual([String.raw`string:E'a\'b'`]);
+  });
+
+  test("dollar quotes, prefixed strings, parameters and nested comments are one token each", () => {
+    expect(kinds("$tag$ a $$ b $tag$ $1 B'101' X'1F' U&'d\\0061t' /* a /* b */ c */")).toEqual([
+      "string:$tag$ a $$ b $tag$",
+      "param:$1",
+      "string:B'101'",
+      "string:X'1F'",
+      "string:U&'d\\0061t'",
+      "comment:/* a /* b */ c */",
+    ]);
+  });
+
+  test("a double quote makes an identifier; a backtick is an operator character", () => {
+    expect(kinds('"My Col" `')).toEqual(['qident:"My Col"', "op:`"]);
+  });
+
+  test("numbers never run into names, and an operator does not end in a sign", () => {
+    expect(kinds("1e-3 .5 0x1F 1_000 2abc")).toEqual(["number:1e-3", "number:.5", "number:0x1F", "number:1_000", "number:2", "ident:abc"]);
+    expect(kinds("a=-30 b<>-1 c@-1")).toEqual(["ident:a", "op:=", "op:-", "number:30", "ident:b", "op:<>", "op:-", "number:1", "ident:c", "op:@-", "number:1"]);
+  });
+});
+
+describe("CREATE TABLE", () => {
+  const node = one<TableNode>(`CREATE UNLOGGED TABLE IF NOT EXISTS App.Orders (
+    id        bigint GENERATED ALWAYS AS IDENTITY (START WITH 10) PRIMARY KEY,
+    "UserId"  bigint NOT NULL REFERENCES app.users (id) ON DELETE CASCADE DEFERRABLE INITIALLY DEFERRED,
+    status    text COLLATE "C" NOT NULL DEFAULT 'placed',
+    amount    numeric(12, 2) NOT NULL CHECK (amount >= 0),
+    total     numeric GENERATED ALWAYS AS (amount * 2) STORED,
+    tags      text[] DEFAULT ARRAY['a', 'b'],
+    during    tstzrange,
+    CONSTRAINT orders_status_ck CHECK (status IN ('placed', 'paid')) NOT VALID,
+    UNIQUE NULLS NOT DISTINCT (status, amount) INCLUDE (id) WITH (fillfactor = 90),
+    EXCLUDE USING gist (during WITH &&) WHERE (status <> 'cancelled'),
+    FOREIGN KEY ("UserId") REFERENCES app.users MATCH FULL ON UPDATE SET NULL ("UserId")
+  ) PARTITION BY RANGE (id) WITH (fillfactor = 70, toast.autovacuum_enabled = false) TABLESPACE fast`);
+
+  test("reads names, folding the unquoted ones", () => {
+    expect(node.persistence).toBe("unlogged");
+    expect(node.ifNotExists).toBe(true);
+    expect(node.name.pieces).toEqual(["app", "orders"]);
+    expect(node.columns.map((c) => c.name)).toEqual(["id", "UserId", "status", "amount", "total", "tags", "during"]);
+  });
+
+  test("reads identity, generated, defaults and column constraints", () => {
+    const [id, user, status, amount, total] = node.columns;
+    expect(id!.generated).toMatchObject({ kind: "identity", always: true });
+    expect(id!.constraints.map((c) => c.kind)).toEqual(["PRIMARY KEY"]);
+    expect(user!.constraints[0]).toMatchObject({ kind: "FOREIGN KEY", deferrable: true, initiallyDeferred: true });
+    expect(status!.notNull).toBe(true);
+    expect(status!.collate).toBeDefined();
+    expect(amount!.constraints.map((c) => c.kind)).toEqual(["CHECK"]);
+    expect(total!.generated).toMatchObject({ kind: "stored", always: true });
+  });
+
+  test("reads every table constraint kind and its attributes", () => {
+    expect(node.constraints.map((c) => c.kind)).toEqual(["CHECK", "UNIQUE", "EXCLUDE", "FOREIGN KEY"]);
+    expect(node.constraints[0]).toMatchObject({ name: "orders_status_ck", notValid: true });
+    expect(node.constraints[1]).toMatchObject({ nullsNotDistinct: true });
+    expect(node.constraints[2]).toMatchObject({ using: "gist" });
+    expect(node.constraints[3]!.references).toMatchObject({ match: "FULL" });
+    expect(node.partitionBy).toBeDefined();
+    expect(node.with).toBeDefined();
+  });
+
+  test("partitions, typed tables and LIKE parse", () => {
+    expect(one<TableNode>("CREATE TABLE p1 PARTITION OF orders FOR VALUES FROM (1) TO (100)").partitionOf?.pieces).toEqual(["orders"]);
+    expect(one<TableNode>("CREATE TABLE p2 PARTITION OF orders DEFAULT").partitionBound).toBeDefined();
+    expect(one<TableNode>("CREATE TABLE h PARTITION OF orders FOR VALUES WITH (MODULUS 4, REMAINDER 1)").partitionBound).toBeDefined();
+    expect(one<TableNode>("CREATE TABLE t OF some_type (a WITH OPTIONS NOT NULL)").columns[0]!.notNull).toBe(true);
+    expect(one<TableNode>("CREATE TABLE t (LIKE src INCLUDING ALL EXCLUDING INDEXES, x int)").like).toHaveLength(1);
+  });
+});
+
+describe("the grammar gaps the spike listed are closed", () => {
+  test("a default is a b_expr: a top-level IN, AND or IS NULL fails at that token", () => {
+    expect(at("CREATE TABLE t (a int DEFAULT 1 IN (1, 2))")).toBe("IN");
+    expect(at("CREATE TABLE t (a bool DEFAULT true AND false)")).toBe("AND");
+    expect(at("CREATE TABLE t (a bool DEFAULT 1 IS NULL)")).toBe("IS");
+    expect(() => parse("CREATE TABLE t (a bool DEFAULT (1 IN (1, 2)), b int DEFAULT 1 IS DISTINCT FROM 2)")).not.toThrow();
+  });
+
+  test("LIKE options and ON COMMIT take only their own words", () => {
+    expect(at("CREATE TABLE t (LIKE s INCLUDING EVERYTHING)")).toBe("EVERYTHING");
+    expect(at("CREATE TEMP TABLE t (a int) ON COMMIT KEEP ROWS")).toBe("KEEP");
+  });
+
+  test("a storage parameter list needs a value after =", () => {
+    expect(at("CREATE TABLE t (a int) WITH (fillfactor = )")).toBe(")");
+    expect(() => parse("CREATE TABLE t (a int) WITH (fillfactor=-30.1)")).not.toThrow();
+  });
+
+  test("a reserved word is never a type, and a range bound is never empty", () => {
+    expect(at("CREATE TABLE t (a ARRAY[4])")).toBe("ARRAY");
+    expect(at("CREATE TABLE p PARTITION OF t FOR VALUES FROM () TO (1)")).toBe(")");
+  });
+
+  test("a misspelt key word after an expression fails at the word", () => {
+    expect(at("CREATE TABLE t (a text DEFAULT 'x' CHEK (a <> ''))")).toBe("CHEK");
+    expect(at("CREATE TABLE t (a bigint PRIMRY KEY)")).toBe("PRIMRY");
+  });
+
+  test("a reserved word as a name needs quotes", () => {
+    expect(at("CREATE TABLE foo (with int)")).toBe("with");
+    expect(() => parse('CREATE TABLE foo ("with" int)')).not.toThrow();
+  });
+});
+
+describe("the other statements", () => {
+  test("an index: CONCURRENTLY, its elements, and a name that is never qualified", () => {
+    const node = one<IndexNode>(
+      "CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS users_email ON ONLY app.users USING btree (lower(email) text_pattern_ops, created_at DESC NULLS LAST) INCLUDE (id) WHERE deleted_at IS NULL",
+    );
+    expect(node).toMatchObject({ unique: true, concurrently: true, ifNotExists: true, only: true, using: "btree" });
+    expect(node.elements.map((e) => e.column)).toEqual([undefined, "created_at"]);
+    expect(at("CREATE INDEX app.x ON t (a)")).toBe(".");
+    expect(one<IndexNode>("CREATE INDEX ON t (a)").name).toBeUndefined();
+  });
+
+  test("views stop their query at WITH CHECK OPTION and WITH NO DATA, not at a CTE", () => {
+    const v = one<ViewNode>("CREATE OR REPLACE VIEW v (a, b) WITH (security_barrier) AS WITH x AS (SELECT 1 a, 2 b) SELECT * FROM x WITH LOCAL CHECK OPTION");
+    expect(v.columnNames.map((c) => c.name)).toEqual(["a", "b"]);
+    expect(v.checkOption).toBeDefined();
+    const m = one<ViewNode>("CREATE MATERIALIZED VIEW m AS SELECT 1 WITH NO DATA");
+    expect(m).toMatchObject({ materialized: true, withData: false });
+  });
+
+  test("a sequence's options, a domain, an enum, a schema and an extension", () => {
+    const s = one<SequenceNode>("CREATE SEQUENCE s AS integer INCREMENT BY 2 NO MINVALUE MAXVALUE 100 START WITH 5 CACHE 10 NO CYCLE OWNED BY t.id");
+    expect(s.options.map((o) => o.option)).toEqual(["AS", "INCREMENT", "NO MINVALUE", "MAXVALUE", "START", "CACHE", "NO CYCLE", "OWNED BY"]);
+    expect(parse("CREATE DOMAIN d AS text CONSTRAINT c CHECK (VALUE <> '') NOT VALID")[0]!.statement).toBe("domain");
+    expect(parse("CREATE TYPE mood AS ENUM ('sad', 'ok')")[0]!.statement).toBe("enum");
+    expect(at("CREATE TYPE mood AS (a int)")).toBe("(");
+    expect(parse("CREATE SCHEMA IF NOT EXISTS app AUTHORIZATION owner")[0]!.statement).toBe("schema");
+    expect(parse("CREATE EXTENSION IF NOT EXISTS citext WITH SCHEMA public VERSION '1.6' CASCADE")[0]!.statement).toBe("extension");
+  });
+
+  test("COMMENT ON statements follow a CREATE in one template", () => {
+    const nodes = parse("CREATE TABLE t (a int); COMMENT ON TABLE t IS 'x'; COMMENT ON COLUMN t.a IS NULL;");
+    expect(nodes.map((n) => n.statement)).toEqual(["table", "comment", "comment"]);
+  });
+});
+
+describe("Postgres's own regression SQL (REL_18_6)", () => {
+  const corpus = JSON.parse(readFileSync(join(import.meta.dirname, "testdata", "postgres-regress-corpus.json"), "utf-8")) as {
+    accepted: Record<string, string[]>;
+    rejected: string[];
+  };
+
+  test("every committed statement of the declared subset parses", () => {
+    const failed: string[] = [];
+    let n = 0;
+    for (const sqls of Object.values(corpus.accepted)) {
+      for (const sql of sqls) {
+        n++;
+        try {
+          parse(sql);
+        } catch (err) {
+          failed.push(`${(err as Error).message}: ${sql.slice(0, 120)}`);
+        }
+      }
+    }
+    expect(failed).toEqual([]);
+    expect(n).toBe(408);
+  });
+
+  test("every statement the tests write as a syntax error is rejected", () => {
+    const accepted = corpus.rejected.filter((sql) => {
+      try {
+        parse(sql);
+        return true;
+      } catch (err) {
+        if (err instanceof SqlSyntaxError) return false;
+        throw err;
+      }
+    });
+    expect(accepted).toEqual([]);
+    expect(corpus.rejected.length).toBe(27);
+  });
+});