@byline/db-mysql 4.8.0

package/dist/index.js

@@ -0,0 +1,151 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { drizzle } from 'drizzle-orm/mysql2';
+import mysql from 'mysql2/promise';
+import * as schema from './database/schema/index.js';
+import { assertMySqlVersion } from './lib/boot-check.js';
+import { DBManagerImpl, TXManagerImpl } from './lib/db-manager.js';
+import { createAuditCommands } from './modules/audit/audit-commands.js';
+import { createAuditQueries } from './modules/audit/audit-queries.js';
+import { createCounterCommands } from './modules/counters/counters-commands.js';
+import { classifyError } from './modules/storage/classify-error.js';
+import { createCommandBuilders } from './modules/storage/storage-commands.js';
+import { createQueryBuilders } from './modules/storage/storage-queries.js';
+export const mysqlAdapter = ({ connectionString, collections, defaultContentLocale, connectionLimit = 20, idleTimeout = 2000, connectTimeout = 30000, maxIdle, }) => {
+    const pool = mysql.createPool({
+        uri: connectionString,
+        connectionLimit,
+        idleTimeout,
+        connectTimeout,
+        ...(maxIdle != null ? { maxIdle } : {}),
+        // Every DATETIME column is UTC by convention (spec §2). 'Z' stops
+        // mysql2 from reinterpreting stored UTC values against the server's or
+        // session's local timezone on the way in and out.
+        timezone: 'Z',
+        // Keep DECIMAL columns as strings instead of coercing to JS `number`,
+        // which loses precision on money/decimal values. The storage layer
+        // (Task 9) treats decimal store values as strings end to end, matching
+        // the pg adapter's `numeric` handling.
+        decimalNumbers: false,
+        // Task 10A divergence, found live: mysql2 negotiates
+        // `utf8mb4_unicode_ci` as the connection's default collation unless told
+        // otherwise — it does NOT inherit the schema/database default
+        // (`utf8mb4_0900_ai_ci`, see `database/schema/common.ts`). A typed
+        // `CAST(NULL AS CHAR)` expression (the UNION ALL null-cast machinery in
+        // `storage-store-manifest.ts`) carries the *connection's* collation, so
+        // without this, `getAllFieldValuesForMultipleVersions`'s 7-way UNION ALL
+        // fails with `ER_CANT_AGGREGATE_NCOLLATIONS` ("Illegal mix of
+        // collations") the moment a CAST'd column and a real schema column with
+        // a different collation land in the same UNION output position.
+        // Pinning the connection's collation to match the schema fixes it at
+        // the source rather than adding a `COLLATE` clause to every cast.
+        charset: 'UTF8MB4_0900_AI_CI',
+    });
+    // `drizzle-orm/mysql2` requires `mode` whenever `schema` is supplied.
+    // 'default' matches the pg adapter's un-prefixed-key mode (as opposed to
+    // 'planetscale', which changes how relational queries build).
+    const db = drizzle(pool, {
+        schema,
+        mode: 'default',
+    });
+    // Request-scoped transaction propagation (docs/03-architecture/03-transactions.md), mirroring
+    // the pg adapter. Exported via ./lib/db-manager.js for Tasks 9-12: command
+    // builders land on the DBManager so each `this.db` access resolves to the
+    // ambient transaction when a `withTransaction` boundary is open, else the
+    // pool.
+    const dbManager = new DBManagerImpl({ dbPool: db });
+    const txManager = new TXManagerImpl({ db: dbManager });
+    const commandBuilders = createCommandBuilders(dbManager, defaultContentLocale);
+    // Most reads run on the raw `db` (not the DBManager) — they don't need to
+    // join an ambient `withTransaction`. `dbManager` is still threaded through
+    // as the 4th argument (matching pg's `storage-queries.ts`) because
+    // `DocumentQueries` accepts it as `transactionDb` for the one read that
+    // DOES need the ambient transaction: `getDocumentSystemFieldsForUpdate`
+    // (Task 10B) takes a `SELECT … FOR UPDATE` lock that must run inside the
+    // caller's transaction to serialise concurrent system-field writers —
+    // dropping `dbManager` here would silently run that lock outside the
+    // transaction and defeat the concurrency guard it exists to provide.
+    // `transactionDb` is a required parameter (no default) precisely so this
+    // can never be omitted by accident — see the §H ruling in the Task 10B
+    // report.
+    const queryBuilders = createQueryBuilders(db, collections, defaultContentLocale, dbManager);
+    // Counters run on the raw mysql2 `pool` — never `dbManager` — so they never
+    // join an ambient `withTransaction`: a long document-create transaction
+    // holding the counter row would serialise every other writer in that
+    // group (Task 11). Audit appends run on `dbManager` so they DO join the
+    // ambient transaction and commit atomically with the mutation they
+    // record; audit reads run on the plain `db` (the pool) since they never
+    // need to join that transaction. See ./modules/counters/counters-commands.js
+    // and ./modules/audit/{audit-commands,audit-queries}.js.
+    const counterCommands = createCounterCommands(pool);
+    const auditCommands = createAuditCommands(dbManager);
+    const auditQueries = createAuditQueries(db);
+    // Boot check: run lazily on the pool's first physical connection rather
+    // than eagerly here, because `mysqlAdapter` is synchronous (mirroring
+    // `pgAdapter`) and cannot await a round trip before returning. mysql2
+    // pools open no connections at construction time — the `'connection'`
+    // event fires the first time a query actually needs one, which in
+    // practice is during `initBylineCore()`'s own boot sequence. A too-old
+    // server or MariaDB is a configuration error, not a recoverable runtime
+    // condition, so a failed check is rethrown on the next tick to surface as
+    // a loud, fail-fast crash instead of a silently swallowed rejection.
+    //
+    // The `mysql2/promise` typings claim this event hands back a
+    // promise-wrapped `PoolConnection`, but at runtime it is the underlying
+    // callback-style connection (confirmed against a live server) — calling
+    // `.query()` on it directly returns an `EventEmitter`, not a `Promise`.
+    // `.promise()` is the callback API's own escape hatch back to the
+    // promise wrapper; see https://sidorares.github.io/node-mysql2/docs/documentation/promise-wrapper.
+    let versionCheckStarted = false;
+    pool.on('connection', (connection) => {
+        if (versionCheckStarted)
+            return;
+        versionCheckStarted = true;
+        const rawConnection = connection;
+        const promiseConnection = rawConnection.promise();
+        assertMySqlVersion(async (sql) => {
+            const [rows] = await promiseConnection.query(sql);
+            return rows;
+        }).catch((err) => {
+            process.nextTick(() => {
+                throw err;
+            });
+        });
+    });
+    return {
+        commands: {
+            // `commandBuilders.collections` fully implements `ICollectionCommands`
+            // (Task 9A) — see `./modules/storage/storage-commands.js`.
+            collections: commandBuilders.collections,
+            // `commandBuilders.documents` (`DocumentCommands`) fully implements
+            // `IDocumentCommands` as of Task 9B — see that class's docblock.
+            documents: commandBuilders.documents,
+            // `counterCommands` fully implements `ICounterCommands` as of Task 11
+            // — see `./modules/counters/counters-commands.js`.
+            counters: counterCommands,
+            // `auditCommands` fully implements `IAuditCommands` as of Task 11 —
+            // see `./modules/audit/audit-commands.js`.
+            audit: auditCommands,
+        },
+        queries: {
+            // `queryBuilders.collections` fully implements `ICollectionQueries`
+            // (Task 10A) — see `./modules/storage/storage-queries.js`.
+            collections: queryBuilders.collections,
+            // `queryBuilders.documents` (`DocumentQueries`) fully implements
+            // `IDocumentQueries` as of Task 10B — see that class's docblock.
+            documents: queryBuilders.documents,
+            // `auditQueries` fully implements `IAuditQueries` as of Task 11 — see
+            // `./modules/audit/audit-queries.js`.
+            audit: auditQueries,
+        },
+        withTransaction: (fn) => txManager.withTransaction(fn),
+        classifyError,
+        drizzle: db,
+        pool,
+    };
+};

