@jskit-ai/database-runtime-mysql 0.1.157 → 0.1.159

package/package.json

@@ -1,73 +1,35 @@
 {
   "name": "@jskit-ai/database-runtime-mysql",
-  "version": "0.1.157",
+  "version": "0.1.159",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "exports": {
     "./client": "./src/client/index.js",
-    "./server/providers/DatabaseRuntimeMysqlServiceProvider": "./src/server/providers/DatabaseRuntimeMysqlServiceProvider.js",
+    "./server/providers/MysqlDatabaseDriverProvider": "./src/server/providers/MysqlDatabaseDriverProvider.js",
     "./shared": "./src/shared/index.js",
     "./shared/dialect": "./src/shared/dialect.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.159",
-    "@jskit-ai/kernel": "0.1.159"
+    "@jskit-ai/database-runtime": "0.1.161",
+    "@jskit-ai/kernel": "0.1.161",
+    "mysql2": "^3.11.2"
   },
   "jskit": {
     "kind": "runtime",
-    "options": {
-      "db-host": {
-        "required": false,
-        "values": [],
-        "defaultValue": "localhost",
-        "promptLabel": "Database host",
-        "promptHint": "MySQL host (for example 127.0.0.1)"
-      },
-      "db-port": {
-        "required": false,
-        "values": [],
-        "defaultValue": "3306",
-        "promptLabel": "Database port",
-        "promptHint": "MySQL port (usually 3306)"
-      },
-      "db-name": {
-        "required": true,
-        "values": [],
-        "promptLabel": "Database name",
-        "promptHint": "Schema/database name to connect to"
-      },
-      "db-user": {
-        "required": true,
-        "values": [],
-        "promptLabel": "Database user",
-        "promptHint": "Database username"
-      },
-      "db-password": {
-        "required": true,
-        "values": [],
-        "inputType": "password",
-        "promptLabel": "Database password",
-        "promptHint": "Database password"
-      }
-    },
     "capabilities": {
       "provides": [
-        "runtime.database.driver",
-        "runtime.database.driver.mysql"
+        "runtime.database.driver"
       ],
-      "requires": [
-        "runtime.database"
-      ]
+      "requires": []
     },
     "runtime": {
       "server": {
-        "providerEntrypoint": "src/server/providers/DatabaseRuntimeMysqlServiceProvider.js",
         "providers": [
           {
-            "entrypoint": "src/server/providers/DatabaseRuntimeMysqlServiceProvider.js",
-            "export": "DatabaseRuntimeMysqlServiceProvider"
+            "entrypoint": "src/server/providers/MysqlDatabaseDriverProvider.js",
+            "export": "MysqlDatabaseDriverProvider"
           }
         ]
       },
@@ -80,7 +42,7 @@
         "surfaces": [
           {
             "subpath": "./server",
-            "summary": "Exports MySQL database runtime provider."
+            "summary": "Provides the exclusive runtime.database.driver capability for MySQL."
           },
           {
             "subpath": "./shared",
@@ -90,116 +52,8 @@
             "subpath": "./client",
             "summary": "Exports no runtime API today (reserved client entrypoint)."
           }
-        ],
-        "containerTokens": {
-          "server": [
-            "runtime.database.driver.mysql"
-          ],
-          "client": []
-        }
+        ]
       }
-    },
-    "ci": {
-      "environment": {
-        "DB_CLIENT": "mysql2",
-        "DB_HOST": "127.0.0.1",
-        "DB_PORT": "33060",
-        "DB_NAME": "jskit_ci",
-        "DB_USER": "jskit_ci",
-        "DB_PASSWORD": "jskit_ci_only_password"
-      },
-      "services": [
-        {
-          "id": "mariadb",
-          "image": "mariadb:11.4",
-          "environment": {
-            "MARIADB_DATABASE": "jskit_ci",
-            "MARIADB_USER": "jskit_ci",
-            "MARIADB_PASSWORD": "jskit_ci_only_password",
-            "MARIADB_ROOT_PASSWORD": "jskit_ci_only_root_password"
-          },
-          "ports": [
-            "33060:3306"
-          ],
-          "healthCheck": {
-            "command": "healthcheck.sh --connect --innodb_initialized",
-            "interval": "10s",
-            "timeout": "5s",
-            "retries": 10
-          }
-        }
-      ],
-      "steps": []
-    },
-    "mutations": {
-      "dependencies": {
-        "runtime": {
-          "@jskit-ai/database-runtime": "0.1.159",
-          "mysql2": "^3.11.2"
-        },
-        "dev": {}
-      },
-      "packageJson": {
-        "scripts": {}
-      },
-      "procfile": {},
-      "files": [],
-      "text": [
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_CLIENT",
-          "value": "mysql2",
-          "reason": "Configure database client driver for runtime wiring.",
-          "category": "runtime-config",
-          "id": "database-client-mysql"
-        },
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_HOST",
-          "value": "${option:db-host}",
-          "reason": "Configure database host.",
-          "category": "runtime-config",
-          "id": "database-host"
-        },
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_PORT",
-          "value": "${option:db-port}",
-          "reason": "Configure database port.",
-          "category": "runtime-config",
-          "id": "database-port"
-        },
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_NAME",
-          "value": "${option:db-name}",
-          "reason": "Configure database name.",
-          "category": "runtime-config",
-          "id": "database-name"
-        },
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_USER",
-          "value": "${option:db-user}",
-          "reason": "Configure database user.",
-          "category": "runtime-config",
-          "id": "database-user"
-        },
-        {
-          "file": ".env",
-          "op": "upsert-env",
-          "key": "DB_PASSWORD",
-          "value": "${option:db-password}",
-          "reason": "Configure database password.",
-          "category": "runtime-config",
-          "id": "database-password"
-        }
-      ]
     }
   }
 }

