@bolvrk/engine-sqlite 0.1.4

package/src/rules/indexes-and-types.ts

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+/** Index builds and the two rowid traps every SQLite schema eventually meets. */
+import type { Finding } from "@bolvrk/engine";
+import { constraintOf, createdColumns, dataTypeName, nameOf, tableConstraints, tableCreatedInMigration, tableOf, tableOptions } from "../helpers";
+import { sl016Meta, sl017Meta, sl018Meta } from "../metas/index";
+import { finding, type SlRule } from "../rule";
+
+type AnyNode = Record<string, any>;
+
+/** SL016: CREATE INDEX on a table that already exists — built under the write lock, no CONCURRENTLY. */
+export const sl016: SlRule = {
+  meta: sl016Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      if (stmt.node.type !== "create_index_stmt") continue;
+      const table = tableOf(stmt) ?? "";
+      if (table && tableCreatedInMigration(ctx.migration, stmt.index, table)) continue;
+      const index = nameOf((stmt.node as AnyNode).name);
+      out.push(
+        finding(sl016, stmt, {
+          title: `Index "${index}" is built under the write lock on "${table}"`,
+          message:
+            `SQLite has no concurrent index build: the table is scanned and the index written in one write transaction, and every other writer waits (or gets SQLITE_BUSY) until it finishes. ` +
+            `Small table, no problem; large table, build it in a window with busy_timeout set on the application's connections.`,
+          object: { table, index },
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+/** Column-level PRIMARY KEY constraint on a column definition, if any. */
+function primaryKeyOf(column: AnyNode): AnyNode | undefined {
+  return constraintOf(column, "constraint_primary_key");
+}
+
+/** SL017: a PRIMARY KEY column that is not exactly `INTEGER` (or is `INTEGER ... DESC`) in a rowid table. */
+export const sl017: SlRule = {
+  meta: sl017Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      if (stmt.node.type !== "create_table_stmt") continue;
+      if (tableOptions(stmt).includes("WITHOUT ROWID")) continue;
+      const table = tableOf(stmt) ?? "";
+      const columns = createdColumns(stmt);
+      // Composite or table-level keys are not rowid aliases by design; the trap is the single integer-looking column.
+      if (tableConstraints(stmt).some((c) => c.type === "constraint_primary_key" || c.constraint?.type === "constraint_primary_key")) continue;
+      for (const column of columns) {
+        const pk = primaryKeyOf(column);
+        if (!pk) continue;
+        const type = dataTypeName(column);
+        const direction = (pk.direction ?? pk.constraint?.direction)?.type;
+        const integerLike = /^(INT|INTEGER|BIGINT|SMALLINT|TINYINT|MEDIUMINT|INT2|INT8|UNSIGNED BIG INT)$/.test(type);
+        if (!integerLike) continue;
+        const exact = type === "INTEGER" && direction !== "sort_direction_desc";
+        if (exact) continue;
+        const name = nameOf(column.name);
+        out.push(
+          finding(sl017, stmt, {
+            title: `"${name}" ${type} PRIMARY KEY${direction === "sort_direction_desc" ? " DESC" : ""} on "${table}" is not a rowid alias`,
+            message:
+              `Only a column declared exactly INTEGER PRIMARY KEY aliases the rowid. This one gets its own unique index: every primary-key lookup is an extra B-tree hop, the value is not the rowid, and VACUUM may renumber the real rowid underneath it. ` +
+              `Spell it INTEGER PRIMARY KEY (ascending).`,
+            object: { table, column: name },
+          }),
+        );
+      }
+    }
+    return out;
+  },
+};
+
+/** SL018: AUTOINCREMENT. */
+export const sl018: SlRule = {
+  meta: sl018Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      if (stmt.node.type !== "create_table_stmt") continue;
+      const table = tableOf(stmt) ?? "";
+      for (const column of createdColumns(stmt)) {
+        if (!constraintOf(column, "constraint_auto_increment")) continue;
+        const name = nameOf(column.name);
+        out.push(
+          finding(sl018, stmt, {
+            title: `AUTOINCREMENT on "${table}"."${name}" costs every insert an extra write`,
+            message:
+              `Each insert also updates sqlite_sequence; the SQLite manual says AUTOINCREMENT "should be avoided if not strictly needed". INTEGER PRIMARY KEY already assigns increasing ids — keep the keyword only if reusing a deleted id would be a correctness bug.`,
+            object: { table, column: name },
+          }),
+        );
+      }
+    }
+    return out;
+  },
+};

