@jskit-ai/database-runtime 0.1.11 → 0.1.13

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/database-runtime",
-  version: "0.1.11",
+  version: "0.1.13",
   dependsOn: [
     "@jskit-ai/kernel"
   ],
@@ -55,7 +55,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/kernel": "0.1.11",
+        "@jskit-ai/kernel": "0.1.12",
         "dotenv": "^16.4.5",
         "knex": "^3.1.0"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/database-runtime",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -25,6 +25,6 @@
     "./shared/transactions": "./src/shared/transactions.js"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.11"
+    "@jskit-ai/kernel": "0.1.12"
   }
 }

package/src/server/providers/DatabaseRuntimeServiceProvider.js

@@ -7,6 +7,7 @@ import {
   normalizeDatabaseClient,
   toKnexClientId
 } from "../../shared/databaseClient.js";
+import { resolveDatabaseConnectionFromEnvironment } from "../../shared/databaseConnection.js";
 
 const DATABASE_RUNTIME_TOKEN = "runtime.database";
 const DATABASE_DRIVER_TOKEN = "runtime.database.driver";
@@ -42,22 +43,6 @@ function resolveDriverDialectId(driver) {
   return "";
 }
 
-function resolveRequiredEnvString(env, key) {
-  const value = normalizeText(env?.[key]);
-  if (!value) {
-    throw new Error(`${key} is required for database runtime.`);
-  }
-  return value;
-}
-
-function resolvePort(value, fallbackPort) {
-  const parsed = Number.parseInt(normalizeText(value), 10);
-  if (Number.isInteger(parsed) && parsed > 0) {
-    return parsed;
-  }
-  return fallbackPort;
-}
-
 function loadKnexFactory() {
   let moduleValue;
   try {
@@ -142,16 +127,14 @@ function createKnexConfig(scope) {
 
   const client = toKnexClientId(dialectId);
   const defaultPort = dialectId === "pg" ? 5432 : 3306;
+  const connection = resolveDatabaseConnectionFromEnvironment(env, {
+    defaultPort,
+    context: "database runtime"
+  });
 
   return {
     client,
-    connection: {
-      host: normalizeText(env.DB_HOST) || "localhost",
-      port: resolvePort(env.DB_PORT, defaultPort),
-      database: resolveRequiredEnvString(env, "DB_NAME"),
-      user: resolveRequiredEnvString(env, "DB_USER"),
-      password: String(env.DB_PASSWORD ?? "")
-    }
+    connection
   };
 }
 

package/src/shared/databaseConnection.js

@@ -0,0 +1,116 @@
+import { normalizeDatabaseClient, normalizeText } from "./databaseClient.js";
+
+const DATABASE_URL_PROTOCOL_TO_CLIENT = Object.freeze({
+  "mysql:": "mysql2",
+  "mysql2:": "mysql2",
+  "mariadb:": "mysql2",
+  "postgres:": "pg",
+  "postgresql:": "pg",
+  "pg:": "pg"
+});
+
+function toPositiveInteger(value, fallback) {
+  const parsed = Number.parseInt(normalizeText(value), 10);
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallback;
+}
+
+function parseDatabaseUrl(databaseUrl, { context = "DATABASE_URL", allowEmpty = false } = {}) {
+  const normalized = normalizeText(databaseUrl);
+  if (!normalized) {
+    if (allowEmpty) {
+      return null;
+    }
+    throw new Error(`${context} is required.`);
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(normalized);
+  } catch {
+    throw new Error(`${context} must be a valid absolute URL.`);
+  }
+
+  const databaseName = normalizeText(decodeURIComponent(String(parsed.pathname || "").replace(/^\/+/, "")));
+  const user = normalizeText(decodeURIComponent(parsed.username || ""));
+  const password = decodeURIComponent(parsed.password || "");
+
+  return Object.freeze({
+    protocol: normalizeText(parsed.protocol).toLowerCase(),
+    host: normalizeText(parsed.hostname),
+    port: toPositiveInteger(parsed.port, 0),
+    database: databaseName,
+    user,
+    password
+  });
+}
+
+function resolveDatabaseClientFromEnvironment(env = {}, { allowEmpty = false } = {}) {
+  const source = env && typeof env === "object" ? env : {};
+  const explicitClient = normalizeText(source.DB_CLIENT);
+  if (explicitClient) {
+    return normalizeDatabaseClient(explicitClient, { allowEmpty });
+  }
+
+  const parsedUrl = parseDatabaseUrl(source.DATABASE_URL, { allowEmpty: true });
+  const inferredClient = parsedUrl ? DATABASE_URL_PROTOCOL_TO_CLIENT[parsedUrl.protocol] || "" : "";
+  if (inferredClient) {
+    return normalizeDatabaseClient(inferredClient, { allowEmpty });
+  }
+
+  if (allowEmpty) {
+    return "";
+  }
+
+  if (parsedUrl) {
+    throw new Error(
+      `Unsupported DATABASE_URL protocol "${parsedUrl.protocol}". Use one of: mysql, mysql2, mariadb, postgres, postgresql, pg.`
+    );
+  }
+
+  throw new Error("DB_CLIENT is required. Set DB_CLIENT or DATABASE_URL.");
+}
+
+function resolveDatabaseConnectionFromEnvironment(
+  env = {},
+  {
+    defaultHost = "localhost",
+    defaultPort = 3306,
+    context = "database runtime"
+  } = {}
+) {
+  const source = env && typeof env === "object" ? env : {};
+  const parsedUrl = parseDatabaseUrl(source.DATABASE_URL, { allowEmpty: true });
+
+  const host = normalizeText(source.DB_HOST) || normalizeText(parsedUrl?.host) || defaultHost;
+  const port = toPositiveInteger(source.DB_PORT, parsedUrl?.port || defaultPort);
+
+  const database = normalizeText(source.DB_NAME) || normalizeText(parsedUrl?.database);
+  if (!database) {
+    throw new Error(`DB_NAME is required for ${context}. Set DB_NAME or DATABASE_URL.`);
+  }
+
+  const user = normalizeText(source.DB_USER) || normalizeText(parsedUrl?.user);
+  if (!user) {
+    throw new Error(`DB_USER is required for ${context}. Set DB_USER or DATABASE_URL.`);
+  }
+
+  const hasDbPassword = Object.prototype.hasOwnProperty.call(source, "DB_PASSWORD");
+  const password = hasDbPassword ? String(source.DB_PASSWORD ?? "") : String(parsedUrl?.password || "");
+
+  return Object.freeze({
+    host,
+    port,
+    database,
+    user,
+    password
+  });
+}
+
+export {
+  parseDatabaseUrl,
+  resolveDatabaseClientFromEnvironment,
+  resolveDatabaseConnectionFromEnvironment
+};

package/src/shared/index.js

@@ -15,6 +15,11 @@ export {
 } from "./dateUtils.js";
 export { normalizeDialect, detectDialectFromClient } from "./dialect.js";
 export { normalizeText, normalizeDatabaseClient, toKnexClientId } from "./databaseClient.js";
+export {
+  parseDatabaseUrl,
+  resolveDatabaseClientFromEnvironment,
+  resolveDatabaseConnectionFromEnvironment
+} from "./databaseConnection.js";
 export { isDuplicateEntryError } from "./duplicateEntry.js";
 export { normalizePath, jsonTextExpression, whereJsonTextEquals } from "./json.js";
 export { DEFAULT_VISIBILITY_COLUMNS, applyVisibility, applyVisibilityOwners } from "./visibility.js";

package/templates/knexfile.js

@@ -2,25 +2,10 @@ import path from "node:path";
 import dotenv from "dotenv";
 import {
   normalizeText,
-  normalizeDatabaseClient,
-  toKnexClientId
-} from "@jskit-ai/database-runtime/shared/databaseClient";
-
-function resolveRequiredEnvString(env, key) {
-  const value = normalizeText(env[key]);
-  if (!value) {
-    throw new Error(`${key} is required.`);
-  }
-  return value;
-}
-
-function resolvePort(value, fallbackPort) {
-  const parsed = Number.parseInt(normalizeText(value), 10);
-  if (Number.isInteger(parsed) && parsed > 0) {
-    return parsed;
-  }
-  return fallbackPort;
-}
+  toKnexClientId,
+  resolveDatabaseClientFromEnvironment,
+  resolveDatabaseConnectionFromEnvironment
+} from "@jskit-ai/database-runtime/shared";
 
 const appRoot = process.cwd();
 dotenv.config({
@@ -28,20 +13,17 @@ dotenv.config({
   quiet: true
 });
 
-const dialectId = normalizeDatabaseClient(process.env.DB_CLIENT);
+const dialectId = resolveDatabaseClientFromEnvironment(process.env);
 const client = toKnexClientId(dialectId);
 const defaultPort = dialectId === "pg" ? 5432 : 3306;
 const migrationsDirectory = path.resolve(appRoot, normalizeText(process.env.DB_MIGRATIONS_DIR) || "migrations");
 
 export default {
   client,
-  connection: {
-    host: normalizeText(process.env.DB_HOST) || "localhost",
-    port: resolvePort(process.env.DB_PORT, defaultPort),
-    database: resolveRequiredEnvString(process.env, "DB_NAME"),
-    user: resolveRequiredEnvString(process.env, "DB_USER"),
-    password: String(process.env.DB_PASSWORD ?? "")
-  },
+  connection: resolveDatabaseConnectionFromEnvironment(process.env, {
+    defaultPort,
+    context: "knex migrations"
+  }),
   migrations: {
     directory: migrationsDirectory,
     extension: "cjs"

package/test/databaseConnection.test.js

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  parseDatabaseUrl,
+  resolveDatabaseClientFromEnvironment,
+  resolveDatabaseConnectionFromEnvironment
+} from "../src/shared/databaseConnection.js";
+
+test("parseDatabaseUrl parses mysql url fields", () => {
+  const parsed = parseDatabaseUrl("mysql://appuser:apppass@db.local:3307/appdb");
+  assert.equal(parsed.protocol, "mysql:");
+  assert.equal(parsed.host, "db.local");
+  assert.equal(parsed.port, 3307);
+  assert.equal(parsed.database, "appdb");
+  assert.equal(parsed.user, "appuser");
+  assert.equal(parsed.password, "apppass");
+});
+
+test("resolveDatabaseClientFromEnvironment infers client from DATABASE_URL when DB_CLIENT is absent", () => {
+  const client = resolveDatabaseClientFromEnvironment({
+    DATABASE_URL: "postgres://user:pass@db.local:5432/appdb"
+  });
+  assert.equal(client, "pg");
+});
+
+test("resolveDatabaseConnectionFromEnvironment falls back to DATABASE_URL values", () => {
+  const connection = resolveDatabaseConnectionFromEnvironment({
+    DATABASE_URL: "mysql://urluser:urlpass@db.url.local:3308/url_db_name"
+  }, {
+    defaultPort: 3306,
+    context: "database runtime"
+  });
+
+  assert.equal(connection.host, "db.url.local");
+  assert.equal(connection.port, 3308);
+  assert.equal(connection.database, "url_db_name");
+  assert.equal(connection.user, "urluser");
+  assert.equal(connection.password, "urlpass");
+});
+
+test("resolveDatabaseConnectionFromEnvironment keeps explicit DB_* values over DATABASE_URL", () => {
+  const connection = resolveDatabaseConnectionFromEnvironment({
+    DATABASE_URL: "mysql://urluser:urlpass@db.url.local:3308/url_db_name",
+    DB_HOST: "db.explicit.local",
+    DB_PORT: "3310",
+    DB_NAME: "explicit_db",
+    DB_USER: "explicit_user",
+    DB_PASSWORD: "explicit_pass"
+  }, {
+    defaultPort: 3306,
+    context: "database runtime"
+  });
+
+  assert.equal(connection.host, "db.explicit.local");
+  assert.equal(connection.port, 3310);
+  assert.equal(connection.database, "explicit_db");
+  assert.equal(connection.user, "explicit_user");
+  assert.equal(connection.password, "explicit_pass");
+});
+

package/test/providerRuntime.test.js

@@ -57,6 +57,47 @@ function createKnexStub() {
   };
 }
 
+async function withAppRootKnexStub(callback) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "jskit-db-runtime-test-"));
+  const knexPackageDir = path.join(appRoot, "node_modules", "knex");
+  await mkdir(knexPackageDir, { recursive: true });
+  await writeFile(path.join(appRoot, "package.json"), JSON.stringify({ name: "runtime-app", private: true }), "utf8");
+  await writeFile(
+    path.join(knexPackageDir, "package.json"),
+    JSON.stringify({
+      name: "knex",
+      version: "0.0.0-test",
+      main: "index.js",
+      type: "commonjs"
+    }),
+    "utf8"
+  );
+  await writeFile(
+    path.join(knexPackageDir, "index.js"),
+    [
+      "module.exports = function knex(config) {",
+      "  return {",
+      "    __source: 'app-root-knex',",
+      "    __config: config,",
+      "    transaction: async function transaction(callback) {",
+      "      return callback({ trxId: 'trx-app-root' });",
+      "    }",
+      "  };",
+      "};",
+      ""
+    ].join("\n"),
+    "utf8"
+  );
+
+  const previousCwd = process.cwd();
+  try {
+    process.chdir(appRoot);
+    await callback();
+  } finally {
+    process.chdir(previousCwd);
+  }
+}
+
 test("DatabaseRuntimeServiceProvider registers runtime api", () => {
   const app = createSingletonApp();
   const provider = new DatabaseRuntimeServiceProvider();
@@ -112,41 +153,7 @@ test("DatabaseRuntimeServiceProvider driver token throws when multiple drivers a
 });
 
 test("DatabaseRuntimeServiceProvider resolves knex from app root package context", async () => {
-  const appRoot = await mkdtemp(path.join(tmpdir(), "jskit-db-runtime-test-"));
-  const knexPackageDir = path.join(appRoot, "node_modules", "knex");
-  await mkdir(knexPackageDir, { recursive: true });
-  await writeFile(path.join(appRoot, "package.json"), JSON.stringify({ name: "runtime-app", private: true }), "utf8");
-  await writeFile(
-    path.join(knexPackageDir, "package.json"),
-    JSON.stringify({
-      name: "knex",
-      version: "0.0.0-test",
-      main: "index.js",
-      type: "commonjs"
-    }),
-    "utf8"
-  );
-  await writeFile(
-    path.join(knexPackageDir, "index.js"),
-    [
-      "module.exports = function knex(config) {",
-      "  return {",
-      "    __source: 'app-root-knex',",
-      "    __config: config,",
-      "    transaction: async function transaction(callback) {",
-      "      return callback({ trxId: 'trx-app-root' });",
-      "    }",
-      "  };",
-      "};",
-      ""
-    ].join("\n"),
-    "utf8"
-  );
-
-  const previousCwd = process.cwd();
-  try {
-    process.chdir(appRoot);
-
+  await withAppRootKnexStub(async () => {
     const app = createSingletonApp();
     app.instance("runtime.database.driver.mysql", Object.freeze({ DIALECT_ID: "mysql2" }));
     app.instance(KERNEL_TOKENS.Env, {
@@ -168,7 +175,27 @@ test("DatabaseRuntimeServiceProvider resolves knex from app root package context
     assert.equal(knex.__config.connection.database, "appdb");
     assert.equal(knex.__config.connection.user, "appuser");
     assert.equal(knex.__config.connection.password, "apppass");
-  } finally {
-    process.chdir(previousCwd);
-  }
+  });
+});
+
+test("DatabaseRuntimeServiceProvider resolves knex config from DATABASE_URL when DB_* vars are omitted", async () => {
+  await withAppRootKnexStub(async () => {
+    const app = createSingletonApp();
+    app.instance("runtime.database.driver.mysql", Object.freeze({ DIALECT_ID: "mysql2" }));
+    app.instance(KERNEL_TOKENS.Env, {
+      DATABASE_URL: "mysql://urluser:urlpass@db.url.local:3308/url_db_name"
+    });
+
+    const provider = new DatabaseRuntimeServiceProvider();
+    provider.register(app);
+
+    const knex = app.make(KERNEL_TOKENS.Knex);
+    assert.equal(knex.__source, "app-root-knex");
+    assert.equal(knex.__config.client, "mysql2");
+    assert.equal(knex.__config.connection.host, "db.url.local");
+    assert.equal(knex.__config.connection.port, 3308);
+    assert.equal(knex.__config.connection.database, "url_db_name");
+    assert.equal(knex.__config.connection.user, "urluser");
+    assert.equal(knex.__config.connection.password, "urlpass");
+  });
 });