saltcorn-db-code 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# Saltcorn DB Code
+
+Saltcorn DB Code is a Saltcorn plugin for inspecting and managing PostgreSQL database code objects from the Saltcorn UI.
+
+- List functions and procedures in the current tenant schema.
+- View routine metadata.
+- View the full SQL definition returned by PostgreSQL.
+- Filter a shared routine list by function or stored procedure.
+- Create functions and stored procedures with structured forms and Saltcorn's code editor for the body.
+- Create routines from full DDL when you already have the exact PostgreSQL SQL.
+- Edit routines from their current PostgreSQL DDL.
+- Delete routines with confirmation and without default `CASCADE`.
+- Call routines from Saltcorn events/workflows through the `DB_Routine` action.
+- Restrict access to Saltcorn administrators.
+- Show a clear unsupported-database message on SQLite.
+
+TODO
+
+- Storeds as Action from triggers, callable from scheduled or API calls
+
+## Some Screenshots
+
+![Main screen](./screenshots/main.png)
+
+![New function screen](./screenshots/new_function.png)
+
+![Test functions screen](./screenshots/test_functions.png)
+
+
+## Local installation during development
+
+From the Saltcorn checkout:
+
+```bash
+cd /home/devgiu/dev/saltcorn
+./packages/saltcorn-cli/bin/saltcorn dev:localize-plugin db-code /home/devgiu/dev/saltcorn-db-code
+```
+
+After loading the plugin, create a Saltcorn view with the `DBCodeConsole` view pattern. This is the recommended entrypoint because it behaves like other Saltcorn plugin consoles and can be added to menus normally.
+
+Alternative direct route for development:
+
+```txt
+/db-code
+```
+
+Administrators can add either the created view URL, usually `/view/<view-name>`, or the direct `/db-code` route to a normal Saltcorn menu link.
+
+## Development commands
+
+```bash
+npm test
+npm run lint
+```
+
+## Scope
+
+The first milestone is read-only PostgreSQL routines. Creation, editing, deletion, execution, configuration, and additional database object types are tracked in `PLAN.md` and `docs/TODO.md`.

package/index.js

@@ -0,0 +1,41 @@
+const listRoute = require("./routes/list");
+const showRoute = require("./routes/show");
+const placeholder = require("./routes/placeholder");
+const { executeFormRoute, executePostRoute } = require("./routes/execute");
+const { createFormRoute, createPostRoute, createProcedureFormRoute, createProcedurePostRoute, createDdlFormRoute, createDdlPostRoute } = require("./routes/create");
+const { editFormRoute, editPostRoute } = require("./routes/edit");
+const { deleteFormRoute, deletePostRoute } = require("./routes/delete");
+const { generateRoutineSqlRoute } = require("./routes/ai");
+const { exportFormRoute, exportPostRoute } = require("./routes/export");
+const { importFormRoute, importPostRoute, importExecuteRoute } = require("./routes/import");
+const { DB_Routine } = require("./lib/db-routine-action");
+const dbCodeConsole = require("./viewtemplates/db-code-console");
+
+module.exports = {
+  sc_plugin_api_version: 1,
+  plugin_name: "db-code",
+  viewtemplates: [dbCodeConsole],
+  actions: { DB_Routine },
+  routes: [
+    { url: "/db-code", method: "get", callback: listRoute },
+    { url: "/db-code/routine/:oid", method: "get", callback: showRoute },
+    { url: "/db-code/new", method: "get", callback: createFormRoute },
+    { url: "/db-code/new", method: "post", callback: createPostRoute },
+    { url: "/db-code/new-procedure", method: "get", callback: createProcedureFormRoute },
+    { url: "/db-code/new-procedure", method: "post", callback: createProcedurePostRoute },
+    { url: "/db-code/new-ddl", method: "get", callback: createDdlFormRoute },
+    { url: "/db-code/new-ddl", method: "post", callback: createDdlPostRoute },
+    { url: "/db-code/routine/:oid/edit", method: "get", callback: editFormRoute },
+    { url: "/db-code/routine/:oid/edit", method: "post", callback: editPostRoute },
+    { url: "/db-code/routine/:oid/delete", method: "get", callback: deleteFormRoute },
+    { url: "/db-code/routine/:oid/delete", method: "post", callback: deletePostRoute },
+    { url: "/db-code/routine/:oid/execute", method: "get", callback: executeFormRoute },
+    { url: "/db-code/routine/:oid/execute", method: "post", callback: executePostRoute },
+    { url: "/db-code/ai/generate-sql", method: "post", callback: generateRoutineSqlRoute },
+    { url: "/db-code/export", method: "get", callback: exportFormRoute },
+    { url: "/db-code/export", method: "post", callback: exportPostRoute },
+    { url: "/db-code/import", method: "get", callback: importFormRoute },
+    { url: "/db-code/import", method: "post", callback: importPostRoute },
+    { url: "/db-code/import/execute", method: "post", callback: importExecuteRoute }
+  ]
+};