package/patterns/mysql-application/PATTERN.md

@@ -0,0 +1,80 @@
+---
+id: database/mysql-application
+title: MySQL application database
+summary: Configure a JSKIT application for MySQL with a fixed driver, ordinary environment values, and rebuildable Knex migrations.
+keywords: database, knex, mariadb, migrations, mysql, mysql2
+requires: @jskit-ai/database-runtime-mysql
+---
+
+# MySQL application database
+
+## Use when
+
+Use this pattern when an application deliberately chooses MySQL or MariaDB.
+Install `@jskit-ai/database-runtime-mysql`; its normal npm dependencies provide
+the database runtime, Knex, and `mysql2` without a package-setup wizard.
+
+## Do not use when
+
+Do not use this pattern for PostgreSQL, a database-neutral library, or a service
+that does not own its database connection. Do not install both JSKIT drivers
+unless the application genuinely selects between them at runtime.
+
+## Product decisions
+
+Decide the database name, credentials, host, deployment secret source, backup
+policy, and application migrations. Those are application and environment
+decisions, not framework questions.
+
+## Invariants
+
+- The application depends directly on the selected JSKIT driver.
+- Credentials stay outside Git.
+- `knexfile.js` fixes `mysql2`; a single-driver application does not require
+  `DB_CLIENT`.
+- Schema changes are ordinary immutable migrations.
+- The current package graph, environment, and migrations are authoritative.
+
+## Framework APIs
+
+Use `createKnexMigrationConfigFromApp()` from
+`@jskit-ai/database-runtime/server/knexMigrationConfig`. The running JSKIT
+application automatically selects the sole installed database driver, while
+Knex discovers package-owned migrations from the installed dependency graph.
+
+## Example files
+
+`example/package.json` contains the runtime dependency and database scripts.
+`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.
+
+## Variation points
+
+Change scripts, migration location, connection values, and secret injection to
+fit the application. Supply `DATABASE_URL` instead of individual values when
+the environment owns a URL. Add `DB_CLIENT=mysql2` only when a shared external
+tool explicitly needs a dialect selector. When the product needs initial data,
+import one idempotent app-owned seed function in `prepare-database.js` and pass
+it as `seed` to `prepareDatabaseFromApp()`.
+
+## Verification
+
+- Install dependencies once with `npm install`.
+- Run `npm run db:prepare` against a fresh disposable database.
+- 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.
+
+`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 metadata.
+
+## Avoid
+
+- framework questionnaires for credentials
+- generated `.env` secrets
+- depending on a live schema as the source contract
+- a second driver installed “just in case”
+- migration receipts, provenance, replay logs, or generator ownership

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