package/dist/lib/boot-check.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * Boot-time engine check for the MySQL adapter. `mysqlAdapter` runs this
+ * lazily against the first connection the pool hands out (see
+ * `src/index.ts`) so a too-old server or a MariaDB instance fails fast at
+ * `initBylineCore()` boot rather than surfacing as an obscure SQL error the
+ * first time the storage layer emits a LATERAL join (Task 10+).
+ */
+/**
+ * Assert the connected server is MySQL (not MariaDB) at or above the
+ * supported floor. `query` is injected so this is unit-testable without a
+ * live server — the adapter passes a thin wrapper around the pool's
+ * `SELECT VERSION()` round trip.
+ */
+export declare function assertMySqlVersion(query: (sql: string) => Promise<Array<{
+    v: string;
+}>>): Promise<void>;

package/dist/lib/boot-check.js

@@ -0,0 +1,42 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * Boot-time engine check for the MySQL adapter. `mysqlAdapter` runs this
+ * lazily against the first connection the pool hands out (see
+ * `src/index.ts`) so a too-old server or a MariaDB instance fails fast at
+ * `initBylineCore()` boot rather than surfacing as an obscure SQL error the
+ * first time the storage layer emits a LATERAL join (Task 10+).
+ */
+const MIN = { major: 8, minor: 0, patch: 14 };
+const unsupportedEngineError = (reported) => new Error(`@byline/db-mysql requires MySQL ${MIN.major}.${MIN.minor}.${MIN.patch}+ (LATERAL joins); server reports ${reported}. MariaDB is not supported.`);
+/**
+ * Assert the connected server is MySQL (not MariaDB) at or above the
+ * supported floor. `query` is injected so this is unit-testable without a
+ * live server — the adapter passes a thin wrapper around the pool's
+ * `SELECT VERSION()` round trip.
+ */
+export async function assertMySqlVersion(query) {
+    const rows = await query('SELECT VERSION() AS v');
+    const v = rows?.[0]?.v;
+    if (typeof v !== 'string' || v.length === 0) {
+        throw new Error("@byline/db-mysql: could not determine the MySQL server version — 'SELECT VERSION()' returned no usable result.");
+    }
+    // MariaDB reports version strings that satisfy the numeric floor below
+    // (it commonly claims a 10.x/11.x series, sometimes fronted by the
+    // legacy `5.5.5-` replication-handshake prefix), so it must be rejected
+    // explicitly before the numeric comparison, not merely by chance.
+    if (/mariadb/i.test(v)) {
+        throw unsupportedEngineError(v);
+    }
+    const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+    const [major = 0, minor = 0, patch = 0] = m ? m.slice(1).map(Number) : [];
+    const ok = major > MIN.major ||
+        (major === MIN.major && (minor > MIN.minor || (minor === MIN.minor && patch >= MIN.patch)));
+    if (!ok) {
+        throw unsupportedEngineError(v);
+    }
+}

