@jskit-ai/database-runtime-mysql 0.1.197 → 0.1.199

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/database-runtime-mysql",
-  "version": "0.1.197",
+  "version": "0.1.199",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -12,7 +12,7 @@
     "./shared/dialect": "./src/shared/dialect.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.199",
+    "@jskit-ai/database-runtime": "0.1.201",
     "mysql2": "^3.11.2"
   },
   "jskit": {
@@ -56,6 +56,6 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.1.199"
+    "@jskit-ai/kernel": "0.1.201"
   }
 }

package/patterns/mysql-application/PATTERN.md

@@ -48,7 +48,29 @@ Knex discovers package-owned migrations from the installed dependency graph.
 `example/knexfile.js` loads an optional local `.env` and fixes the MySQL dialect.
 `example/scripts/prepare-database.js` is the portable migrate-then-seed
 entrypoint for managed sessions and deployments. `example/.env.example` names
-the five connection values without a secret.
+the connection values and separate test databases without a secret.
+
+`example/tests/browser/database.js` is the application-owned browser preparation
+helper. It requires the exact `BROWSER_TEST_DB_NAME`, rejects the ordinary and
+disposable `TEST_DB_NAME` databases,
+retains the schema and migration ledger, applies pending migrations, then clears
+test rows and calls one explicit fixture seed transaction. The seed must restore
+any migration-owned baseline rows the app needs. Call it once before starting
+the isolated test server, never in `beforeEach`. It closes its connections without
+dropping the database. The launcher selects that database only for its own server
+and identity process, disables external effects, and proves actual server identity
+before the suite writes data. It must not edit the normal environment. Provision
+both test databases with exact grants for the application account. A disposable
+integration or migration test must never drop the browser database.
+
+Startup reports whether the schema exists, the number of migrations applied,
+and the migration, fixture-reset and seed durations. Use those measurements to
+diagnose a slow start before rerunning a browser case.
+
+Keep fixtures small for the selected test scope. Run related cases in one suite
+invocation. Use the development launcher for ordinary browser checks; test the
+production build separately when needed. Fresh-schema migration proofs are
+separate from browser startup.
 
 ## Variation points
 
@@ -66,6 +88,11 @@ it as `seed` to `prepareDatabaseFromApp()`.
 - Run `npm run db:migrate:status` and the application verification command.
 - Exercise one transaction and one negative connection case.
 - When a seed exists, run `db:prepare` twice and require the second run to be safe.
+- For browser preparation, run a disposable test between two starts: the second applies no
+  old migrations, stale fixture data is removed, baseline rows are restored,
+  foreign-key checks remain enabled, and the normal database is unchanged.
+  Also prove that a new pending migration is applied. Keep this as a regression
+  test when adapting the example; reject a harness that recreates the schema.
 
 `example/.github/workflows/verify.yml` is a normal app-owned CI workflow with
 an explicit MariaDB service. Adapt it as source rather than generating it from

package/patterns/mysql-application/example/.env.example

@@ -3,3 +3,5 @@ DB_PORT=3306
 DB_NAME=application
 DB_USER=application
 DB_PASSWORD=replace-me
+TEST_DB_NAME=application_test
+BROWSER_TEST_DB_NAME=application_browser_test

package/patterns/mysql-application/example/package.json

@@ -8,6 +8,6 @@
     "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime-mysql": "0.1.197"
+    "@jskit-ai/database-runtime-mysql": "0.1.199"
   }
 }

package/patterns/mysql-application/example/tests/browser/database.js