package/lib/action-args.js

@@ -0,0 +1,42 @@
+function getPath(source, path) {
+  if (!path) return undefined;
+  return String(path).split(".").reduce((acc, part) => (acc == null ? undefined : acc[part]), source);
+}
+
+function resolveTemplateValue(value, context) {
+  if (Array.isArray(value)) return value.map((item) => resolveTemplateValue(item, context));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, val]) => [key, resolveTemplateValue(val, context)]));
+  }
+  if (typeof value !== "string") return value;
+  const exact = value.match(/^\s*\{\{\s*([A-Za-z_][A-Za-z0-9_.]*)\s*\}\}\s*$/);
+  if (exact) {
+    const key = exact[1];
+    if (key.startsWith("row.")) return getPath(context.row, key.slice(4));
+    if (key.startsWith("user.")) return getPath(context.user, key.slice(5));
+    if (key.startsWith("configuration.")) return getPath(context.configuration, key.slice(14));
+    return getPath(context.row, key) ?? getPath(context.configuration, key) ?? getPath(context.user, key);
+  }
+  return value.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_.]*)\s*\}\}/g, (_, key) => {
+    const resolved = key.startsWith("row.")
+      ? getPath(context.row, key.slice(4))
+      : key.startsWith("user.")
+        ? getPath(context.user, key.slice(5))
+        : key.startsWith("configuration.")
+          ? getPath(context.configuration, key.slice(14))
+          : getPath(context.row, key) ?? getPath(context.configuration, key) ?? getPath(context.user, key);
+    return resolved == null ? "" : String(resolved);
+  });
+}
+
+function parseArgumentsJson(argumentsJson, context, opts = {}) {
+  const text = String(argumentsJson || "").trim();
+  if (!text) return [];
+  const parsed = JSON.parse(text);
+  if (!Array.isArray(parsed) && !(opts.allowObject && parsed && typeof parsed === "object")) {
+    throw new Error("DB_Routine arguments JSON must be an array.");
+  }
+  return resolveTemplateValue(parsed, context);
+}
+
+module.exports = { getPath, resolveTemplateValue, parseArgumentsJson };

package/lib/auth.js

@@ -0,0 +1,18 @@
+function isAdmin(req) {
+  return Boolean(req && req.user && req.user.role_id === 1);
+}
+
+function requireAdmin(req, res) {
+  if (isAdmin(req)) return true;
+  if (!req.user && res && typeof res.redirect === "function") {
+    res.redirect(`/auth/login?dest=${encodeURIComponent(req.originalUrl || req.url || "/db-code")}`);
+    return false;
+  }
+  if (res && typeof res.status === "function") res.status(403);
+  if (res && typeof res.send === "function") {
+    res.send("Forbidden: DB Code is available to administrators only.");
+  }
+  return false;
+}
+
+module.exports = { isAdmin, requireAdmin };

