dbopt-engine 0.2.0 → 0.3.0

package/.env.example

@@ -6,7 +6,7 @@ DATABASE_URL=postgres://postgres:changeme@localhost:5432/mydb
 # Multiple databases (uncomment; commas in passwords must be encoded as %2C):
 # DATABASE_URL=postgres://user:pass@host1:5432/appdb,mysql://user:pass@host2:3306/shopdb
 
-PORT=8000
+PORT=1305
 SCAN_INTERVAL_MINUTES=15
 MIN_ROWS_FOR_SEQ_SCAN_FLAG=1000
 MIN_IMPROVEMENT_PCT_TO_RECOMMEND=30

package/README.md

@@ -24,7 +24,7 @@ the variables below (copy `.env.example` from the package as a template):
 ```bash
 # one database — or several, comma-separated (see "Multiple databases")
 DATABASE_URL=mysql://user:password@host:3306/mydb
-PORT=8000
+PORT=1305
 SCAN_INTERVAL_MINUTES=15
 MIN_ROWS_FOR_SEQ_SCAN_FLAG=1000
 MIN_IMPROVEMENT_PCT_TO_RECOMMEND=30
@@ -41,8 +41,8 @@ Then start it:
 
 ```bash
 dbopt
-# dashboard: http://localhost:8000/dashboard
-# topology:  http://localhost:8000/topology
+# dashboard: http://localhost:1305/dashboard
+# topology:  http://localhost:1305/topology
 ```
 
 Or per-project:
@@ -55,6 +55,34 @@ npx dbopt-engine
 
 If any variable is missing, startup fails with a list of what's not set.
 
+## Embed in your backend (share its port)
+
+Instead of running dbopt as a separate process on its own port, you can mount
+it inside an existing Express app — the same way `swagger-ui-express` serves
+docs on your API's port:
+
+```js
+const express = require("express");
+const dbopt = require("dbopt-engine");
+
+const app = express();
+// ... your own routes ...
+
+await dbopt.attach(app);                        // mounts under /dbopt
+// or: await dbopt.attach(app, { prefix: "/optimizer" });
+
+app.listen(4000);
+// dashboard: http://localhost:4000/dbopt/dashboard
+// topology:  http://localhost:4000/dbopt/topology
+```
+
+`attach()` mounts all routes and dashboards under the prefix, connects to the
+configured targets, and starts the analysis scheduler. Configuration still
+comes from environment variables / `.env` (`PORT` is ignored in this mode —
+the host app owns the port). For finer control, `createApp()` returns the bare
+Express app without starting the engine, and `startEngine()` starts the
+scheduler on its own.
+
 ## Connection strings
 
 The scheme picks the engine; the port is optional (engine default is used):
@@ -91,7 +119,7 @@ override the ones that have one — flags win).
 | Flag | Env var | Suggested value | Meaning |
 |---|---|---|---|
 | `--database-url` | `DATABASE_URL` | — | one or more comma-separated connection strings |
-| `--port` | `PORT` | 8000 | HTTP port for dashboard/API |
+| `--port` | `PORT` | 1305 | HTTP port for dashboard/API |
 | `--scan-interval` | `SCAN_INTERVAL_MINUTES` | 15 | minutes between analysis cycles |
 | `--auto-create` | `AUTO_CREATE_INDEXES` | true | create verified indexes automatically |
 | `--auto-drop` | `AUTO_DROP_UNUSED_INDEXES` | false | drop unused indexes automatically |

package/bin/cli.js

@@ -2,7 +2,7 @@
 "use strict";
 
 /* Simple CLI: flags map onto env vars before config loads.
- *   dbopt --database-url mysql://u:p@host:3306/db --port 8000
+ *   dbopt --database-url mysql://u:p@host:3306/db --port 1305
  */
 const args = process.argv.slice(2);
 const FLAG_TO_ENV = {
@@ -26,7 +26,7 @@ Usage:
 Options:
   --database-url <urls>   postgres:// | mysql:// | sqlserver:// connection string;
                           comma-separate several to watch multiple databases
-  --port <n>              HTTP port for dashboard/API (default 8000)
+  --port <n>              HTTP port for dashboard/API (default 1305)
   --scan-interval <min>   analysis cycle interval in minutes (default 15)
   --auto-create <bool>    create verified indexes automatically (default true)
   --auto-drop <bool>      drop unused indexes automatically (default false)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbopt-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Self-optimizing database engine: watches real query traffic, verifies missing indexes before creating them, drops unused ones, with a live dashboard and schema topology explorer. PostgreSQL, MySQL 8, SQL Server.",
   "license": "MIT",
   "author": "Evvo Technology <dev@evvotechnology.com>",

package/src/config.js

@@ -46,7 +46,7 @@ const REQUIRED_VARS = [
 }
 
 const settings = {
-  httpPort: parseInt(env("PORT", "8000"), 10),
+  httpPort: parseInt(env("PORT", "1305"), 10),
   scanIntervalMinutes: parseInt(env("SCAN_INTERVAL_MINUTES", "15"), 10),
   minRowsForSeqScanFlag: parseInt(env("MIN_ROWS_FOR_SEQ_SCAN_FLAG", "1000"), 10),
   minImprovementPct: parseFloat(env("MIN_IMPROVEMENT_PCT_TO_RECOMMEND", "30")),

package/src/index.js

@@ -32,10 +32,30 @@ function createApp() {
   };
   app.get("/dashboard", page("dashboard.html"));
   app.get("/topology", page("topology.html"));
-  app.get("/", (req, res) => res.redirect("/dashboard"));
+  // req.baseUrl carries the mount prefix when embedded in a host app.
+  app.get("/", (req, res) => res.redirect(`${req.baseUrl}/dashboard`));
   return app;
 }
 
+/** Connect to the targets and begin the analysis loop (no HTTP server). */
+async function startEngine() {
+  for (const t of targets) await t.adapter.ensurePrerequisites(t);
+  startScheduler();
+  runAnalysisCycle(); // immediate first cycle, like the Python edition
+}
+
+/** Embed the optimizer in a host Express app, sharing its port:
+ *    const dbopt = require("dbopt-engine");
+ *    await dbopt.attach(app);                      // routes under /dbopt
+ *    await dbopt.attach(app, { prefix: "/opt" });  // or a custom prefix
+ *  Dashboard: <prefix>/dashboard · Topology: <prefix>/topology */
+async function attach(app, { prefix = "/dbopt" } = {}) {
+  const sub = createApp();
+  app.use(prefix, sub);
+  await startEngine();
+  return sub;
+}
+
 async function start() {
   const app = createApp();
   app.listen(settings.httpPort, () => {
@@ -46,10 +66,8 @@ async function start() {
     console.log(`  dashboard: http://localhost:${settings.httpPort}/dashboard`);
     console.log(`  topology:  http://localhost:${settings.httpPort}/topology`);
   });