@@ -0,0 +1,68 @@
+import knex from "knex";
+
+// Application-owned test setup. Schema migration tests use a separate fresh database.
+async function prepareBrowserTestDatabase({ knexConfig, environment = process.env, seed }) {
+  const started = performance.now();
+  if (environment.NODE_ENV === "production") throw new Error("Browser tests cannot prepare a production runtime.");
+  if (typeof seed !== "function") throw new TypeError("An explicit browser fixture seed is required.");
+  if (knexConfig?.client !== "mysql2" || !knexConfig.connection || typeof knexConfig.connection !== "object") {
+    throw new Error("Browser preparation requires a resolved MySQL Knex configuration.");
+  }
+  const database = String(environment.BROWSER_TEST_DB_NAME || "").trim();
+  if (!/^[a-zA-Z0-9_]{1,64}$/.test(database)) throw new Error("BROWSER_TEST_DB_NAME must name the exact browser database.");
+  const protectedNames = [knexConfig.connection.database, environment.DB_NAME, environment.TEST_DB_NAME];
+  if (environment.DATABASE_URL) {
+    try { protectedNames.push(decodeURIComponent(new URL(environment.DATABASE_URL).pathname.slice(1))); }
+    catch { throw new Error("DATABASE_URL must be a valid database URL."); }
+  }
+  if (!knexConfig.connection.database || protectedNames.some(name => String(name || "").trim().toLowerCase() === database.toLowerCase())) {
+    throw new Error("BROWSER_TEST_DB_NAME must differ from the application and disposable TEST_DB_NAME databases.");
+  }
+  const adminConnection = { ...knexConfig.connection };
+  delete adminConnection.database;
+  const admin = knex({ ...knexConfig, connection: adminConnection, pool: { min: 0, max: 1 } });
+  let schemaExisted;
+  try {
+    const [[row]] = await admin.raw("SELECT COUNT(*) AS count FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = ?", [database]);
+    schemaExisted = Number(row.count) === 1;
+    await admin.raw("CREATE DATABASE IF NOT EXISTS ??", [database]);
+  }
+  finally { await admin.destroy(); }
+  console.info(`Browser database ${database}: ${schemaExisted ? "existing schema" : "new schema"}.`);
+  const db = knex({ ...knexConfig, connection: { ...knexConfig.connection, database } });
+  try {
+    const migrationStarted = performance.now();
+    const [, migrations] = await db.migrate.latest();
+    const migrationMs = Math.round(performance.now() - migrationStarted);
+    console.info(`Browser migrations: ${migrations.length} applied in ${migrationMs}ms.`);
+    const resetStarted = performance.now();
+    let resetTables = 0;
+    const connection = await db.client.acquireConnection();
+    try {
+      const [[actual]] = await db.raw("SELECT DATABASE() AS databaseName").connection(connection);
+      if (actual.databaseName !== database) throw new Error("Browser reset requires the exact BROWSER_TEST_DB_NAME connection.");
+      const [tables] = await db.raw(
+        "SELECT TABLE_NAME AS name FROM information_schema.TABLES WHERE TABLE_SCHEMA = ? AND TABLE_TYPE = 'BASE TABLE'", [database]
+      ).connection(connection);
+      const ledger = knexConfig.migrations?.tableName || "knex_migrations";
+      await db.raw("SET FOREIGN_KEY_CHECKS = 0").connection(connection);
+      try {
+        for (const { name } of tables) {
+          if (name === ledger || name === `${ledger}_lock`) continue;
+          await db.raw("TRUNCATE TABLE ??", [name]).connection(connection);
+          resetTables += 1;
+        }
+      } finally { await db.raw("SET FOREIGN_KEY_CHECKS = 1").connection(connection); }
+    } finally { await db.client.releaseConnection(connection); }
+    const resetMs = Math.round(performance.now() - resetStarted);
+    console.info(`Browser fixture reset: ${resetTables} tables in ${resetMs}ms.`);
+    const seedStarted = performance.now();
+    await db.transaction(seed);
+    const seedMs = Math.round(performance.now() - seedStarted);
+    const totalMs = Math.round(performance.now() - started);
+    console.info(`Browser fixture seed: ${seedMs}ms; database preparation total: ${totalMs}ms.`);
+    return { database, migrations, schemaExisted, timings: { migrationMs, resetMs, seedMs, totalMs } };
+  } finally { await db.destroy(); }
+}
+
+export { prepareBrowserTestDatabase };

package/test/browserDatabasePattern.test.js

