sqlite-hub 2.0.1 → 2.2.0

package/server/routes/documents.js

@@ -1,6 +1,7 @@
 const express = require("express");
 const path = require("node:path");
 const { DatabaseRequiredError, route, successResponse } = require("../utils/errors");
+const { recordUserAction } = require("../utils/userActionLog");
 
 function getActiveDatabaseKey(connectionManager) {
   return connectionManager.getActiveConnection()?.id ?? null;
@@ -27,20 +28,23 @@ function resolveActiveDatabaseDocumentName(connection) {
   return basename || "Database";
 }
 
-function buildInitialDocumentPayload(connection) {
+function buildInitialDocumentPayload(connection, options = {}) {
   const databaseName = resolveActiveDatabaseDocumentName(connection);
+  const timestamp = new Date().toISOString();
+  const createdAt = String(options.createdAt ?? connection?.createdAt ?? "").trim() || timestamp;
+  const lastModifiedAt = String(options.lastModifiedAt ?? "").trim() || timestamp;
 
   return {
     title: databaseName,
     filename: databaseName,
-    content: `# ${databaseName}\n`,
+    content: `# ${databaseName}\n\n- created at:    ${createdAt}\n- last modified: ${lastModifiedAt}\n\n## Purpose\n`,
   };
 }
 
 function pickDocumentPatch(body = {}) {
   const patch = {};
 
-  for (const field of ["title", "filename", "content"]) {
+  for (const field of ["title", "filename", "content", "folderId"]) {
     if (Object.prototype.hasOwnProperty.call(body, field)) {
       patch[field] = body[field];
     }
@@ -58,7 +62,9 @@ function ensureDatabaseDocuments({ appStateStore, connectionManager, databaseKey
 
   appStateStore.createDatabaseDocument(
     databaseKey,
-    buildInitialDocumentPayload(connectionManager.getActiveConnection())
+    buildInitialDocumentPayload(connectionManager.getActiveConnection(), {
+      lastModifiedAt: appStateStore.getLatestActivityLogTimestamp?.(databaseKey),
+    })
   );
 
   return appStateStore.listDatabaseDocuments(databaseKey);
@@ -76,6 +82,7 @@ function createDocumentsRouter({ appStateStore, connectionManager }) {
         successResponse({
           data: {
             items: ensureDatabaseDocuments({ appStateStore, connectionManager, databaseKey }),
+            folders: appStateStore.listDatabaseDocumentFolders(databaseKey),
           },
           metadata: { databaseKey },
         })
@@ -83,6 +90,27 @@ function createDocumentsRouter({ appStateStore, connectionManager }) {
     })
   );
 
+  router.post(
+    "/folders",
+    route((req, res) => {
+      const databaseKey = requireActiveDatabaseKey(connectionManager);
+      const folder = appStateStore.createDatabaseDocumentFolder(databaseKey, {
+        name: req.body?.name,
+      });
+
+      res.status(201).json(
+        successResponse({
+          message: "Document folder created.",
+          data: folder,
+          metadata: {
+            databaseKey,
+            folders: appStateStore.listDatabaseDocumentFolders(databaseKey),
+          },
+        })
+      );
+    })
+  );
+
   router.post(
     "/",
     route((req, res) => {
@@ -91,6 +119,19 @@ function createDocumentsRouter({ appStateStore, connectionManager }) {
         title: req.body?.title,
         filename: req.body?.filename,
         content: req.body?.content,
+        folderId: req.body?.folderId,
+      });
+      recordUserAction({
+        appStateStore,
+        connectionManager,
+        action: "document.create",
+        databaseKey,
+        targetType: "document",
+        targetName: document.filename ?? document.id,
+        metadata: {
+          documentId: document.id,
+          title: document.title ?? null,
+        },
       });
 
       res.status(201).json(
@@ -140,11 +181,26 @@ function createDocumentsRouter({ appStateStore, connectionManager }) {
     "/:documentId",
     route((req, res) => {
       const databaseKey = requireActiveDatabaseKey(connectionManager);
+      const document = appStateStore.getDatabaseDocument(databaseKey, req.params.documentId);
+      const deleted = appStateStore.deleteDatabaseDocument(databaseKey, req.params.documentId);
+
+      recordUserAction({
+        appStateStore,
+        connectionManager,
+        action: "document.delete",
+        databaseKey,
+        targetType: "document",
+        targetName: document.filename ?? req.params.documentId,
+        metadata: {
+          documentId: req.params.documentId,
+          title: document.title ?? null,
+        },
+      });
 
       res.json(
         successResponse({
           message: "Document deleted.",
-          data: appStateStore.deleteDatabaseDocument(databaseKey, req.params.documentId),
+          data: deleted,
           metadata: { databaseKey },
         })
       );

package/server/routes/settings.js

@@ -10,6 +10,7 @@ const {
 } = require("../services/appInfoService");
 const { McpStatusService } = require("../services/mcpStatusService");
 const { MCP_TOOL_DEFINITIONS } = require("../services/mcpToolService");
+const { recordUserAction } = require("../utils/userActionLog");
 
 function getActiveTokenContext({ connectionManager, tokenService }) {
   const activeDatabase = connectionManager?.getActiveConnection?.() ?? null;
@@ -161,6 +162,20 @@ function createSettingsRouter({ appStateStore, connectionManager, tokenService,
       const activeDatabase = requireActiveDatabase(connectionManager);
       const token = tokenService.createToken(activeDatabase.id, req.body?.name);
 
+      recordUserAction({
+        appStateStore,
+        connectionManager,
+        action: "settings.api-token.create",
+        targetType: "api-token",
+        targetName: token.name ?? token.id,
+        databaseKey: activeDatabase.id,
+        metadata: {
+          apiTokenId: token.id,
+          apiTokenName: token.name ?? null,
+          tokenPrefix: token.tokenPrefix ?? null,
+        },
+      });
+
       res.status(201).json(
         successResponse({
           message: "API token created. It will only be shown once.",
@@ -175,8 +190,25 @@ function createSettingsRouter({ appStateStore, connectionManager, tokenService,
     "/api-tokens/:tokenId",
     route((req, res) => {
       const activeDatabase = requireActiveDatabase(connectionManager);
+      const token = tokenService
+        .listTokens(activeDatabase.id)
+        .find((candidate) => candidate.id === req.params.tokenId);
       const result = tokenService.deleteToken(activeDatabase.id, req.params.tokenId);
 
+      recordUserAction({
+        appStateStore,
+        connectionManager,
+        action: "settings.api-token.delete",
+        targetType: "api-token",
+        targetName: token?.name ?? req.params.tokenId,
+        databaseKey: activeDatabase.id,
+        metadata: {
+          apiTokenId: req.params.tokenId,
+          apiTokenName: token?.name ?? null,
+          tokenPrefix: token?.tokenPrefix ?? null,
+        },
+      });
+
       res.json(
         successResponse({
           message: "API token deleted.",

package/server/routes/tableDesigner.js

@@ -1,7 +1,8 @@
 const express = require("express");
 const { route, successResponse } = require("../utils/errors");
+const { recordUserAction } = require("../utils/userActionLog");
 
-function createTableDesignerRouter({ tableDesignerService }) {
+function createTableDesignerRouter({ tableDesignerService, appStateStore = null, connectionManager = null }) {
   const router = express.Router();
 
   router.get(
@@ -18,6 +19,20 @@ function createTableDesignerRouter({ tableDesignerService }) {
     })
   );
 
+  router.post(
+    "/validate-check",
+    route((req, res) => {
+      const data = tableDesignerService.validateCheckExpression(req.body ?? {});
+
+      res.json(
+        successResponse({
+          data,
+          message: "CHECK expression validated.",
+        })
+      );
+    })
+  );
+
   router.get(
     "/:tableName",
     route((req, res) => {
@@ -38,12 +53,30 @@ function createTableDesignerRouter({ tableDesignerService }) {
       const data = tableDesignerService.saveDraft(req.body ?? {});
       const isCreate = String(req.body?.draft?.mode ?? req.body?.mode ?? "").trim() !== "edit";
       const fillsImportedRows = Boolean(req.body?.draft?.fillImportedRows ?? req.body?.fillImportedRows);
+      const importedRows = req.body?.draft?.importRows ?? req.body?.draft?.importedCsvRows ?? [];
+      const executedSqlCount = Array.isArray(data.executedSql) ? data.executedSql.length : 0;
+
+      if (isCreate || executedSqlCount > 0) {
+        recordUserAction({
+          appStateStore,
+          connectionManager,
+          action: isCreate ? "table-designer.table.create" : "table-designer.table.update",
+          targetType: "table",
+          targetName: data.savedTableName ?? req.body?.draft?.tableName ?? req.body?.tableName,
+          metadata: {
+            mode: isCreate ? "create" : "edit",
+            executedSqlCount,
+            fillsImportedRows,
+            importedRowCount: fillsImportedRows && Array.isArray(importedRows) ? importedRows.length : 0,
+          },
+        });
+      }
 
       res.json(
         successResponse({
           message: isCreate
             ? fillsImportedRows
-              ? "Table created and filled from CSV."
+              ? "Table created and data imported."
               : "Table created."
             : "Table schema updated.",
           data,

package/server/server.js

@@ -129,13 +129,13 @@ app.use(
     nativeFileDialogService,
   })
 );
-app.use("/api/backups", createBackupsRouter({ backupService }));
+app.use("/api/backups", createBackupsRouter({ backupService, appStateStore, connectionManager }));
 app.use("/api/db", createOverviewRouter({ overviewService }));
 app.use("/api/sql", createSqlRouter({ appStateStore, connectionManager, sqlExecutor }));
 app.use("/api/charts", createChartsRouter({ appStateStore, connectionManager, sqlExecutor }));
 app.use("/api/structure", createStructureRouter({ structureService }));
-app.use("/api/data", createDataRouter({ dataBrowserService }));
-app.use("/api/table-designer", createTableDesignerRouter({ tableDesignerService }));
+app.use("/api/data", createDataRouter({ dataBrowserService, appStateStore, connectionManager }));
+app.use("/api/table-designer", createTableDesignerRouter({ tableDesignerService, appStateStore, connectionManager }));
 app.use("/api/media-tagging", createMediaTaggingRouter({ mediaTaggingService }));
 app.use(
   "/api/settings",

package/server/services/mcpToolService.js

@@ -76,6 +76,28 @@ const MCP_TOOL_DEFINITIONS = [
       ["databaseId", "sql"]
     ),
   },
+  {
+    name: "get_saved_queries",
+    description: "List saved SQL Editor queries for a database. This is the MCP equivalent of `sqlite-hub --database:name --queries`.",
+    inputSchema: objectSchema({
+      databaseId: databaseIdProperty(),
+      limit: { type: "integer", minimum: 1, maximum: 500, default: 100 },
+    }, ["databaseId"]),
+  },
+  {
+    name: "execute_stored_query",
+    description: "Execute a saved SQL Editor query by id, title, display title, or SQL fragment. This is the MCP equivalent of `sqlite-hub --database:name --execute:\"query\"`.",
+    inputSchema: objectSchema(
+      {
+        databaseId: databaseIdProperty(),
+        queryName: {
+          type: "string",
+          description: "Saved query id, title, display title, or SQL fragment.",
+        },
+      },
+      ["databaseId", "queryName"]
+    ),
+  },
   {
     name: "explain_query_plan",
     description: "Run SQLite EXPLAIN QUERY PLAN for a read-only query and return structured plan rows.",
@@ -142,6 +164,7 @@ function redactConnection(connection = {}) {
     label: connection.label,
     readOnly: Boolean(connection.readOnly),
     sizeBytes: connection.sizeBytes ?? null,
+    createdAt: connection.createdAt ?? null,
     lastOpenedAt: connection.lastOpenedAt ?? null,
     lastModifiedAt: connection.lastModifiedAt ?? null,
   };
@@ -154,6 +177,7 @@ function redactOverview(overview = {}) {
     file: {
       filename: overview.file?.filename ?? overview.connection?.label ?? null,
       sizeBytes: overview.file?.sizeBytes ?? null,
+      createdAt: overview.file?.createdAt ?? null,
       lastModifiedAt: overview.file?.lastModifiedAt ?? null,
     },
   };
@@ -227,6 +251,12 @@ class McpToolService {
             executedBy: "mcp",
             maxRows: args.maxRows,
           });
+        case "get_saved_queries":
+          return this.databaseService.listSavedQueries(args.databaseId, args.limit);
+        case "execute_stored_query":
+          return this.databaseService.executeSavedQuery(args.databaseId, args.queryName, {
+            executedBy: "mcp",
+          });
         case "explain_query_plan":
           return this.databaseService.explainQueryPlan(args.databaseId, args.sql);
         case "read_documents":

package/server/services/sqlite/connectionManager.js

@@ -70,6 +70,7 @@ class ConnectionManager {
       label: options.label?.trim() || path.basename(filePath),
       path: filePath,
       lastOpenedAt: new Date().toISOString(),
+      createdAt: metadata.createdAt,
       lastModifiedAt: metadata.lastModifiedAt,
       sizeBytes: metadata.sizeBytes,
       readOnly: options.readOnly ?? !isWritable(filePath),
@@ -216,7 +217,7 @@ class ConnectionManager {
     return recentConnections;
   }
 
-  updateRecentConnection(id, { filePath, label, readOnly = false, logoUpload = null, clearLogo = false }) {
+  updateRecentConnection(id, { filePath, label, readOnly = false, logoUpload = null, clearLogo = false, tags = null }) {
     const recentConnections = this.appStateStore.getRecentConnections();
     const existing = recentConnections.find((connection) => connection.id === id);
 
@@ -245,7 +246,7 @@ class ConnectionManager {
 
     try {
       if (this.current?.id === id) {
-        return this.openConnection({
+        const connection = this.openConnection({
           filePath: resolvedPath,
           label: normalizedLabel,
           id,
@@ -253,6 +254,15 @@ class ConnectionManager {
           readOnly: normalizedReadOnly,
           logoPath: nextLogoPath,
         });
+
+        if (Array.isArray(tags)) {
+          this.appStateStore.setConnectionTags(id, tags);
+        }
+
+        return {
+          ...connection,
+          tags: this.appStateStore.getConnectionTags(id),
+        };
       }
 
       const db = this.openRawDatabase(resolvedPath, {
@@ -267,6 +277,7 @@ class ConnectionManager {
         ...existing,
         label: normalizedLabel,
         path: resolvedPath,
+        createdAt: metadata.createdAt,
         lastModifiedAt: metadata.lastModifiedAt,
         sizeBytes: metadata.sizeBytes,
         readOnly: normalizedReadOnly,
@@ -275,9 +286,14 @@ class ConnectionManager {
 
       this.appStateStore.updateRecentConnection(id, () => nextConnection);
 
+      if (Array.isArray(tags)) {
+        this.appStateStore.setConnectionTags(id, tags);
+      }
+
       return {
         ...nextConnection,
         logoUrl: this.appStateStore.getConnectionLogoUrl(nextLogoPath),
+        tags: this.appStateStore.getConnectionTags(id),
         isActive: false,
       };
     } catch (error) {
@@ -295,8 +311,11 @@ class ConnectionManager {
     }
 
     const { db, ...connection } = this.current;
+    const storedConnection = this.appStateStore.getRecentConnection(connection.id);
+
     return {
       ...connection,
+      tags: storedConnection?.tags ?? [],
       isActive: true,
     };
   }
@@ -334,6 +353,10 @@ class ConnectionManager {
     }));
   }
 
+  listConnectionTags() {
+    return this.appStateStore.listConnectionTags();
+  }
+
   getStatus() {
     const active = this.getActiveConnection();
 

package/server/services/sqlite/dataBrowserService.js

@@ -83,6 +83,14 @@ function isUnchangedSubmittedValue(currentValue, submittedValue) {
   return formatPreviewValue(currentValue) === formatPreviewValue(submittedValue);
 }
 
+function assertDataTableWritable(tableDetail) {
+  if (tableDetail.isShadow) {
+    throw new ValidationError(
+      `Shadow table ${tableDetail.name} is read-only in Data.`
+    );
+  }
+}
+
 class DataBrowserService {
   constructor({ connectionManager }) {
     this.connectionManager = connectionManager;
@@ -102,6 +110,9 @@ class DataBrowserService {
         return {
           name: entry.name,
           columnCount,
+          tableKind: entry.tableKind ?? "table",
+          isVirtual: Boolean(entry.isVirtual),
+          isShadow: Boolean(entry.isShadow),
         };
       });
   }
@@ -161,6 +172,10 @@ class DataBrowserService {
     return {
       name: tableDetail.name,
       type: tableDetail.type,
+      tableKind: tableDetail.tableKind,
+      isVirtual: Boolean(tableDetail.isVirtual),
+      isShadow: Boolean(tableDetail.isShadow),
+      readOnly: Boolean(tableDetail.isShadow),
       rowCount,
       limit,
       offset,
@@ -253,6 +268,8 @@ class DataBrowserService {
     const tableDetail = getTableDetail(db, tableName, { includeRowCount: false });
     const identity = payload.identity ?? null;
 
+    assertDataTableWritable(tableDetail);
+
     if (tableDetail.notSafelyUpdatable) {
       throw new ValidationError(
         `Table ${tableName} cannot be safely updated because it has no stable row identity.`
@@ -299,6 +316,8 @@ class DataBrowserService {
     const db = this.connectionManager.getActiveDatabase();
     const tableDetail = getTableDetail(db, tableName, { includeRowCount: false });
 
+    assertDataTableWritable(tableDetail);
+
     return insertSyntheticRows(db, tableDetail, payload);
   }
 
@@ -351,6 +370,8 @@ class DataBrowserService {
     const values = payload.values ?? {};
     const identity = payload.identity ?? null;
 
+    assertDataTableWritable(tableDetail);
+
     if (tableDetail.notSafelyUpdatable) {
       throw new ValidationError(
         `Table ${tableName} cannot be safely updated because it has no stable row identity.`

package/server/services/sqlite/introspection.js

@@ -19,6 +19,37 @@ function getTableListMap(db) {
   }
 }
 
+function normalizeTableKind(entry = {}, tableListEntry = null) {
+  const pragmaType = String(tableListEntry?.type ?? "")
+    .trim()
+    .toLowerCase();
+
+  if (pragmaType) {
+    return pragmaType;
+  }
+
+  if (entry.type === "table" && /^\s*CREATE\s+VIRTUAL\s+TABLE\b/i.test(entry.sql || "")) {
+    return "virtual";
+  }
+
+  return entry.type;
+}
+
+function decorateStructureEntry(entry, tableListMap = null) {
+  if (entry.type !== "table") {
+    return entry;
+  }
+
+  const tableKind = normalizeTableKind(entry, tableListMap?.get(entry.name));
+
+  return {
+    ...entry,
+    tableKind,
+    isVirtual: tableKind === "virtual",
+    isShadow: tableKind === "shadow",
+  };
+}
+
 function getMasterEntry(db, type, name) {
   const entry = db
     .prepare(
@@ -34,6 +65,8 @@ function getMasterEntry(db, type, name) {
 }
 
 function getRawStructureEntries(db) {
+  const tableListMap = getTableListMap(db);
+
   return db
     .prepare(
       [
@@ -43,7 +76,8 @@ function getRawStructureEntries(db) {
         "ORDER BY type ASC, name ASC",
       ].join(" ")
     )
-    .all();
+    .all()
+    .map((entry) => decorateStructureEntry(entry, tableListMap));
 }
 
 function normalizeColumn(column, visibleSet) {
@@ -607,11 +641,15 @@ function getTableDetail(db, tableName, options = {}) {
     typeof tableListEntry?.wr === "number"
       ? Boolean(tableListEntry.wr)
       : /WITHOUT\s+ROWID/i.test(entry.sql || "");
+  const tableKind = normalizeTableKind(entry, tableListEntry);
 
   const tableDetail = {
     type: entry.type,
     name: entry.name,
     ddl: entry.sql,
+    tableKind,
+    isVirtual: tableKind === "virtual",
+    isShadow: tableKind === "shadow",
     withoutRowId,
     strict: Boolean(tableListEntry?.strict),
     columns,

package/server/services/sqlite/overviewService.js

@@ -123,6 +123,7 @@ class OverviewService {
         filename: connection.label,
         path: connection.path,
         sizeBytes: connection.sizeBytes,
+        createdAt: connection.createdAt,
         lastModifiedAt: connection.lastModifiedAt,
       },
       sqlite: {

package/server/services/sqlite/structureService.js

@@ -3,6 +3,65 @@ const { quoteIdentifier } = require("../../utils/identifier");
 const { serializeRows } = require("../../utils/sqliteTypes");
 const { TypeGenerationService } = require("../typeGenerationService");
 
+function resolveShadowOwnerTableName(shadowTable, tables) {
+  if (!shadowTable?.isShadow) {
+    return null;
+  }
+
+  return (
+    tables
+      .filter((table) => table.isVirtual && shadowTable.name.startsWith(`${table.name}_`))
+      .sort((left, right) => right.name.length - left.name.length)[0]?.name ?? null
+  );
+}
+
+function unquoteSqlIdentifier(identifier) {
+  const value = String(identifier ?? "").trim();
+
+  if (value.length >= 2 && value[0] === '"' && value.at(-1) === '"') {
+    return value.slice(1, -1).replace(/""/g, '"');
+  }
+
+  if (value.length >= 2 && value[0] === "`" && value.at(-1) === "`") {
+    return value.slice(1, -1).replace(/``/g, "`");
+  }
+
+  if (value.length >= 2 && value[0] === "[" && value.at(-1) === "]") {
+    return value.slice(1, -1);
+  }
+
+  return value;
+}
+
+function extractVirtualTableModule(ddl = "") {
+  const match = String(ddl ?? "").match(
+    /\bUSING\s+("[^"]+(?:""[^"]*)*"|`[^`]+(?:``[^`]*)*`|\[[^\]]+\]|[A-Za-z_][A-Za-z0-9_]*)/i
+  );
+
+  return match ? unquoteSqlIdentifier(match[1]) : null;
+}
+
+function serializeGraphTable(table, shadowOwnerTableName = null) {
+  const isVirtual = Boolean(table.isVirtual);
+
+  return {
+    type: table.type,
+    name: table.name,
+    ddl: table.ddl,
+    tableKind: table.tableKind,
+    isVirtual,
+    isShadow: Boolean(table.isShadow),
+    virtualModule: isVirtual ? extractVirtualTableModule(table.ddl) : null,
+    shadowOwnerTable: shadowOwnerTableName,
+    withoutRowId: table.withoutRowId,
+    strict: table.strict,
+    columns: table.columns,
+    foreignKeys: table.foreignKeys,
+    identityStrategy: table.identityStrategy,
+    notSafelyUpdatable: table.notSafelyUpdatable,
+  };
+}
+
 class StructureService {
   constructor({ connectionManager, appStateStore }) {
     this.connectionManager = connectionManager;
@@ -35,17 +94,9 @@ class StructureService {
         triggers: entries.filter((entry) => entry.type === "trigger"),
       },
       graph: {
-        tables: tables.map((table) => ({
-          type: table.type,
-          name: table.name,
-          ddl: table.ddl,
-          withoutRowId: table.withoutRowId,
-          strict: table.strict,
-          columns: table.columns,
-          foreignKeys: table.foreignKeys,
-          identityStrategy: table.identityStrategy,
-          notSafelyUpdatable: table.notSafelyUpdatable,
-        })),
+        tables: tables.map((table) =>
+          serializeGraphTable(table, resolveShadowOwnerTableName(table, tables))
+        ),
         relationshipCount,
       },
     };
@@ -65,6 +116,10 @@ class StructureService {
       type: table.type,
       name: table.name,
       ddl: table.ddl,
+      tableKind: table.tableKind,
+      isVirtual: Boolean(table.isVirtual),
+      isShadow: Boolean(table.isShadow),
+      virtualModule: table.isVirtual ? extractVirtualTableModule(table.ddl) : null,
       withoutRowId: table.withoutRowId,
       strict: table.strict,
       columns: table.columns,

package/server/services/sqlite/tableAdvisor.js

@@ -763,12 +763,18 @@ function analyzeTable(db, tableName) {
     score: calculateScore(issues),
     issueCount: issues.length,
     rowCount: Number(tableDetail.rowCount ?? 0),
+    tableKind: tableDetail.tableKind,
+    isVirtual: Boolean(tableDetail.isVirtual),
+    isShadow: Boolean(tableDetail.isShadow),
     issues,
     columnProfiles,
     table: {
       columnCount: (tableDetail.columns ?? []).filter((column) => column.visible && !column.generated).length,
       indexCount: (tableDetail.indexes ?? []).length,
       foreignKeyCount: (tableDetail.foreignKeys ?? []).length,
+      tableKind: tableDetail.tableKind,
+      isVirtual: Boolean(tableDetail.isVirtual),
+      isShadow: Boolean(tableDetail.isShadow),
     },
     analyzedAt: new Date().toISOString(),
   };