-  for (const t of targets) await t.adapter.ensurePrerequisites(t);
-  startScheduler();
-  runAnalysisCycle(); // immediate first cycle, like the Python edition
+  await startEngine();
   return app;
 }
 
-module.exports = { createApp, start };
+module.exports = { createApp, attach, startEngine, start };

package/src/static/dashboard.html

@@ -366,7 +366,13 @@ for (const el of document.querySelectorAll(".info[data-tip]")) {
 // Every API call is scoped to the database picked in the header selector
 // (?db=<name>); without it the server uses its first configured target.
 const DB = new URLSearchParams(location.search).get("db");
-const withDb = (url) => DB ? url + (url.includes("?") ? "&" : "?") + "db=" + encodeURIComponent(DB) : url;
+// When the app is mounted inside a host server (e.g. at /dbopt), API calls
+// must carry that prefix; derive it from this page's own path.
+const BASE = location.pathname.replace(/\/(dashboard|topology)\/?$/, "");
+const withDb = (url) => {
+  const u = BASE + url;
+  return DB ? u + (u.includes("?") ? "&" : "?") + "db=" + encodeURIComponent(DB) : u;
+};
 async function getJSON(url) {
   const res = await fetch(withDb(url));
   if (!res.ok) throw new Error(url + " -> HTTP " + res.status);
@@ -375,8 +381,8 @@ async function getJSON(url) {
 
 async function initDbSelect() {
   try {
-    const ts = await getJSON("/targets");
     $("#topo-link").href = withDb("/topology");
+    const ts = await getJSON("/targets");
     if (ts.length < 2) return;
     const sel = $("#db-select");
     const current = DB || ts[0].name;

package/src/static/topology.html

@@ -363,7 +363,13 @@ const history = [];
 // Every API call is scoped to the database picked in the toolbar selector
 // (?db=<name>); without it the server uses its first configured target.
 const DB = new URLSearchParams(location.search).get("db");
-const withDb = (url) => DB ? url + (url.includes("?") ? "&" : "?") + "db=" + encodeURIComponent(DB) : url;
+// When the app is mounted inside a host server (e.g. at /dbopt), API calls
+// must carry that prefix; derive it from this page's own path.
+const BASE = location.pathname.replace(/\/(dashboard|topology)\/?$/, "");
+const withDb = (url) => {
+  const u = BASE + url;
+  return DB ? u + (u.includes("?") ? "&" : "?") + "db=" + encodeURIComponent(DB) : u;
+};
 async function getJSON(url, opts) {
   const r = await fetch(withDb(url), opts);
   if (!r.ok) throw new Error((await r.json().catch(() => ({}))).detail || r.status);
@@ -372,8 +378,8 @@ async function getJSON(url, opts) {
 
 async function initDbSelect() {
   try {
-    const ts = await getJSON("/targets");
     $("#dash-link").href = withDb("/dashboard");
+    const ts = await getJSON("/targets");
     if (ts.length < 2) return;
     const sel = $("#db-select");
     const current = DB || ts[0].name;