package/lib/db-routine-action.js

@@ -0,0 +1,146 @@
+const db = require("@saltcorn/data/db");
+const { listRoutines, getRoutineByOid } = require("./introspection");
+const { quoteIdent } = require("./sql-builders");
+const { routineArity } = require("./routine-args");
+
+function placeholders(count) {
+  return Array.from({ length: count }, (_, index) => `$${index + 1}`).join(", ");
+}
+
+async function callRoutine({ routineOid, argumentsJson, row, user, configuration }) {
+  const routine = await getRoutineByOid(routineOid);
+  if (!routine) throw new Error("Configured DB routine was not found in the current tenant schema.");
+  if (!["function", "procedure"].includes(routine.kind)) throw new Error("DB_Routine only supports functions and procedures.");
+
+  const values = parseAndValidateArgs(argumentsJson, routine, { row, user, configuration });
+  const routineRef = `${quoteIdent(routine.schema)}.${quoteIdent(routine.name)}`;
+  if (routine.kind === "procedure") {
+    const result = await db.query(`CALL ${routineRef}(${placeholders(values.length)})`, values);
+    return { success: true, kind: routine.kind, routine: routine.name, rowCount: result.rowCount || 0 };
+  }
+
+  const result = await db.query(`SELECT * FROM ${routineRef}(${placeholders(values.length)})`, values);
+  return { success: true, kind: routine.kind, routine: routine.name, rows: result.rows || [], rowCount: result.rowCount || 0 };
+}
+
+function resolveTemplateValue(value, context) {
+  if (Array.isArray(value)) return value.map((item) => resolveTemplateValue(item, context));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveTemplateValue(v, context)]));
+  }
+  if (typeof value !== "string") return value;
+  return value.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_.]*)\s*\}\}/g, (match) => match);
+}
+
+function parseAndValidateArgs(argumentsJson, routine, context) {
+  const text = String(argumentsJson || "").trim();
+  const { required, total } = routineArity(routine);
+
+  if (!text) {
+    if (required > 0) {
+      throw new Error(
+        `Routine "${routine.name}" requires ${required} argument${required > 1 ? "s" : ""} (${routine.identity_arguments}) but none were provided.`
+      );
+    }
+    return [];
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (e) {
+    throw new Error(`Arguments JSON is not valid JSON: ${e.message}`);
+  }
+
+  if (Array.isArray(parsed)) {
+    const count = parsed.length;
+    if (count < required) {
+      throw new Error(
+        `Routine "${routine.name}" requires at least ${required} argument${required > 1 ? "s" : ""} (${routine.identity_arguments}) but ${count} were provided.`
+      );
+    }
+    if (count > total) {
+      throw new Error(
+        `Routine "${routine.name}" accepts at most ${total} argument${total > 1 ? "s" : ""} (${routine.identity_arguments}) but ${count} were provided.`
+      );
+    }
+    return resolveTemplateValue(parsed, context);
+  }
+
+  if (parsed && typeof parsed === "object") {
+    if (required === 0 && total === 0) {
+      throw new Error(`Routine "${routine.name}" takes no arguments.`);
+    }
+    return resolveTemplateValue(parsed, context);
+  }
+
+  throw new Error("Arguments JSON must be an array or object.");
+}
+
+async function routineOptions() {
+  const routines = await listRoutines();
+  return routines
+    .filter((routine) => ["function", "procedure"].includes(routine.kind))
+    .map((routine) => ({
+      value: String(routine.oid),
+      label: `${routine.kind}: ${routine.name}(${routine.identity_arguments || ""})`
+    }));
+}
+
+const DB_Routine = {
+  namespace: "Database",
+  description: "Call a PostgreSQL function or stored procedure from the current tenant schema",
+  configFields: async () => [
+    {
+      name: "routine_oid",
+      label: "DB routine",
+      type: "String",
+      input_type: "select",
+      required: true,
+      options: await routineOptions(),
+      sublabel: "Select a function or stored procedure from the current tenant schema."
+    },
+    {
+      name: "arguments_json",
+      label: "Arguments JSON",
+      input_type: "code",
+      type: "String",
+      required: false,
+      attributes: { mode: "application/json", nojoins: true },
+      sublabel: "JSON array (positional) or JSON object (named). Supports templates like {{row.id}}, {{user.email}}, {{configuration.some_value}}. Leave blank only for zero-argument routines.",
+      validator(s) {
+        if (!s || !String(s).trim()) return true;
+        try {
+          const parsed = JSON.parse(s);
+          if (!Array.isArray(parsed) && (parsed === null || typeof parsed !== "object")) {
+            return "Arguments must be a JSON array or object.";
+          }
+          return true;
+        } catch (e) {
+          return `Invalid JSON: ${e.message}`;
+        }
+      }
+    }
+  ],
+  configuration_summary: (cfg = {}) => `Call DB routine OID ${cfg.routine_oid || "not selected"}`,
+  run: async ({ row, user, configuration }) => {
+    try {
+      if (!configuration?.routine_oid) {
+        return {
+          error: "DB_Routine is not configured: no routine selected. Open the trigger/action configuration and select a DB routine."
+        };
+      }
+      return await callRoutine({
+        routineOid: configuration.routine_oid,
+        argumentsJson: configuration.arguments_json,
+        row,
+        user,
+        configuration
+      });
+    } catch (error) {
+      return { error: error.message || "DB_Routine execution failed." };
+    }
+  }
+};
+
+module.exports = { DB_Routine, callRoutine };

package/lib/export-import.js

@@ -0,0 +1,137 @@
+/**
+ * Export/import helpers for database routines.
+ *
+ * Pack format:
+ * {
+ *   format: "saltcorn-db-code-routines",
+ *   version: 1,
+ *   exported_at: "2026-05-09T...",
+ *   source_schema: "public",
+ *   routines: [
+ *     {
+ *       name: "hello",
+ *       kind: "function",
+ *       identity_arguments: "",
+ *       arguments: "",
+ *       result_type: "text",
+ *       language: "sql",
+ *       volatility: "IMMUTABLE",
+ *       security_definer: false,
+ *       input_args: [],
+ *       description: "...",
+ *       ddl: "CREATE OR REPLACE FUNCTION ..."
+ *     }
+ *   ]
+ * }
+ */
+
+const { escapeHtml } = require("./html");
+
+const PACK_FORMAT = "saltcorn-db-code-routines";
+const PACK_VERSION = 1;
+
+/**
+ * Build an export pack from an array of routine rows (as returned by listRoutines).
+ * Each routine's `definition` (from pg_get_functiondef) is used as the DDL.
+ */
+function buildExportPack(routines, schema) {
+  return {
+    format: PACK_FORMAT,
+    version: PACK_VERSION,
+    exported_at: new Date().toISOString(),
+    source_schema: schema,
+    routines: routines.map((r) => ({
+      name: r.name,
+      kind: r.kind,
+      identity_arguments: r.identity_arguments || "",
+      arguments: r.arguments || "",
+      result_type: r.result_type || null,
+      language: r.language || "plpgsql",
+      volatility: r.volatility || "VOLATILE",
+      security_definer: !!r.prosecdef,
+      input_args: r.input_args || [],
+      description: r.description || null,
+      ddl: r.definition || "",
+    })),
+  };
+}
+
+/**
+ * Validate an imported pack object.
+ * Returns { valid: true, pack } or { valid: false, error: "..." }.
+ */
+function validateImportPack(raw) {
+  if (!raw || typeof raw !== "object") {
+    return { valid: false, error: "Invalid file: not a JSON object." };
+  }
+  if (raw.format !== PACK_FORMAT) {
+    return { valid: false, error: `Unrecognised format "${raw.format || "(missing)"}". Expected "${PACK_FORMAT}".` };
+  }
+  if ((raw.version || 0) > PACK_VERSION) {
+    return { valid: false, error: `Pack version ${raw.version} is newer than supported version ${PACK_VERSION}. Please update the DB Code plugin.` };
+  }
+  if (!Array.isArray(raw.routines)) {
+    return { valid: false, error: "Pack has no routines array." };
+  }
+  for (let i = 0; i < raw.routines.length; i++) {
+    const r = raw.routines[i];
+    if (!r.name) return { valid: false, error: `Routine #${i + 1} has no name.` };
+    if (!r.kind) return { valid: false, error: `Routine "${r.name}" has no kind.` };
+    if (!r.ddl) return { valid: false, error: `Routine "${r.name}" has no DDL.` };
+  }
+  return { valid: true, pack: raw };
+}
+
+/**
+ * Remap schema references in a DDL string from oldSchema to newSchema.
+ * Simple string replacement of "oldSchema". and oldSchema. patterns.
+ */
+function remapSchemaInDdl(ddl, oldSchema, newSchema) {
+  if (!ddl || oldSchema === newSchema) return ddl;
+  const escapedOld = oldSchema.replace(/"/g, '""');
+  // Replace quoted and unquoted schema references
+  let result = ddl;
+  result = result.replace(new RegExp(`"${escapedOld.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"\\.`, "g"), `"${newSchema.replace(/"/g, '""')}".`);
+  result = result.replace(new RegExp(`(?<!")\\b${oldSchema.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\.(?!")`, "g"), `${newSchema}.`);
+  return result;
+}
+
+/**
+ * Render an HTML table previewing the routines in a pack.
+ */
+function renderPackPreview(pack) {
+  const routineRows = pack.routines.map((r, i) => {
+    const kindIcon = r.kind === "procedure" ? "fas fa-cogs" : "fas fa-cube";
+    const kindLabel = r.kind === "procedure" ? "Stored procedure" : "Function";
+    const kindClass = r.kind === "procedure" ? "bg-warning text-dark" : "bg-primary";
+    return `<tr>
+  <td><input class="form-check-input" type="checkbox" name="import_${i}" value="1" checked></td>
+  <td><span class="badge ${kindClass}"><i class="${kindIcon} me-1"></i>${escapeHtml(kindLabel)}</span></td>
+  <td><code>${escapeHtml(r.name)}</code></td>
+  <td><code>${escapeHtml(r.identity_arguments || "none")}</code></td>
+  <td><code>${escapeHtml(r.result_type || "—")}</code></td>
+  <td><span class="badge bg-light text-dark border">${escapeHtml(r.language || "")}</span></td>
+</tr>`;
+  }).join("");
+
+  return `<div class="table-responsive"><table class="table table-sm table-hover align-middle mb-0">
+<thead><tr>
+  <th><input class="form-check-input" type="checkbox" id="importToggleAll" checked></th>
+  <th>Type</th><th>Name</th><th>Arguments</th><th>Returns</th><th>Language</th>
+</tr></thead>
+<tbody>${routineRows}</tbody>
+</table></div>
+<div class="small text-muted mt-2">${pack.routines.length} routine${pack.routines.length !== 1 ? "s" : ""} · exported from schema <code>${escapeHtml(pack.source_schema || "?")}</code></div>
+<script>
+(function(){
+  var toggle = document.getElementById('importToggleAll');
+  if (!toggle) return;
+  var boxes = document.querySelectorAll('input[name^="import_"]');
+  toggle.addEventListener('change', function(){
+    boxes.forEach(function(b){ b.checked = toggle.checked; });
+  });
+})();
+</script>`;
+}
+
+module.exports = { PACK_FORMAT, PACK_VERSION, buildExportPack, validateImportPack, remapSchemaInDdl, renderPackPreview };

package/lib/html.js

@@ -0,0 +1,16 @@
+function escapeHtml(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function page(req, res, title, body) {
+  const html = `<div class="container mt-4 db-code-plugin"><h1>${escapeHtml(title)}</h1>${body}</div>`;
+  if (res && typeof res.sendWrap === "function") return res.sendWrap(title, html);
+  return res.send(`<!doctype html><html><head><meta charset="utf-8"><title>${escapeHtml(title)}</title><link rel="stylesheet" href="/static_assets/bootstrap.min.css"></head><body>${html}</body></html>`);
+}
+
+module.exports = { escapeHtml, page };

package/lib/introspection.js

@@ -0,0 +1,87 @@
+const db = require("@saltcorn/data/db");
+
+const ROUTINE_SELECT = `
+SELECT
+  p.oid,
+  n.nspname AS schema,
+  p.proname AS name,
+  p.prokind,
+  CASE p.prokind
+    WHEN 'f' THEN 'function'
+    WHEN 'p' THEN 'procedure'
+    WHEN 'a' THEN 'aggregate'
+    WHEN 'w' THEN 'window'
+  END AS kind,
+  pg_get_function_identity_arguments(p.oid) AS identity_arguments,
+  pg_get_function_arguments(p.oid) AS arguments,
+  pg_get_function_result(p.oid) AS result_type,
+  pg_get_functiondef(p.oid) AS definition,
+  l.lanname AS language,
+  p.provolatile,
+  p.pronargs,
+  p.pronargdefaults,
+  COALESCE(argmeta.input_args, '[]'::json) AS input_args,
+  CASE p.provolatile
+    WHEN 'i' THEN 'IMMUTABLE'
+    WHEN 's' THEN 'STABLE'
+    WHEN 'v' THEN 'VOLATILE'
+  END AS volatility,
+  p.prosecdef,
+  obj_description(p.oid, 'pg_proc') AS description
+FROM pg_proc p
+JOIN pg_namespace n ON n.oid = p.pronamespace
+JOIN pg_language l ON l.oid = p.prolang
+LEFT JOIN LATERAL (
+  SELECT json_agg(
+    json_build_object(
+      'position', u.ord,
+      'name', CASE
+        WHEN p.proargnames IS NOT NULL AND array_length(p.proargnames, 1) >= u.ord THEN p.proargnames[u.ord]
+        ELSE NULL
+      END,
+      'type', format_type(u.type_oid, NULL)
+    )
+    ORDER BY u.ord
+  ) AS input_args
+  FROM unnest(p.proargtypes::oid[]) WITH ORDINALITY AS u(type_oid, ord)
+) argmeta ON true
+`;
+
+function ensurePostgres() {
+  if (db.isSQLite) {
+    throw new Error("DB Code only supports PostgreSQL. SQLite does not support persistent stored routines.");
+  }
+}
+
+function currentTenantSchema() {
+  if (typeof db.getTenantSchema !== "function") throw new Error("Cannot resolve the current Saltcorn tenant schema.");
+  return db.getTenantSchema();
+}
+
+async function listRoutines() {
+  ensurePostgres();
+  const schema = currentTenantSchema();
+  const { rows } = await db.query(
+    `${ROUTINE_SELECT}
+WHERE n.nspname = $1
+ORDER BY p.proname, identity_arguments`,
+    [schema]
+  );
+  return rows;
+}
+
+async function getRoutineByOid(oid) {
+  ensurePostgres();
+  const schema = currentTenantSchema();
+  const parsedOid = Number.parseInt(oid, 10);
+  if (!Number.isInteger(parsedOid) || parsedOid <= 0) throw new Error("Invalid routine OID.");
+  const { rows } = await db.query(
+    `${ROUTINE_SELECT}
+WHERE n.nspname = $1 AND p.oid = $2
+LIMIT 1`,
+    [schema, parsedOid]
+  );
+  return rows[0] || null;
+}
+
+module.exports = { ensurePostgres, currentTenantSchema, listRoutines, getRoutineByOid };