@galadrim/galadmin 0.1.236 → 0.2.7

package/tests/dbManager.init.test.ts

@@ -0,0 +1,129 @@
+import dbManager from "../src/utils/dbManager";
+
+jest.mock("mysql", () => ({ createPool: jest.fn() }));
+jest.mock("mysql2", () => ({ createPool: jest.fn() }));
+jest.mock("pg", () => ({ Pool: jest.fn() }));
+
+import { createPool as mysqlCreatePool } from "mysql";
+import { createPool as mysql2CreatePool } from "mysql2";
+import { Pool as PgPool } from "pg";
+
+const mockMysqlCreatePool = mysqlCreatePool as unknown as jest.Mock;
+const mockMysql2CreatePool = mysql2CreatePool as unknown as jest.Mock;
+const mockPgPool = PgPool as unknown as jest.Mock;
+
+// Pool-construction wiring only; driver interaction is covered in
+// tests/integration/dbManager.integration.test.ts.
+describe("dbManager.init (pool wiring)", () => {
+  beforeEach(() => {
+    mockMysqlCreatePool.mockClear();
+    mockMysql2CreatePool.mockClear();
+    mockPgPool.mockClear();
+  });
+
+  const mysqlConfig = {
+    mysql: {
+      host: "db.local",
+      user: "root",
+      password: "secret",
+      database: "galadmin",
+    },
+  };
+
+  it("creates a mysql pool with the expected options", () => {
+    const manager = new dbManager();
+    manager.init(mysqlConfig);
+    expect(mockMysqlCreatePool).toHaveBeenCalledTimes(1);
+    expect(mockMysqlCreatePool).toHaveBeenCalledWith(
+      expect.objectContaining({
+        host: "db.local",
+        user: "root",
+        password: "secret",
+        database: "galadmin",
+        port: 3306,
+        charset: "UTF8MB4_GENERAL_CI",
+        dateStrings: true,
+        multipleStatements: false,
+      }),
+    );
+    expect(manager.dbType).toBe("MYSQL");
+  });
+
+  it("honours a custom mysql port", () => {
+    const manager = new dbManager();
+    manager.init({
+      mysql: { ...mysqlConfig.mysql, port: 3307 },
+    });
+    expect(mockMysqlCreatePool).toHaveBeenCalledWith(
+      expect.objectContaining({ port: 3307 }),
+    );
+  });
+
+  it("keeps multipleStatements OFF unless explicitly opted in", () => {
+    const manager = new dbManager();
+    manager.init({
+      mysql: { ...mysqlConfig.mysql, multipleStatements: true },
+    });
+    expect(mockMysqlCreatePool).toHaveBeenCalledWith(
+      expect.objectContaining({ multipleStatements: true }),
+    );
+  });
+
+  it("switches to the mysql2 driver with useMysql2", () => {
+    const manager = new dbManager();
+    manager.init({ ...mysqlConfig, useMysql2: true });
+    expect(mockMysqlCreatePool).not.toHaveBeenCalled();
+    expect(mockMysql2CreatePool).toHaveBeenCalledTimes(1);
+    expect(manager.dbType).toBe("MYSQL");
+  });
+
+  it("creates a pg pool with port and ssl defaults", () => {
+    const manager = new dbManager();
+    manager.init({
+      postgresql: {
+        host: "pg.local",
+        user: "admin",
+        password: "secret",
+        database: "galadmin",
+      },
+    });
+    expect(mockPgPool).toHaveBeenCalledTimes(1);
+    expect(mockPgPool).toHaveBeenCalledWith(
+      expect.objectContaining({
+        host: "pg.local",
+        user: "admin",
+        password: "secret",
+        database: "galadmin",
+        port: 5432,
+        ssl: undefined,
+      }),
+    );
+    expect(manager.dbType).toBe("POSTGRESQL");
+  });
+
+  it("passes the ssl option through to the pg pool", () => {
+    const manager = new dbManager();
+    const ssl = { rejectUnauthorized: false };
+    manager.init({
+      postgresql: {
+        host: "pg.local",
+        user: "admin",
+        password: "secret",
+        database: "galadmin",
+        ssl,
+      },
+    });
+    expect(mockPgPool).toHaveBeenCalledWith(
+      expect.objectContaining({ ssl }),
+    );
+  });
+
+  it("leaves the manager uninitialised without a database config", () => {
+    const manager = new dbManager();
+    manager.init({});
+    expect(mockMysqlCreatePool).not.toHaveBeenCalled();
+    expect(mockMysql2CreatePool).not.toHaveBeenCalled();
+    expect(mockPgPool).not.toHaveBeenCalled();
+    expect(manager.dbType).toBeUndefined();
+  });
+});

