@galadrim/galadmin 0.1.236 → 0.2.7

package/tests/integration/dbHarness.ts

@@ -0,0 +1,381 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { MySqlContainer } from "@testcontainers/mysql";
+import { PostgreSqlContainer } from "@testcontainers/postgresql";
+import type { StartedMySqlContainer } from "@testcontainers/mysql";
+import type { StartedPostgreSqlContainer } from "@testcontainers/postgresql";
+import * as mysqlDriver from "mysql";
+import { Client as PgClient } from "pg";
+import dbManager from "../../src/utils/dbManager";
+
+/**
+ * Real-database harness for the integration suite.
+ *
+ * The MySQL and PostgreSQL containers are started ONCE per jest run by
+ * tests/integration/globalSetup.ts, which records their connection details
+ * in a state file (path exported through GALADMIN_IT_STATE so every worker
+ * and the teardown find it). The factories below only create fresh driver
+ * pools against the shared containers; globalTeardown stops the containers.
+ *
+ * Started explicitly via `npm run test:integration` (TEST_INTEGRATION=1 with
+ * jest.integration.config.js). When the flag is absent, globalSetup starts
+ * nothing and describeIntegration skips every block, so laptop runs without
+ * Docker still pass.
+ *
+ * One MySQL container backs both driver integrations (the `mysql` package and
+ * `mysql2` via the useMysql2 flag); one PostgreSQL container backs the
+ * third backend. Schema DDL is applied once by globalSetup through the
+ * native drivers, one statement at a time (multipleStatements stays off —
+ * that is a security property worth not relaxing in tests).
+ */
+
+export const INTEGRATION_ENABLED = process.env.TEST_INTEGRATION === "1";
+
+// describeIntegration is only consumed by test files, which always run inside
+// jest where `describe` is injected. globalSetup/globalTeardown import this
+// module OUTSIDE jest, where the global does not exist — hence the guard.
+const jestDescribe: any = (globalThis as any).describe;
+export const describeIntegration: any = jestDescribe
+  ? INTEGRATION_ENABLED
+    ? jestDescribe
+    : jestDescribe.skip
+  : undefined;
+
+export type BackendName = "mysql" | "mysql2" | "postgresql";
+
+export const MYSQL_DDL = [
+  `CREATE TABLE fruits (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    fruitName VARCHAR(255) NULL,
+    acidity INT NULL,
+    note VARCHAR(255) NULL,
+    slug VARCHAR(255) NULL,
+    ownerId INT NULL,
+    role VARCHAR(50) NULL,
+    age INT NULL,
+    activity_id INT NULL
+  )`,
+  `CREATE TABLE fruit_tags (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    tag VARCHAR(255) NOT NULL,
+    fruitId INT NOT NULL
+  )`,
+  `CREATE TABLE fruit_notes (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    text VARCHAR(255) NULL,
+    fruitId INT NOT NULL
+  )`,
+  `CREATE TABLE uuid_fruits (
+    id VARCHAR(64) PRIMARY KEY,
+    fruitName VARCHAR(255) NULL
+  )`,
+  `CREATE TABLE unique_fruits (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    fruitName VARCHAR(255) NOT NULL UNIQUE
+  )`,
+  // The joined lookup table's PK is activity_id (not id) so the bare `id`
+  // tiebreak in ORDER BY stays unambiguous on every engine.
+  `CREATE TABLE activities (
+    activity_id INT AUTO_INCREMENT PRIMARY KEY,
+    name VARCHAR(255) NULL
+  )`,
+  // Foreign-select fixtures: familyId doubles as the default label source,
+  // uuid/active/ownerId/f_id exercise foreignName, filters and joins.
+  `CREATE TABLE families (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    name VARCHAR(255) NULL,
+    familyId INT NULL,
+    uuid VARCHAR(64) NULL,
+    active INT NULL,
+    ownerId INT NULL,
+    f_id INT NULL
+  )`,
+  `CREATE TABLE family_labels (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    label VARCHAR(255) NULL
+  )`,
+];
+
+export const PG_DDL = [
+  `CREATE TABLE fruits (
+    id SERIAL PRIMARY KEY,
+    "fruitName" VARCHAR(255),
+    acidity INT,
+    note VARCHAR(255),
+    slug VARCHAR(255),
+    "ownerId" INT,
+    role VARCHAR(50),
+    age INT,
+    activity_id INT
+  )`,
+  `CREATE TABLE fruit_tags (
+    id SERIAL PRIMARY KEY,
+    tag VARCHAR(255) NOT NULL,
+    "fruitId" INT NOT NULL
+  )`,
+  `CREATE TABLE fruit_notes (
+    id SERIAL PRIMARY KEY,
+    text VARCHAR(255),
+    "fruitId" INT NOT NULL
+  )`,
+  `CREATE TABLE uuid_fruits (
+    id VARCHAR(64) PRIMARY KEY,
+    "fruitName" VARCHAR(255)
+  )`,
+  `CREATE TABLE unique_fruits (
+    id SERIAL PRIMARY KEY,
+    "fruitName" VARCHAR(255) NOT NULL UNIQUE
+  )`,
+  `CREATE TABLE activities (
+    activity_id SERIAL PRIMARY KEY,
+    name VARCHAR(255)
+  )`,
+  `CREATE TABLE families (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(255),
+    "familyId" INT,
+    uuid VARCHAR(64),
+    active INT,
+    "ownerId" INT,
+    f_id INT
+  )`,
+  `CREATE TABLE family_labels (
+    id SERIAL PRIMARY KEY,
+    label VARCHAR(255)
+  )`,
+];
+
+/** Truncated between tests; order matters (children before parents). */
+export const RESET_TABLES = [
+  "fruit_tags",
+  "fruit_notes",
+  "fruits",
+  "uuid_fruits",
+  "unique_fruits",
+  "activities",
+  "families",
+  "family_labels",
+];
+
+const DB_NAME = "galadmin_test";
+const DB_USER = "galadmin";
+const DB_PASSWORD = "galadmin";
+
+export type MysqlConnInfo = {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+};
+export type PgConnInfo = MysqlConnInfo & { connectionUri: string };
+
+export type IntegrationState = {
+  enabled: boolean;
+  mysql: MysqlConnInfo | null;
+  postgresql: PgConnInfo | null;
+  containerIds: { mysql?: string; postgresql?: string };
+};
+
+export function stateFilePath(): string {
+  return (
+    process.env.GALADMIN_IT_STATE ||
+    path.join(os.tmpdir(), "galadmin-it-state.json")
+  );
+}
+
+export function writeIntegrationState(state: IntegrationState) {
+  fs.writeFileSync(stateFilePath(), JSON.stringify(state));
+}
+
+export function readIntegrationState(): IntegrationState | null {
+  try {
+    return JSON.parse(fs.readFileSync(stateFilePath(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export class DbHarness {
+  manager: dbManager;
+  /** Raw pg client for maintenance SQL that must bypass the conversion pipeline. */
+  rawPg?: PgClient;
+
+  get dbType() {
+    return this.manager.dbType;
+  }
+
+  query(sql: string, args: any[] = []) {
+    return this.manager.query(sql, args);
+  }
+
+  async stop() {
+    // Close the driver pool; the containers are shared for the whole jest
+    // run and are stopped by globalTeardown. Closing before the run's end
+    // is fine — each pool is private to the file that created it.
+    await this.rawPg?.end();
+    const pool: any = (this.manager as any)._db;
+    if (pool?.end) {
+      await new Promise<void>((resolve) => pool.end(() => resolve()));
+    }
+  }
+}
+
+function managerForMysql(conn: MysqlConnInfo, useMysql2: boolean) {
+  const manager = new dbManager();
+  manager.init({
+    mysql: conn,
+    useMysql2,
+  });
+  return manager;
+}
+
+function managerForPg(conn: PgConnInfo) {
+  const manager = new dbManager();
+  manager.init({
+    postgresql: conn,
+  });
+  return manager;
+}
+
+/**
+ * Applies DDL through the NATIVE driver, not the galadmin manager:
+ * quotePostgresQuery only knows DML keywords, so DDL sent through the PG
+ * conversion pipeline would get its CREATE/TABLE/PRIMARY KEY keywords quoted
+ * and rejected by the server.
+ */
+export async function applyMysqlDdl(
+  conn: MysqlConnInfo,
+  statements: string[],
+) {
+  const connection = mysqlDriver.createConnection(conn);
+  await new Promise<void>((resolve, reject) =>
+    connection.connect((err) => (err ? reject(err) : resolve())),
+  );
+  for (const statement of statements) {
+    await new Promise<void>((resolve, reject) =>
+      connection.query(statement, (err) => (err ? reject(err) : resolve())),
+    );
+  }
+  await new Promise<void>((resolve) => connection.end(() => resolve()));
+}
+
+export async function applyPgDdl(conn: PgConnInfo, statements: string[]) {
+  const client = new PgClient({ connectionString: conn.connectionUri });
+  await client.connect();
+  for (const statement of statements) {
+    await client.query(statement);
+  }
+  await client.end();
+}
+
+/**
+ * Starts the shared containers, applies the schema on both engines and
+ * returns the state that globalSetup persists for the rest of the run.
+ * Container handles are stashed on globalThis so globalTeardown (same jest
+ * process) can stop them gracefully.
+ */
+export async function startSharedContainers(): Promise<IntegrationState> {
+  const mysqlContainer = await new MySqlContainer("mysql:8.0")
+    .withDatabase(DB_NAME)
+    .withUsername(DB_USER)
+    .withUserPassword(DB_PASSWORD)
+    // The legacy `mysql` driver does not support MySQL 8's default
+    // caching_sha2_password; real deployments using the v1 driver must run
+    // with mysql_native_password (or switch to useMysql2).
+    .withCommand(["--default-authentication-plugin=mysql_native_password"])
+    .start();
+  const mysqlConn: MysqlConnInfo = {
+    host: mysqlContainer.getHost(),
+    port: mysqlContainer.getPort(),
+    user: DB_USER,
+    password: DB_PASSWORD,
+    database: mysqlContainer.getDatabase(),
+  };
+  await applyMysqlDdl(mysqlConn, MYSQL_DDL);
+
+  const pgContainer = await new PostgreSqlContainer("postgres:16-alpine")
+    .withDatabase(DB_NAME)
+    .withUsername(DB_USER)
+    .withPassword(DB_PASSWORD)
+    .start();
+  const pgConn: PgConnInfo = {
+    host: pgContainer.getHost(),
+    port: pgContainer.getPort(),
+    user: pgContainer.getUsername(),
+    password: pgContainer.getPassword(),
+    database: pgContainer.getDatabase(),
+    connectionUri: pgContainer.getConnectionUri(),
+  };
+  await applyPgDdl(pgConn, PG_DDL);
+
+  (globalThis as any).__GALADMIN_IT_CONTAINERS__ = {
+    mysql: mysqlContainer,
+    postgresql: pgContainer,
+  };
+
+  return {
+    enabled: true,
+    mysql: mysqlConn,
+    postgresql: pgConn,
+    containerIds: {
+      mysql: mysqlContainer.getId(),
+      postgresql: pgContainer.getId(),
+    },
+  };
+}
+
+function requireState(): IntegrationState {
+  const state = readIntegrationState();
+  if (!state || !state.enabled) {
+    throw new Error(
+      "Integration state missing — containers must be started via globalSetup (run with TEST_INTEGRATION=1).",
+    );
+  }
+  return state;
+}
+
+/** Fresh `mysql` driver pool against the shared MySQL container. */
+export async function getMysqlHarness(): Promise<DbHarness> {
+  const state = requireState();
+  const harness = new DbHarness();
+  harness.manager = managerForMysql(state.mysql!, false);
+  return harness;
+}
+
+/** Fresh `mysql2` driver pool sharing the same MySQL container/tables. */
+export async function getMysql2Harness(): Promise<DbHarness> {
+  const state = requireState();
+  const harness = new DbHarness();
+  harness.manager = managerForMysql(state.mysql!, true);
+  return harness;
+}
+
+/** Fresh pg pool + raw maintenance client against the shared PG container. */
+export async function getPgHarness(): Promise<DbHarness> {
+  const state = requireState();
+  const harness = new DbHarness();
+  harness.manager = managerForPg(state.postgresql!);
+  harness.rawPg = new PgClient({
+    connectionString: state.postgresql!.connectionUri,
+  });
+  await harness.rawPg.connect();
+  return harness;
+}
+
+/** Removes every row created by previous tests (keeps the schema, resets ids). */
+export async function resetTables(harness: DbHarness) {
+  if (harness.dbType === "POSTGRESQL") {
+    // TRUNCATE/RESTART IDENTITY are DDL: run them through the raw client,
+    // the conversion pipeline quotes non-DML keywords.
+    await harness.rawPg!.query(
+      `TRUNCATE TABLE ${RESET_TABLES.join(", ")} RESTART IDENTITY`,
+    );
+    return;
+  }
+  for (const statement of RESET_TABLES.map((t) => `TRUNCATE TABLE ${t}`)) {
+    const { err } = await harness.query(statement);
+    if (err) throw err;
+  }
+}

package/tests/integration/dbManager.integration.test.ts

@@ -0,0 +1,69 @@
+import {
+  DbHarness,
+  describeIntegration,
+  getMysql2Harness,
+  getPgHarness,
+} from "./dbHarness";
+
+/**
+ * dbManager pool wiring + driver interaction against real engines. The
+ * scripted suite asserted the createPool options; here the manager is
+ * initialized against the shared containers and the result-shape
+ * normalization ({err, rows, fields}) is verified for real.
+ */
+describeIntegration("dbManager against real databases", () => {
+  const harnesses: Record<string, DbHarness> = {};
+
+  beforeAll(async () => {
+    harnesses.mysql2 = await getMysql2Harness();
+    harnesses.postgresql = await getPgHarness();
+  });
+
+  afterAll(async () => {
+    await harnesses.mysql2?.stop();
+    await harnesses.postgresql?.stop();
+  });
+
+  it("resolves {err, rows, fields} passthrough for MySQL", async () => {
+    const result = await harnesses.mysql2.query("SELECT 1 AS one");
+    expect(result.err).toBeNull();
+    expect(result.rows).toEqual([{ one: 1 }]);
+    expect(result.fields).toBeDefined();
+  });
+
+  it("unwraps {rows, fields} from the pg result object", async () => {
+    const result = await harnesses.postgresql.query("SELECT 1 AS one");
+    // pg resolves success with an undefined err (MySQL passes null); every
+    // consumer only checks truthiness.
+    expect(result.err).toBeFalsy();
+    expect(result.rows).toEqual([{ one: 1 }]);
+    expect(result.fields).toBeDefined();
+  });
+
+  it("propagates engine errors instead of throwing", async () => {
+    const result = await harnesses.postgresql.query("SELECT broken");
+    expect(result.err).toBeTruthy();
+    expect(result.rows).toBeUndefined();
+  });
+
+  it("keeps MySQL-style ? placeholders working on the MySQL2 driver", async () => {
+    await harnesses.mysql2.query(
+      "CREATE TEMPORARY TABLE gm_probe (id INT PRIMARY KEY, name VARCHAR(50))",
+    );
+    const { err } = await harnesses.mysql2.query(
+      "INSERT INTO gm_probe (id, name) VALUES (?, ?)",
+      [1, "pomme"],
+    );
+    expect(err).toBeFalsy();
+    const { rows } = await harnesses.mysql2.query(
+      "SELECT name FROM gm_probe WHERE id = ?",
+      [1],
+    );
+    expect(rows).toEqual([{ name: "pomme" }]);
+  });
+
+  it("rejects stacked statements (multipleStatements off by default)", async () => {
+    const result = await harnesses.mysql2.query("SELECT 1; SELECT 2");
+    expect(result.err).toBeTruthy();
+  });
+});

package/tests/integration/globalSetup.ts

@@ -0,0 +1,43 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import {
+  INTEGRATION_ENABLED,
+  startSharedContainers,
+  writeIntegrationState,
+} from "./dbHarness";
+
+const run = promisify(execFile);
+
+// Fail fast with an actionable message when Docker is unreachable.
+async function assertDockerAvailable() {
+  try {
+    await run("docker", ["info"], { timeout: 10_000 });
+  } catch (err: any) {
+    throw new Error(
+      "Integration tests (and therefore `npm run test:coverage`) require a running Docker daemon, " +
+        "but `docker info` failed. Start Docker, or use `npm test` for the unit-only suite. " +
+        `Cause: ${err?.message ?? err}`,
+    );
+  }
+}
+
+/**
+ * Jest globalSetup for the integration suite: boots the shared MySQL and
+ * PostgreSQL containers once for the whole run and persists their connection
+ * details to the state file every harness factory reads. Without
+ * TEST_INTEGRATION=1 it records an "enabled: false" state so the harness
+ * factories fail loudly if anything tries to reach the databases.
+ */
+export default async function globalSetup() {
+  if (!INTEGRATION_ENABLED) {
+    writeIntegrationState({
+      enabled: false,
+      mysql: null,
+      postgresql: null,
+      containerIds: {},
+    });
+    return;
+  }
+  await assertDockerAvailable();
+  writeIntegrationState(await startSharedContainers());
+}

package/tests/integration/globalTeardown.ts

@@ -0,0 +1,42 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { readIntegrationState, stateFilePath } from "./dbHarness";
+
+const run = promisify(execFile);
+
+/**
+ * Jest globalTeardown: stops the shared containers. The graceful path uses
+ * the container handles stashed on globalThis by globalSetup (same jest
+ * process); if that fails or is unavailable, fall back to `docker rm -f`
+ * with the recorded container ids. Anything left behind is reaped by ryuk
+ * once this process exits.
+ */
+export default async function globalTeardown() {
+  const handles = (globalThis as any).__GALADMIN_IT_CONTAINERS__;
+  for (const key of ["mysql", "postgresql"]) {
+    const handle = handles?.[key];
+    if (handle) {
+      try {
+        await handle.stop();
+      } catch {
+        // fall through to the docker fallback below
+      }
+    }
+  }
+  const state = readIntegrationState();
+  if (state?.enabled) {
+    for (const id of [state.containerIds.mysql, state.containerIds.postgresql]) {
+      if (!id) continue;
+      try {
+        await run("docker", ["rm", "-f", id]);
+      } catch {
+        // already removed by the graceful path — nothing to do
+      }
+    }
+  }
+  try {
+    require("fs").unlinkSync(stateFilePath());
+  } catch {
+    // state file is disposable
+  }
+}