package/src/rules/performance.ts

@@ -0,0 +1,207 @@
+// SPDX-License-Identifier: Apache-2.0
+/** Performance rules: indexes that cost writes without paying back, rebuild ordering, table shape, and pragmas that persist (or do not). */
+import type { Finding } from "@bolvrk/engine";
+import { constraintOf, createdColumns, dataTypeName, items, nameOf, pragmaOf, tableConstraints, tableOf, tableOptions } from "../helpers";
+import { sl031Meta, sl032Meta, sl033Meta, sl034Meta, sl035Meta } from "../metas/index";
+import { finding, type SlRule, type SlRuleContext } from "../rule";
+
+type AnyNode = Record<string, any>;
+type Stmt = SlRuleContext["migration"]["statements"][number];
+
+interface IndexDef {
+  stmt: Stmt;
+  name: string;
+  table: string;
+  columns: string[];
+  unique: boolean;
+}
+
+function indexColumns(stmt: Stmt): string[] {
+  return items((stmt.node as AnyNode).columns).map((spec: AnyNode) => (nameOf(spec.expr ?? spec) ?? "").toLowerCase());
+}
+
+/** Indexes the migration creates, in order. Expression indexes are left out — their columns are not comparable. */
+function createdIndexes(ctx: SlRuleContext): IndexDef[] {
+  const out: IndexDef[] = [];
+  for (const stmt of ctx.migration.statements) {
+    if (stmt.node.type !== "create_index_stmt") continue;
+    const specs = items((stmt.node as AnyNode).columns);
+    if (specs.some((spec: AnyNode) => (spec.expr ?? spec).type !== "identifier")) continue;
+    out.push({
+      stmt,
+      name: nameOf((stmt.node as AnyNode).name) ?? "",
+      table: (tableOf(stmt) ?? "").toLowerCase(),
+      columns: indexColumns(stmt),
+      unique: String((stmt.node as AnyNode).indexTypeKw?.name ?? "").toUpperCase() === "UNIQUE",
+    });
+  }
+  return out;
+}
+
+/** Columns a CREATE TABLE in this migration already keys: the rowid alias and UNIQUE columns. */
+function keyedColumns(ctx: SlRuleContext, table: string): { rowid?: string; unique: string[][] } {
+  const out: { rowid?: string; unique: string[][] } = { unique: [] };
+  for (const stmt of ctx.migration.statements) {
+    if (stmt.node.type !== "create_table_stmt" || (tableOf(stmt) ?? "").toLowerCase() !== table) continue;
+    const withoutRowid = tableOptions(stmt).includes("WITHOUT ROWID");
+    for (const column of createdColumns(stmt)) {
+      const name = (nameOf(column.name) ?? "").toLowerCase();
+      const pk = constraintOf(column, "constraint_primary_key");
+      if (pk && !withoutRowid && dataTypeName(column) === "INTEGER" && (pk.direction ?? pk.constraint?.direction)?.type !== "sort_direction_desc") out.rowid = name;
+      else if (pk || constraintOf(column, "constraint_unique")) out.unique.push([name]);
+    }
+    for (const constraint of tableConstraints(stmt)) {
+      const inner = constraint.constraint ?? constraint;
+      if (inner.type === "constraint_primary_key" || inner.type === "constraint_unique") {
+        out.unique.push(items(inner.columns).map((spec: AnyNode) => (nameOf(spec.expr ?? spec) ?? "").toLowerCase()));
+      }
+    }
+  }
+  return out;
+}
+
+const isPrefix = (short: string[], long: string[]) => short.length <= long.length && short.every((c, i) => long[i] === c);
+const sameColumns = (a: string[], b: string[]) => a.length === b.length && isPrefix(a, b);
+
+/** SL031: an index the planner will never prefer over what already exists. */
+export const sl031: SlRule = {
+  meta: sl031Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    const indexes = createdIndexes(ctx);
+    for (const index of indexes) {
+      const keyed = keyedColumns(ctx, index.table);
+      let why: string | undefined;
+      if (index.columns.length === 1 && index.columns[0] === keyed.rowid) {
+        why = `"${index.columns[0]}" is the INTEGER PRIMARY KEY — the rowid, which the table's own B-tree already indexes`;
+      } else if (keyed.unique.some((u) => sameColumns(u, index.columns))) {
+        why = `(${index.columns.join(", ")}) is already UNIQUE, which SQLite enforces with an index of its own`;
+      } else {
+        const wider = indexes.find(
+          (other) =>
+            other !== index &&
+            other.table === index.table &&
+            isPrefix(index.columns, other.columns) &&
+            // A unique index on a prefix is a constraint, not redundancy; a duplicate is reported once, on the later one.
+            (!index.unique || other.unique) &&
+            (other.columns.length > index.columns.length || other.stmt.index < index.stmt.index),
+        );
+        if (wider) {
+          why =
+            sameColumns(index.columns, wider.columns)
+              ? `it duplicates "${wider.name}"`
+              : `(${index.columns.join(", ")}) is a leading prefix of "${wider.name}" (${wider.columns.join(", ")}), which serves the same lookups`;
+        }
+      }
+      if (!why) continue;
+      out.push(
+        finding(sl031, index.stmt, {
+          title: `Index "${index.name}" on "${index.table}" is redundant`,
+          message: `${why[0]!.toUpperCase()}${why.slice(1)}. The index changes no plan and costs a write on every insert, update and delete. Drop it.`,
+          object: { table: index.table, index: index.name },
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+/** SL032: CREATE INDEX on a new table before the INSERT ... SELECT that fills it. */
+export const sl032: SlRule = {
+  meta: sl032Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    const statements = ctx.migration.statements;
+    for (const stmt of statements) {
+      if (stmt.node.type !== "create_index_stmt") continue;
+      const table = (tableOf(stmt) ?? "").toLowerCase();
+      const created = statements.some((s) => s.index < stmt.index && s.node.type === "create_table_stmt" && (tableOf(s) ?? "").toLowerCase() === table);
+      if (!created) continue;
+      const copy = statements.find(
+        (s) => s.index > stmt.index && s.node.type === "insert_stmt" && (tableOf(s) ?? "").toLowerCase() === table && (s.node as AnyNode).clauses?.some((c: AnyNode) => c.type === "select_stmt" || c.type === "compound_select_stmt"),
+      );
+      if (!copy) continue;
+      const index = nameOf((stmt.node as AnyNode).name) ?? "";
+      out.push(
+        finding(sl032, stmt, {
+          title: `Index "${index}" is built before the copy into "${table}"`,
+          message: `The INSERT ... SELECT that fills "${table}" maintains this index row by row. Move the CREATE INDEX after the copy so SQLite builds it once, sorted, over the populated table.`,
+          object: { table, index },
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+/** SL033: TEXT/BLOB primary key on a rowid table. */
+export const sl033: SlRule = {
+  meta: sl033Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      if (stmt.node.type !== "create_table_stmt" || tableOptions(stmt).includes("WITHOUT ROWID")) continue;
+      const columns = createdColumns(stmt);
+      const tableLevel = tableConstraints(stmt).some((c) => (c.constraint ?? c).type === "constraint_primary_key");
+      if (tableLevel) continue; // composite keys are SL017/SL024 territory and often deliberate
+      const pk = columns.find((c) => constraintOf(c, "constraint_primary_key"));
+      if (!pk) continue;
+      const type = dataTypeName(pk);
+      if (!/^(TEXT|BLOB|VARCHAR|CHAR|CLOB|CHARACTER|NCHAR|NVARCHAR|UUID)/.test(type)) continue;
+      const table = tableOf(stmt) ?? "";
+      const name = nameOf(pk.name) ?? "";
+      out.push(
+        finding(sl033, stmt, {
+          title: `"${table}" keys on ${type} "${name}" but stays a rowid table`,
+          message: `The primary key is a separate unique index over a rowid B-tree: every lookup by "${name}" walks two trees and the key is stored twice. Declare the table WITHOUT ROWID so the key is the table's own B-tree (small rows), or keep rowid deliberately for wide rows.`,
+          object: { table, column: name },
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+/** SL034: journal_mode set to a rollback mode. */
+export const sl034: SlRule = {
+  meta: sl034Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      const pragma = pragmaOf(stmt);
+      if (pragma?.name !== "journal_mode" || pragma.value === undefined || pragma.value === "wal") continue;
+      out.push(
+        finding(sl034, stmt, {
+          title: `journal_mode = ${pragma.value.toUpperCase()} is stored in the file for every connection`,
+          message: `${pragma.value.toUpperCase()} is a rollback-journal mode: a writer blocks every reader for the length of its transaction, and this setting outlives the migration — it is written into the database file. Set WAL, or leave the mode to the application's connection setup.`,
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+const CONNECTION_PRAGMAS = new Set(["cache_size", "synchronous", "temp_store", "mmap_size", "busy_timeout"]);
+
+/** SL035: a pragma that only affects the runner's connection. */
+export const sl035: SlRule = {
+  meta: sl035Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const stmt of ctx.migration.statements) {
+      const pragma = pragmaOf(stmt);
+      if (!pragma || pragma.value === undefined || !CONNECTION_PRAGMAS.has(pragma.name)) continue;
+      const durability = pragma.name === "synchronous" && ["off", "0"].includes(pragma.value);
+      out.push(
+        finding(sl035, stmt, {
+          title: `PRAGMA ${pragma.name} in a migration reaches only the runner's connection`,
+          message:
+            `${pragma.name} is per connection: the application never sees this value. ` +
+            (durability ? `And synchronous=OFF means a crash during the schema change can corrupt the file. ` : ``) +
+            `Set connection pragmas where the application opens connections.`,
+        }),
+      );
+    }
+    return out;
+  },
+};

package/src/rules/rebuild-pragmas.ts

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The twelve-step table rebuild and the pragmas around it. SQLite's ALTER
+ * TABLE does so little that most real schema changes are this recipe, and
+ * the recipe's steps 1, 10 and 12 are the ones people forget.
+ */
+import type { Finding } from "@bolvrk/engine";
+import { insideTransaction, pragmaIsOff, pragmaIsOn, pragmaOf, tableRebuilds } from "../helpers";
+import { sl009Meta, sl010Meta, sl011Meta, sl012Meta, sl019Meta } from "../metas/index";
+import { finding, type SlRule, type SlRuleContext } from "../rule";
+
+/** Statement indexes at which foreign keys are switched off / on / checked. */
+function pragmaTimeline(ctx: SlRuleContext) {
+  const off: number[] = [];
+  const on: number[] = [];
+  const check: number[] = [];
+  for (const stmt of ctx.migration.statements) {
+    const pragma = pragmaOf(stmt);
+    if (!pragma) continue;
+    if (pragma.name === "foreign_keys" && pragmaIsOff(pragma.value)) off.push(stmt.index);
+    else if (pragma.name === "foreign_keys" && pragmaIsOn(pragma.value)) on.push(stmt.index);
+    else if (pragma.name === "foreign_key_check") check.push(stmt.index);
+  }
+  return { off, on, check };
+}
+
+/** SL009: the rebuild recipe without PRAGMA foreign_keys=OFF before it. */
+export const sl009: SlRule = {
+  meta: sl009Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    const { off } = pragmaTimeline(ctx);
+    const inTx = insideTransaction(ctx.migration);
+    for (const { drop, table } of tableRebuilds(ctx.migration)) {
+      // Foreign keys are off for this DROP when an earlier OFF exists that was itself issued outside a transaction (inside one it is a no-op — SL010's finding).
+      const effectiveOff = off.some((index) => index < drop.index && !inTx[index]);
+      if (effectiveOff) continue;
+      out.push(
+        finding(sl009, drop, {
+          title: `Rebuild of "${table}" drops it with foreign keys still enforced`,
+          message:
+            `This file rebuilds "${table}" (drop, then rename a new table onto the name) without PRAGMA foreign_keys=OFF first. ` +
+            `With enforcement on, DROP TABLE runs an implicit DELETE FROM "${table}": rows referencing it fail the migration, or ON DELETE CASCADE removes them. ` +
+            `Switch foreign keys off outside the transaction, rebuild, run PRAGMA foreign_key_check, commit, switch them on.`,
+          object: { table },
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+const TRANSACTION_NOOP_PRAGMAS = new Set(["foreign_keys", "journal_mode"]);
+
+/** SL010: PRAGMA foreign_keys / journal_mode after BEGIN — silently ignored. */
+export const sl010: SlRule = {
+  meta: sl010Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    const inTx = insideTransaction(ctx.migration);
+    for (const stmt of ctx.migration.statements) {
+      const pragma = pragmaOf(stmt);
+      if (!pragma || pragma.value === undefined || !TRANSACTION_NOOP_PRAGMAS.has(pragma.name)) continue;
+      if (!inTx[stmt.index]) continue;
+      out.push(
+        finding(sl010, stmt, {
+          title: `PRAGMA ${pragma.name} inside a transaction does nothing`,
+          message:
+            `SQLite ignores PRAGMA ${pragma.name} while a transaction is open — no error, the setting stays as it was. ` +
+            `Move it before BEGIN (and its counterpart after COMMIT); if the runner wraps the file in a transaction, the runner has to set it.`,
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+/** SL011: foreign keys switched off and never back on in this file. */
+export const sl011: SlRule = {
+  meta: sl011Meta,
+  check(ctx) {
+    const { off, on } = pragmaTimeline(ctx);
+    if (off.length === 0) return [];
+    const lastOff = off[off.length - 1]!;
+    if (on.some((index) => index > lastOff)) return [];
+    const stmt = ctx.migration.statements[lastOff]!;
+    return [
+      finding(sl011, stmt, {
+        title: "Foreign keys are switched off and not switched back on",
+        message:
+          `PRAGMA foreign_keys=OFF is per connection and survives COMMIT; nothing in this file re-enables it, so the runner's connection accepts orphaned rows for every statement that follows. ` +
+          `End the file with PRAGMA foreign_keys=ON after the transaction that needed it off.`,
+      }),
+    ];
+  },
+};
+
+/** SL012: foreign keys re-enabled without PRAGMA foreign_key_check in between. */
+export const sl012: SlRule = {
+  meta: sl012Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    const { off, on, check } = pragmaTimeline(ctx);
+    for (const onIndex of on) {
+      const offIndex = [...off].reverse().find((index) => index < onIndex);
+      if (offIndex === undefined) continue;
+      if (check.some((index) => index > offIndex && index < onIndex)) continue;
+      const stmt = ctx.migration.statements[onIndex]!;
+      out.push(
+        finding(sl012, stmt, {
+          title: "Foreign keys re-enabled without a foreign_key_check",
+          message:
+            `Turning enforcement back on does not validate rows written while it was off. Run PRAGMA foreign_key_check inside the transaction, before COMMIT, so a violation can still be rolled back.`,
+        }),
+      );
+    }
+    return out;
+  },
+};
+
+/** SL019: the rebuild recipe with the copy step missing — the old table is dropped before its rows reach the new one. */
+export const sl019: SlRule = {
+  meta: sl019Meta,
+  check(ctx) {
+    const out: Finding[] = [];
+    for (const rebuild of tableRebuilds(ctx.migration)) {
+      // Only the documented recipe (new table created here, then swapped in) says anything about the rows; renaming one live table onto another is SL007's business.
+      if (!rebuild.replacementCreatedHere || rebuild.copy) continue;
+      const { drop, table, replacement } = rebuild;
+      out.push(
+        finding(sl019, drop, {
+          title: `Rebuild of "${table}" drops it without copying its rows into "${replacement}"`,
+          message:
+            `This file creates "${replacement}", drops "${table}" and renames "${replacement}" onto the name, but no INSERT INTO "${replacement}" ... SELECT ... FROM "${table}" runs before the DROP. ` +
+            `DROP TABLE discards the rows; the rename brings back the name with an empty table. Copy first (INSERT INTO "${replacement}" SELECT ... FROM "${table}"), then drop — or, if the data is meant to go, say so in a bolvrk-ignore reason.`,
+          object: { table },
+        }),
+      );
+    }
+    return out;
+  },
+};