package/tests/dbManager.test.ts

@@ -0,0 +1,265 @@
+import {
+  convertQuery,
+  quotePostgresQuery,
+  quoteIdentifier,
+} from "../src/utils/dbManager";
+
+/**
+ * Pure string-transformation helpers of dbManager. Pool wiring and driver
+ * interaction run against real engines in tests/integration/
+ * dbManager.integration.test.ts.
+ */
+
+describe("convertQuery (MySQL -> PostgreSQL placeholder conversion)", () => {
+  it("converts ? placeholders to $N in order", () => {
+    const { pgQuery, pgParams } = convertQuery(
+      "SELECT * FROM t WHERE a = ? AND b = ?",
+      ["x", 2],
+    );
+    expect(pgQuery).toBe("SELECT * FROM t WHERE a = $1 AND b = $2");
+    expect(pgParams).toEqual(["x", 2]);
+  });
+
+  it("substitutes ?? identifiers inline (unquoted)", () => {
+    const { pgQuery, pgParams } = convertQuery("SELECT * FROM ?? WHERE id = ?", [
+      "fruits",
+      7,
+    ]);
+    expect(pgQuery).toBe("SELECT * FROM fruits WHERE id = $1");
+    expect(pgParams).toEqual([7]);
+  });
+
+  it("handles mixed ?? and ? sequences", () => {
+    const { pgQuery, pgParams } = convertQuery(
+      "UPDATE ?? SET `a` = ? WHERE ?? = ?",
+      ["fruits", 1, "fruits", 2],
+    );
+    expect(pgQuery).toBe("UPDATE fruits SET `a` = $1 WHERE fruits = $2");
+    expect(pgParams).toEqual([1, 2]);
+  });
+
+  it("handles a query without placeholders", () => {
+    const { pgQuery, pgParams } = convertQuery("SELECT 1", []);
+    expect(pgQuery).toBe("SELECT 1");
+    expect(pgParams).toEqual([]);
+  });
+});
+
+describe("quotePostgresQuery", () => {
+  it("converts backticks to double quotes", () => {
+    expect(quotePostgresQuery("SELECT * FROM `fruits`")).toBe(
+      'SELECT * FROM "fruits"',
+    );
+  });
+
+  it("quotes bare identifiers", () => {
+    expect(quotePostgresQuery("SELECT fruitName FROM fruits")).toBe(
+      'SELECT "fruitName" FROM "fruits"',
+    );
+  });
+
+  it("quotes dotted identifiers", () => {
+    expect(quotePostgresQuery("SELECT fruits.id FROM fruits")).toBe(
+      'SELECT "fruits"."id" FROM "fruits"',
+    );
+  });
+
+  it("leaves reserved keywords unquoted", () => {
+    const query = "SELECT COUNT(*) FROM fruits WHERE a = 1 ORDER BY a DESC";
+    const result = quotePostgresQuery(query);
+    expect(result).toContain("COUNT(*)");
+    expect(result).toContain("ORDER BY");
+    expect(result).toContain("DESC");
+    expect(result).not.toContain('"ORDER"');
+    expect(result).not.toContain('"COUNT"');
+    expect(result).not.toContain('"DESC"');
+  });
+
+  it("leaves the upsert keywords (ON CONFLICT / DO / EXCLUDED / RETURNING) unquoted", () => {
+    // Input as it arrives after convertQuery (no `??` placeholders left).
+    const query =
+      'INSERT INTO fruits ("id", "fruitName") VALUES($1, $2) ON CONFLICT ("id") DO UPDATE SET "fruitName" = EXCLUDED."fruitName" RETURNING id';
+    const result = quotePostgresQuery(query);
+    expect(result).toContain("ON CONFLICT");
+    expect(result).toContain("DO UPDATE");
+    expect(result).toContain('EXCLUDED."fruitName"');
+    expect(result).toContain("RETURNING");
+    expect(result).not.toContain('"CONFLICT"');
+    expect(result).not.toContain('"DO"');
+    expect(result).not.toContain('"EXCLUDED"');
+    expect(result).not.toContain('"RETURNING"');
+  });
+
+  it("leaves string literals unquoted but quotes bare identifiers around them", () => {
+    expect(quotePostgresQuery("SELECT * FROM fruits WHERE name = 'pomme'")).toBe(
+      "SELECT * FROM \"fruits\" WHERE \"name\" = 'pomme'",
+    );
+  });
+
+  it("leaves $N placeholders unquoted", () => {
+    expect(quotePostgresQuery("SELECT * FROM fruits WHERE id = $1")).toBe(
+      'SELECT * FROM "fruits" WHERE "id" = $1',
+    );
+  });
+
+  it("leaves numbers unquoted", () => {
+    expect(quotePostgresQuery("SELECT * FROM fruits LIMIT 10")).toContain(
+      "LIMIT 10",
+    );
+  });
+
+  it("converts LIKE to ::text ILIKE", () => {
+    expect(
+      quotePostgresQuery("SELECT * FROM fruits WHERE name LIKE '%abc%'"),
+    ).toBe(
+      "SELECT * FROM \"fruits\" WHERE \"name\"::text ILIKE '%abc%'",
+    );
+  });
+
+  it("converts ) LIKE to ) ILIKE", () => {
+    expect(
+      quotePostgresQuery("SELECT * FROM fruits WHERE (name) LIKE '%abc%'"),
+    ).toBe(
+      "SELECT * FROM \"fruits\" WHERE (\"name\") ILIKE '%abc%'",
+    );
+  });
+
+  it("quotes identifiers inside a count subquery", () => {
+    const result = quotePostgresQuery(
+      "SELECT COUNT(*) AS count FROM (SELECT * FROM fruits) s",
+    );
+    expect(result).toContain('FROM (SELECT * FROM "fruits")');
+    expect(result).toContain("COUNT(*)");
+  });
+});
+
+describe("quoteIdentifier", () => {
+  it("uses backticks for MySQL", () => {
+    expect(quoteIdentifier("fruits", "MYSQL")).toBe("`fruits`");
+  });
+
+  it("uses double quotes for PostgreSQL", () => {
+    expect(quoteIdentifier("fruits", "POSTGRESQL")).toBe('"fruits"');
+  });
+});
+
+describe("convertQuery / quotePostgresQuery (adversarial cases)", () => {
+  it("quotes identifiers containing digits and underscores", () => {
+    expect(quotePostgresQuery("SELECT address_2, col1 FROM t1")).toBe(
+      'SELECT "address_2", "col1" FROM "t1"',
+    );
+  });
+
+  it("does not quote numeric-only words", () => {
+    expect(quotePostgresQuery("SELECT * FROM t LIMIT 123")).not.toContain(
+      '"123"',
+    );
+  });
+
+  it("keeps placeholders for parameters arriving after identifier interpolation", () => {
+    const { pgQuery, pgParams } = convertQuery(
+      "UPDATE ?? SET `a` = ?, `b` = ? WHERE ?? IN(?, ?)",
+      ["fruits", 1, "x", "fruits", 2, 3],
+    );
+    expect(pgQuery).toBe(
+      "UPDATE fruits SET `a` = $1, `b` = $2 WHERE fruits IN($3, $4)",
+    );
+    expect(pgParams).toEqual([1, "x", 2, 3]);
+  });
+
+  it("keeps a literal '?' inside a string literal out of the placeholder conversion", () => {
+    // Placeholders only carry meaning outside '…' literals: the LIKE pattern
+    // below is interpolated before conversion and its '?' must survive verbatim.
+    // (`??` consumes its parameter inline and adds nothing to pgParams.)
+    const { pgQuery, pgParams } = convertQuery(
+      "SELECT * FROM ?? WHERE fruitName::text ILIKE '%what?%'",
+      ["fruits"],
+    );
+    expect(pgQuery).toBe(
+      "SELECT * FROM fruits WHERE fruitName::text ILIKE '%what?%'",
+    );
+    expect(pgParams).toEqual([]);
+  });
+
+  it("keeps doubled quotes inside string literals without leaving string mode", () => {
+    const { pgQuery, pgParams } = convertQuery(
+      "SELECT * FROM ?? WHERE a = 'l''orange?' AND b = ?",
+      ["fruits", 5],
+    );
+    expect(pgQuery).toBe(
+      "SELECT * FROM fruits WHERE a = 'l''orange?' AND b = $1",
+    );
+    expect(pgParams).toEqual([5]);
+  });
+
+  it("treats a backslash as an ordinary character in standard string literals", () => {
+    const { pgQuery, pgParams } = convertQuery(
+      "SELECT * FROM t WHERE path = 'C:\\' AND id = ?",
+      [7],
+    );
+    expect(pgQuery).toBe("SELECT * FROM t WHERE path = 'C:\\' AND id = $1");
+    expect(pgParams).toEqual([7]);
+  });
+
+  it("honours backslash escapes in E'…' string literals", () => {
+    const { pgQuery, pgParams } = convertQuery(
+      "SELECT * FROM t WHERE a = E'l\\'orange?' AND b = e'C:\\\\' AND c = ?",
+      [7],
+    );
+    expect(pgQuery).toBe(
+      "SELECT * FROM t WHERE a = E'l\\'orange?' AND b = e'C:\\\\' AND c = $1",
+    );
+    expect(pgParams).toEqual([7]);
+  });
+
+  it("does not treat an identifier ending in 'e' as an E'…' prefix", () => {
+    const { pgQuery, pgParams } = convertQuery(
+      "SELECT * FROM t WHERE code = some'C:\\' AND id = ?",
+      [7],
+    );
+    expect(pgQuery).toBe("SELECT * FROM t WHERE code = some'C:\\' AND id = $1");
+    expect(pgParams).toEqual([7]);
+  });
+
+  it("copies comments verbatim, ignoring quotes and placeholders inside them", () => {
+    const { pgQuery, pgParams } = convertQuery(
+      "-- l'utilisateur ?\nSELECT * FROM t /* l'id ? */ WHERE id = ? -- fin ?",
+      [7],
+    );
+    expect(pgQuery).toBe(
+      "-- l'utilisateur ?\nSELECT * FROM t /* l'id ? */ WHERE id = $1 -- fin ?",
+    );
+    expect(pgParams).toEqual([7]);
+  });
+
+  it("ignores reserved words written in mixed case", () => {
+    const result = quotePostgresQuery(
+      "select count(*) from fruits where a = 1 group by a order by a desc",
+    );
+    expect(result).not.toContain('"select"');
+    expect(result).not.toContain('"group"');
+    expect(result).toContain('"fruits"');
+  });
+
+  it("quotes dotted (table-qualified) identifiers segment by segment", () => {
+    expect(
+      quotePostgresQuery("SELECT * FROM fruits WHERE fruits.id = $1"),
+    ).toBe('SELECT * FROM "fruits" WHERE "fruits"."id" = $1');
+  });
+
+  it("keeps $N placeholders and IN lists intact while quoting identifiers", () => {
+    expect(
+      quotePostgresQuery("DELETE FROM fruits WHERE id IN($1, $2)"),
+    ).toBe('DELETE FROM "fruits" WHERE "id" IN($1, $2)');
+  });
+
+  it("leaves doubled quote escapes inside literals untouched while quoting", () => {
+    expect(
+      quotePostgresQuery(
+        "SELECT * FROM fruits WHERE fruitName LIKE '%l''orange%'",
+      ),
+    ).toBe(
+      "SELECT * FROM \"fruits\" WHERE \"fruitName\"::text ILIKE '%l''orange%'",
+    );
+  });
+});