package/dist/lib/boot-check.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/lib/boot-check.test.node.js

@@ -0,0 +1,46 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { assertMySqlVersion } from './boot-check.js';
+const queryReturning = (v) => async () => [{ v }];
+describe('assertMySqlVersion', () => {
+    describe('accepts supported MySQL server versions', () => {
+        it.each([
+            ['8.0.14', '8.0.14 — the exact floor'],
+            ['8.4.0', '8.4.0'],
+            ['9.7.1', "9.7.1 — this repo's dev container"],
+            ['8.0.35-0ubuntu0.22.04.1', 'a distro-suffixed release string'],
+        ])('%s (%s)', async (version) => {
+            await expect(assertMySqlVersion(queryReturning(version))).resolves.toBeUndefined();
+        });
+    });
+    describe('rejects unsupported servers', () => {
+        it.each([
+            ['8.0.13', 'one patch below the floor'],
+            ['8.0.0', 'the 8.0 GA release, below the floor'],
+            ['5.7.44', 'MySQL 5.7'],
+            ['11.4.2-MariaDB', 'a MariaDB version string'],
+            ['5.5.5-10.11.2-MariaDB', 'the MariaDB replication-handshake version shape'],
+        ])('%s (%s)', async (version) => {
+            await expect(assertMySqlVersion(queryReturning(version))).rejects.toThrow(/MariaDB is not supported/);
+        });
+        it('names MariaDB explicitly, not just a failed numeric comparison', async () => {
+            await expect(assertMySqlVersion(queryReturning('11.4.2-MariaDB'))).rejects.toThrow(/MariaDB/);
+            await expect(assertMySqlVersion(queryReturning('5.5.5-10.11.2-MariaDB'))).rejects.toThrow(/MariaDB/);
+        });
+    });
+    describe('malformed results', () => {
+        it('throws a clear error (not a destructuring TypeError) when the query returns no rows', async () => {
+            await expect(assertMySqlVersion(async () => [])).rejects.toThrow(/@byline\/db-mysql/);
+            await expect(assertMySqlVersion(async () => [])).rejects.not.toThrow(TypeError);
+        });
+        it('throws a clear error when the query returns a row without a usable version string', async () => {
+            await expect(assertMySqlVersion(async () => [{ v: undefined }])).rejects.toThrow(/@byline\/db-mysql/);
+        });
+    });
+});