@@ -0,0 +1,82 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import knex from "knex";
+import { prepareBrowserTestDatabase } from "../patterns/mysql-application/example/tests/browser/database.js";
+
+const seed = async (db) => db("fixtures").insert({ id: 1, label: "baseline" });
+
+test("browser preparation rejects missing, ordinary and production databases before connecting", async () => {
+  const knexConfig = { client: "mysql2", connection: { database: "application" } };
+  for (const environment of [
+    {}, { BROWSER_TEST_DB_NAME: "application" }, { BROWSER_TEST_DB_NAME: "APPLICATION" },
+    { BROWSER_TEST_DB_NAME: "other", DB_NAME: "other" },
+    { BROWSER_TEST_DB_NAME: "other", DATABASE_URL: "mysql://localhost/other" },
+    { BROWSER_TEST_DB_NAME: "tests", TEST_DB_NAME: "TESTS" },
+    { BROWSER_TEST_DB_NAME: "tests", NODE_ENV: "production" }
+  ]) {
+    await assert.rejects(prepareBrowserTestDatabase({ knexConfig, environment, seed }), /TEST_DB_NAME|production/u);
+  }
+  await assert.rejects(prepareBrowserTestDatabase({ knexConfig, environment: { BROWSER_TEST_DB_NAME: "tests" } }), /seed/u);
+});
+
+test("native browser preparation retains schema, clears data and applies only new migrations", {
+  skip: !process.env.BROWSER_TEST_DB_NAME || !process.env.TEST_DB_NAME || !process.env.DB_HOST
+}, async () => {
+  const environment = process.env;
+  const connection = { host: environment.DB_HOST, port: Number(environment.DB_PORT), user: environment.DB_USER,
+    password: environment.DB_PASSWORD, database: environment.DB_NAME };
+  const admin = knex({ client: "mysql2", connection: { ...connection, database: undefined } });
+  const [[existing]] = await admin.raw("SELECT COUNT(*) AS n FROM information_schema.SCHEMATA WHERE SCHEMA_NAME IN (?, ?)", [environment.BROWSER_TEST_DB_NAME, environment.TEST_DB_NAME]);
+  if (Number(existing.n)) {
+    await admin.destroy();
+    throw new Error("The native pattern regression requires fresh, explicitly supplied test database names.");
+  }
+  let db;
+  let applied = 0;
+  const migrations = [{ name: "001_fixture.js", async up(db) {
+    applied += 1;
+    await db.schema.createTable("fixtures", table => { table.increments("id"); table.string("label"); });
+    await db.schema.createTable("children", table => { table.increments("id"); table.integer("parent_id").unsigned().references("fixtures.id"); });
+  }, async down() {} }];
+  const knexConfig = { client: "mysql2", connection, migrations: { migrationSource: {
+    getMigrations: () => migrations, getMigrationName: migration => migration.name, getMigration: migration => migration
+  } } };
+  try {
+    const [normalBefore] = await admin.raw("SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA = ?", [environment.DB_NAME]);
+    const first = await prepareBrowserTestDatabase({ knexConfig, environment, seed });
+    assert.deepEqual(first.migrations, ["001_fixture.js"]);
+    assert.equal(first.schemaExisted, false);
+    db = knex({ client: "mysql2", connection: { ...connection, database: environment.BROWSER_TEST_DB_NAME } });
+    const ledger = await db("knex_migrations").select();
+    await db("fixtures").insert({ id: 2, label: "stale" });
+    await db("children").insert({ parent_id: 2 });
+    // A disposable integration test between browser starts must not erase its schema.
+    await admin.raw("CREATE DATABASE ??", [environment.TEST_DB_NAME]);
+    await admin.raw("CREATE TABLE ??.proof (id INT PRIMARY KEY)", [environment.TEST_DB_NAME]);
+    await admin.raw("DROP DATABASE ??", [environment.TEST_DB_NAME]);
+    const second = await prepareBrowserTestDatabase({ knexConfig, environment, seed });
+    assert.equal(second.schemaExisted, true);
+    assert.deepEqual(second.migrations, []);
+    assert.equal(applied, 1);
+    assert.deepEqual(await db("knex_migrations").select(), ledger);
+    assert.deepEqual(await db("fixtures").select(), [{ id: 1, label: "baseline" }]);
+    assert.deepEqual(await db("children").select(), []);
+    // The preparation connection has foreign-key checks restored before seeding.
+    await assert.rejects(prepareBrowserTestDatabase({ knexConfig, environment,
+      seed: async db => db("children").insert({ parent_id: 99 }) }), /foreign key constraint/iu);
+    migrations.push({ name: "002_pending.js", async up(db) {
+      await db.schema.alterTable("fixtures", table => table.string("extra"));
+    }, async down() {} });
+    const third = await prepareBrowserTestDatabase({ knexConfig, environment, seed });
+    assert.deepEqual(third.migrations, ["002_pending.js"]);
+    assert.equal(await db.schema.hasColumn("fixtures", "extra"), true);
+    assert.equal(applied, 1);
+    const [normalAfter] = await admin.raw("SELECT TABLE_NAME FROM information_schema.TABLES WHERE TABLE_SCHEMA = ?", [environment.DB_NAME]);
+    assert.deepEqual(normalAfter, normalBefore);
+  } finally {
+    await db?.destroy();
+    await admin.raw("DROP DATABASE IF EXISTS ??", [environment.BROWSER_TEST_DB_NAME]);
+    await admin.raw("DROP DATABASE IF EXISTS ??", [environment.TEST_DB_NAME]);
+    await admin.destroy();
+  }
+});