package/tests/edge-cases.test.ts

@@ -0,0 +1,167 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import * as request from "supertest";
+import { buildApiApp } from "./helpers/app";
+import { FakeDb } from "./helpers/fakeDb";
+import {
+  baseConfig,
+  fruitSchema,
+  fruitView,
+} from "./helpers/fixtures";
+import { generateUniqueIdForObject } from "../src/api";
+
+jest.mock("axios");
+jest.mock("uuid", () => ({ v4: jest.fn(() => "test-uuid-1234-5678") }));
+
+describe("column-name validation through the routes", () => {
+  let db: FakeDb;
+
+  beforeEach(() => {
+    db = new FakeDb();
+    db.schemaRows = fruitSchema();
+  });
+
+  it.each([
+    ["semicolon", { "a;b": "x" }],
+    ["space", { "a b": "x" }],
+    ["dash", { "a-b": "x" }],
+    ["backtick", { "`a`": "x" }],
+    ["quote", { "a'": "x" }],
+    ["unicode", { "café": "x" }],
+    ["empty key", { "": "x" }],
+    ["newline", { "a\nb": "x" }],
+  ])("POST /api/updateRecord rejects a %s column name with 400", async (
+    _label,
+    data,
+  ) => {
+    const app = buildApiApp(db, baseConfig());
+    await request(app)
+      .post("/api/updateRecord")
+      .send({ viewIndex: 0, primaryValue: 5, data })
+      .expect(400);
+    expect(db.dataQueries().length).toBe(0);
+  });
+
+  it("POST /api/createRecord rejects unsafe column names with 400", async () => {
+    const app = buildApiApp(db, baseConfig());
+    await request(app)
+      .post("/api/createRecord")
+      .send({ viewIndex: 0, data: { "a;b": "x" } })
+      .expect(400);
+    expect(db.dataQueries().length).toBe(0);
+  });
+
+  it("accepts long but plain identifiers", async () => {
+    const longName = "c".repeat(64);
+    db.queueRows({ insertId: 1 });
+    const app = buildApiApp(db, baseConfig());
+    await request(app)
+      .post("/api/updateRecord")
+      .send({ viewIndex: 0, primaryValue: 5, data: { [longName]: "x" } })
+      .expect(200);
+    expect(db.lastQuery().params).toEqual(["fruits", "x", "id", 5]);
+  });
+});
+
+describe("upload edge cases (local fs backend)", () => {
+  let db: FakeDb;
+  let uploadRoot: string;
+  let fileColumn: any;
+
+  beforeEach(() => {
+    db = new FakeDb();
+    db.schemaRows = fruitSchema();
+    uploadRoot = fs.mkdtempSync(path.join(os.tmpdir(), "galadmin-upload-"));
+    fs.mkdirSync(path.join(uploadRoot, "up"));
+    fileColumn = {
+      label: "Fichier",
+      name: "file",
+      publicPath: uploadRoot,
+      subdirectory: "/up",
+    };
+  });
+
+  afterEach(() => {
+    fs.rmSync(uploadRoot, { recursive: true, force: true });
+  });
+
+  const configFor = () =>
+    baseConfig({ views: [fruitView({ columns: [fileColumn] })] });
+
+  it("returns 500 for a malformed multipart body instead of hanging", async () => {
+    const app = buildApiApp(db, configFor());
+    await request(app)
+      .post("/api/uploadFile")
+      .query({
+        viewIndex: 0,
+        columnId: generateUniqueIdForObject(fileColumn),
+      })
+      .set("content-type", "multipart/form-data; boundary=XXBOUNDARYXX")
+      .send("this is not multipart data")
+      .expect(500);
+  });
+
+  it("returns 500 (ENOENT) when the target subdirectory does not exist", async () => {
+    // No mkdir: documents that a traversal-bearing subdirectory is not
+    // validated but fails closed because multiparty requires the dir.
+    fileColumn.subdirectory = "/../escape";
+    const app = buildApiApp(db, configFor());
+    await request(app)
+      .post("/api/uploadFile")
+      .query({
+        viewIndex: 0,
+        columnId: generateUniqueIdForObject(fileColumn),
+      })
+      .attach("file", Buffer.from("png"), { filename: "x.png" })
+      .expect(500);
+    expect(fs.existsSync(path.join(uploadRoot, "escape"))).toBe(false);
+  });
+
+  it("silently accepts an empty file", async () => {
+    const app = buildApiApp(db, configFor());
+    const res = await request(app)
+      .post("/api/uploadFile")
+      .query({
+        viewIndex: 0,
+        columnId: generateUniqueIdForObject(fileColumn),
+      })
+      .attach("file", Buffer.alloc(0), { filename: "empty.png" })
+      .expect(200);
+    expect(res.body.originalFilename).toBe("empty.png");
+    // The temp file was written into the target directory.
+    expect(fs.readdirSync(path.join(uploadRoot, "up")).length).toBe(1);
+  });
+});
+
+describe("CHARACTERIZATION: multi-query operations are not transactional", () => {
+  let db: FakeDb;
+
+  beforeEach(() => {
+    db = new FakeDb();
+    db.schemaRows = fruitSchema();
+  });
+
+  it("createRecord: a throwing createCallbackFunction does not fail the request", async () => {
+    // The INSERT is committed before the callback runs; reporting a 500 would
+    // invite a client retry that duplicates the row, so the callback error is
+    // logged and the request still answers 200.
+    const config = baseConfig({
+      views: [
+        fruitView({
+          createCallbackFunction: () => {
+            throw new Error("callback exploded");
+          },
+        }),
+      ],
+    });
+    db.queueRows({ insertId: 42 });
+    const app = buildApiApp(db, config);
+    await request(app)
+      .post("/api/createRecord")
+      .send({ viewIndex: 0, data: { fruitName: "pomme" } })
+      .expect(200);
+    expect(db.dataQueries().length).toBe(1);
+    expect(db.dataQueries()[0].sql).toContain("INSERT INTO ??");
+  });
+});

