sqlite-hub 1.0.0 → 1.1.0

package/README.md

@@ -19,7 +19,7 @@ SQLite Hub keeps that workflow sharp:
 - filter, sort, page through, and export table data
 - inspect schema, structure, and relationships
 - edit records in place with typed value previews and an SQL diff preview before saving
-- export tables and query results as CSV, TSV, Markdown, or duplicate them as a table
+- export tables and query results as CSV, TSV, Markdown, JSON, Parquet, or duplicate them as a table
 - copy result columns with formatting, headers, first-10 previews, TXT export, and Markdown todo export
 - keep database-scoped Markdown documents with previews, autosave, imports, exports, and saved-query inserts
 - switch between recent databases with sidebar quick picks
@@ -58,13 +58,13 @@ The database overview combines operational and schema information for the active
   <a href="./frontend/assets/mockups/structure_2_inspector_1200.webp"><img src="./frontend/assets/mockups/structure_2_inspector_1200.webp" alt="SQLite Hub structure inspector" width="49%"></a>
 </p>
 
-Inspect tables, views, indexes, triggers, columns, declared types, primary keys, nullability, foreign keys, and DDL without losing pace. The searchable object list and relationship graph support fit, relayout, selection clearing, direct navigation to table data, and a hideable inspector/sidebar. SQLite Hub remembers the last selected table while you move between views, and DDL can be copied directly from the inspector.
+Inspect tables, views, indexes, triggers, columns, declared types, primary keys, nullability, foreign keys, and DDL without losing pace. The searchable object list and relationship graph support fit, relayout, selection clearing, direct navigation to table data, and a hideable inspector/sidebar. Clicking a relationship edge opens a join preview with the mapped columns and a copyable SQL `JOIN` snippet. SQLite Hub remembers the last selected table while you move between views, and DDL can be copied directly from the inspector.
 
 ### Data browser
 
 [![SQLite Hub data browser](./frontend/assets/mockups/data_1_1200.webp)](./frontend/assets/mockups/data_1_1200.webp)
 
-Scan rows, sort columns, move through local data quickly, and export full tables as CSV, TSV, or Markdown. The Data browser also supports duplicating exports as a new table, searchable and hideable table navigation, page sizes up to 250 rows, and advanced filters with column/operator/value controls. Text filters support case-insensitive `contains`, `not contains`, and exact `equals` matching.
+Scan rows, sort columns, move through local data quickly, and export full tables as CSV, TSV, Markdown, JSON, or Parquet. The Data browser also supports duplicating exports as a new table, searchable and hideable table navigation, page sizes up to 250 rows, and advanced filters with column/operator/value controls. Text filters support case-insensitive `contains`, `not contains`, and exact `equals` matching.
 
 Wide tables keep their horizontal scroll position when sorting causes the grid to re-render. Cells use compact previews for long values, BLOBs, and detected file paths, while exports retain complete BLOB content.
 
@@ -89,9 +89,9 @@ The Row Editor adds contextual previews without changing the stored raw value:
 
 [![SQLite Hub SQL editor](./frontend/assets/mockups/sql_editor_1_1200.webp)](./frontend/assets/mockups/sql_editor_1_1200.webp)
 
-Write queries in a syntax-highlighted editor, execute them with the Run button or `Shift + Enter`, format SQL with the editor Format button, inspect results in the same workflow, and export result sets as CSV, TSV, Markdown, or duplicate them as a table. Query drafts survive reloads, query history can be searched and saved, and direct single-table `SELECT` results can be edited or deleted from the result grid when a stable row identity is available.
+Write queries in a syntax-highlighted editor, execute them with the Run button or `Shift + Enter`, format SQL with the editor Format button, inspect results in the same workflow, and export result sets as CSV, TSV, Markdown, JSON, Parquet, or duplicate them as a table. Query drafts survive reloads, query history can be searched and saved, and direct single-table `SELECT` results can be edited or deleted from the result grid when a stable row identity is available.
 
-Interactive result sets are limited to the first 5,000 rows to keep the application responsive. A visible notice and Messages entry indicate truncation; CSV, TSV, Markdown, and duplicate-table exports execute without that interactive row limit and include complete BLOB values. Sorting wide results preserves the horizontal scroll position.
+Interactive result sets are limited to the first 5,000 rows to keep the application responsive. A visible notice and Messages entry indicate truncation; CSV, TSV, Markdown, JSON, Parquet, and duplicate-table exports execute without that interactive row limit and include complete BLOB values. Sorting wide results preserves the horizontal scroll position.
 
 [![SQLite Hub query export](./frontend/assets/mockups/sql_editor_5_export_query_result_1200.webp)](./frontend/assets/mockups/sql_editor_5_export_query_result_1200.webp)
 