package/dist/lib/db-manager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * Request-scoped transaction propagation via AsyncLocalStorage.
+ *
+ * Mirrors the Postgres adapter's `db-manager.ts` — the same ALS mechanism
+ * Byline's logger already uses (`packages/core/src/lib/logger.ts`,
+ * `withLogContext`). The full design — the service-owned `withTransaction`
+ * boundary, the DB↔DB vs DB↔external distinction, the incremental-adoption
+ * caveat, and the serverless db-contract-seam decisions — lives in
+ * `docs/03-architecture/03-transactions.md`. This machinery is deliberately adapter-internal:
+ * transactions are driver-specific, so `@byline/core` only declares the
+ * `withTransaction` capability on `IDbAdapter`, never the implementation.
+ */
+import type { MySql2Database } from 'drizzle-orm/mysql2';
+import type * as schema from '../database/schema/index.js';
+export type DBExecutor = MySql2Database<typeof schema>;
+export interface DBManager {
+    /**
+     * The current executor: the ambient transaction when a `withTransaction`
+     * boundary is open in this async context, otherwise the pool.
+     */
+    get(): DBExecutor;
+}
+export declare class DBManagerImpl implements DBManager {
+    private readonly dbPool;
+    constructor(deps: {
+        dbPool: DBExecutor;
+    });
+    get(): DBExecutor;
+}
+export interface TXManager {
+    /**
+     * Run `fn` inside a single database transaction. Every `DBManager.get()`
+     * call made during `fn` (transitively, across `await`s) returns that
+     * transaction, so the commands `fn` invokes commit or roll back together.
+     *
+     * Nesting: when already inside a `withTransaction`, the inner call opens a
+     * SAVEPOINT (Drizzle nested transaction) — an inner throw rolls back to the
+     * savepoint, an outer throw rolls back everything.
+     */
+    withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+}
+export declare class TXManagerImpl implements TXManager {
+    private readonly db;
+    constructor(deps: {
+        db: DBManager;
+    });
+    withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+}

package/dist/lib/db-manager.js