@@ -0,0 +1,5 @@
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_NAME=application
+DB_USER=application
+DB_PASSWORD=replace-me

package/patterns/mysql-application/example/.github/workflows/verify.yml

@@ -0,0 +1,39 @@
+name: Verify
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    services:
+      mariadb:
+        image: mariadb:11.4
+        env:
+          MARIADB_DATABASE: app_test
+          MARIADB_USER: app_test
+          MARIADB_PASSWORD: app_test_password
+          MARIADB_ROOT_PASSWORD: root_test_password
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="healthcheck.sh --connect --innodb_initialized"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+    env:
+      DB_HOST: 127.0.0.1
+      DB_PORT: 3306
+      DB_NAME: app_test
+      DB_USER: app_test
+      DB_PASSWORD: app_test_password
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - run: npm ci
+      - run: npm run db:migrate
+      - run: npm run verify

package/patterns/mysql-application/example/knexfile.js

@@ -0,0 +1,11 @@
+import { createKnexMigrationConfigFromApp } from "@jskit-ai/database-runtime/server/knexMigrationConfig";
+
+try {
+  process.loadEnvFile?.(".env");
+} catch (error) {
+  if (error?.code !== "ENOENT") {
+    throw error;
+  }
+}
+
+export default await createKnexMigrationConfigFromApp({ client: "mysql2" });

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

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "db:prepare": "node ./scripts/prepare-database.js",
+    "db:migrate": "knex --knexfile ./knexfile.js migrate:latest",
+    "db:migrate:rollback": "knex --knexfile ./knexfile.js migrate:rollback",
+    "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
+  },
+  "dependencies": {
+    "@jskit-ai/database-runtime-mysql": "0.1.159"
+  }
+}

package/patterns/mysql-application/example/scripts/prepare-database.js

@@ -0,0 +1,3 @@
+import { prepareDatabaseFromApp } from "@jskit-ai/database-runtime/server/databaseSetup";
+
+await prepareDatabaseFromApp({ client: "mysql2" });

package/src/server/providers/MysqlDatabaseDriverProvider.js

@@ -0,0 +1,16 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import * as mysqlDriver from "../../shared/index.js";
+
+const MysqlDatabaseDriverProvider = defineProvider({
+  id: "runtime.database.driver.mysql",
+  provides: {
+    driver: "runtime.database.driver"
+  },
+  setup() {
+    return {
+      driver: Object.freeze({ ...mysqlDriver })
+    };
+  }
+});
+
+export { MysqlDatabaseDriverProvider };

package/test/applicationPattern.test.js

