@jskit-ai/database-runtime-mysql 0.1.198 → 0.1.200

package/package.json

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

package/patterns/mysql-application/PATTERN.md

@@ -48,17 +48,24 @@ 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 `TEST_DB_NAME`, rejects the ordinary database,
+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.
+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
@@ -81,7 +88,7 @@ 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, prove two consecutive starts: the second applies no
+- 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

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.198"
+    "@jskit-ai/database-runtime-mysql": "0.1.200"
   }
 }

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

@@ -2,33 +2,45 @@ 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.TEST_DB_NAME || "").trim();
-  if (!/^[a-zA-Z0-9_]{1,64}$/.test(database)) throw new Error("TEST_DB_NAME must name the exact disposable database.");
-  const protectedNames = [knexConfig.connection.database, environment.DB_NAME];
+  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("TEST_DB_NAME must differ from every configured application database.");
+    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 } });
-  try { await admin.raw("CREATE DATABASE IF NOT EXISTS ??", [database]); }
+  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 TEST_DB_NAME 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);
@@ -38,11 +50,18 @@ async function prepareBrowserTestDatabase({ knexConfig, environment = process.en
         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);
-    return { database, migrations };
+    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(); }
 }
 

package/test/browserDatabasePattern.test.js

@@ -8,27 +8,28 @@ 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 [
-    {}, { TEST_DB_NAME: "application" }, { TEST_DB_NAME: "APPLICATION" },
-    { TEST_DB_NAME: "other", DB_NAME: "other" },
-    { TEST_DB_NAME: "other", DATABASE_URL: "mysql://localhost/other" },
-    { TEST_DB_NAME: "tests", NODE_ENV: "production" }
+    {}, { 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: { TEST_DB_NAME: "tests" } }), /seed/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.TEST_DB_NAME || !process.env.DB_HOST
+  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 = ?", [environment.TEST_DB_NAME]);
+  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 a fresh, explicitly supplied TEST_DB_NAME.");
+    throw new Error("The native pattern regression requires fresh, explicitly supplied test database names.");
   }
   let db;
   let applied = 0;
@@ -44,11 +45,17 @@ test("native browser preparation retains schema, clears data and applies only ne
     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"]);
-    db = knex({ client: "mysql2", connection: { ...connection, database: environment.TEST_DB_NAME } });
+    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);
@@ -68,6 +75,7 @@ test("native browser preparation retains schema, clears data and applies only ne
     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();
   }