@@ -215,7 +215,7 @@ SQLite Hub ships with a built-in CLI that lets you start the app or query inform
 sqlite-hub                  # start on default port 4173
 sqlite-hub --port:4174      # start on a custom port
 sqlite-hub --open           # open SQLite Hub in the browser
-sqlite-hub --config         # show port, URL, app version, and SQLite version
+sqlite-hub --info           # show port, URL, versions, and update status
 sqlite-hub --help           # show help text
 sqlite-hub --version        # show version number
 ```
@@ -261,7 +261,18 @@ sqlite-hub --database:Billly --table:companies
 
 Prints table metadata such as columns, primary keys, foreign keys, indexes, row count, and row identity strategy.
 
-### SQL Editor - Saved Queries
+### SQL Editor - Raw SQL And Saved Queries
+
+Execute raw SQL through the same SQL Editor execution path used by the app:
+
+```bash
+sqlite-hub --database:Unit-00 --query:"SELECT * FROM companies LIMIT 10"
+sqlite-hub --database:Unit-00 --query:"SELECT * FROM companies LIMIT 10" --store:"Company Sample"
+```
+
+Raw CLI queries are recorded in Query History. Add `--store:"name"` to title the
+history item and mark it as saved. Raw SQL execution is rejected when the target
+database is marked read-only.
 
 List all saved queries for a database:
 
@@ -280,7 +291,7 @@ This searches the query history for the given database, finds the matching saved
 Show the saved query SQL without executing it:
 
 ```bash
-sqlite-hub --database:Unit-00 --query:"Stock Winners"
+sqlite-hub --database:Unit-00 --saved-query:"Stock Winners"
 ```
 
 Show the saved notes for a query:
@@ -289,12 +300,13 @@ Show the saved notes for a query:
 sqlite-hub --database:Unit-00 --notes:"TOP25 Loser and Winner EOD, T1, T3, T5"
 ```
 
-Export a saved query using the same CSV, TSV, and Markdown export logic as the SQL Editor:
+Export a saved query using the same CSV, TSV, Markdown, and JSON export logic as the SQL Editor:
 
 ```bash
 sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:csv
 sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:tsv
 sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:md
+sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:json
 ```
 
 The export is written to the current working directory using the generated query export filename.
@@ -332,29 +344,31 @@ sqlite-hub --database:Unit-00 --table:companies --export:0a754aba373d34972998792
 
 ### Available flags
 
-| Flag                                                     | Description                                     |
-| -------------------------------------------------------- | ----------------------------------------------- |
-| `--help`, `-h`                                           | Show help text                                  |
-| `--version`, `-v`                                        | Show version number                             |
-| `--config`                                               | Show port, URL, app version, and SQLite version |
-| `--open`                                                 | Open SQLite Hub in the browser                  |
-| `--port:PORT`                                            | Start the server on a custom port               |
-| `--database`, `-d`                                       | List all imported databases                     |
-| `--database:name`                                        | Select a database by name or id                 |
-| `--database:name --path`                                 | Get the file path of a database                 |
-| `--database:name --size`                                 | Get the size of a database                      |
-| `--database:name --lastopened`                           | Get the last opened timestamp                   |
-| `--database:name --tables`                               | Get all table names from a database             |
-| `--database:name --queries`                              | List saved queries for a database               |
-| `--database:name --execute:"query"`                      | Execute a saved query by name                   |
-| `--database:name --query:"query"`                        | Print a saved query by name                     |
-| `--database:name --notes:"query"`                        | Print saved notes for a query                   |
-| `--database:name --export:"query" --format:csv\|tsv\|md` | Set query export format                         |
-| `--database:name --documents`                            | List Markdown documents for a database          |
-| `--database:name --documents:"document"`                 | Print a document's Markdown content             |
-| `--database:name --documents:"document" --export`        | Export a document as Markdown                   |
-| `--database:name --table:"table"`                        | Print table metadata                            |
-| `--database:name --table:"table" --export:"pk"`          | Export one row as JSON                          |
+| Flag                                                            | Description                                     |
+| --------------------------------------------------------------- | ----------------------------------------------- |
+| `--help`, `-h`                                                  | Show help text                                  |
+| `--version`, `-v`                                               | Show version number                             |
+| `--info`                                                        | Show port, URL, versions, and update status     |
+| `--open`                                                        | Open SQLite Hub in the browser                  |
+| `--port:PORT`                                                   | Start the server on a custom port               |
+| `--database`, `-d`                                              | List all imported databases                     |
+| `--database:name`                                               | Select a database by name or id                 |
+| `--database:name --path`                                        | Get the file path of a database                 |
+| `--database:name --size`                                        | Get the size of a database                      |
+| `--database:name --lastopened`                                  | Get the last opened timestamp                   |
+| `--database:name --tables`                                      | Get all table names from a database             |
+| `--database:name --queries`                                     | List saved queries for a database               |
+| `--database:name --query:"sql"`                                 | Execute raw SQL and record it in Query History  |
+| `--database:name --query:"sql" --store:"name"`                  | Save a raw query in Query History with a name   |
+| `--database:name --execute:"query"`                             | Execute a saved query by name                   |
+| `--database:name --saved-query:"query"`                         | Print a saved query by name                     |
+| `--database:name --notes:"query"`                               | Print saved notes for a query                   |
+| `--database:name --export:"query" --format:csv\|tsv\|md\|json` | Set query export format                         |
+| `--database:name --documents`                                   | List Markdown documents for a database          |
+| `--database:name --documents:"document"`                        | Print a document's Markdown content             |
+| `--database:name --documents:"document" --export`               | Export a document as Markdown                   |
+| `--database:name --table:"table"`                               | Print table metadata                            |
+| `--database:name --table:"table" --export:"pk"`                 | Export one row as JSON                          |
 
 Legacy aliases such as `--database-path:name`, `--database-size:name`, `--database-lastopened:name`, `--database-tables:name`, and `--database:name --sqleditor:"query"` still work.
 