package/tests/helpers/app.ts

@@ -0,0 +1,69 @@
+import * as express from "express";
+import api from "../../src/api";
+import dbManager from "../../src/utils/dbManager";
+import { FakeDb } from "./fakeDb";
+import { FakePool } from "./fakePool";
+
+export type SessionUser = { role: string; userId?: number } | null;
+
+export type SessionMode =
+  | SessionUser // a user object, or null for "logged out" (session without user)
+  | "none"; // no session object at all (MW1 would throw on a bare router)
+
+function appWithSession(sessionUser: SessionMode, router: any) {
+  const app = express();
+  app.use(express.json({ limit: "50mb" }));
+  app.use((req: any, _res, next) => {
+    if (sessionUser === "none") {
+      req.session = undefined;
+    } else {
+      req.session = { user: sessionUser };
+    }
+    next();
+  });
+  app.use("/api", router);
+  return app;
+}
+
+/**
+ * Builds an express app exposing the api router under /api, exactly like
+ * src/index.ts does, but with an injectable session stub so tests can pick
+ * the caller's role without a real session store.
+ */
+export function buildApiApp(
+  db: FakeDb,
+  config: any,
+  sessionUser: SessionMode = { role: "root", userId: 1 },
+) {
+  return appWithSession(sessionUser, api(db, config));
+}
+
+/**
+ * Builds the same app on top of an externally provided db manager (real
+ * driver pool or FakePool). Used by the PostgreSQL pipeline unit tests and
+ * by the real-database integration suite.
+ */
+export function buildAppForManager(
+  manager: any,
+  config: any,
+  sessionUser: SessionMode = { role: "root", userId: 1 },
+) {
+  return appWithSession(sessionUser, api(manager, config));
+}
+
+/**
+ * Builds the same app on top of a REAL dbManager whose driver pool is the
+ * scripted FakePool. The dialect conversion pipeline (MySQL -> PostgreSQL
+ * placeholder conversion + identifier quoting) therefore runs for real and
+ * the recorded SQL is what the driver would receive.
+ */
+export function buildManagerApp(
+  pool: FakePool,
+  config: any,
+  sessionUser: SessionMode = { role: "root", userId: 1 },
+) {
+  const manager = new dbManager();
+  manager.dbType = pool.dbType;
+  (manager as any)._db = pool;
+  return buildAppForManager(manager, config, sessionUser);
+}