@@ -0,0 +1,49 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ *
+ * Request-scoped transaction propagation via AsyncLocalStorage.
+ *
+ * Mirrors the Postgres adapter's `db-manager.ts` — the same ALS mechanism
+ * Byline's logger already uses (`packages/core/src/lib/logger.ts`,
+ * `withLogContext`). The full design — the service-owned `withTransaction`
+ * boundary, the DB↔DB vs DB↔external distinction, the incremental-adoption
+ * caveat, and the serverless db-contract-seam decisions — lives in
+ * `docs/03-architecture/03-transactions.md`. This machinery is deliberately adapter-internal:
+ * transactions are driver-specific, so `@byline/core` only declares the
+ * `withTransaction` capability on `IDbAdapter`, never the implementation.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+const transactionALS = new AsyncLocalStorage();
+export class DBManagerImpl {
+    dbPool;
+    constructor(deps) {
+        this.dbPool = deps.dbPool;
+    }
+    get() {
+        return transactionALS.getStore() ?? this.dbPool;
+    }
+}
+export class TXManagerImpl {
+    db;
+    constructor(deps) {
+        this.db = deps.db;
+    }
+    withTransaction(fn) {
+        return this.db.get().transaction((tx) => 
+        // `tx` is Drizzle's MySqlTransaction; it carries the full
+        // query-builder surface every command uses. The cast bridges the
+        // structural gap to MySql2Database the same way the pg adapter
+        // bridges to NodePgDatabase. See docs/03-architecture/03-transactions.md.
+        transactionALS.run(tx, fn), {
+            // Spec decision: pin the isolation level to match the pg adapter's
+            // assumptions (Postgres's default is READ COMMITTED; MySQL/InnoDB
+            // defaults to REPEATABLE READ). Canonical adapters must behave
+            // identically for the shared db-conformance suite.
+            isolationLevel: 'read committed',
+        });
+    }
+}

package/dist/lib/test-db.d.ts

@@ -0,0 +1,37 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { type MySql2Database } from 'drizzle-orm/mysql2';
+import * as schema from '../database/schema/index.js';
+/**
+ * Belt for the script-level braces in `common.sh`. Parses the connection
+ * string and refuses to continue unless the database name ends in `_test`.
+ * Called at every test-process entry point so a stray `.env` pointed at
+ * `byline_dev` (or anything else) trips the guard before any DDL runs.
+ */
+export declare function assertTestDatabase(connectionString: string | undefined): string;
+/**
+ * Run Drizzle migrations against the configured connection. Idempotent —
+ * Drizzle tracks applied migrations in `__drizzle_migrations`. Opens and
+ * closes its own pool; safe to call from a vitest globalSetup.
+ */
+export declare function migrateTestDatabase(connectionString: string): Promise<void>;
+/**
+ * Wipe every user table so each test file starts from a known state. MySQL
+ * has no `TRUNCATE ... CASCADE` — foreign keys must be disabled around the
+ * truncates instead, and restored afterwards (including on failure), or a
+ * later test file inherits a permanently-disabled FK session setting.
+ * Skips Drizzle's own `__drizzle_migrations` ledger. Self-maintaining as the
+ * schema grows — new tables come along for the ride without any code change.
+ */
+export declare function truncateAllTables(db: MySql2Database<typeof schema>): Promise<void>;
+/**
+ * Convenience: assert + open a short-lived pool + truncate + close. Useful
+ * from a vitest setupFile (`beforeAll`) where the caller doesn't otherwise
+ * need a long-lived db handle.
+ */
+export declare function resetTestDatabase(connectionString: string): Promise<void>;

package/dist/lib/test-db.js