@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+const patternUrl = new URL("../patterns/mysql-application/", import.meta.url);
+
+test("MySQL application pattern is driver-fixed and questionnaire-free", async () => {
+  const [document, manifestSource, knexfile] = await Promise.all([
+    readFile(new URL("PATTERN.md", patternUrl), "utf8"),
+    readFile(new URL("example/package.json", patternUrl), "utf8"),
+    readFile(new URL("example/knexfile.js", patternUrl), "utf8")
+  ]);
+  const manifest = JSON.parse(manifestSource);
+
+  assert.equal(manifest.dependencies["@jskit-ai/database-runtime-mysql"], "0.1.158");
+  assert.match(knexfile, /client: "mysql2"/u);
+  assert.doesNotMatch(`${document}\n${knexfile}`, /promptLabel|promptHint|\$\{option:/u);
+});

package/test/entrypoints.boundary.test.js

@@ -4,15 +4,15 @@ import test from "node:test";
 
 import * as clientApi from "../src/client/index.js";
 import * as sharedApi from "../src/shared/index.js";
-import { DatabaseRuntimeMysqlServiceProvider } from "../src/server/providers/DatabaseRuntimeMysqlServiceProvider.js";
+import { MysqlDatabaseDriverProvider } from "../src/server/providers/MysqlDatabaseDriverProvider.js";
 
 test("package exports include explicit shared and provider entrypoints", async () => {
   const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
   const exportsMap = packageJson && typeof packageJson === "object" ? packageJson.exports : {};
   assert.equal(exportsMap["./server"], undefined);
   assert.equal(
-    exportsMap["./server/providers/DatabaseRuntimeMysqlServiceProvider"],
-    "./src/server/providers/DatabaseRuntimeMysqlServiceProvider.js"
+    exportsMap["./server/providers/MysqlDatabaseDriverProvider"],
+    "./src/server/providers/MysqlDatabaseDriverProvider.js"
   );
   assert.equal(exportsMap["./shared"], "./src/shared/index.js");
 });
@@ -21,13 +21,14 @@ test("client entrypoint exports no mysql runtime api", () => {
   assert.deepEqual(Object.keys(clientApi), []);
 });
 
-test("server provider module exports mysql service provider only", () => {
-  assert.equal(typeof DatabaseRuntimeMysqlServiceProvider, "function");
+test("server provider module exports the declarative mysql driver provider", () => {
+  assert.equal(MysqlDatabaseDriverProvider.id, "runtime.database.driver.mysql");
+  assert.deepEqual(MysqlDatabaseDriverProvider.provides, { driver: "runtime.database.driver" });
 });
 
 test("shared entrypoint exports mysql dialect helpers", () => {
   assert.equal(sharedApi.DIALECT_ID, "mysql2");
   assert.equal(sharedApi.getDialectId(), "mysql2");
   assert.equal(typeof sharedApi.introspectCrudTableSnapshot, "function");
-  assert.equal(typeof sharedApi.DatabaseRuntimeMysqlServiceProvider, "undefined");
+  assert.equal(typeof sharedApi.MysqlDatabaseDriverProvider, "undefined");
 });

package/test/packageMetadata.test.js

@@ -1,24 +1,23 @@
 import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
 import test from "node:test";
+import { fileURLToPath } from "node:url";
 import packageJson from "../package.json" with { type: "json" };
 
-const packageMetadata = packageJson.jskit;
-import { DIALECT_ID } from "../src/shared/dialect.js";
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
-test("database-runtime-mysql contributes canonical synthetic MariaDB CI requirements", () => {
-  assert.equal(packageMetadata.ci.environment.DB_CLIENT, DIALECT_ID);
-  assert.equal(packageMetadata.ci.environment.DB_HOST, "127.0.0.1");
-  assert.equal(packageMetadata.ci.environment.DB_PORT, "33060");
-  assert.match(packageMetadata.ci.environment.DB_PASSWORD, /ci_only/u);
+test("database-runtime-mysql owns its driver while CI remains app-owned source", async () => {
+  const workflow = await readFile(
+    path.join(PACKAGE_ROOT, "patterns/mysql-application/example/.github/workflows/verify.yml"),
+    "utf8"
+  );
 
-  const service = packageMetadata.ci.services.find((entry) => entry.id === "mariadb");
-  assert.equal(service.image, "mariadb:11.4");
-  assert.equal(service.environment.MARIADB_DATABASE, packageMetadata.ci.environment.DB_NAME);
-  assert.equal(service.environment.MARIADB_USER, packageMetadata.ci.environment.DB_USER);
-  assert.equal(service.environment.MARIADB_PASSWORD, packageMetadata.ci.environment.DB_PASSWORD);
-  assert.deepEqual(service.ports, ["33060:3306"]);
-  assert.match(service.healthCheck.command, /healthcheck\.sh/u);
-
-  const clientMutation = packageMetadata.mutations.text.find((entry) => entry.key === "DB_CLIENT");
-  assert.equal(clientMutation.value, DIALECT_ID);
+  assert.equal(packageJson.dependencies.mysql2, "^3.11.2");
+  assert.equal(Object.hasOwn(packageJson.jskit, "options"), false);
+  assert.equal(Object.hasOwn(packageJson.jskit, "mutations"), false);
+  assert.equal(Object.hasOwn(packageJson.jskit, "ci"), false);
+  assert.match(workflow, /image: mariadb:11\.4/u);
+  assert.match(workflow, /npm run db:migrate/u);
+  assert.match(workflow, /npm run verify/u);
 });

package/test/providerRuntime.test.js

@@ -1,33 +1,23 @@
-import test from "node:test";
 import assert from "node:assert/strict";
-import { DatabaseRuntimeMysqlServiceProvider } from "../src/server/providers/DatabaseRuntimeMysqlServiceProvider.js";
+import test from "node:test";
 
-function createSingletonApp() {
-  const singletons = new Map();
+import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { MysqlDatabaseDriverProvider } from "../src/server/providers/MysqlDatabaseDriverProvider.js";
 
-  return {
-    has(token) {
-      return singletons.has(token);
-    },
-    singleton(token, factory) {
-      singletons.set(token, factory(this));
-    },
-    make(token) {
-      if (!singletons.has(token)) {
-        throw new Error(`Token ${String(token)} is not registered.`);
-      }
-      return singletons.get(token);
+test("MysqlDatabaseDriverProvider provides the exclusive database driver capability", async () => {
+  let driver;
+  const consumer = defineProvider({
+    id: "test.mysql.consumer",
+    requires: { databaseDriver: "runtime.database.driver" },
+    setup({ databaseDriver }) {
+      driver = databaseDriver;
+      return {};
     }
-  };
-}
-
-test("DatabaseRuntimeMysqlServiceProvider registers mysql driver api", () => {
-  const app = createSingletonApp();
-  const provider = new DatabaseRuntimeMysqlServiceProvider();
-  provider.register(app);
+  });
+  const runtime = createCapabilityRuntime({ providers: [MysqlDatabaseDriverProvider, consumer] });
 
-  assert.equal(app.has("runtime.database.driver.mysql"), true);
-  const api = app.make("runtime.database.driver.mysql");
-  assert.equal(api.DIALECT_ID, "mysql2");
-  assert.equal(api.getDialectId(), "mysql2");
+  await runtime.start();
+  assert.equal(driver.DIALECT_ID, "mysql2");
+  assert.equal(driver.getDialectId(), "mysql2");
+  await runtime.shutdown();
 });

package/src/server/providers/DatabaseRuntimeMysqlServiceProvider.js

@@ -1,21 +0,0 @@
-import * as mysqlDialect from "../../shared/index.js";
-
-const MYSQL_DATABASE_DRIVER_API = Object.freeze({
-  ...mysqlDialect
-});
-
-class DatabaseRuntimeMysqlServiceProvider {
-  static id = "runtime.database.driver.mysql";
-
-  register(app) {
-    if (!app || typeof app.singleton !== "function") {
-      throw new Error("DatabaseRuntimeMysqlServiceProvider requires application singleton().");
-    }
-
-    app.singleton("runtime.database.driver.mysql", () => MYSQL_DATABASE_DRIVER_API);
-  }
-
-  boot() {}
-}
-
-export { DatabaseRuntimeMysqlServiceProvider };