@@ -388,7 +402,7 @@ Results:
 
 ## API
 
-SQLite Hub also provides a local JSON API for database metadata, tables, saved queries, exports, and documents. Access is protected by database-specific API tokens created in Settings. See the [API documentation](./docs/API.md) for authentication, endpoints, and examples.
+SQLite Hub also provides a local JSON API for app info, database metadata, tables, saved queries, exports, and documents. `/api/v1/info` returns the same app/version status as `sqlite-hub --info`; database data is protected by database-specific API tokens created in Settings. See the [API documentation](./docs/API.md) for authentication, endpoints, and examples.
 
 ## Changelog
 

package/bin/sqlite-hub.js

@@ -3,13 +3,11 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { spawn } = require('node:child_process');
-const {
-    DatabaseCommandService,
-    getQueryTitle,
-} = require('../server/services/databaseCommandService');
+const { DatabaseCommandService, getQueryTitle } = require('../server/services/databaseCommandService');
+const { buildAppInfo } = require('../server/services/appInfoService');
 
 const DEFAULT_PORT = 4173;
-const EXPORT_FORMATS = new Set(['csv', 'tsv', 'md']);
+const EXPORT_FORMATS = new Set(['csv', 'tsv', 'md', 'json']);
 
 function printHelp() {
     console.log(`SQLite Hub CLI
@@ -18,8 +16,10 @@ Usage:
   sqlite-hub [--port:4173]
   sqlite-hub --database
   sqlite-hub --database:"name" --tables
+  sqlite-hub --database:"name" --query:"SELECT * FROM table_name"
+  sqlite-hub --database:"name" --query:"SELECT * FROM table_name" --store:"Query Name"
   sqlite-hub --database:"name" --execute:"Saved Query"
-  sqlite-hub --database:"name" --query:"Saved Query"
+  sqlite-hub --database:"name" --saved-query:"Saved Query"
   sqlite-hub --database:"name" --notes:"Saved Query"
   sqlite-hub --database:"name" --export:"Saved Query" --format:csv
   sqlite-hub --database:"name" --documents
@@ -31,7 +31,7 @@ Usage:
 Options:
   --help, -h                         Show this help text.
   --version, -v                      Show the version number.
-  --config                           Show CLI port, URL, app version, and SQLite version.
+  --info                             Show port, URL, app version, SQLite version, and update status.
   --open                             Start/open SQLite Hub in the browser.
   --port:PORT                        Start the server on a custom port.
   --database, -d                     List all imported databases.
@@ -41,20 +41,18 @@ Options:
   --lastopened                       Print the selected database last-opened timestamp.
   --tables                           List tables in the selected database.
   --queries                          List saved SQL Editor queries for the selected database.
+  --query:"sql"                      Execute raw SQL and record it in query history.
+  --store:"name"                     Save a raw --query history item with this name.
   --execute:"query"                  Execute a saved SQL Editor query by name.
-  --query:"query"                    Print a saved SQL Editor query by name.
+  --saved-query:"query"              Print a saved SQL Editor query by name.
   --notes:"query"                    Print notes for a saved SQL Editor query by name.
   --export:"query"                   Export a saved query when --table is not set.
-  --format:csv|tsv|md                Export format for query exports. Defaults to csv.
+  --format:csv|tsv|md|json           Export format for query exports. Defaults to csv.
   --documents                        List Markdown documents for the selected database.
   --documents:"name"                 Print a document's Markdown content.
   --documents:"name" --export        Export a document as a Markdown file.
   --table:"table"                    Print table metadata.
   --table:"table" --export:"pk"      Export one row as JSON by primary key or rowid.
-
-Legacy aliases still work:
-  --database-path:name, --database-size:name, --database-lastopened:name
-  --database-tables:name, --database:name --sqleditor, --database:name --sqleditor:"query"
 `);
 }
 