@@ -0,0 +1,111 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { drizzle } from 'drizzle-orm/mysql2';
+import { migrate } from 'drizzle-orm/mysql2/migrator';
+import mysql from 'mysql2/promise';
+import * as schema from '../database/schema/index.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Drizzle migrations folder. Migrations (`*.sql` + `meta/_journal.json`)
+ * live only under `src/` — the TypeScript build doesn't copy them into
+ * `dist/`. Anchor on `src/database/migrations` from either location:
+ *
+ *   src/lib/test-db.ts  → ../../src/database/migrations ✓
+ *   dist/lib/test-db.js → ../../src/database/migrations ✓
+ *
+ * `path.resolve` normalises the `../..` away, so the same string works
+ * for both build modes. Mirrors `packages/db-postgres/src/lib/test-db.ts`.
+ */
+const MIGRATIONS_FOLDER = path.resolve(__dirname, '../../src/database/migrations');
+/**
+ * Belt for the script-level braces in `common.sh`. Parses the connection
+ * string and refuses to continue unless the database name ends in `_test`.
+ * Called at every test-process entry point so a stray `.env` pointed at
+ * `byline_dev` (or anything else) trips the guard before any DDL runs.
+ */
+export function assertTestDatabase(connectionString) {
+    if (!connectionString) {
+        throw new Error('BYLINE_DB_MYSQL_CONNECTION_STRING is not set. Copy .env.test.example to .env.test.');
+    }
+    let dbName;
+    try {
+        const url = new URL(connectionString);
+        dbName = url.pathname.replace(/^\//, '');
+    }
+    catch (err) {
+        throw new Error(`BYLINE_DB_MYSQL_CONNECTION_STRING is not a valid URL: ${err.message}`);
+    }
+    if (!dbName.endsWith('_test')) {
+        throw new Error(`Refusing to run tests against database '${dbName}'. ` +
+            `Integration tests require a database whose name ends in '_test'. ` +
+            `Update BYLINE_DB_MYSQL_CONNECTION_STRING in .env.test.`);
+    }
+    return dbName;
+}
+/**
+ * Run Drizzle migrations against the configured connection. Idempotent —
+ * Drizzle tracks applied migrations in `__drizzle_migrations`. Opens and
+ * closes its own pool; safe to call from a vitest globalSetup.
+ */
+export async function migrateTestDatabase(connectionString) {
+    assertTestDatabase(connectionString);
+    const pool = mysql.createPool({ uri: connectionString, connectionLimit: 1, timezone: 'Z' });
+    try {
+        const db = drizzle(pool, { schema, mode: 'default' });
+        await migrate(db, { migrationsFolder: MIGRATIONS_FOLDER });
+    }
+    finally {
+        await pool.end();
+    }
+}
+/**
+ * Wipe every user table so each test file starts from a known state. MySQL
+ * has no `TRUNCATE ... CASCADE` — foreign keys must be disabled around the
+ * truncates instead, and restored afterwards (including on failure), or a
+ * later test file inherits a permanently-disabled FK session setting.
+ * Skips Drizzle's own `__drizzle_migrations` ledger. Self-maintaining as the
+ * schema grows — new tables come along for the ride without any code change.
+ */
+export async function truncateAllTables(db) {
+    const [rows] = await db.execute(`
+    SELECT TABLE_NAME AS table_name FROM information_schema.tables
+    WHERE table_schema = DATABASE()
+      AND table_type = 'BASE TABLE'
+      AND table_name <> '__drizzle_migrations'
+  `);
+    const tables = rows.map((r) => `\`${r.table_name}\``);
+    if (tables.length === 0)
+        return;
+    await db.execute('SET FOREIGN_KEY_CHECKS = 0');
+    try {
+        for (const table of tables) {
+            await db.execute(`TRUNCATE TABLE ${table}`);
+        }
+    }
+    finally {
+        await db.execute('SET FOREIGN_KEY_CHECKS = 1');
+    }
+}
+/**
+ * Convenience: assert + open a short-lived pool + truncate + close. Useful
+ * from a vitest setupFile (`beforeAll`) where the caller doesn't otherwise
+ * need a long-lived db handle.
+ */
+export async function resetTestDatabase(connectionString) {
+    assertTestDatabase(connectionString);
+    const pool = mysql.createPool({ uri: connectionString, connectionLimit: 1, timezone: 'Z' });
+    try {
+        const db = drizzle(pool, { schema, mode: 'default' });
+        await truncateAllTables(db);
+    }
+    finally {
+        await pool.end();
+    }
+}

package/dist/lib/test-helper.d.ts

@@ -0,0 +1,33 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { CollectionDefinition } from '@byline/core';
+import { type MySql2Database } from 'drizzle-orm/mysql2';
+import mysql from 'mysql2/promise';
+import * as schema from '../database/schema/index.js';
+import { DBManagerImpl, TXManagerImpl } from './db-manager.js';
+/**
+ * Mirrors `packages/db-postgres/src/lib/test-helper.ts`. `queryBuilders` is
+ * wired as of Task 10A (the UNION ALL reconstruction path) and fully
+ * implements `IDocumentQueries` as of Task 10B (the predicate compiler,
+ * `findDocuments`' full surface, tree reads, and `getDocumentSystemFieldsForUpdate`).
+ */
+export declare function setupTestDB(collections?: CollectionDefinition[]): {
+    pool: mysql.Pool;
+    db: MySql2Database<typeof schema>;
+    dbManager: DBManagerImpl;
+    txManager: TXManagerImpl;
+    commandBuilders: {
+        collections: import("../modules/storage/storage-commands.js").CollectionCommands;
+        documents: import("../modules/storage/storage-commands.js").DocumentCommands;
+    };
+    queryBuilders: {
+        collections: import("../modules/storage/storage-queries.js").CollectionQueries;
+        documents: import("../modules/storage/storage-queries.js").DocumentQueries;
+    };
+};
+export declare function teardownTestDB(): Promise<void>;

package/dist/lib/test-helper.js

@@ -0,0 +1,68 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { drizzle } from 'drizzle-orm/mysql2';
+import mysql from 'mysql2/promise';
+import * as schema from '../database/schema/index.js';
+import { createCommandBuilders } from '../modules/storage/storage-commands.js';
+import { createQueryBuilders } from '../modules/storage/storage-queries.js';
+import { DBManagerImpl, TXManagerImpl } from './db-manager.js';
+import { assertTestDatabase } from './test-db.js';
+let pool;
+let db;
+let dbManager;
+let txManager;
+let commandBuilders;
+let queryBuilders;
+/**
+ * Mirrors `packages/db-postgres/src/lib/test-helper.ts`. `queryBuilders` is
+ * wired as of Task 10A (the UNION ALL reconstruction path) and fully
+ * implements `IDocumentQueries` as of Task 10B (the predicate compiler,
+ * `findDocuments`' full surface, tree reads, and `getDocumentSystemFieldsForUpdate`).
+ */
+export function setupTestDB(collections = []) {
+    if (!pool) {
+        assertTestDatabase(process.env.BYLINE_DB_MYSQL_CONNECTION_STRING);
+        pool = mysql.createPool({
+            uri: process.env.BYLINE_DB_MYSQL_CONNECTION_STRING,
+            // Mirrors the pg test helper: tests are serial and run one query at a
+            // time, so a small pool per test file is sufficient.
+            connectionLimit: 4,
+            timezone: 'Z',
+            decimalNumbers: false,
+            // Match the schema's collation — see the identical option on the
+            // production pool in `src/index.ts` for why this is required (not
+            // just a nicety) once the storage-queries UNION ALL is in play.
+            charset: 'UTF8MB4_0900_AI_CI',
+        });
+    }
+    if (!db) {
+        db = drizzle(pool, { schema, mode: 'default' });
+    }
+    if (!dbManager) {
+        dbManager = new DBManagerImpl({ dbPool: db });
+        txManager = new TXManagerImpl({ db: dbManager });
+    }
+    if (!commandBuilders) {
+        commandBuilders = createCommandBuilders(dbManager, 'en');
+    }
+    // Recreate queryBuilders when collections are provided so that
+    // DocumentQueries can resolve collection definitions by path.
+    queryBuilders = createQueryBuilders(db, collections, 'en', dbManager);
+    return { pool, db, dbManager, txManager, commandBuilders, queryBuilders };
+}
+export async function teardownTestDB() {
+    if (pool) {
+        await pool.end();
+        pool = undefined;
+        db = undefined;
+        dbManager = undefined;
+        txManager = undefined;
+        commandBuilders = undefined;
+        queryBuilders = undefined;
+    }
+}