package/tests/helpers/fakeDb.ts

@@ -0,0 +1,66 @@
+/**
+ * Scripted fake for the dbManager abstraction used by the galadmin routes.
+ *
+ * Mirrors the contract produced by src/utils/dbManager.ts:
+ *   db.dbType: "MYSQL" | "POSTGRESQL"
+ *   db.query(sql, params) -> Promise<{ err, rows, fields }>
+ *
+ * - Every executed query is recorded in `queries` so tests can assert the
+ *   exact SQL and bound parameters.
+ * - `information_schema` queries (config enrichment) are answered from
+ *   `schemaRows` and never consume the scripted queue.
+ * - Everything else consumes the FIFO `queue`; an empty queue yields
+ *   `{ err: null, rows: [] }`.
+ */
+export type FakeQueryResult = { err?: any; rows?: any; fields?: any };
+export type RecordedQuery = { sql: string; params: any[] };
+
+export class FakeDb {
+  dbType: "MYSQL" | "POSTGRESQL" = "MYSQL";
+  schemaRows: any[] = [];
+  queries: RecordedQuery[] = [];
+  private queue: FakeQueryResult[] = [];
+  defaultResult: FakeQueryResult = { err: null, rows: [] };
+
+  queueResult(result: FakeQueryResult) {
+    this.queue.push({ err: null, rows: [], ...result });
+    return this;
+  }
+
+  queueRows(rows: any) {
+    return this.queueResult({ err: null, rows });
+  }
+
+  queueErr(err: any) {
+    return this.queueResult({ err, rows: null });
+  }
+
+  async query(sql: string, params: any[] = []): Promise<FakeQueryResult> {
+    this.queries.push({ sql, params });
+    if (typeof sql === "string" && sql.includes("information_schema")) {
+      return { err: null, rows: this.schemaRows };
+    }
+    if (this.queue.length > 0) {
+      return this.queue.shift()!;
+    }
+    return this.defaultResult;
+  }
+
+  reset() {
+    this.queue = [];
+    this.queries = [];
+  }
+
+  lastQuery(): RecordedQuery {
+    return this.queries[this.queries.length - 1];
+  }
+
+  /** Queries excluding the information_schema enrichment probe. */
+  dataQueries(): RecordedQuery[] {
+    return this.queries.filter((q) => !q.sql.includes("information_schema"));
+  }
+
+  queriesMatching(substring: string): RecordedQuery[] {
+    return this.dataQueries().filter((q) => q.sql.includes(substring));
+  }
+}