@@ -146,7 +144,7 @@ function normalizeExportFormat(format) {
     const normalized = String(format ?? 'csv').toLowerCase();
 
     if (!EXPORT_FORMATS.has(normalized)) {
-        throw new Error(`Unsupported export format: ${format}. Use csv, tsv, or md.`);
+        throw new Error(`Unsupported export format: ${format}. Use csv, tsv, md, or json.`);
     }
 
     return normalized;
@@ -156,7 +154,7 @@ function parseCliArguments(argv) {
     const options = {
         help: false,
         version: false,
-        config: false,
+        info: false,
         open: false,
         port: undefined,
         databaseList: false,
@@ -167,6 +165,8 @@ function parseCliArguments(argv) {
         tables: false,
         queries: false,
         executeQuery: null,
+        rawQuery: null,
+        storeName: null,
         showQuery: null,
         showNotes: null,
         exportTarget: null,
@@ -191,8 +191,8 @@ function parseCliArguments(argv) {
             continue;
         }
 
-        if (flag === '--config') {
-            options.config = true;
+        if (flag === '--info' || flag === '--config') {
+            options.info = true;
             continue;
         }
 
@@ -299,6 +299,20 @@ function parseCliArguments(argv) {
         }
 
         if (flag === '--query') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.rawQuery = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--store') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.storeName = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--saved-query') {
             const parsed = takeFlagValue(flag, value, argv, index);
             options.showQuery = parsed.value;
             index = parsed.nextIndex;
@@ -379,18 +393,20 @@ function parseCliArguments(argv) {
 function hasDatabaseOperation(options) {
     return Boolean(
         options.pathInfo ||
-            options.sizeInfo ||
-            options.lastOpenedInfo ||
-            options.tables ||
-            options.queries ||
-            options.executeQuery ||
-            options.showQuery ||
-            options.showNotes ||
-            options.documents ||
-            options.documentName ||
-            options.documentExport ||
-            options.exportTarget ||
-            options.tableName,
+        options.sizeInfo ||
+        options.lastOpenedInfo ||
+        options.tables ||
+        options.queries ||
+        options.executeQuery ||
+        options.rawQuery ||
+        options.storeName ||
+        options.showQuery ||
+        options.showNotes ||
+        options.documents ||
+        options.documentName ||
+        options.documentExport ||
+        options.exportTarget ||
+        options.tableName,
     );
 }
 
@@ -559,6 +575,22 @@ function executeSavedQuery({ databaseService, conn, queryName }) {
     printExecutionResult(result);
 }
 
+function executeRawQuery({ databaseService, conn, sql, storeName = null }) {
+    const { result, storedQuery } = databaseService.executeRawQuery(conn.id, sql, { storeName });
+
+    console.log(`\nExecuting raw SQL against: ${conn.label}`);
+    console.log('─'.repeat(60));
+    printExecutionResult(result);
+
+    if (result.historyId) {
+        console.log(`\nHistory ID: ${result.historyId}`);
+    }
+
+    if (storedQuery) {
+        console.log(`Stored query: ${getQueryTitle(storedQuery)}`);
+    }
+}
+
 function showSavedQuery({ databaseService, conn, queryName }) {
     const matchingQuery = databaseService.getSavedQuery(conn.id, queryName);
 
@@ -690,28 +722,51 @@ function printTableInfo(tableDetail) {
         console.log(`Indexes: ${tableDetail.indexes.length}`);
         tableDetail.indexes.forEach(index => {
             const unique = index.unique ? ' UNIQUE' : '';
-            const columns = index.columns.map(column => column.name).filter(Boolean).join(', ') || 'expression';
+            const columns =
+                index.columns
+                    .map(column => column.name)
+                    .filter(Boolean)
+                    .join(', ') || 'expression';
             console.log(`  - ${index.name}${unique}: ${columns}`);
         });
     }
 }
 
-function printConfig(port) {
-    const Database = require('better-sqlite3');
-    const { version } = require('../package.json');
-    const db = new Database(':memory:');
+function formatVersionStatus(versionCheck) {
+    if (!versionCheck || versionCheck.status === 'unknown') {
+        return `unknown${versionCheck?.error?.message ? ` (${versionCheck.error.message})` : ''}`;
+    }
 
-    try {
-        const sqliteVersion = db.prepare('SELECT sqlite_version() AS version').get().version;
-        const url = `http://127.0.0.1:${port}`;
+    if (versionCheck.updateAvailable) {
+        return `update available (${versionCheck.currentVersion} -> ${versionCheck.latestVersion})`;
+    }
+
+    if (versionCheck.status === 'ahead') {
+        return `ahead of npm latest (${versionCheck.currentVersion} > ${versionCheck.latestVersion})`;
+    }
+
+    return `current (${versionCheck.currentVersion})`;
+}
+
+async function printInfo(port, options = {}) {
+    const infoService = options.appInfoService ?? buildAppInfo;
+    const url = `http://127.0.0.1:${port}`;
+    const info = await infoService({ port, url });
+
+    console.log('SQLite Hub info');
+    console.log(`Port: ${info.port}`);
+    console.log(`URL: ${info.url}`);
+    console.log(`Package: ${info.packageName}`);
+    console.log(`App version: ${info.appVersion}`);
+    console.log(`SQLite version: ${info.sqliteVersion}`);
+    console.log(`Version status: ${formatVersionStatus(info.versionCheck)}`);
 
-        console.log('SQLite Hub config');
-        console.log(`Port: ${port}`);
-        console.log(`URL: ${url}`);
-        console.log(`App version: ${version}`);
-        console.log(`SQLite version: ${sqliteVersion}`);
-    } finally {
-        db.close();
+    if (info.versionCheck?.latestVersion) {
+        console.log(`Latest version: ${info.versionCheck.latestVersion}`);
+    }
+
+    if (info.versionCheck?.releaseUrl) {
+        console.log(`Release URL: ${info.versionCheck.releaseUrl}`);
     }
 }
 
@@ -757,8 +812,8 @@ async function main(argv = process.argv.slice(2), dependencies = {}) {
         return;
     }
 
-    if (options.config) {
-        printConfig(port);
+    if (options.info) {
+        await printInfo(port, dependencies);
         return;
     }
 
@@ -767,6 +822,10 @@ async function main(argv = process.argv.slice(2), dependencies = {}) {
         return;
     }
 
+    if (options.storeName && !options.rawQuery) {
+        throw new Error('--store requires --query:"sql".');
+    }
+
     const databaseService =
         dependencies.databaseService ??
         new DatabaseCommandService({
@@ -805,7 +864,16 @@ async function main(argv = process.argv.slice(2), dependencies = {}) {
             return;
         }
 
-        if (options.tableName || options.tables || options.queries || options.executeQuery || options.showQuery || options.showNotes || options.exportTarget) {
+        if (
+            options.tableName ||
+            options.tables ||
+            options.queries ||
+            options.executeQuery ||
+            options.rawQuery ||
+            options.showQuery ||
+            options.showNotes ||
+            options.exportTarget
+        ) {
             if (options.tableName) {
                 if (options.exportTarget) {
                     exportTableRowAsJson({
@@ -840,6 +908,16 @@ async function main(argv = process.argv.slice(2), dependencies = {}) {
                 return;
             }
 
+            if (options.rawQuery) {
+                executeRawQuery({
+                    databaseService,
+                    conn,
+                    sql: options.rawQuery,
+                    storeName: options.storeName,
+                });
+                return;
+            }
+
             if (options.showQuery) {
                 showSavedQuery({ databaseService, conn, queryName: options.showQuery });
                 return;
@@ -897,7 +975,9 @@ if (require.main === module) {
 
 module.exports = {
     main,
+    formatVersionStatus,
     normalizeExportFormat,
     openInDefaultBrowser,
     parseCliArguments,
+    printInfo,
 };

package/frontend/js/api.js

@@ -431,6 +431,10 @@ export function patchSettings(settings) {
   });
 }
 
+export function checkAppVersion() {
+  return request("/api/settings/version-check");
+}
+
 export function createApiToken(name) {
   return request("/api/settings/api-tokens", {
     method: "POST",
@@ -448,6 +452,8 @@ const TEXT_EXPORT_EXTENSIONS = {
   csv: "csv",
   tsv: "tsv",
   md: "md",
+  json: "json",
+  parquet: "parquet",
 };
 
 function normalizeTextExportFormat(format) {