dbopt-engine 0.2.0

package/src/adapters/mysql.js

@@ -0,0 +1,177 @@
+"use strict";
+/** MySQL 8 adapter: performance_schema + EXPLAIN FORMAT=JSON + INVISIBLE
+ *  index verification. FK-required and FULLTEXT indexes are protected. */
+const mysql = require("mysql2/promise");
+const { calcImprovementPct } = require("../planParser");
+
+const engine = "mysql";
+const supportsPartialIndexes = false;
+
+const connect = (target) => mysql.createConnection({
+  host: target.host, port: target.port, database: target.database,
+  user: target.user, password: target.password,
+});
+const close = (c) => c.end().catch(() => {});
+const ping = async (c) => { await c.query("SELECT 1"); };
+
+async function ensurePrerequisites(target) {
+  const status = { checked: true, performance_schema: false, actions_needed: [] };
+  let c;
+  try {
+    c = await connect(target);
+    const [[row]] = await c.query("SELECT @@performance_schema AS ps");
+    if (row.ps === 1) status.performance_schema = true;
+    else status.actions_needed.push(
+      "performance_schema is OFF. Set performance_schema=ON in my.cnf and restart MySQL.");
+  } catch (e) {
+    status.actions_needed.push(`Could not connect to the target database: ${e.message}`);
+  } finally { if (c) close(c); }
+  Object.assign(target.prerequisites, status);
+  return status;
+}
+
+async function getSlowQueries(c, minCalls = 1, limit = 30) {
+  const [rows] = await c.query(`
+    SELECT DIGEST AS queryid, DIGEST_TEXT AS query, COUNT_STAR AS calls,
+           AVG_TIMER_WAIT / 1e9 AS mean_exec_time, SUM_TIMER_WAIT / 1e9 AS total_exec_time,
+           SUM_ROWS_SENT AS \`rows\`
+    FROM performance_schema.events_statements_summary_by_digest
+    WHERE SCHEMA_NAME = DATABASE() AND COUNT_STAR >= ?
+      AND DIGEST_TEXT NOT LIKE 'EXPLAIN%' AND DIGEST_TEXT NOT LIKE 'CREATE%'
+      AND DIGEST_TEXT NOT LIKE 'DROP%' AND DIGEST_TEXT NOT LIKE 'ALTER%'
+      AND DIGEST_TEXT NOT LIKE 'INSERT%' AND DIGEST_TEXT NOT LIKE 'SET %'
+      AND DIGEST_TEXT NOT LIKE '%performance_schema%' AND DIGEST_TEXT NOT LIKE '%information_schema%'
+    ORDER BY AVG_TIMER_WAIT DESC LIMIT ?;`, [minCalls, limit]);
+  return rows.map(r => ({ ...r, calls: Number(r.calls), mean_exec_time: Number(r.mean_exec_time),
+    total_exec_time: Number(r.total_exec_time), rows: Number(r.rows) }));
+}
+
+async function getUnusedIndexes(c, target) {
+  const [rows] = await c.query(`
+    SELECT p.OBJECT_NAME AS table_name, p.INDEX_NAME AS index_name, p.COUNT_STAR AS idx_scan,
+           GROUP_CONCAT(s.COLUMN_NAME ORDER BY s.SEQ_IN_INDEX) AS columns_list
+    FROM performance_schema.table_io_waits_summary_by_index_usage p
+    JOIN information_schema.STATISTICS s
+      ON s.TABLE_SCHEMA = p.OBJECT_SCHEMA AND s.TABLE_NAME = p.OBJECT_NAME
+     AND s.INDEX_NAME = p.INDEX_NAME
+    WHERE p.OBJECT_SCHEMA = DATABASE() AND p.INDEX_NAME IS NOT NULL
+      AND p.INDEX_NAME <> 'PRIMARY' AND p.COUNT_STAR = 0 AND s.NON_UNIQUE = 1
+      AND s.INDEX_TYPE = 'BTREE'
+      AND NOT EXISTS (
+        SELECT 1 FROM information_schema.STATISTICS s1
+        JOIN information_schema.KEY_COLUMN_USAGE k
+          ON k.TABLE_SCHEMA = s1.TABLE_SCHEMA AND k.TABLE_NAME = s1.TABLE_NAME
+         AND k.COLUMN_NAME = s1.COLUMN_NAME AND k.REFERENCED_TABLE_NAME IS NOT NULL
+        WHERE s1.TABLE_SCHEMA = p.OBJECT_SCHEMA AND s1.TABLE_NAME = p.OBJECT_NAME
+          AND s1.INDEX_NAME = p.INDEX_NAME AND s1.SEQ_IN_INDEX = 1)
+    GROUP BY p.OBJECT_NAME, p.INDEX_NAME, p.COUNT_STAR;`);
+  const out = [];
+  for (const r of rows) {
+    let size = 0;
+    try {
+      const [[sz]] = await c.query(
+        `SELECT stat_value * @@innodb_page_size AS b FROM mysql.innodb_index_stats
+         WHERE database_name = DATABASE() AND table_name = ? AND index_name = ? AND stat_name = 'size'`,
+        [r.table_name, r.index_name]);
+      size = sz ? Number(sz.b) : 0;
+    } catch { /* size is cosmetic */ }
+    out.push({ schemaname: target.database, table_name: r.table_name, index_name: r.index_name,
+      idx_scan: Number(r.idx_scan), size_bytes: size,
+      indexdef: `CREATE INDEX ${r.index_name} ON ${r.table_name} (${r.columns_list})` });
+  }
+  return out;
+}
+
+async function getAllIndexesForTable(c, table) {
+  const [rows] = await c.query(`
+    SELECT INDEX_NAME AS n, GROUP_CONCAT(COLUMN_NAME ORDER BY SEQ_IN_INDEX) AS cols
+    FROM information_schema.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? GROUP BY INDEX_NAME;`, [table]);
+  return rows.map(r => ({ indexname: r.n, indexdef: `INDEX ${r.n} ON ${table} (${r.cols})` }));
+}
+
+function prettySize(b) {
+  for (const u of ["bytes", "kB", "MB", "GB"]) {
+    if (b < 1024) return `${Math.round(b)} ${u}`;
+    b /= 1024;
+  }
+  return `${Math.round(b)} TB`;
+}
+
+async function getTableGrowthStats(c) {
+  const [rows] = await c.query(`
+    SELECT TABLE_NAME AS table_name, COALESCE(TABLE_ROWS, 0) AS live_rows,
+           COALESCE(DATA_LENGTH, 0) + COALESCE(INDEX_LENGTH, 0) AS total_size_bytes
+    FROM information_schema.TABLES
+    WHERE TABLE_SCHEMA = DATABASE() AND TABLE_TYPE = 'BASE TABLE'
+    ORDER BY total_size_bytes DESC;`);
+  return rows.map(r => ({
+    table_name: r.table_name, live_rows: Number(r.live_rows), dead_rows: 0,
+    total_size: prettySize(Number(r.total_size_bytes)),
+    total_size_bytes: Number(r.total_size_bytes), seq_scan: 0, idx_scan: 0,
+  }));
+}
+
+const substitute = (q, asString) =>
+  q.replace(/\.\.\./g, "?").replace(/\?/g, asString ? "'1'" : "1");
+
+function walkTables(node, out) {
+  if (node && typeof node === "object") {
+    if (!Array.isArray(node) && node.access_type !== undefined && node.table_name !== undefined) out.push(node);
+    for (const v of Object.values(node)) walkTables(v, out);
+  }
+  return out;
+}
+
+async function explainJson(c, safeQuery) {
+  const [rows] = await c.query(`EXPLAIN FORMAT=JSON ${safeQuery}`);
+  return JSON.parse(rows[0].EXPLAIN);
+}
+
+async function analyzeQuery(c, queryText, minRows) {
+  for (const asString of [false, true]) {
+    const safeQuery = substitute(queryText, asString);
+    let explained;
+    try { explained = await explainJson(c, safeQuery); } catch { continue; }
+    const qb = explained.query_block || {};
+    const oldCost = parseFloat(qb.cost_info?.query_cost) || null;
+    const findings = [];
+    for (const t of walkTables(qb, [])) {
+      if (t.access_type !== "ALL") continue;
+      const rows = t.rows_examined_per_scan || 0;
+      if (rows <= minRows) continue;
+      let filter = (t.attached_condition || "").replace(/`/g, "");
+      filter = filter.replace(/\b\w+\.(\w+\.)?/g, "");
+      findings.push({ table: t.table_name, filter: filter || null, rows_scanned: rows, cost: null });
+    }
+    return { oldCost, findings, safeQuery };
+  }
+  return { oldCost: null, findings: [], safeQuery: null };
+}
+
+async function verifyIndexBenefit(c, safeQuery, table, columns, predicate, oldCost) {
+  const { indexNameFor, validateIdentifier } = require("../executor");
+  if (predicate) throw new Error("MySQL does not support partial indexes");
+  validateIdentifier(table);
+  columns.forEach(validateIdentifier);
+  const indexName = indexNameFor(engine, table, columns);
+  let created = false;
+  try {
+    await c.query(`CREATE INDEX ${indexName} ON ${table} (${columns.join(", ")}) INVISIBLE`);
+    created = true;
+    await c.query("SET SESSION optimizer_switch = 'use_invisible_indexes=on'");
+    const plan = await explainJson(c, safeQuery);
+    const newCost = parseFloat(plan.query_block?.cost_info?.query_cost) || oldCost;
+    return { improvement: calcImprovementPct(oldCost, newCost), newCost };
+  } finally {
+    await c.query("SET SESSION optimizer_switch = 'use_invisible_indexes=off'").catch(() => {});
+    if (created) await c.query(`DROP INDEX ${indexName} ON ${table}`).catch(() => {});
+  }
+}
+
+module.exports = {
+  engine, supportsPartialIndexes,
+  connect, close, ping, ensurePrerequisites,
+  getSlowQueries, getUnusedIndexes, getAllIndexesForTable, getTableGrowthStats,
+  analyzeQuery, verifyIndexBenefit,
+};

package/src/adapters/postgres.js

@@ -0,0 +1,137 @@
+"use strict";
+/** PostgreSQL adapter: pg_stat_statements + EXPLAIN ANALYZE + HypoPG. */
+const { Client } = require("pg");
+const { calcImprovementPct } = require("../planParser");
+
+const engine = "postgres";
+const supportsPartialIndexes = true;
+
+async function connect(target) {
+  const c = new Client({
+    host: target.host, port: target.port, database: target.database,
+    user: target.user, password: target.password,
+  });
+  await c.connect();
+  return c;
+}
+const close = (c) => c.end().catch(() => {});
+const ping = async (c) => { await c.query("SELECT 1"); };
+
+async function ensurePrerequisites(target) {
+  const status = { checked: true, pg_stat_statements: false, hypopg: false, actions_needed: [] };
+  let c;
+  try {
+    c = await connect(target);
+    for (const ext of ["pg_stat_statements", "hypopg"]) {
+      try { await c.query(`CREATE EXTENSION IF NOT EXISTS ${ext};`); }
+      catch (e) {
+        const msg = String(e.message).split("\n")[0];
+        status.actions_needed.push(
+          /is not available|extension control file/.test(msg)
+            ? `Extension '${ext}' is not installed on the server. Install the OS package and restart.`
+            : `Could not create extension '${ext}': ${msg}`);
+      }
+    }
+    try { await c.query("SELECT count(*) FROM pg_stat_statements;"); status.pg_stat_statements = true; }
+    catch { status.actions_needed.push(
+      "pg_stat_statements needs preloading: ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements'; then restart PostgreSQL."); }
+    try { await c.query("SELECT hypopg_reset();"); status.hypopg = true; }
+    catch { if (!status.actions_needed.some(a => a.includes("hypopg")))
+      status.actions_needed.push("hypopg extension exists but is not functional."); }
+  } catch (e) {
+    status.actions_needed.push(`Could not connect to the target database: ${e.message}`);
+  } finally { if (c) close(c); }
+  Object.assign(target.prerequisites, status);
+  return status;
+}
+
+async function getSlowQueries(c, minCalls = 1, limit = 30) {
+  const { rows } = await c.query(`
+    SELECT queryid, query, calls, mean_exec_time, total_exec_time, rows
+    FROM pg_stat_statements
+    WHERE calls >= $1
+      AND dbid = (SELECT oid FROM pg_database WHERE datname = current_database())
+      AND query NOT ILIKE '%pg_stat_statements%' AND query NOT ILIKE 'EXPLAIN%'
+      AND query NOT ILIKE 'CREATE%' AND query NOT ILIKE 'DROP%'
+      AND query NOT ILIKE 'ALTER%' AND query NOT ILIKE 'INSERT%' AND query NOT ILIKE 'DO %'
+    ORDER BY mean_exec_time DESC LIMIT $2;`, [minCalls, limit]);
+  return rows;
+}
+
+async function getUnusedIndexes(c, target) {
+  const { rows } = await c.query(`
+    SELECT s.schemaname, s.relname AS table_name, s.indexrelname AS index_name,
+           s.idx_scan, pg_relation_size(s.indexrelid) AS size_bytes, pi.indexdef
+    FROM pg_stat_user_indexes s
+    JOIN pg_index i ON s.indexrelid = i.indexrelid
+    JOIN pg_indexes pi ON pi.indexname = s.indexrelname
+    WHERE s.idx_scan = 0 AND NOT i.indisunique AND NOT i.indisprimary
+    ORDER BY pg_relation_size(s.indexrelid) DESC;`);
+  return rows.map(r => ({ ...r, size_bytes: Number(r.size_bytes), idx_scan: Number(r.idx_scan) }));
+}
+
+async function getAllIndexesForTable(c, table) {
+  const { rows } = await c.query(
+    "SELECT indexname, indexdef FROM pg_indexes WHERE tablename = $1;", [table]);
+  return rows;
+}
+
+async function getTableGrowthStats(c) {
+  const { rows } = await c.query(`
+    SELECT relname AS table_name, n_live_tup AS live_rows, n_dead_tup AS dead_rows,
+           pg_size_pretty(pg_total_relation_size(relid)) AS total_size,
+           pg_total_relation_size(relid) AS total_size_bytes,
+           seq_scan, COALESCE(idx_scan, 0) AS idx_scan
+    FROM pg_stat_user_tables ORDER BY pg_total_relation_size(relid) DESC;`);
+  return rows.map(r => ({ ...r, live_rows: Number(r.live_rows), dead_rows: Number(r.dead_rows),
+    total_size_bytes: Number(r.total_size_bytes), seq_scan: Number(r.seq_scan), idx_scan: Number(r.idx_scan) }));
+}
+
+const substitute = (q, asString) => q.replace(/\$\d+/g, asString ? "'1'" : "1");
+
+function findSeqScans(node, out, minRows) {
+  if (["Seq Scan", "Parallel Seq Scan"].includes(node["Node Type"])) {
+    const scanned = (node["Actual Rows"] || 0) + (node["Rows Removed by Filter"] || 0);
+    if (scanned > minRows) out.push({
+      table: node["Relation Name"], filter: node["Filter"] || null,
+      rows_scanned: scanned, cost: node["Total Cost"],
+    });
+  }
+  for (const child of node.Plans || []) findSeqScans(child, out, minRows);
+  return out;
+}
+
+async function analyzeQuery(c, queryText, minRows) {
+  for (const asString of [false, true]) {
+    const safeQuery = substitute(queryText, asString);
+    try {
+      const { rows } = await c.query(`EXPLAIN (ANALYZE, FORMAT JSON) ${safeQuery}`);
+      const plan = rows[0]["QUERY PLAN"][0].Plan;
+      return { oldCost: plan["Total Cost"], findings: findSeqScans(plan, [], minRows), safeQuery };
+    } catch { await c.query("ROLLBACK").catch(() => {}); }
+  }
+  return { oldCost: null, findings: [], safeQuery: null };
+}
+
+async function verifyIndexBenefit(c, safeQuery, table, columns, predicate, oldCost) {
+  const { predicateToSql, validateIdentifier } = require("../executor");
+  validateIdentifier(table);
+  columns.forEach(validateIdentifier);
+  let create = `CREATE INDEX ON ${table} (${columns.join(", ")})`;
+  if (predicate) create += ` WHERE ${predicateToSql(predicate)}`;
+  try {
+    await c.query("SELECT * FROM hypopg_create_index($1)", [create]);
+    const { rows } = await c.query(`EXPLAIN (FORMAT JSON) ${safeQuery}`);
+    const newCost = rows[0]["QUERY PLAN"][0].Plan["Total Cost"] ?? oldCost;
+    return { improvement: calcImprovementPct(oldCost, newCost), newCost };
+  } finally {
+    await c.query("SELECT hypopg_reset();").catch(() => {});
+  }
+}
+
+module.exports = {
+  engine, supportsPartialIndexes,
+  connect, close, ping, ensurePrerequisites,
+  getSlowQueries, getUnusedIndexes, getAllIndexesForTable, getTableGrowthStats,
+  analyzeQuery, verifyIndexBenefit,
+};

package/src/config.js

@@ -0,0 +1,140 @@
+"use strict";
+require("dotenv").config();
+
+const SCHEME_TO_ENGINE = {
+  postgres: "postgres", postgresql: "postgres",
+  mysql: "mysql", mariadb: "mysql",
+  mssql: "mssql", sqlserver: "mssql",
+  oracle: "oracle", mongodb: "mongodb", mongo: "mongodb",
+};
+const DEFAULT_PORTS = { postgres: 5432, mysql: 3306, mssql: 1433, oracle: 1521, mongodb: 27017 };
+
+function env(name, fallback) {
+  const v = process.env[name];
+  return v === undefined || v === "" ? fallback : v;
+}
+const bool = (v) => String(v).toLowerCase() === "true";
+
+// Every setting must be provided explicitly — via a .env file in the working
+// directory, real environment variables, or the matching CLI flag.
+const REQUIRED_VARS = [
+  "DATABASE_URL",
+  "PORT",
+  "SCAN_INTERVAL_MINUTES",
+  "MIN_ROWS_FOR_SEQ_SCAN_FLAG",
+  "MIN_IMPROVEMENT_PCT_TO_RECOMMEND",
+  "AUTO_CREATE_INDEXES",
+  "AUTO_DROP_UNUSED_INDEXES",
+  "INDEX_NAME_PREFIX",
+  "UNUSED_INDEX_GRACE_MINUTES",
+  "REAPPLY_COOLDOWN_MINUTES",
+  "STORAGE_LIMIT_MB",
+  "STATE_DB_PATH",
+];
+{
+  const missing = REQUIRED_VARS.filter((n) => env(n) === undefined);
+  if (missing.length) {
+    console.error(
+      `dbopt: missing required environment variables:\n` +
+      missing.map((n) => `  - ${n}`).join("\n") +
+      `\n\nCreate a .env file in the directory you run dbopt from,\n` +
+      `defining all of them (copy .env.example from the package for a template):\n` +
+      `  node_modules/dbopt-engine/.env.example`
+    );
+    process.exit(1);
+  }
+}
+
+const settings = {
+  httpPort: parseInt(env("PORT", "8000"), 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")),
+  autoCreateIndexes: bool(env("AUTO_CREATE_INDEXES", "true")),
+  autoDropUnusedIndexes: bool(env("AUTO_DROP_UNUSED_INDEXES", "false")),
+  indexNamePrefix: env("INDEX_NAME_PREFIX", "opt"),
+  unusedIndexGraceMinutes: parseInt(env("UNUSED_INDEX_GRACE_MINUTES", "60"), 10),
+  reapplyCooldownMinutes: parseInt(env("REAPPLY_COOLDOWN_MINUTES", "60"), 10),
+  storageLimitMb: parseInt(env("STORAGE_LIMIT_MB", "0"), 10),
+  historyRetentionDays: parseInt(env("HISTORY_RETENTION_DAYS", "90"), 10),
+  stateDbPath: env("STATE_DB_PATH", "optimizer_state.db"),
+  targets: [],
+};
+
+/** Parse one connection URL: engine://user:pass@host:port/db, plus the
+ *  ADO-style variant engine://host:port;database=..;user=..;password=..  */
+function parseDatabaseUrl(url) {
+  url = url.trim().replace(/^["']|["']$/g, "");
+  const sep = url.indexOf("://");
+  if (sep < 0) throw new Error("DATABASE_URL must look like engine://user:pass@host:port/dbname");
+  const scheme = url.slice(0, sep).toLowerCase();
+  const rest = url.slice(sep + 3);
+  const engine = SCHEME_TO_ENGINE[scheme];
+  if (!engine) throw new Error(`Unknown DATABASE_URL scheme '${scheme}'`);
+
+  const t = {
+    dbEngine: engine,
+    host: env("TARGET_DB_HOST", ""),
+    port: 0,
+    database: env("TARGET_DB_NAME", ""),
+    user: env("TARGET_DB_USER", ""),
+    password: env("TARGET_DB_PASSWORD", ""),
+  };
+
+  if (rest.includes(";")) {
+    const [hostPart, ...params] = rest.split(";");
+    const [host, port] = hostPart.split(":");
+    const kv = {};
+    for (const p of params) {
+      const eq = p.indexOf("=");
+      if (eq > 0) kv[p.slice(0, eq).trim().toLowerCase()] = p.slice(eq + 1).trim();
+    }
+    t.host = host;
+    t.port = parseInt(port || kv.port || DEFAULT_PORTS[engine], 10);
+    t.database = kv.database || kv.dbname || t.database;
+    t.user = kv.user || kv.uid || kv.username || t.user;
+    t.password = kv.password || kv.pwd || t.password;
+  } else {
+    const u = new URL(`${scheme === "mongodb" ? "mongodb" : "http"}://${rest}`);
+    t.host = u.hostname;
+    t.port = u.port ? parseInt(u.port, 10) : DEFAULT_PORTS[engine];
+    t.database = decodeURIComponent(u.pathname.replace(/^\//, ""));
+    if (u.username) t.user = decodeURIComponent(u.username);
+    if (u.password) t.password = decodeURIComponent(u.password);
+  }
+  if (!t.database) throw new Error(`DATABASE_URL '${scheme}://…' is missing the database name (/dbname)`);
+  if (!t.port) t.port = DEFAULT_PORTS[engine] || 5432;
+  return t;
+}
+
+/* DATABASE_URL holds one or more comma-separated connection URLs, so one
+ * process can watch several databases at once. Commas inside passwords must
+ * be URL-encoded as %2C (like the other special characters). */
+const urls = String(process.env.DATABASE_URL).split(",").map((s) => s.trim()).filter(Boolean);
+if (!urls.length) {
+  console.error("dbopt: DATABASE_URL is empty — set at least one connection URL.");
+  process.exit(1);
+}
+settings.targets = urls.map(parseDatabaseUrl);
+
+/* Give each target a stable, human-friendly name for the API (?db=<name>)
+ * and the dashboard selector: the database name, disambiguated by host and
+ * port only when two targets share it. */
+{
+  const count = (fn) => settings.targets.reduce((m, t) => {
+    const k = fn(t); m[k] = (m[k] || 0) + 1; return m;
+  }, {});
+  const byDb = count((t) => t.database);
+  const byDbHost = count((t) => `${t.database}@${t.host}`);
+  const seen = {};
+  for (const t of settings.targets) {
+    let name = t.database;
+    if (byDb[t.database] > 1) name = `${t.database}@${t.host}`;
+    if (byDbHost[`${t.database}@${t.host}`] > 1) name = `${t.database}@${t.host}:${t.port}`;
+    if (seen[name]) name += `-${++seen[name]}`;
+    else seen[name] = 1;
+    t.name = name;
+  }
+}
+
+module.exports = { settings };

package/src/executor.js

@@ -0,0 +1,127 @@
+"use strict";
+/** Builds and executes index DDL with identifier validation; every action is
+ *  recorded with rollback SQL. All functions are scoped to one target. */
+const { settings } = require("./config");
+
+const SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const MAX_IDENTIFIER = { postgres: 63, mysql: 64, mssql: 128 };
+
+function validateIdentifier(name) {
+  if (!name || !SAFE_IDENTIFIER.test(name)) {
+    throw new Error(`Unsafe identifier rejected: ${JSON.stringify(name)}`);
+  }
+}
+
+function indexNameFor(engine, table, columns, partial = false) {
+  let name = `${settings.indexNamePrefix}_idx_${table}_${columns.join("_")}`;
+  if (partial) name += "_part";
+  return name.slice(0, MAX_IDENTIFIER[engine] || 63);
+}
+
+function predicateToSql(predicate) {
+  validateIdentifier(predicate.column || "");
+  if (predicate.op === "IS NOT NULL") return `${predicate.column} IS NOT NULL`;
+  if (predicate.op === "=" && ["true", "false"].includes(predicate.value)) {
+    return `${predicate.column} = ${predicate.value}`;
+  }
+  throw new Error(`Unsupported partial-index predicate: ${JSON.stringify(predicate)}`);
+}
+
+function buildSqlForRecommendation(target, rec) {
+  validateIdentifier(rec.table);
+  const engine = target.dbEngine;
+  const prefixNote = `The ${settings.indexNamePrefix}_ name prefix keeps this index outside any ORM/migration namespace.`;
+
+  if (rec.type === "missing_index") {
+    const columns = rec.detail.columns;
+    columns.forEach(validateIdentifier);
+    const predicate = rec.detail.predicate || null;
+    const colList = columns.join(", ");
+
+    if (engine === "mysql" || engine === "mssql") {
+      if (predicate) throw new Error("Partial indexes are Postgres-only");
+      const indexName = indexNameFor(engine, rec.table, columns);
+      validateIdentifier(indexName);
+      return {
+        index_name: indexName,
+        apply_sql: `CREATE INDEX ${indexName} ON ${rec.table} (${colList});`,
+        rollback_sql: `DROP INDEX ${indexName} ON ${rec.table};`,
+        notes: (engine === "mysql"
+          ? "InnoDB online DDL builds the index without locking the table. "
+          : "On Enterprise/Azure use WITH (ONLINE = ON) for fully non-blocking builds. ") + prefixNote,
+      };
+    }
+    const where = predicate ? ` WHERE ${predicateToSql(predicate)}` : "";
+    const indexName = indexNameFor(engine, rec.table, columns, !!predicate);
+    validateIdentifier(indexName);
+    return {
+      index_name: indexName,
+      apply_sql: `CREATE INDEX CONCURRENTLY IF NOT EXISTS ${indexName} ON ${rec.table} (${colList})${where};`,
+      rollback_sql: `DROP INDEX CONCURRENTLY IF EXISTS ${indexName};`,
+      notes: "CONCURRENTLY avoids locking the table. " + prefixNote,
+    };
+  }
+
+  if (rec.type === "unused_index") {
+    const indexName = rec.detail.index_name;
+    validateIdentifier(indexName);
+    const rollback = rec.detail.original_index_definition ||
+      `-- Original definition not captured for ${indexName}.`;
+    const dropSql = engine === "postgres"
+      ? `DROP INDEX CONCURRENTLY IF EXISTS ${indexName};`
+      : `DROP INDEX ${indexName} ON ${rec.table};`;
+    return {
+      index_name: indexName,
+      apply_sql: dropSql,
+      rollback_sql: rollback,
+      notes: "Zero usage only reflects activity since the last stats reset / server start. " +
+             "The original definition is stored as rollback_sql so the drop is fully reversible.",
+    };
+  }
+  throw new Error(`Unknown recommendation type: ${rec.type}`);
+}
+
+async function execDdl(target, sqlText) {
+  const conn = await target.adapter.connect(target);
+  try {
+    if (target.adapter.engine === "mssql") await conn.request().batch(sqlText);
+    else await conn.query(sqlText);
+  } finally {
+    target.adapter.close(conn);
+  }
+}
+
+async function applyRecommendation(target, rec) {
+  try {
+    const built = buildSqlForRecommendation(target, rec);
+    await execDdl(target, built.apply_sql);
+    console.log(`[executor] [${target.name}] applied rec #${rec.id}: ${built.apply_sql}`);
+    target.store.updateDetail(rec.id, { ...rec.detail, index_name: built.index_name });
+    return target.store.markApplied(rec.id, built.apply_sql, built.rollback_sql);
+  } catch (e) {
+    console.error(`[executor] [${target.name}] failed rec #${rec.id}: ${e.message}`);
+    return target.store.markFailed(rec.id, e.message);
+  }
+}
+
+async function rollbackRecommendation(target, rec) {
+  let rollbackSql = rec.rollback_sql;
+  if (rec.status !== "applied" || !rollbackSql) {
+    throw new Error("Recommendation is not in an applied state with rollback SQL.");
+  }
+  if (rollbackSql.trimStart().startsWith("--")) {
+    throw new Error("No executable rollback SQL was captured for this recommendation.");
+  }
+  if (target.dbEngine === "postgres" && rec.type === "unused_index" &&
+      rollbackSql.toUpperCase().startsWith("CREATE INDEX ")) {
+    rollbackSql = "CREATE INDEX CONCURRENTLY " + rollbackSql.slice("CREATE INDEX ".length);
+  }
+  await execDdl(target, rollbackSql);
+  console.log(`[executor] [${target.name}] rolled back rec #${rec.id}`);
+  return target.store.updateStatus(rec.id, "rolled_back");
+}
+
+module.exports = {
+  validateIdentifier, indexNameFor, predicateToSql,
+  buildSqlForRecommendation, applyRecommendation, rollbackRecommendation,
+};

package/src/index.js

@@ -0,0 +1,55 @@
+"use strict";
+const path = require("path");
+const express = require("express");
+const { settings } = require("./config");
+const { targets, getTarget } = require("./targets");
+const { router } = require("./routes");
+const { topologyRouter } = require("./topology");
+const { runAnalysisCycle, startScheduler } = require("./scheduler");
+
+function createApp() {
+  const app = express();
+  app.use(express.json());
+
+  // Every API call is scoped to one target database, chosen with ?db=<name>
+  // (see GET /targets). Without the parameter the first target is used.
+  app.use((req, res, next) => {
+    req.target = getTarget(req.query.db);
+    if (!req.target) {
+      return res.status(404).json({
+        detail: `Unknown database '${req.query.db}'. Configured: ${targets.map((t) => t.name).join(", ")}`,
+      });
+    }
+    next();
+  });
+
+  app.use(router);
+  app.use(topologyRouter);
+
+  const page = (file) => (req, res) => {
+    res.set("Cache-Control", "no-store");
+    res.sendFile(path.join(__dirname, "static", file));
+  };
+  app.get("/dashboard", page("dashboard.html"));
+  app.get("/topology", page("topology.html"));
+  app.get("/", (req, res) => res.redirect("/dashboard"));
+  return app;
+}
+
+async function start() {
+  const app = createApp();
+  app.listen(settings.httpPort, () => {
+    console.log(`dbopt listening on http://localhost:${settings.httpPort}`);
+    for (const t of targets) {
+      console.log(`  target '${t.name}': ${t.dbEngine} · ${t.host}:${t.port}/${t.database}`);
+    }
+    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
+  return app;
+}
+
+module.exports = { createApp, start };

package/src/planParser.js

@@ -0,0 +1,35 @@
+"use strict";
+/** Shared filter-string parsing (engine adapters normalize their plan
+ *  predicates to "col = value" style strings before calling these). */
+
+const stripCasts = (s) => s.replace(/::\w+(\s+\w+)?/g, "");
+
+/** '(a = 1) AND (b = 2)' -> ['a','b'].  OR can't be served by one index ->
+ *  first column only. */
+function extractColumnsFromFilter(filterStr) {
+  if (!filterStr) return [];
+  const cleaned = stripCasts(filterStr);
+  const cols = [...cleaned.matchAll(/\(*\s*(\w+)\s*\)*\s*=/g)].map((m) => m[1]);
+  const unique = [...new Set(cols)];
+  return / OR /.test(cleaned) ? unique.slice(0, 1) : unique;
+}
+
+/** Detect filters that call for a partial index (Postgres only). */
+function extractPartialPredicate(filterStr) {
+  if (!filterStr) return null;
+  const cleaned = stripCasts(filterStr);
+  let m = cleaned.match(/(\w+)\s+IS NOT NULL/);
+  if (m) return { column: m[1], op: "IS NOT NULL" };
+  m = cleaned.match(/(\w+)\s*=\s*(true|false)\b/);
+  if (m) return { column: m[1], op: "=", value: m[2] };
+  m = cleaned.match(/(?<![A-Z] )NOT\s+\(?(\w+)/);
+  if (m) return { column: m[1], op: "=", value: "false" };
+  m = cleaned.match(/^\(*\s*(\w+)\s*\)*$/);
+  if (m) return { column: m[1], op: "=", value: "true" };
+  return null;
+}
+
+const calcImprovementPct = (oldCost, newCost) =>
+  !oldCost ? 0 : Math.round((1 - newCost / oldCost) * 1000) / 10;
+
+module.exports = { extractColumnsFromFilter, extractPartialPredicate, calcImprovementPct };