feat(tui): SQL Runner over the sql-workbench extension

The owner asked whether anyone was getting the SQL Runner working in the
terminal. The Next UI's Runner (a SQL_WORKBENCH widget on its own app page)
had no TUI screen: its app opened an empty app home.

Add a classic database-TUI screen over the sql-workbench UI API extension:
- editor on top: multi-line buffer, syntax tint (server keywords included),
  F5 / Ctrl+Enter (Ctrl+J) runs the statement under the cursor, Tab completes
  tables and columns (alias.columns) from the schema endpoint, Ctrl+Up/Down
  steps through the on-disk run history; :name parameters are asked for,
  bound as values and remembered
- result grid below: server-paged and server-sorted over the cached result,
  column widths from the column kinds, NULL dimmed, V whole value, x export
  (csv/xlsx/json through the file flow), status line with rows, elapsed,
  backend, read-only and the row limit (cursor tokens dropped first)
- errors inline under the editor with the SQL position marked (H2 [*],
  PostgreSQL Position, line/column forms)
- F6 EXPLAIN as an indented, foldable plan tree with costs and a relative
  cost bar (raw text with r); quick text bar charts (c)
- F3 schema browser (backends, tables, columns; filter; Enter inserts)
- F2 notebooks (mine/shared, open, save as a new version, save as,
  duplicate, delete, publish when allowed), F4 cells (SQL and markdown,
  markdown rendered as text, move, title, backend, run all), F7 audited
  history with open and re-run
- reachable from the Runner app in the tree, `/` (the SQL Workbench widget
  hit opens the Runner instead of `widget get`), F9 > Work and :sql
  (:sql <statement>, :sql open <id>); without the extension the Runner apps
  and their SQL_WORKBENCH widgets leave the metadata and :sql says the
  extension is missing

Registration is kept to a few lines: store.setMeta hides the Runner apps
(extensions now load before the metadata), a screen may claim a global key
(F2 here; its keys reach F1 through the existing helpKeys), openApp routes
Runner apps, and commands gain :sql, the Work entry and the widget route. Write mode is not offered (the Next UI keeps
the gated write flow).

Tests: editor model, completion, statements, parameters, error positions,
history, notebooks, absent-extension metadata, result paging and sort,
column widths, plan tree, bars, and the screen end to end against a fake
server (80x24 clipping checked). scripts/smoke-sql.sh drives it in tmux at
80x24 and 120x36 against a server with the extension.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
james.maesandClaude Fable 5.1 committed 2026-11-01 06:00:35 -06:00
1 parent 3c45c8ee2f
commit cc7839639f
17 files changed
+3467 -4

No files matched your search

+8
View File
@@ -211,6 +211,14 @@ candidate's, plus the changes since it listed first.
the grid footer shows the column's help. Large tables stay quick: on a 10,000 x 40 table the first page
draws in about 100 ms. A soak test (`packages/tui/scripts/soak.sh`) drives the real UI in tmux with
random keys from the keymap and fails on any exit or error.
- **SQL Runner** (with the sql-workbench extension): the Next UI Runner in the terminal, from the SQL
Workbench app, `/`, F9 › Work and `:sql`. A SQL editor with syntax tint, F5 / Ctrl+Enter running the
statement under the cursor, Tab completion of tables and columns from the schema endpoint, Ctrl+↑↓
history; a server-paged, server-sorted result grid with typed column widths, whole values and export;
errors inline with their SQL position; EXPLAIN as an indented plan tree (F6); a schema browser (F3);
notebooks with SQL and markdown cells, run all, save, save as, duplicate, delete and publish (F2, F4);
quick text bar charts; the audited run history with re-run (F7). Hidden, and `:sql` explains why, when
the server lacks the extension. Read-only runs only.
- **Dashboards and widgets** in block characters: stats, bar charts, sparklines, percentage bars, tables
and steppers.
- **Terminal care**: `qqq ui --check` (and a quick check at startup) finds tmux key and colour problems and
+35 -1
View File
@@ -228,13 +228,46 @@ and the result. Shareable records (saved reports, saved views) have Share (`Z`,
group Read-Only or Read and Edit, change, remove; only the owner may share. `:helpkeys` turns on
help-authoring mode (F1 shows every help slot key).
## SQL Runner
With the `sql-workbench` UI API extension (qbit-sql-workbench), the SQL Runner is the terminal face of the
Next UI's Runner page (a `SQL_WORKBENCH` widget). Open it from the SQL Workbench app's Runner in the Apps
tree, `/` (type "sql"), F9 › Work › SQL Runner, or `:sql` (`:sql SELECT …` opens and runs a statement,
`:sql open <id>` opens a notebook). Without the extension the Runner app and the entries are hidden and
`:sql` says the extension is missing. The SQL Workbench app's home is the usual app dashboard (notebooks and
the execution audit), and its tables open as tables.
The layout is a classic database TUI: the SQL editor on top (line numbers, syntax tint, the server's
keywords), the result grid below with a status line (rows, elapsed, backend, read-only, row limit, sort),
an error under the editor with its SQL position marked in the text, and the schema browser on the right.
| Key | Does |
|---|---|
| F5, Ctrl+Enter (Ctrl+J) | run the statement under the cursor (the whole cell when it has one); `:name` parameters are asked for, bound as values and remembered |
| F6 | EXPLAIN: the plan as an indented tree with cost, rows and a relative cost bar; ←→ or Enter fold, `r` the raw text |
| F3 | schema browser: backends › tables › columns, type to filter, → unfolds, Enter inserts the name (on a backend: run this cell there) |
| Tab | complete table and column names from the schema endpoint (after `alias.` the columns of that table); Tabs again cycle |
| Ctrl+↑ Ctrl+↓ | earlier and later SQL from your run history (kept on disk) |
| F2 | notebooks, Mine and Shared: open, `s` save (a new version), `a` save as, `n` new, `u` duplicate, `d` delete, `p` publish |
| F4 | cells: Enter edits one, `a` add SQL, `m` add notes, K J (Shift+↑↓) move, `t` title, `b` backend, `d` delete, `R` run all |
| F7 | your audited runs (status, time, rows, SQL); type to filter, Enter opens the SQL in the editor, Ctrl+R re-runs it |
| Shift+Tab, Esc | to the results and back; Esc also cancels a running statement and, from the editor, leaves (asking about unsaved changes) |
| results: ↑↓ PgUp PgDn ←→ | move; rows load page by page from the server's cached result |
| results: `s` `V` `x` | sort by the column (the server sorts: asc, desc, off), the whole value, export (csv, xlsx, json through the file flow) |
| results: `g` `c` `p` | grid, quick chart (text bars of a number column; ←→ value column, `l` label column), plan |
Markdown cells are edited as text and shown rendered below. Runs are read-only (one statement, the server's
row limit and timeout; every run is audited). The capabilities decide the backends offered, the row limit
shown and whether EXPLAIN ANALYZE is offered (it needs the write permission). `scripts/smoke-sql.sh [server]`
drives it in tmux at 80x24 and 120x36 against a server with the extension (default `http://localhost:8078`).
## The `:` command line
TUI commands: `home`, `back`, `quit`, `reset`, `refresh`, `help`, `helpkeys`, `menu`, `search <text>` (also `find`, `goto`, `palette`), `view`,
`views`, `share`, `actions`, `audits`, `dev`, `tags`, `report run <name>`, `theme <name>`, `ascii on|off`,
`linear on|off`, `shortcuts on|off`, `lock`, `pin`, `pin remove`, `idle <minutes>`, `filter [clear|<grammar>]`,
`export <format>`, `jobs`, `profile [name]`, `servers`, `server <url>`, `signout`, `connection`, `doctor`, `open <table>`,
`app <name>`, `record <table> <key>`. `table query|get|create|update|delete` and `process run` open screens;
`app <name>`, `record <table> <key>`, `sql [statement | open <id>]`. `table query|get|create|update|delete` and `process run` open screens;
any other CLI command runs in-process (`runCli` from `@qrun-io/qqq-cli/program`) and shows its output;
an extension operation (`:alerts get-inbox`, `:collab get-records-tasks customer 1`, `:api <operationId>`)
shows its JSON as key/value rows and sub-tables, with `J` for the raw JSON.
@@ -307,6 +340,7 @@ before any program sees it. `qqq ui --check` (and the quick check at startup) fi
cd packages/tui && bun test # or npm run test:tui at the root: the whole TUI against a fake server in memory
packages/tui/scripts/smoke.sh # tmux against a running server (profile "sample"); captures kept
packages/tui/scripts/smoke-widths.sh # fixed grid widths across pages (fake large-instance server)
packages/tui/scripts/smoke-sql.sh [server] # SQL Runner at 80x24 and 120x36 (default the enterprise server on 8078)
packages/tui/scripts/perf-large-table.sh # PRF-001: 10,000 rows x 40 columns, timings against a 2 s budget
packages/tui/scripts/soak.sh [server] [minutes] # random keys for 10 min; fails on an exit or an error boundary
```
+78
View File
@@ -0,0 +1,78 @@
#!/usr/bin/env bash
# Copyright 2026 QRun.IO, Inc.
# Licensed under the Apache License, Version 2.0 (see LICENSE).
#
# tmux smoke test of the SQL Runner against a server with the sql-workbench extension (default: the
# enterprise test server on 8078, MOCK sign-in). Uses its own config, state and cache directories, so
# no profile of yours is touched. At 80x24 and 120x36: SELECT 1, a real table query (paging, sort),
# a SQL error with its position, EXPLAIN, the schema browser and history; captures go to $OUT.
# packages/tui/scripts/smoke-sql.sh [server] OUT=dir SQL_TABLE=CUSTOMER
set -euo pipefail
here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
pkg="$(cd "$here/.." && pwd)"
root="$(cd "$pkg/../.." && pwd)"
server="${1:-http://localhost:8078}"
table="${SQL_TABLE:-CUSTOMER}"
out="${OUT:-$(mktemp -d)}"
cfg="$(mktemp -d)"
export QQQ_CONFIG_DIR="$cfg/config" QQQ_STATE_DIR="$cfg/state" QQQ_CACHE_DIR="$cfg/cache" QQQ_KEYRING=file
s="qqq-sql-$$"
fails=0
mkdir -p "$out"
cleanup() { tmux kill-session -t "$s" 2>/dev/null || true; rm -rf "$cfg"; }
trap cleanup EXIT
login="$(node "$root/packages/cli/dist/main.js" --server "$server" login 2>&1)"
profile="$(sed -n 's/.*as profile "\([^"]*\)".*/\1/p' <<< "$login")"
[[ -n $profile ]] || { echo "sign-in failed: $login"; exit 1; }
keys() { for k in "$@"; do if [[ $k == T:* ]]; then tmux send-keys -t "$s" -l -- "${k#T:}"; else tmux send-keys -t "$s" "$k"; fi; sleep 0.3; done; }
cap() { tmux capture-pane -t "$s" -p > "$out/$1.txt"; }
expect() { # name text...
local name=$1; shift
for _ in $(seq 1 40); do
cap "$name"
local ok=1
for t in "$@"; do grep -qF -- "$t" "$out/$name.txt" || ok=0; done
[[ $ok == 1 ]] && { echo "ok $name"; return 0; }
sleep 0.25
done
echo "FAIL $name (wanted: $*)"; fails=$((fails + 1))
}
# no line wider than the terminal (the clipping rule)
fits() { local name=$1 w=$2; if node -e 'const [f, w] = process.argv.slice(1); process.exit(require("fs").readFileSync(f, "utf8").split("\n").some((l) => [...l].length > Number(w)) ? 1 : 0)' "$out/$name.txt" "$w"; then :; else echo "FAIL $name: a line is wider than $w"; fails=$((fails + 1)); fi; }
run_at() { # width height suffix
local w=$1 h=$2 x=$3
# the environment goes in the command: a running tmux server does not pass this shell's exports on
tmux new-session -d -s "$s" -x "$w" -y "$h" "cd '$pkg' && QQQ_CONFIG_DIR='$QQQ_CONFIG_DIR' QQQ_STATE_DIR='$QQQ_STATE_DIR' QQQ_CACHE_DIR='$QQQ_CACHE_DIR' QQQ_KEYRING=file bun run src/main.tsx --no-check --profile '$profile'; sleep 5"
expect "$x-00-home" 'Home' 'Recently viewed'
keys T:: 'T:sql SELECT 1' Enter
expect "$x-01-select-1" 'SQL · cell 1/1' '1 row ·' 'read-only' 'limit '
fits "$x-01-select-1" "$w"
keys Escape End C-u "T:SELECT * FROM $table" F5
expect "$x-02-table" 'rows ·' 'col 1/'
fits "$x-02-table" "$w"
keys Right T:s T:s
expect "$x-03-sorted" 'desc'
keys End
expect "$x-04-last-row" 'row '
keys Escape End C-u 'T:SELECT * FRM X' F5
expect "$x-05-error" 'FAILED' 'at line 1, col 10'
fits "$x-05-error" "$w"
keys End C-u "T:SELECT * FROM $table WHERE 1 = 1" F6
expect "$x-06-explain" 'Plan' 'EXPLAIN'
fits "$x-06-explain" "$w"
keys Escape F3
expect "$x-07-schema" 'Schema' "$table"
fits "$x-07-schema" "$w"
keys F3 F7
expect "$x-08-history" 'History' 'SELECT 1'
fits "$x-08-history" "$w"
keys Escape
tmux kill-session -t "$s" 2>/dev/null || true
}
run_at 80 24 80
run_at 120 36 120
echo "captures in $out"
[[ $fails == 0 ]] || { echo "$fails failed"; exit 1; }
echo "sql smoke: ok"
+6 -1
View File
@@ -26,6 +26,8 @@ import { SignInScreen } from './screens/signin'
import { ServersOverlay } from './overlays/servers'
import type { AppStore, CommandsLike } from './store'
import type { MenuEntry } from './types'
import { openSqlRunner, sqlCommand, sqlMenuEntries } from './sql/entry'
import { isRunnerWidget } from './sql/apps'
import { errorText, shellSplit } from './util/text'
import { openPrintJobs } from './printing'
@@ -42,7 +44,7 @@ const NOUNS: Record<string, string[]> = {
apps: [], whoami: [], search: [], 'help-search': [],
}
const TUI_COMMANDS = ['quit', 'home', 'reset', 'tags', 'audits', 'dev', 'actions', 'back', 'help', 'menu', 'goto', 'view', 'theme', 'ascii', 'linear', 'shortcuts', 'lock', 'pin', 'idle', 'refresh', 'filter', 'export', 'jobs', 'printjobs', 'profile', 'servers', 'server', 'signout', 'connection', 'open', 'record', 'app']
const TUI_COMMANDS = ['quit', 'home', 'reset', 'tags', 'audits', 'dev', 'actions', 'back', 'help', 'menu', 'goto', 'view', 'theme', 'ascii', 'linear', 'shortcuts', 'lock', 'pin', 'idle', 'refresh', 'filter', 'export', 'jobs', 'printjobs', 'profile', 'servers', 'server', 'signout', 'connection', 'open', 'record', 'app', 'sql']
export class Commands implements CommandsLike {
constructor(private store: AppStore) {}
@@ -129,6 +131,7 @@ export class Commands implements CommandsLike {
else if (kind === 'process') openProcess(s, name)
else if (kind === 'app') openApp(s, name)
else if (kind === 'report') openReport(s, name)
else if (kind === 'widget' && isRunnerWidget(s.meta, name)) openSqlRunner(s)
else if (kind === 'widget') void this.run(`widget get ${name}`)
}
@@ -335,6 +338,7 @@ export class Commands implements CommandsLike {
case 'connection': return this.connection()
case 'open': return rest[0] ? openTable(s, rest[0]) : fail('open <table>')
case 'app': return rest[0] ? openApp(s, rest[0]) : fail('app <name>')
case 'sql': return sqlCommand(s, line.replace(/^sql\b/, ''))
case 'report':
if (rest[0] === 'run' && rest[1] && !rest.includes('--format') && !rest.includes('--out')) return openReport(s, rest[1])
break
@@ -631,6 +635,7 @@ export class Commands implements CommandsLike {
out.push({ section: 'Work', label: 'Print jobs', detail: s.status.print, command: 'printjobs', disabled: s.extensions.has('printing') ? undefined : 'needs the printing extension', run: () => openPrintJobs(s) })
out.push({ section: 'Work', label: 'Notifications', disabled: s.extensions.has('alerts') ? undefined : 'needs the alerts extension' })
out.push({ section: 'Work', label: 'My work', disabled: s.extensions.has('collaboration') ? undefined : 'needs the collaboration extension' })
out.push(...sqlMenuEntries(s))
for (const e of s.extensions.all()) out.push({ section: 'Work', label: `Extension: ${e.name} ${e.version}`, detail: e.description, command: `api --list`, run: () => s.message(`${e.name} ${e.version}\n${e.description ?? ''}\nPath: ${e.pathPrefix ?? ''}\nIts panels are not drawn by this TUI yet; its operations are reachable with :api.`, 'info', 'Extension') })
// Connection
out.push({ section: 'Connection', label: `Server ${s.status.server}`, detail: `UI API ${s.status.apiVersion}`, command: 'connection', run: () => this.connection() })
+3
View File
@@ -13,6 +13,8 @@ import { ProcessScreen, type ProcessOptions } from './screens/process'
import { RecordScreen } from './screens/record'
import { TableScreen } from './screens/table'
import type { AppStore } from './store'
import { isRunnerApp } from './sql/apps'
import { openSqlRunner } from './sql/entry'
/**
* Whether a table, process or app can be opened: unknown names (hidden from this user: not in
@@ -73,6 +75,7 @@ export function openProcess(store: AppStore, name: string, options: ProcessOptio
export function openApp(store: AppStore, name: string): void {
if (!known(store, 'apps', name)) return
if (isRunnerApp(store.meta, name)) return openSqlRunner(store)
store.push(new AppHomeScreen(store, name))
}
+53
View File
@@ -0,0 +1,53 @@
/*
* Copyright 2026 QRun.IO, Inc.
* Licensed under the Apache License, Version 2.0 (see LICENSE).
*/
/**
* Where the SQL Runner shows up: the apps whose page is a SQL_WORKBENCH widget (the Runner of the
* qbit-sql-workbench app). Without the `sql-workbench` UI API extension those apps are taken out
* of the metadata the TUI shows, so the tree, the palette and the app cards do not offer a screen
* that cannot work. No drawing here: the store imports it.
*/
import type { MetaDataDocument } from '@qrun-io/qqq-core'
export const SQL_EXTENSION = 'sql-workbench'
export const SQL_WIDGET_TYPE = 'SQL_WORKBENCH'
type Apps = Record<string, { widgets?: string[]; children?: Array<{ name: string; type: string }>; childMap?: Record<string, unknown> }>
type Widgets = Record<string, { type?: string }>
interface TreeNode { type: string; name: string; children?: TreeNode[] }
/** The apps whose page carries a SQL_WORKBENCH widget. */
export function runnerApps(meta: MetaDataDocument | undefined): string[] {
const apps = (meta?.apps ?? {}) as Apps
const widgets = (meta?.widgets ?? {}) as Widgets
return Object.entries(apps).filter(([, a]) => (a.widgets ?? []).some((w) => widgets[w]?.type === SQL_WIDGET_TYPE)).map(([name]) => name)
}
/** Whether an app is a Runner page. */
export function isRunnerApp(meta: MetaDataDocument | undefined, name: string): boolean {
return runnerApps(meta).includes(name)
}
/** Whether a widget is a SQL_WORKBENCH widget (search hits on it open the Runner). */
export function isRunnerWidget(meta: MetaDataDocument | undefined, name: string): boolean {
return ((meta?.widgets ?? {}) as Widgets)[name]?.type === SQL_WIDGET_TYPE
}
/** The metadata without the Runner apps and their SQL_WORKBENCH widgets when the extension is absent (unchanged when it is installed or there are none). */
export function hideRunnerApps(meta: MetaDataDocument, installed: boolean): MetaDataDocument {
if (installed) return meta
const hidden = new Set(runnerApps(meta))
if (!hidden.size) return meta
const prune = (nodes: TreeNode[] | undefined): TreeNode[] | undefined => nodes?.filter((n) => !(n.type === 'APP' && hidden.has(n.name))).map((n) => (n.children ? { ...n, children: prune(n.children) } : n))
const apps: Apps = {}
for (const [name, app] of Object.entries((meta.apps ?? {}) as Apps)) {
if (hidden.has(name)) continue
const childMap = app.childMap ? Object.fromEntries(Object.entries(app.childMap).filter(([k]) => !hidden.has(k))) : undefined
apps[name] = { ...app, ...(app.children ? { children: app.children.filter((c) => !(c.type === 'APP' && hidden.has(c.name))) } : {}), ...(childMap ? { childMap } : {}) }
}
const widgets = Object.fromEntries(Object.entries((meta.widgets ?? {}) as Widgets).filter(([, w]) => w?.type !== SQL_WIDGET_TYPE))
return { ...meta, apps, widgets, appTree: prune(meta.appTree as TreeNode[] | undefined) } as MetaDataDocument
}
+49
View File
@@ -0,0 +1,49 @@
/*
* Copyright 2026 QRun.IO, Inc.
* Licensed under the Apache License, Version 2.0 (see LICENSE).
*/
/** Opening the SQL Runner: from its app, `/`, F9 › Work and `:sql`, only with the extension installed. */
import type { AppStore } from '../store'
import type { MenuEntry } from '../types'
import { SQL_EXTENSION } from './apps'
import { SqlRunnerScreen } from './screen'
export function sqlWorkbenchInstalled(store: AppStore): boolean {
return store.extensions.has(SQL_EXTENSION)
}
/** What `:sql` says without the extension. */
export function sqlMissingText(store: AppStore): string {
return `The SQL Runner needs the sql-workbench extension (qbit-sql-workbench), which this server does not have (installed: ${store.extensions.describe() || 'none'}).`
}
/** Opens the runner (or, when it is already on top, loads the SQL into it). */
export function openSqlRunner(store: AppStore, options: { sql?: string; run?: boolean; notebookId?: number } = {}): void {
if (!sqlWorkbenchInstalled(store)) return store.flash(sqlMissingText(store), 'error')
const top = store.screen
if (top instanceof SqlRunnerScreen) {
if (options.notebookId !== undefined) top.openNotebook(options.notebookId)
else if (options.sql) {
top.addCell('SQL', options.sql)
if (options.run) top.run()
}
return store.bump()
}
store.push(new SqlRunnerScreen(store, options))
}
/** `:sql`, `:sql <statement>` (opens and runs it), `:sql open <notebook id>`. */
export function sqlCommand(store: AppStore, rest: string): void {
const text = rest.trim()
const open = /^open\s+(\d+)$/i.exec(text)
if (open) return openSqlRunner(store, { notebookId: Number(open[1]) })
openSqlRunner(store, text ? { sql: text, run: true } : {})
}
/** The F9 › Work entry (and through it the palette's commands); none without the extension. */
export function sqlMenuEntries(store: AppStore): MenuEntry[] {
if (!sqlWorkbenchInstalled(store)) return []
return [{ id: 'work:sql', section: 'Work', label: 'SQL Runner', detail: 'SQL notebook over the instance\'s databases', command: 'sql', run: () => openSqlRunner(store) }]
}
+643
View File
@@ -0,0 +1,643 @@
/*
* Copyright 2026 QRun.IO, Inc.
* Licensed under the Apache License, Version 2.0 (see LICENSE).
*/
/**
* The SQL Runner's editor model, free of drawing: a multi-line buffer driven by key events,
* statement splitting (the statement under the cursor), `:name` parameters, a tokenizer for the
* syntax tint, completion of table and column names from the schema endpoint, the SQL position of
* a server error, the run history, and notebook cells. Tests drive all of it without a terminal.
*/
import { History } from '@qrun-io/qqq-core'
import { isPrintable, type Key } from '../keys'
// ---- the buffer ----
/** A multi-line text buffer with a cursor (row, col), driven by key events. */
export class SqlBuffer {
lines: string[]
row = 0
col = 0
/** First visible line and column (kept by the view so the cursor stays visible). */
top = 0
left = 0
constructor(text = '') {
this.lines = text.split(/\r\n|\r|\n/)
this.end()
}
get text(): string {
return this.lines.join('\n')
}
/** Replaces the text; the cursor goes to the end. */
set(text: string): void {
this.lines = text.split(/\r\n|\r|\n/)
this.top = 0
this.left = 0
this.end()
}
/** Cursor to the end of the text. */
end(): void {
this.row = this.lines.length - 1
this.col = this.lines[this.row]!.length
}
get line(): string {
return this.lines[this.row] ?? ''
}
/** The cursor as a character offset into `text`. */
offset(): number {
let n = 0
for (let i = 0; i < this.row; i++) n += this.lines[i]!.length + 1
return n + this.col
}
/** Moves the cursor to a character offset. */
setOffset(offset: number): void {
let rest = Math.max(0, Math.min(offset, this.text.length))
for (let i = 0; i < this.lines.length; i++) {
const len = this.lines[i]!.length
if (rest <= len) {
this.row = i
this.col = rest
return
}
rest -= len + 1
}
this.end()
}
/** Inserts text at the cursor (line breaks split lines; tabs become two spaces). */
insert(text: string): void {
const clean = text.replace(/\r\n|\r/g, '\n').replace(/\t/g, ' ')
const parts = clean.split('\n')
const before = this.line.slice(0, this.col)
const after = this.line.slice(this.col)
if (parts.length === 1) {
this.lines[this.row] = before + clean + after
this.col += clean.length
return
}
const middle = parts.slice(1, -1)
const last = parts[parts.length - 1]!
this.lines.splice(this.row, 1, before + parts[0], ...middle, last + after)
this.row += parts.length - 1
this.col = last.length
}
/** A line break that keeps the indent of the current line. */
newline(): void {
const indent = /^\s*/.exec(this.line)![0].slice(0, this.col)
this.insert('\n' + indent)
}
backspace(): void {
if (this.col > 0) {
// in leading whitespace, remove back to the previous two-space stop
const lead = /^ */.exec(this.line)![0].length
const n = this.col <= lead && this.col >= 2 ? (this.col % 2 === 0 ? 2 : 1) : 1
this.lines[this.row] = this.line.slice(0, this.col - n) + this.line.slice(this.col)
this.col -= n
} else if (this.row > 0) {
const prev = this.lines[this.row - 1]!
this.lines.splice(this.row - 1, 2, prev + this.line)
this.row--
this.col = prev.length
}
}
del(): void {
if (this.col < this.line.length) this.lines[this.row] = this.line.slice(0, this.col) + this.line.slice(this.col + 1)
else if (this.row < this.lines.length - 1) this.lines.splice(this.row, 2, this.line + this.lines[this.row + 1])
}
move(dRow: number): void {
this.row = Math.max(0, Math.min(this.lines.length - 1, this.row + dRow))
this.col = Math.min(this.col, this.line.length)
}
/** The identifier (with an optional `qualifier.`) that ends at the cursor. */
wordBefore(): { qualifier?: string; prefix: string; from: number } {
const before = this.line.slice(0, this.col)
const m = /(?:([A-Za-z_][\w$]*|"[^"]+")\.)?([A-Za-z_][\w$]*|"[^"]*)?$/.exec(before)!
const prefix = m[2] ?? ''
const qualifier = m[1]?.replace(/"/g, '')
return { qualifier, prefix, from: this.offset() - prefix.length }
}
/** Replaces `length` characters before the cursor with text. */
replaceBefore(length: number, text: string): void {
const at = this.offset()
const all = this.text
const next = all.slice(0, at - length) + text + all.slice(at)
const top = this.top
this.lines = next.split('\n')
this.top = top
this.setOffset(at - length + text.length)
}
/** Handles an editing or movement key; returns whether it was one. Enter is the caller's. */
handle(key: Key, pageLines = 10): boolean {
if (key.ctrl && !key.meta) {
switch (key.name) {
case 'a': this.col = 0; return true
case 'e': this.col = this.line.length; return true
case 'u': this.lines[this.row] = this.line.slice(this.col); this.col = 0; return true
case 'w': {
const before = this.line.slice(0, this.col).replace(/\S+\s*$/, '')
this.lines[this.row] = before + this.line.slice(this.col)
this.col = before.length
return true
}
case 'home': this.row = 0; this.col = 0; return true
case 'end': this.end(); return true
case 'left': {
const before = this.line.slice(0, this.col).replace(/\w+\W*$|\W+$/, '')
this.col = before.length
return true
}
case 'right': {
const m = /^\W*\w+|^\W+/.exec(this.line.slice(this.col))
this.col += m ? m[0].length : 0
return true
}
default: return false
}
}
switch (key.name) {
case 'backspace': this.backspace(); return true
case 'delete': this.del(); return true
case 'left':
if (this.col > 0) this.col--
else if (this.row > 0) { this.row--; this.col = this.line.length }
return true
case 'right':
if (this.col < this.line.length) this.col++
else if (this.row < this.lines.length - 1) { this.row++; this.col = 0 }
return true
case 'up': this.move(-1); return true
case 'down': this.move(1); return true
case 'home': {
const lead = /^\s*/.exec(this.line)![0].length
this.col = this.col === lead ? 0 : lead
return true
}
case 'end': this.col = this.line.length; return true
case 'pageup': this.move(-pageLines); return true
case 'pagedown': this.move(pageLines); return true
default:
if (isPrintable(key) && !key.meta) {
this.insert(key.sequence)
return true
}
return false
}
}
/** Scrolls so the cursor is inside a view of `height` lines and `width` columns. */
scrollTo(height: number, width: number): void {
if (this.row < this.top) this.top = this.row
if (this.row >= this.top + height) this.top = this.row - height + 1
this.top = Math.max(0, Math.min(this.top, Math.max(0, this.lines.length - 1)))
if (this.col < this.left) this.left = this.col
if (this.col >= this.left + width) this.left = this.col - width + 1
}
}
// ---- scanning: statements, parameters, tokens ----
export type TokenKind = 'keyword' | 'string' | 'quoted' | 'number' | 'comment' | 'param' | 'ident' | 'punct' | 'space'
export interface Token {
kind: TokenKind
text: string
start: number
}
/** SQL keywords tinted in the editor (servers add theirs through the schema endpoint). */
export const SQL_KEYWORDS = new Set(('SELECT FROM WHERE AND OR NOT IN IS NULL LIKE ILIKE BETWEEN EXISTS AS ON JOIN INNER LEFT RIGHT FULL OUTER CROSS NATURAL USING ' +
'GROUP BY ORDER HAVING LIMIT OFFSET FETCH FIRST NEXT ROWS ROW ONLY UNION ALL INTERSECT EXCEPT MINUS DISTINCT CASE WHEN THEN ELSE END ' +
'WITH RECURSIVE VALUES INSERT INTO UPDATE SET DELETE MERGE CREATE ALTER DROP TABLE VIEW INDEX ASC DESC NULLS LAST TRUE FALSE ' +
'COUNT SUM AVG MIN MAX CAST COALESCE NULLIF EXPLAIN ANALYZE SHOW OVER PARTITION WINDOW FILTER LATERAL TOP ANY SOME').split(' '))
/**
* Tokenizes SQL with the backend scanner's rules: `--` and `/* *\/` comments, '…' strings, "…" and
* `…` quoted identifiers, $tag$ dollar quotes, `::` casts, `:name` parameters, numbers, words.
*/
export function tokenize(sql: string, keywords: Set<string> = SQL_KEYWORDS): Token[] {
const out: Token[] = []
const n = sql.length
let i = 0
const push = (kind: TokenKind, end: number) => {
out.push({ kind, text: sql.slice(i, end), start: i })
i = end
}
while (i < n) {
const c = sql[i]!
const next = sql[i + 1]
if (c === '-' && next === '-') {
const end = sql.indexOf('\n', i)
push('comment', end < 0 ? n : end)
} else if (c === '/' && next === '*') {
const end = sql.indexOf('*/', i + 2)
push('comment', end < 0 ? n : end + 2)
} else if (c === "'" || c === '"' || c === '`') {
let j = i + 1
while (j < n) {
if (sql[j] === c && sql[j + 1] === c) j += 2
else if (sql[j] === c) break
else j++
}
push(c === "'" ? 'string' : 'quoted', Math.min(n, j + 1))
} else if (c === '$' && /^\$([A-Za-z_]\w*)?\$/.test(sql.slice(i))) {
const tag = /^\$([A-Za-z_]\w*)?\$/.exec(sql.slice(i))![0]
const end = sql.indexOf(tag, i + tag.length)
push('string', end < 0 ? n : end + tag.length)
} else if (c === ':' && next === ':') {
push('punct', i + 2)
} else if (c === ':' && next !== undefined && /[A-Za-z_]/.test(next) && sql[i - 1] !== ':') {
let j = i + 1
while (j < n && /\w/.test(sql[j]!)) j++
push('param', j)
} else if (/\s/.test(c)) {
let j = i + 1
while (j < n && /\s/.test(sql[j]!)) j++
push('space', j)
} else if (/[0-9]/.test(c) || (c === '.' && next !== undefined && /[0-9]/.test(next) && !/[\w)]/.test(sql[i - 1] ?? ''))) {
const m = /^(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?/.exec(sql.slice(i))!
push('number', i + m[0].length)
} else if (/[A-Za-z_]/.test(c)) {
let j = i + 1
while (j < n && /[\w$]/.test(sql[j]!)) j++
push(keywords.has(sql.slice(i, j).toUpperCase()) ? 'keyword' : 'ident', j)
} else {
push('punct', i + 1)
}
}
return out
}
/** Splits tokens into display lines: tokens that cross a line break (comments, strings) are cut. */
export function tokenLines(sql: string, keywords?: Set<string>): Token[][] {
const lines: Token[][] = [[]]
for (const t of tokenize(sql, keywords)) {
const parts = t.text.split('\n')
let start = t.start
parts.forEach((p, i) => {
if (i > 0) lines.push([])
if (p) lines[lines.length - 1]!.push({ kind: t.kind, text: p, start })
start += p.length + 1
})
}
return lines
}
export interface Statement {
start: number
end: number
text: string
}
/** The statements of a text, split at `;` outside strings, quoted names and comments (blank ones dropped). */
export function splitStatements(sql: string): Statement[] {
const out: Statement[] = []
let start = 0
const flush = (end: number) => {
const raw = sql.slice(start, end)
const lead = raw.length - raw.trimStart().length
const text = raw.trim()
if (text && tokenize(text).some((t) => t.kind !== 'comment' && t.kind !== 'space')) out.push({ start: start + lead, end: start + lead + text.length, text })
}
for (const t of tokenize(sql)) {
if (t.kind === 'punct' && t.text === ';') {
flush(t.start)
start = t.start + 1
}
}
flush(sql.length)
return out
}
/**
* The statement to run for a cursor offset: the one containing it, else the one that ended just
* before it (the cursor after `;`), else the next one; undefined for a blank text.
*/
export function statementAt(sql: string, offset: number): Statement | undefined {
const all = splitStatements(sql)
if (all.length <= 1) return all[0]
const inside = all.find((s) => offset >= s.start && offset <= s.end)
if (inside) return inside
const before = [...all].reverse().find((s) => s.end <= offset)
return before ?? all[0]
}
/** The `:name` parameters of SQL in order of first appearance (the server's scanner rules). */
export function extractParameters(sql: string): string[] {
const seen: string[] = []
for (const t of tokenize(sql)) if (t.kind === 'param' && !seen.includes(t.text.slice(1))) seen.push(t.text.slice(1))
return seen
}
/** A parameter value as the server binds it: numbers and booleans for typed parameters, else text; '' is null. */
export function coerceParameter(raw: string | undefined, type?: string): string | number | boolean | null {
if (raw === undefined || raw === '') return null
if (type === 'INTEGER' || type === 'DECIMAL') {
const n = Number(raw)
return Number.isFinite(n) ? n : raw
}
if (type === 'BOOLEAN') return /^(true|1|yes|y)$/i.test(raw.trim())
return raw
}
// ---- completion ----
/** The parts of GET /sql-workbench/schema/{backend} the runner reads. */
export interface SqlSchema {
backendName?: string
dialect?: string
schemas?: Array<{ name: string; tables?: Array<{ name: string; type?: string; columns?: Array<{ name: string; typeName?: string; nullable?: boolean }> }> }>
qqqTables?: Array<{ name: string; label?: string; sqlName?: string; fields?: Array<{ name: string; label?: string; sqlName?: string; type?: string }> }>
keywords?: string[]
functions?: string[]
truncated?: boolean
}
/** Every keyword word the schema endpoint lists, plus the built-in ones. */
export function keywordSet(schema?: SqlSchema): Set<string> {
const set = new Set(SQL_KEYWORDS)
for (const k of schema?.keywords ?? []) for (const w of k.split(/\s+/)) if (/^[A-Za-z_]+$/.test(w)) set.add(w.toUpperCase())
return set
}
/** The tables of a schema document: name, schema, columns. */
export function schemaTables(schema?: SqlSchema): Array<{ name: string; schema: string; columns: Array<{ name: string; typeName?: string }> }> {
return (schema?.schemas ?? []).flatMap((s) => (s.tables ?? []).map((t) => ({ name: t.name, schema: s.name, columns: t.columns ?? [] })))
}
/** Tables named after FROM / JOIN / UPDATE / INTO in a statement, with their aliases (upper-cased keys). */
export function referencedTables(sql: string): Map<string, string> {
const out = new Map<string, string>()
const re = /\b(?:FROM|JOIN|UPDATE|INTO)\s+((?:"[^"]+"|[\w$]+)(?:\.(?:"[^"]+"|[\w$]+))?)(?:\s+(?:AS\s+)?([A-Za-z_][\w$]*))?/gi
for (let m = re.exec(sql); m; m = re.exec(sql)) {
const table = m[1]!.replace(/"/g, '').split('.').pop()!
out.set(table.toUpperCase(), table)
const alias = m[2]
if (alias && !SQL_KEYWORDS.has(alias.toUpperCase())) out.set(alias.toUpperCase(), table)
}
return out
}
export interface Completion {
/** Offset where the replaced word starts. */
from: number
prefix: string
candidates: string[]
}
/**
* Completion at a cursor: after `alias.` the columns of that table; otherwise columns of the tables
* the statement names, then table names (database names and QQQ tables' SQL names), then keywords.
* Case-insensitive prefix match; keywords follow the case the user typed.
*/
export function complete(sql: string, offset: number, schema?: SqlSchema): Completion {
const before = sql.slice(0, offset)
const m = /(?:([A-Za-z_][\w$]*|"[^"]+")\.)?([A-Za-z_][\w$]*)?$/.exec(before)!
const prefix = m[2] ?? ''
const from = offset - prefix.length
const qualifier = m[1]?.replace(/"/g, '')
const statement = statementAt(sql, offset)?.text ?? sql
const tables = schemaTables(schema)
const byName = new Map(tables.map((t) => [t.name.toUpperCase(), t]))
const refs = referencedTables(statement)
const columnsOf = (name: string) => byName.get((refs.get(name.toUpperCase()) ?? name).toUpperCase())?.columns.map((c) => c.name) ?? []
const up = prefix.toUpperCase()
const match = (list: string[]) => list.filter((c) => c.toUpperCase().startsWith(up) && c.toUpperCase() !== up)
if (qualifier) return { from, prefix, candidates: [...new Set(match(columnsOf(qualifier)))] }
if (!prefix) return { from, prefix, candidates: [] }
const columns = [...new Set([...refs.values()].flatMap((t) => columnsOf(t)))]
const names = [...tables.map((t) => t.name), ...(schema?.qqqTables ?? []).map((t) => t.sqlName ?? t.name)]
const lower = prefix === prefix.toLowerCase()
const keywords = [...keywordSet(schema)].map((k) => (lower ? k.toLowerCase() : k))
const functions = (schema?.functions ?? []).filter((f) => /^[A-Za-z_]\w*$/.test(f))
const seen = new Set<string>()
const unique = [...match(columns).sort(), ...match(names).sort(), ...match(keywords).sort(), ...match(functions).sort()].filter((c) => !seen.has(c.toUpperCase()) && Boolean(seen.add(c.toUpperCase())))
return { from, prefix, candidates: unique }
}
/** The longest common prefix of candidates, ignoring case (taken from the first). */
export function commonPrefix(candidates: string[]): string {
if (!candidates.length) return ''
let p = candidates[0]!
for (const c of candidates.slice(1)) {
let i = 0
while (i < p.length && i < c.length && p[i]!.toUpperCase() === c[i]!.toUpperCase()) i++
p = p.slice(0, i)
}
return p
}
// ---- errors ----
export interface SqlPosition {
/** Character offset into the statement text (when the server says where). */
offset?: number
line: number
col?: number
}
/** Line and column (1-based) of an offset in a text. */
export function lineCol(text: string, offset: number): { line: number; col: number } {
const before = text.slice(0, offset)
const line = before.split('\n').length
return { line, col: offset - before.lastIndexOf('\n') }
}
/**
* Where in the statement a database error points, when its message says: H2's `[*]` marker inside
* the quoted statement, PostgreSQL's `Position: N`, `line N, column M`, or MySQL's `at line N`.
*/
export function errorPosition(message: string, sql: string): SqlPosition | undefined {
const h2 = /"((?:[^"]|"")*\[\*\](?:[^"]|"")*)"/.exec(message)
if (h2) {
const quoted = h2[1]!.replace(/""/g, '"')
const at = quoted.indexOf('[*]')
const whole = quoted.replace('[*]', '')
let offset: number | undefined
const idx = sql.indexOf(whole)
if (idx >= 0) offset = idx + at
else if (whole.endsWith(sql)) offset = at - (whole.length - sql.length)
else {
// a prefix the server added (EXPLAIN …): match the text after the marker
const tail = whole.slice(at)
const t = tail ? sql.lastIndexOf(tail) : sql.length
if (t >= 0) offset = t
}
if (offset !== undefined && offset >= 0 && offset <= sql.length) return { offset, ...lineCol(sql, offset) }
}
const pg = /\bPosition: (\d+)/i.exec(message)
if (pg) {
const offset = Math.min(sql.length, Math.max(0, Number(pg[1]) - 1))
return { offset, ...lineCol(sql, offset) }
}
const lc = /\bline (\d+),? col(?:umn)? (\d+)/i.exec(message)
if (lc) return { line: Number(lc[1]), col: Number(lc[2]) }
const my = /\bat line (\d+)/i.exec(message)
if (my) return { line: Number(my[1]) }
return undefined
}
// ---- history ----
/**
* The SQL run history for Ctrl+↑↓: every statement that was run, newest first, kept on disk by the
* kernel's History (one JSON string per line, so multi-line SQL survives).
*/
export class SqlHistory {
private readonly store: { entries(): string[]; add(line: string): void }
/** -1: the draft (what was in the editor before browsing). */
index = -1
draft = ''
constructor(store?: { entries(): string[]; add(line: string): void }) {
this.store = store ?? new History('sql')
}
entries(): string[] {
return this.store.entries().map((l) => {
try {
const v = JSON.parse(l) as unknown
return typeof v === 'string' ? v : l
} catch {
return l
}
})
}
add(sql: string): void {
const text = sql.trim()
if (text) this.store.add(JSON.stringify(text))
this.index = -1
}
/** Older (dir 1) or newer (dir -1) entry; returns the text to show, or undefined at the end. */
step(dir: 1 | -1, current: string): string | undefined {
const list = this.entries()
if (this.index === -1 && dir === 1) this.draft = current
const next = this.index + dir
if (next < -1 || next >= list.length) return undefined
this.index = next
return next === -1 ? this.draft : list[next]
}
reset(): void {
this.index = -1
}
}
// ---- notebooks ----
export interface NotebookCell {
cellKey: string
cellType: 'SQL' | 'MARKDOWN'
title?: string | null
content: string
backendName?: string | null
sortOrder?: number
}
export interface NotebookParameter {
name: string
type?: string
defaultValue?: string | null
label?: string | null
}
export interface Notebook {
id?: number
title: string
description?: string | null
visibility?: string
ownerName?: string | null
defaultBackendName?: string | null
parameters?: NotebookParameter[]
currentVersion?: number
canEdit?: boolean
cells: NotebookCell[]
}
export function newCellKey(): string {
return typeof crypto !== 'undefined' && 'randomUUID' in crypto ? crypto.randomUUID() : `cell-${Date.now()}-${Math.random().toString(16).slice(2)}`
}
/** A notebook that is not saved yet: one SQL cell. */
export function scratchNotebook(sql = ''): Notebook {
return { title: 'Untitled', canEdit: true, cells: [{ cellKey: newCellKey(), cellType: 'SQL', content: sql, title: null, backendName: null }] }
}
/** Every parameter a notebook's SQL cells use, with the declared ones first. */
export function notebookParameters(notebook: Notebook): string[] {
const names = (notebook.parameters ?? []).map((p) => p.name)
for (const c of notebook.cells) if (c.cellType === 'SQL') for (const n of extractParameters(c.content)) if (!names.includes(n)) names.push(n)
return names
}
/** The body of POST/PUT /notebooks for a notebook and the current parameter values. */
export function notebookRequest(notebook: Notebook, values: Record<string, string>, comment?: string): Record<string, unknown> {
return {
title: notebook.title.trim() || 'Untitled notebook',
description: notebook.description ?? null,
defaultBackendName: notebook.defaultBackendName ?? null,
parameters: notebookParameters(notebook).map((name) => {
const declared = notebook.parameters?.find((p) => p.name === name)
return { name, type: declared?.type ?? 'STRING', defaultValue: values[name] ?? declared?.defaultValue ?? null, label: declared?.label ?? null }
}),
cells: notebook.cells.map((c, i) => ({ cellKey: c.cellKey, cellType: c.cellType, title: c.title ?? null, content: c.content, backendName: c.backendName ?? null, sortOrder: i })),
...(comment ? { comment } : {}),
}
}
/** Moves a cell by `delta` places; returns its new index. */
export function moveCell(cells: NotebookCell[], index: number, delta: number): number {
const to = Math.max(0, Math.min(cells.length - 1, index + delta))
if (to === index) return index
const [cell] = cells.splice(index, 1)
cells.splice(to, 0, cell!)
return to
}
/** The one-line summary of a cell for lists: its title, else its first non-blank line. */
export function cellSummary(cell: NotebookCell): string {
if (cell.title?.trim()) return cell.title.trim()
const first = cell.content.split('\n').map((l) => (cell.cellType === 'MARKDOWN' ? l.replace(/^\s*(#{1,6}|[-*+>])\s+/, '') : l).trim()).find((l) => l) ?? ''
return first || (cell.cellType === 'SQL' ? '(empty SQL)' : '(empty notes)')
}
/** Markdown as plain text lines for the terminal: headings, bullets, quotes and code kept; inline marks dropped. */
export function markdownLines(markdown: string): Array<{ text: string; style: 'heading' | 'code' | 'quote' | 'text' }> {
const out: Array<{ text: string; style: 'heading' | 'code' | 'quote' | 'text' }> = []
let code = false
const inline = (s: string) => s.replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1').replace(/\[([^\]]+)\]\(([^)]+)\)/g, '$1 ($2)').replace(/(\*\*|__)(.+?)\1/g, '$2').replace(/(\*|_)(\S.*?)\1/g, '$2').replace(/`([^`]+)`/g, '$1')
for (const raw of markdown.split('\n')) {
if (/^\s*```/.test(raw)) {
code = !code
continue
}
if (code) {
out.push({ text: ` ${raw}`, style: 'code' })
continue
}
const h = /^(#{1,6})\s+(.*)$/.exec(raw)
if (h) out.push({ text: inline(h[2]!), style: 'heading' })
else if (/^\s*[-*+]\s+/.test(raw)) out.push({ text: raw.replace(/^(\s*)[-*+]\s+/, '$1• ').replace(/^(\s*• )(.*)$/, (_m, a: string, b: string) => a + inline(b)), style: 'text' })
else if (/^\s*>/.test(raw)) out.push({ text: `│ ${inline(raw.replace(/^\s*>\s?/, ''))}`, style: 'quote' })
else if (/^\s*([-*_])\1\1+\s*$/.test(raw)) out.push({ text: '─'.repeat(20), style: 'text' })
else out.push({ text: inline(raw), style: 'text' })
}
return out
}
+325
View File
@@ -0,0 +1,325 @@
/*
* Copyright 2026 QRun.IO, Inc.
* Licensed under the Apache License, Version 2.0 (see LICENSE).
*/
/** The SQL Runner's dialogs: notebooks (F2), cells (F4) and the execution history (F7). */
import type { Key } from '../keys'
import { charOf } from '../keys'
import { overlayId, PromptOverlay } from '../overlays/basic'
import { Frame, Line } from '../overlays/frame'
import type { AppStore } from '../store'
import { glyphs, theme } from '../theme'
import type { Overlay } from '../types'
import { errorText, pad, trunc } from '../util/text'
import { cellSummary, type Notebook } from './model'
import type { SqlRunnerScreen } from './screen'
/** One line of key help that drops whole tokens from the end when it does not fit. */
function hint(tokens: string[], width: number): string {
let out = ''
for (const t of tokens) {
const next = out ? `${out} · ${t}` : t
if (next.length + 1 > width) break
out = next
}
return ` ${out}`
}
function Row(props: { text: string; width: number; selected: boolean; fg?: string }) {
const t = theme()
return <text flexShrink={0} wrapMode="none" fg={props.selected ? t.selFg : props.fg ?? t.fg} bg={props.selected ? t.selBg : undefined}>{pad(props.text, props.width)}</text>
}
/** A scrolling list window around a cursor. */
function windowOf<T>(list: T[], cursor: number, rows: number): { top: number; shown: T[] } {
const top = Math.max(0, Math.min(cursor - Math.floor(rows / 2), list.length - rows))
return { top, shown: list.slice(top, top + rows) }
}
/** GET /notebooks summaries. */
interface NotebookSummary {
id: number
title: string
description?: string | null
visibility?: string
ownerName?: string | null
defaultBackendName?: string | null
currentVersion?: number
canEdit?: boolean
modifyDate?: string | null
}
/** F2: the notebook library (Mine and Shared), with open, new, save, save as, duplicate, delete and publish. */
export class NotebooksOverlay implements Overlay {
readonly id = overlayId('sql-notebooks')
scope: 'mine' | 'shared' = 'mine'
list: NotebookSummary[] = []
cursor = 0
loading = true
error?: string
constructor(private store: AppStore, private screen: SqlRunnerScreen) {
this.load()
}
load(): void {
this.loading = true
this.store.client!.data<{ notebooks?: NotebookSummary[] }>('sqlWorkbenchListNotebooks', { query: { scope: this.scope } }).then((d) => {
this.list = d.notebooks ?? []
this.error = undefined
const at = this.list.findIndex((n) => n.id === this.screen.notebook.id)
this.cursor = at >= 0 ? at : Math.min(this.cursor, Math.max(0, this.list.length - 1))
}).catch((e) => { this.error = errorText(e) }).finally(() => {
this.loading = false
this.store.bump()
})
}
private close(): void {
this.store.closeOverlay(this)
}
onKey(key: Key): void {
const s = this.store
const item = this.list[this.cursor]
const ch = charOf(key)
const canShare = Boolean(this.screen.caps?.canShare)
if (key.name === 'escape') return this.close()
if (key.name === 'tab' || key.name === 'left' || key.name === 'right') {
this.scope = this.scope === 'mine' ? 'shared' : 'mine'
this.cursor = 0
return this.load()
}
if (key.name === 'up') { this.cursor = Math.max(0, this.cursor - 1); return }
if (key.name === 'down') { this.cursor = Math.min(this.list.length - 1, this.cursor + 1); return }
if (key.name === 'pageup') { this.cursor = Math.max(0, this.cursor - 10); return }
if (key.name === 'pagedown') { this.cursor = Math.min(this.list.length - 1, this.cursor + 10); return }
if (key.name === 'return') {
if (!item) return
this.close()
return this.screen.openNotebook(item.id)
}
if (ch === 'n') { this.close(); return this.screen.newNotebook() }
if (ch === 's') { this.close(); return this.screen.save() }
if (ch === 'a') { this.close(); return this.screen.saveAs() }
if (ch === 'r') return this.load()
if (!item) return
if (ch === 'u') {
return s.run(s.client!.data<Notebook>('sqlWorkbenchDuplicateNotebook', { path: { id: String(item.id) }, json: {} }), (nb) => {
s.flash(`duplicated as ${nb.title}`)
this.scope = 'mine'
this.load()
})
}
if (ch === 'd') {
if (item.canEdit === false) return s.flash('only the owner can delete a notebook', 'error')
return s.confirm(`Delete the notebook ${item.title}, its cells, versions and pinned results?`, () => s.run(s.client!.call('sqlWorkbenchDeleteNotebook', { path: { id: String(item.id) } }), () => {
s.flash(`deleted ${item.title}`)
if (this.screen.notebook.id === item.id) {
this.screen.notebook = { ...this.screen.notebook, id: undefined, title: `${item.title} (deleted)` }
this.screen.edited = true
}
this.load()
}))
}
if (ch === 'p') {
if (!canShare) return s.flash('publishing needs the sql_workbench.share permission', 'error')
if (item.canEdit === false) return s.flash('only the owner can publish a notebook', 'error')
const shared = item.visibility !== 'SHARED'
return s.run(s.client!.data<Notebook>('sqlWorkbenchPublishNotebook', { path: { id: String(item.id) }, json: { shared } }), () => {
s.flash(shared ? `${item.title} is in the shared library` : `${item.title} is personal again`)
this.load()
})
}
}
render(sw: number, sh: number) {
const t = theme()
const width = Math.min(sw - 4, 100)
const iw = width - 2
const rows = Math.max(3, Math.min(Math.max(this.list.length, 3), sh - 10))
const { top, shown } = windowOf(this.list, this.cursor, rows)
const tabs = ` ${this.scope === 'mine' ? '[Mine]' : ' Mine '} ${this.scope === 'shared' ? '[Shared]' : ' Shared '} ${this.loading ? 'loading…' : `${this.list.length} notebook${this.list.length === 1 ? '' : 's'}`}`
const current = this.screen.notebook
return (
<Frame title="Notebooks" width={width} height={rows + 5} screenWidth={sw} screenHeight={sh}>
<Line text={tabs} width={iw} fg={t.acc} />
<Line text={trunc(` open: ${current.id !== undefined ? current.title : 'Untitled (not saved)'}${this.screen.edited ? ' · unsaved changes' : ''}`, iw)} width={iw} fg={t.dim} />
{shown.map((n, i) => {
const mark = n.id === current.id ? glyphs().pointer : ' '
const flags = [n.visibility === 'SHARED' ? 'shared' : '', n.canEdit === false ? `by ${n.ownerName ?? 'someone else'}` : '', n.currentVersion ? `v${n.currentVersion}` : '', n.defaultBackendName ?? ''].filter(Boolean).join(' · ')
const room = Math.max(10, iw - flags.length - 4)
return <Row key={n.id} text={` ${mark} ${pad(trunc(n.title, room), room)} ${flags}`} width={iw} selected={top + i === this.cursor} />
})}
{Array.from({ length: rows - shown.length }, (_, i) => <Line key={`e${i}`} text={i === 0 && !shown.length ? (this.error ? ` ${this.error}` : this.loading ? '' : this.scope === 'mine' ? ' (no notebooks yet: s saves this one)' : ' (nothing shared with you)') : ''} width={iw} fg={this.error ? t.err : t.dim} />)}
<Line text={hint(['Enter open', 'Tab mine/shared', 's save', 'a save as', 'n new', 'u duplicate', 'd delete', ...(this.screen.caps?.canShare ? ['p publish'] : []), 'Esc'], iw)} width={iw} fg={t.dim} />
</Frame>
)
}
}
/** F4: the notebook's cells, with go to, add, move, title, backend, delete and run all. */
export class CellsOverlay implements Overlay {
readonly id = overlayId('sql-cells')
cursor: number
constructor(private store: AppStore, private screen: SqlRunnerScreen) {
this.cursor = screen.cellIndex
}
onKey(key: Key): void {
const sc = this.screen
const cells = sc.notebook.cells
const ch = charOf(key)
if (key.name === 'escape') return this.store.closeOverlay(this)
if (key.name === 'up' && key.shift) { this.cursor = sc.moveCellBy(this.cursor, -1); return }
if (key.name === 'down' && key.shift) { this.cursor = sc.moveCellBy(this.cursor, 1); return }
if (key.name === 'up') { this.cursor = Math.max(0, this.cursor - 1); return }
if (key.name === 'down') { this.cursor = Math.min(cells.length - 1, this.cursor + 1); return }
if (key.name === 'return') {
this.store.closeOverlay(this)
sc.goCell(this.cursor)
sc.focus = 'editor'
return
}
if (ch === 'K') { this.cursor = sc.moveCellBy(this.cursor, -1); return }
if (ch === 'J') { this.cursor = sc.moveCellBy(this.cursor, 1); return }
if (ch === 'a' || ch === 'm') {
this.store.closeOverlay(this)
if (sc.cellIndex !== this.cursor) sc.goCell(this.cursor)
return sc.addCell(ch === 'a' ? 'SQL' : 'MARKDOWN')
}
if (ch === 'R') {
this.store.closeOverlay(this)
return sc.runAll()
}
if (ch === 't') {
const cell = cells[this.cursor]
return this.store.open(new PromptOverlay(this.store, `Title of cell ${this.cursor + 1}`, 'Shown in the cell list and the Next UI; empty removes it.', (v) => sc.setCellTitle(this.cursor, v), cell?.title ?? ''))
}
if (ch === 'b') {
if (cells[this.cursor]?.cellType !== 'SQL') return this.store.flash('only SQL cells run on a backend')
return sc.chooseBackend(this.cursor)
}
if (ch === 'd') {
const cell = cells[this.cursor]
if (!cell) return
return this.store.confirm(`Delete cell ${this.cursor + 1} (${trunc(cellSummary(cell), 40)})?`, () => {
sc.deleteCell(this.cursor)
this.cursor = Math.min(this.cursor, sc.notebook.cells.length - 1)
})
}
}
render(sw: number, sh: number) {
const t = theme()
const width = Math.min(sw - 4, 90)
const iw = width - 2
const cells = this.screen.notebook.cells
const rows = Math.max(3, Math.min(cells.length, sh - 9))
const { top, shown } = windowOf(cells, this.cursor, rows)
return (
<Frame title={`Cells of ${this.screen.notebook.id !== undefined ? this.screen.notebook.title : 'Untitled'}`} width={width} height={rows + 4} screenWidth={sw} screenHeight={sh}>
{shown.map((c, i) => {
const index = top + i
const backend = c.cellType === 'SQL' ? this.screen.backendOf(c) ?? '' : ''
const mark = index === this.screen.cellIndex ? glyphs().pointer : ' '
const right = `${c.cellType === 'SQL' ? 'SQL' : 'MD '} ${backend}`
const room = Math.max(8, iw - right.length - 8)
return <Row key={c.cellKey} text={` ${mark} ${String(index + 1).padStart(2)} ${pad(trunc(cellSummary(c), room), room)} ${right}`} width={iw} selected={index === this.cursor} />
})}
{Array.from({ length: rows - shown.length }, (_, i) => <Line key={`e${i}`} text="" width={iw} />)}
<Line text={hint(['Enter edit', 'a add SQL', 'm add notes', 'R run all', 'Esc'], iw)} width={iw} fg={t.dim} />
<Line text={hint(['K J or Shift+↑↓ move', 't title', 'b backend', 'd delete'], iw)} width={iw} fg={t.dim} />
</Frame>
)
}
}
/** An audited execution from GET /history. */
export interface HistoryEntry {
executionUuid?: string
backendName?: string
mode?: string
status?: string
sqlText?: string
notebookId?: number | null
startTime?: string | null
durationMs?: number | null
rowsReturned?: number | null
rowsAffected?: number | null
errorMessage?: string | null
}
/** One history entry as a line: time, status, duration, rows, mode, SQL. */
export function historyLine(e: HistoryEntry, width: number, ascii = false): string {
const d = e.startTime ? new Date(e.startTime) : undefined
const two = (n: number) => String(n).padStart(2, '0')
const time = d && !Number.isNaN(d.getTime()) ? `${two(d.getMonth() + 1)}-${two(d.getDate())} ${two(d.getHours())}:${two(d.getMinutes())}:${two(d.getSeconds())}` : '?'.padEnd(14)
const ok = e.status === 'SUCCEEDED' ? (ascii ? 'ok' : '✓') : e.status === 'RUNNING' ? '…' : (ascii ? 'x ' : '✗')
const rows = e.rowsAffected !== null && e.rowsAffected !== undefined ? `${e.rowsAffected} aff` : e.rowsReturned !== null && e.rowsReturned !== undefined ? `${e.rowsReturned} rows` : ''
const mode = e.mode && e.mode !== 'READ_ONLY' ? ` ${e.mode.toLowerCase()}` : ''
const head = `${time} ${ok} ${String(e.durationMs ?? '').padStart(5)} ms ${rows.padStart(9)}${mode} `
return trunc(head + (e.sqlText ?? '').replace(/\s+/g, ' '), width)
}
/** F7: the caller's audited executions; Enter opens the SQL, r re-runs it. */
export class HistoryOverlay implements Overlay {
readonly id = overlayId('sql-history')
cursor = 0
filter = ''
constructor(private store: AppStore, readonly entries: HistoryEntry[], private pick: (entry: HistoryEntry, rerun: boolean) => void) {}
matches(): HistoryEntry[] {
const n = this.filter.toLowerCase()
return n ? this.entries.filter((e) => (e.sqlText ?? '').toLowerCase().includes(n) || (e.status ?? '').toLowerCase().includes(n)) : this.entries
}
onKey(key: Key): void {
const list = this.matches()
if (key.name === 'escape') {
if (this.filter) { this.filter = ''; this.cursor = 0; return }
return this.store.closeOverlay(this)
}
if (key.name === 'up') { this.cursor = Math.max(0, this.cursor - 1); return }
if (key.name === 'down') { this.cursor = Math.min(list.length - 1, this.cursor + 1); return }
if (key.name === 'pageup') { this.cursor = Math.max(0, this.cursor - 10); return }
if (key.name === 'pagedown') { this.cursor = Math.min(list.length - 1, this.cursor + 10); return }
const e = list[this.cursor]
if (key.name === 'return' || (key.ctrl && key.name === 'r')) {
if (!e) return
this.store.closeOverlay(this)
return this.pick(e, key.name !== 'return')
}
if (key.name === 'backspace') { this.filter = this.filter.slice(0, -1); this.cursor = 0; return }
const ch = charOf(key)
if (ch) {
this.filter += ch
this.cursor = 0
}
}
render(sw: number, sh: number) {
const t = theme()
const width = Math.min(sw - 4, 120)
const iw = width - 2
const list = this.matches()
const rows = Math.max(3, Math.min(Math.max(list.length, 3), sh - 11))
const { top, shown } = windowOf(list, this.cursor, rows)
const e = list[this.cursor]
const ascii = Boolean(glyphs().border)
const detail = e?.errorMessage ? `error: ${e.errorMessage}` : e ? `${e.backendName ?? ''} · ${e.mode ?? ''} · ${e.status ?? ''}${e.executionUuid ? ` · ${e.executionUuid}` : ''}` : ''
return (
<Frame title="History (your audited runs)" width={width} height={rows + 5} screenWidth={sw} screenHeight={sh}>
<Line text={this.filter ? ` filter: ${this.filter}` : ' type to filter'} width={iw} fg={this.filter ? t.acc2 : t.dim} />
{shown.map((h, i) => <Row key={`${h.executionUuid ?? i}`} text={` ${historyLine(h, iw - 2, ascii)}`} width={iw} selected={top + i === this.cursor} fg={h.status === 'SUCCEEDED' ? t.fg : t.err} />)}
{Array.from({ length: rows - shown.length }, (_, i) => <Line key={`e${i}`} text={i === 0 && !shown.length ? ' (no runs yet)' : ''} width={iw} fg={t.dim} />)}
<Line text={trunc(` ${detail.replace(/\s+/g, ' ')}`, iw)} width={iw} fg={e?.errorMessage ? t.err : t.dim} />
<Line text={hint(['Enter open in the editor', 'Ctrl+R re-run', 'type to filter', 'Esc'], iw)} width={iw} fg={t.dim} />
</Frame>
)
}
}
+303
View File
@@ -0,0 +1,303 @@
/*
* Copyright 2026 QRun.IO, Inc.
* Licensed under the Apache License, Version 2.0 (see LICENSE).
*/
/**
* The SQL Runner's result side, free of drawing: typed values as text, column widths from the
* column kinds, the server-paged (and server-sorted) result over GET /executions/{uuid}/rows, the
* EXPLAIN plan as an indented tree, and quick text bar charts.
*/
import type { GridColumn } from '../screens/table'
/** A result column as the server describes it. */
export interface SqlColumn {
name: string
label?: string
typeName?: string
jdbcType?: number
kind?: 'number' | 'string' | 'boolean' | 'date' | 'datetime' | 'time' | 'json' | 'binary' | 'array' | 'other'
}
/** POST /sql-workbench/execute (read-only runs). */
export interface ExecuteResponse {
executionUuid: string
status: string
mode?: string
backendName?: string
columns?: SqlColumn[]
rows?: unknown[][]
rowCount?: number
hasMore?: boolean
truncated?: boolean
truncatedReason?: string | null
durationMs?: number
rowsAffected?: number | null
statements?: Array<{ index: number; kind: string; leadingKeyword?: string; affectedRows?: number | null }>
error?: string
sqlState?: string | null
}
/** GET /sql-workbench/executions/{uuid}/rows. */
export interface RowsResponse {
columns?: SqlColumn[]
rows?: unknown[][]
offset?: number
rowCount?: number
totalRows?: number
truncated?: boolean
}
export interface PlanNode {
label: string
detail?: string | null
startupCost?: number | null
totalCost?: number | null
planRows?: number | null
actualTimeMs?: number | null
actualRows?: number | null
loops?: number | null
extra?: Record<string, unknown>
children?: PlanNode[]
}
/** POST /sql-workbench/explain. */
export interface ExplainResponse {
executionUuid?: string
status?: string
dialect?: string
analyze?: boolean
plan?: PlanNode
raw?: string
error?: string
sqlState?: string | null
durationMs?: number | null
}
// ---- values ----
/** A value as one line of text by its column kind: NULL, `<binary N bytes>`, compact JSON, ISO dates as sent. */
export function valueText(value: unknown, kind?: SqlColumn['kind']): string {
if (value === null || value === undefined) return 'NULL'
if (typeof value === 'object' && (value as { $binary?: boolean }).$binary) return `<binary ${(value as { length?: number }).length ?? '?'} bytes>`
if (typeof value === 'object') return JSON.stringify(value)
if (kind === 'json' && typeof value === 'string') {
try {
return JSON.stringify(JSON.parse(value))
} catch {
return value
}
}
return String(value).replace(/[\r\n\t]+/g, ' ')
}
/** A value in full, for the whole-value view: pretty JSON, binary with its hex preview, text as is. */
export function fullValueText(value: unknown, kind?: SqlColumn['kind']): string {
if (value === null || value === undefined) return 'NULL'
if (typeof value === 'object' && (value as { $binary?: boolean }).$binary) {
const b = value as { length?: number; hexPreview?: string }
return `binary, ${b.length ?? '?'} bytes\nfirst bytes: ${b.hexPreview ? `0x${b.hexPreview}` : '(none)'}`
}
if (typeof value === 'object') return JSON.stringify(value, null, 2)
if (kind === 'json' && typeof value === 'string') {
try {
return JSON.stringify(JSON.parse(value), null, 2)
} catch {
return value
}
}
return String(value)
}
/** Widest a column of a kind starts (its values are cut beyond, V shows them whole). */
const KIND_CAP: Record<string, number> = { number: 20, boolean: 5, date: 10, time: 15, datetime: 27, string: 40, json: 40, array: 30, binary: 22, other: 30 }
/**
* Column widths from the column kinds and the first rows: the longer of the label and the values,
* capped per kind; spare width goes to text columns that were cut. Numbers are right-aligned.
*/
export function sqlColumns(columns: SqlColumn[], rows: unknown[][], available: number): GridColumn[] {
const cols = columns.map((c, i) => {
const label = c.label || c.name
const longest = Math.max(label.length + 1, ...rows.slice(0, 200).map((r) => valueText(r[i], c.kind).length), 4)
const cap = KIND_CAP[c.kind ?? 'other'] ?? 30
return { name: String(i), label, type: c.kind ?? 'other', numeric: c.kind === 'number', width: Math.min(cap, longest), longest }
})
let spare = available - cols.reduce((a, c) => a + c.width + 1, 0)
for (const c of [...cols].filter((x) => x.longest > x.width && !x.numeric).sort((a, b) => (a.longest - a.width) - (b.longest - b.width))) {
if (spare <= 0) break
const add = Math.min(spare, c.longest - c.width, 60 - c.width)
if (add > 0) {
c.width += add
spare -= add
}
}
return cols.map(({ longest: _l, ...c }) => c)
}
// ---- paging ----
export type FetchRows = (offset: number, limit: number, sort?: { column: number; dir: 'asc' | 'desc' }) => Promise<RowsResponse>
/**
* A server-side result read in chunks: the first chunk comes with the execute response; later rows
* load on demand through GET /executions/{uuid}/rows; sorting is the server's (type-aware, nulls
* last) and starts again from the first row.
*/
export class ResultPager {
readonly columns: SqlColumn[]
total: number
truncated: boolean
truncatedReason?: string | null
sort?: { column: number; dir: 'asc' | 'desc' }
loading = false
error?: string
private rows = new Map<number, unknown[]>()
private pending = new Set<number>()
private generation = 0
constructor(first: ExecuteResponse, private readonly fetchRows: FetchRows, readonly chunk = 100) {
this.columns = first.columns ?? []
this.total = first.rowCount ?? first.rows?.length ?? 0
this.truncated = Boolean(first.truncated)
this.truncatedReason = first.truncatedReason
;(first.rows ?? []).forEach((r, i) => this.rows.set(i, r))
}
get(index: number): unknown[] | undefined {
return this.rows.get(index)
}
/** Whether every row from `start` (count rows, within the total) is loaded. */
has(start: number, count: number): boolean {
for (let i = start; i < Math.min(this.total, start + count); i++) if (!this.rows.has(i)) return false
return true
}
/** Loads the chunks that hold rows start..start+count; resolves when they are in. */
async ensure(start: number, count: number): Promise<void> {
const chunks = new Set<number>()
for (let i = Math.max(0, start); i < Math.min(this.total, start + count); i++) if (!this.rows.has(i)) chunks.add(Math.floor(i / this.chunk))
const gen = this.generation
const loads = [...chunks].filter((c) => !this.pending.has(c)).map(async (c) => {
this.pending.add(c)
this.loading = true
try {
const data = await this.fetchRows(c * this.chunk, this.chunk, this.sort)
if (gen !== this.generation) return
;(data.rows ?? []).forEach((r, i) => this.rows.set(c * this.chunk + i, r))
if (typeof data.rowCount === 'number') this.total = data.rowCount
this.error = undefined
} catch (e) {
if (gen === this.generation) this.error = e instanceof Error ? e.message : String(e)
} finally {
this.pending.delete(c)
this.loading = this.pending.size > 0
}
})
await Promise.all(loads)
}
/** Sorts by a column: ascending, then descending, then the order of the result. */
async sortBy(column: number): Promise<void> {
if (this.sort?.column !== column) this.sort = { column, dir: 'asc' }
else if (this.sort.dir === 'asc') this.sort = { column, dir: 'desc' }
else this.sort = undefined
this.generation++
this.rows.clear()
this.pending.clear()
await this.ensure(0, this.chunk)
}
/** The loaded rows from `start` (undefined where not loaded yet). */
window(start: number, count: number): Array<unknown[] | undefined> {
const out: Array<unknown[] | undefined> = []
for (let i = start; i < Math.min(this.total, start + count); i++) out.push(this.rows.get(i))
return out
}
}
// ---- EXPLAIN ----
export interface PlanLine {
/** Path of the node (`0.1.2`), for collapsing. */
path: string
depth: number
hasChildren: boolean
collapsed: boolean
label: string
/** "cost 0.00..12.40 · rows 100 · 1.2 ms × 3" when the database reports them. */
stats: string
/** This node's total cost as a share of the most expensive node (0..1), when costs are known. */
share?: number
}
function num(n: number): string {
return Number.isInteger(n) ? n.toLocaleString('en-US') : n.toFixed(2)
}
/** The plan as lines of an indented tree: children under their parent, collapsed subtrees skipped. */
export function planLines(root: PlanNode, collapsed: Set<string> = new Set()): PlanLine[] {
let maxCost = 0
const visit = (n: PlanNode) => {
if (typeof n.totalCost === 'number') maxCost = Math.max(maxCost, n.totalCost)
for (const c of n.children ?? []) visit(c)
}
visit(root)
const out: PlanLine[] = []
const walk = (n: PlanNode, depth: number, path: string) => {
const kids = n.children ?? []
const stats: string[] = []
if (typeof n.totalCost === 'number') stats.push(`cost ${typeof n.startupCost === 'number' ? `${num(n.startupCost)}..` : ''}${num(n.totalCost)}`)
if (typeof n.planRows === 'number') stats.push(`rows ${num(n.planRows)}`)
if (typeof n.actualTimeMs === 'number') stats.push(`${num(n.actualTimeMs)} ms${typeof n.loops === 'number' && n.loops > 1 ? ` × ${n.loops}` : ''}`)
if (typeof n.actualRows === 'number') stats.push(`actual ${num(n.actualRows)}`)
const isCollapsed = collapsed.has(path)
out.push({
path, depth, hasChildren: kids.length > 0, collapsed: isCollapsed,
label: `${n.label}${n.detail ? ` ${n.detail}` : ''}`.replace(/\s+/g, ' ').trim(),
stats: stats.join(' · '),
share: maxCost > 0 && typeof n.totalCost === 'number' ? n.totalCost / maxCost : undefined,
})
if (!isCollapsed) kids.forEach((c, i) => walk(c, depth + 1, `${path}.${i}`))
}
walk(root, 0, '0')
return out
}
/** One plan line as text in a width: tree glyph and label on the left, stats and a cost bar on the right. */
export function planLineText(line: PlanLine, width: number, glyph: { open: string; closed: string; bar: string }): string {
const marker = line.hasChildren ? (line.collapsed ? glyph.closed : glyph.open) : ' '
const left = `${' '.repeat(line.depth)}${marker} ${line.label}`
const bar = line.share !== undefined ? ' ' + glyph.bar.repeat(Math.max(1, Math.round(line.share * 5))).padEnd(5, ' ') : ''
const right = line.stats ? `${line.stats}${bar}` : ''
if (!right) return left.length > width ? left.slice(0, Math.max(0, width - 1)) + '…' : left
const room = width - right.length - 2
if (room < 12) return left.length > width ? left.slice(0, Math.max(0, width - 1)) + '…' : left
const l = left.length > room ? left.slice(0, room - 1) + '…' : left.padEnd(room)
return `${l} ${right}`
}
// ---- quick charts ----
/** Columns a quick chart can plot: numeric ones. */
export function numericColumns(columns: SqlColumn[]): number[] {
return columns.map((c, i) => (c.kind === 'number' ? i : -1)).filter((i) => i >= 0)
}
/** Horizontal text bars: one line per row, label column, bar scaled to the largest magnitude, value at the end. */
export function barLines(items: Array<{ label: string; value: number }>, width: number, bar = '█'): string[] {
if (!items.length) return []
const labelWidth = Math.min(24, Math.max(...items.map((i) => i.label.length)), Math.max(4, Math.floor(width / 3)))
const values = items.map((i) => num(i.value))
const valueWidth = Math.max(...values.map((v) => v.length))
const barRoom = Math.max(1, width - labelWidth - valueWidth - 2)
const max = Math.max(...items.map((i) => Math.abs(i.value))) || 1
return items.map((it, i) => {
const label = it.label.length > labelWidth ? it.label.slice(0, labelWidth - 1) + '…' : it.label.padEnd(labelWidth)
const n = Math.round((Math.abs(it.value) / max) * barRoom)
const b = (it.value < 0 ? '-' : '') + bar.repeat(Math.max(it.value === 0 ? 0 : 1, n - (it.value < 0 ? 1 : 0)))
return `${label} ${b.padEnd(barRoom)} ${values[i]!.padStart(valueWidth)}`
})
}
File diff suppressed because it is too large. Load diff
+4 -2
View File
@@ -21,6 +21,7 @@ import { collaborationPresence, presenceSource, setPresenceSource } from './pres
import { setAscii, setTheme, theme } from './theme'
import type { FKeyLabels, Overlay, Screen } from './types'
import { errorText } from './util/text'
import { SQL_EXTENSION, hideRunnerApps } from './sql/apps'
export interface Settings {
theme: string
@@ -174,7 +175,7 @@ export class AppStore {
/** Replaces the metadata and rebuilds the search index (once per document). */
setMeta(meta: MetaDataDocument): void {
this.meta = meta
this.meta = hideRunnerApps(meta, this.extensions.has(SQL_EXTENSION))
this.index = new MetaDataIndex(meta)
}
@@ -332,6 +333,7 @@ export class AppStore {
return
}
const screen = this.screen
if (this.focus === 'content' && screen?.claimsKey?.(key) && screen.onKey(key)) return
if (key.name === 'f1') return this.commands().help()
if (this.backslash && charOf(key) === '?') {
this.backslash = false
@@ -458,8 +460,8 @@ export class AppStore {
this.refreshMetaOnConnect = false
const [version, meta] = await Promise.all([client.version(), client.metaData(refresh)])
this.version = version
this.setMeta(meta)
this.extensions.load(version)
this.setMeta(meta)
setPresenceSource(collaborationPresence(this.extensions.registry, client, this.status.user))
this.status.apiVersion = version.apiVersion
this.sidebar = this.sidebarFactory?.(this)
+2
View File
@@ -63,6 +63,8 @@ export interface Screen {
cliEquivalent?(): string | undefined
/** The view-settings dialog for this screen, when it has one. */
viewSettings?(): Overlay | undefined
/** Keys this screen takes before the global ones (F2 on the SQL Runner). */
claimsKey?(key: Key): boolean
/** Keys of this screen for the help overlay, listed before the global ones. */
helpKeys?(): Array<[string, string]>
/** The help topic: table, process or app name, for F1. */
+121
View File
@@ -0,0 +1,121 @@
/*
* Copyright 2026 QRun.IO, Inc.
* Licensed under the Apache License, Version 2.0 (see LICENSE).
*/
/**
* The sql-workbench extension on top of the fake server: /version lists it (or not), the metadata
* carries the SQL Workbench app with its Runner (a SQL_WORKBENCH widget), and /sql-workbench/*
* answers capabilities, schema, execute and rows (with server-side sort), explain, history and
* notebooks from memory.
*/
import { fakeFetch, type FakeLog } from './fake-server'
type J = Record<string, unknown>
const json = (data: unknown, status = 200) => new Response(JSON.stringify(data), { status, headers: { 'content-type': 'application/json' } })
export const CUSTOMERS = Array.from({ length: 250 }, (_, i) => [i + 1, i === 2 ? null : `Customer ${String(i + 1).padStart(3, '0')}`, `c${i + 1}@example.test`])
const SCHEMA = {
backendName: 'h2', dialect: 'h2',
schemas: [{ name: 'PUBLIC', tables: [
{ name: 'CUSTOMER', type: 'BASE TABLE', columns: [{ name: 'ID', typeName: 'INTEGER' }, { name: 'NAME', typeName: 'VARCHAR' }, { name: 'EMAIL', typeName: 'VARCHAR' }] },
{ name: 'ORDERS', type: 'BASE TABLE', columns: [{ name: 'ID', typeName: 'INTEGER' }, { name: 'CUSTOMER_ID', typeName: 'INTEGER' }, { name: 'STATUS', typeName: 'VARCHAR' }] },
] }],
qqqTables: [{ name: 'order', sqlName: 'orders', fields: [] }],
keywords: ['SELECT', 'FROM', 'QUALIFY'], functions: ['abs'],
}
const PLAN = { label: 'Plan', children: [{ label: 'SELECT', totalCost: 10, children: [{ label: 'Seq Scan CUSTOMER', totalCost: 8, planRows: 250 }] }] }
export interface SqlFakeState {
executions: Array<{ uuid: string; sql: string; params?: unknown; status: string }>
notebooks: Array<J & { id: number }>
rowsCalls: Array<Record<string, string>>
}
export const SQL_APPS = {
sqlWorkbench: { name: 'sqlWorkbench', label: 'SQL Workbench', widgets: [], children: [{ type: 'APP', name: 'sqlWorkbenchRunner', label: 'Runner' }] },
sqlWorkbenchRunner: { name: 'sqlWorkbenchRunner', label: 'Runner', widgets: ['sqlWorkbenchWidget'], children: [], helpContents: { help: [{ contentAsText: 'The notebook editor: write SQL in cells.' }] } },
}
/** A fetch: the fake server plus the SQL workbench (installed or not). */
export function sqlFakeFetch(log: FakeLog, installed: boolean, state: SqlFakeState = { executions: [], notebooks: [], rowsCalls: [] }): typeof fetch {
const base = fakeFetch(log)
return (async (input: RequestInfo | URL, init?: RequestInit) => {
const request = new Request(input as RequestInfo, init)
const url = new URL(request.url)
const path = url.pathname.replace('/qqq/v1', '')
if (path === '/version') return json({ apiVersion: '1.8.0', features: ['metaData', 'tables', 'processes'], extensions: installed ? [{ name: 'sql-workbench', version: '1.1.0', pathPrefix: '/sql-workbench' }] : [] })
if (path === '/metaData') {
const meta = await (await base(input, init)).json() as J
return json({
...meta,
apps: { ...(meta.apps as J), ...SQL_APPS },
appTree: [...(meta.appTree as unknown[]), { type: 'APP', name: 'sqlWorkbench', label: 'SQL Workbench', children: [{ type: 'APP', name: 'sqlWorkbenchRunner', label: 'Runner' }] }],
widgets: { ...(meta.widgets as J), sqlWorkbenchWidget: { name: 'sqlWorkbenchWidget', label: 'SQL Workbench', type: 'SQL_WORKBENCH' } },
})
}
if (!path.startsWith('/sql-workbench')) return base(input, init)
const body = request.method !== 'GET' && (request.headers.get('content-type') ?? '').includes('json') ? await request.json() as J : undefined
log.requests.push({ method: request.method, path, body })
const sub = path.replace('/sql-workbench', '')
if (sub === '/capabilities') return json({ version: '1.1.0', canWrite: false, canShare: true, writeModeEnabled: true, limits: { maxRows: 10000, pageSize: 500, maxPageSize: 2000, statementTimeoutSeconds: 30 }, backends: [{ name: 'h2', label: 'h2', vendor: 'h2', dialect: 'h2', readOnlyCredentials: false, readOnlyEnforced: false, writeAllowed: false }] })
if (sub === '/schema/h2') return json(SCHEMA)
if (sub === '/execute') {
const sql = String(body?.sql ?? '')
const uuid = String(body?.executionUuid ?? 'u1')
if (/FRM/.test(sql)) {
state.executions.push({ uuid, sql, status: 'FAILED' })
return json({ executionUuid: uuid, status: 'FAILED', error: `Syntax error in SQL statement "${sql.replace('FRM', '[*]FRM')}"; SQL statement:\n${sql} [42000-240]`, sqlState: '42000', durationMs: 3 })
}
if (/^\s*SELEC\b/i.test(sql)) return json({ code: 'BAD_REQUEST', message: 'Read-only sessions run exactly one read-only statement.' }, 400)
state.executions.push({ uuid, sql, params: body?.params, status: 'SUCCEEDED' })
if (/CUSTOMER/i.test(sql)) {
const size = Number(body?.pageSize ?? 500)
return json({ executionUuid: uuid, status: 'SUCCEEDED', columns: [{ name: 'ID', label: 'ID', typeName: 'INTEGER', kind: 'number' }, { name: 'NAME', label: 'NAME', typeName: 'VARCHAR', kind: 'string' }, { name: 'EMAIL', label: 'EMAIL', typeName: 'VARCHAR', kind: 'string' }], rows: CUSTOMERS.slice(0, size), rowCount: CUSTOMERS.length, hasMore: true, truncated: false, durationMs: 7 })
}
return json({ executionUuid: uuid, status: 'SUCCEEDED', columns: [{ name: '1', label: '1', typeName: 'INTEGER', kind: 'number' }], rows: [[1]], rowCount: 1, hasMore: false, truncated: false, durationMs: 2 })
}
const rows = /^\/executions\/([^/]+)\/rows$/.exec(sub)
if (rows) {
const q = Object.fromEntries(url.searchParams.entries())
state.rowsCalls.push(q)
const offset = Number(q.offset ?? 0)
const limit = Number(q.limit ?? 500)
let all = [...CUSTOMERS]
if (q.sort !== undefined) {
const c = Number(q.sort)
all.sort((a, b) => (a[c] === null ? 1 : b[c] === null ? -1 : a[c]! < b[c]! ? -1 : a[c]! > b[c]! ? 1 : 0) * (q.dir === 'desc' ? -1 : 1))
if (q.dir === 'desc') all = [...all.filter((r) => r[Number(q.sort)] !== null), ...all.filter((r) => r[Number(q.sort)] === null)]
}
return json({ rows: all.slice(offset, offset + limit), offset, rowCount: CUSTOMERS.length, truncated: false })
}
const exp = /^\/executions\/([^/]+)\/export$/.exec(sub)
if (exp) return new Response(`ID,NAME\n1,Customer 001\n`, { status: 200, headers: { 'content-type': 'text/csv' } })
if (sub === '/explain') return json({ executionUuid: 'e1', status: 'SUCCEEDED', dialect: 'h2', analyze: false, plan: PLAN, raw: 'SELECT\n ID\nFROM CUSTOMER', durationMs: 4 })
if (sub === '/history') return json({ executions: [...state.executions].reverse().map((e) => ({ executionUuid: e.uuid, backendName: 'h2', mode: 'READ_ONLY', status: e.status, sqlText: e.sql, startTime: '2026-11-01T10:00:00Z', durationMs: 3, rowsReturned: 1 })) })
if (sub === '/notebooks' && request.method === 'GET') return json({ notebooks: state.notebooks.filter((n) => (url.searchParams.get('scope') === 'shared') === (n.visibility === 'SHARED')).map(({ cells: _c, ...n }) => n) })
if (sub === '/notebooks' && request.method === 'POST') {
const nb = { ...(body as J), id: state.notebooks.length + 1, currentVersion: 1, canEdit: true, visibility: 'PERSONAL' }
state.notebooks.push(nb)
return json(nb)
}
const one = /^\/notebooks\/(\d+)$/.exec(sub)
if (one) {
const i = state.notebooks.findIndex((n) => n.id === Number(one[1]))
if (i < 0) return json({ error: 'not found' }, 404)
if (request.method === 'GET') return json(state.notebooks[i])
if (request.method === 'PUT') {
state.notebooks[i] = { ...state.notebooks[i]!, ...(body as J), currentVersion: Number(state.notebooks[i]!.currentVersion ?? 1) + 1 }
return json(state.notebooks[i])
}
if (request.method === 'DELETE') {
state.notebooks.splice(i, 1)
return json({ deleted: true })
}
}
return json({ error: `fake sql-workbench has no ${request.method} ${sub}` }, 404)
}) as typeof fetch
}
+180
View File
@@ -0,0 +1,180 @@
/*
* Copyright 2026 QRun.IO, Inc.
* Licensed under the Apache License, Version 2.0 (see LICENSE).
*/
import { expect, test } from 'bun:test'
import {
SqlBuffer, SqlHistory, cellSummary, coerceParameter, commonPrefix, complete, errorPosition, extractParameters, markdownLines, moveCell,
notebookParameters, notebookRequest, referencedTables, scratchNotebook, splitStatements, statementAt, tokenize, tokenLines, type SqlSchema,
} from '../src/sql/model'
import { hideRunnerApps, isRunnerWidget, runnerApps } from '../src/sql/apps'
const key = (name: string, extra: Partial<{ ctrl: boolean; shift: boolean; meta: boolean; sequence: string }> = {}) => ({ name, sequence: extra.sequence ?? (name.length === 1 ? name : ''), ...extra })
test('buffer: typing, new lines with indent, backspace across lines, offsets, word movement', () => {
const b = new SqlBuffer('')
for (const ch of 'SELECT 1') b.handle(key(ch === ' ' ? 'space' : ch, { sequence: ch }))
expect(b.text).toBe('SELECT 1')
b.insert('\n FROM t')
expect(b.lines).toEqual(['SELECT 1', ' FROM t'])
b.newline()
expect(b.lines[2]).toBe(' ')
expect(b.offset()).toBe(b.text.length)
b.handle(key('backspace'))
expect(b.lines[2]).toBe('')
b.handle(key('backspace'))
expect(b.lines).toEqual(['SELECT 1', ' FROM t'])
b.setOffset(3)
expect([b.row, b.col]).toEqual([0, 3])
b.handle(key('down'))
expect([b.row, b.col]).toEqual([1, 3])
b.handle(key('home'))
expect(b.col).toBe(2)
b.handle(key('home'))
expect(b.col).toBe(0)
b.handle(key('right', { ctrl: true }))
expect(b.col).toBe(6)
b.handle(key('end'))
b.handle(key('w', { ctrl: true }))
expect(b.line).toBe(' FROM ')
b.setOffset(0)
b.handle(key('left'))
expect(b.offset()).toBe(0)
b.setOffset(8)
b.handle(key('delete'))
expect(b.lines).toEqual(['SELECT 1 FROM '])
b.replaceBefore(0, 'X')
expect(b.text.startsWith('SELECT 1X')).toBe(true)
b.scrollTo(3, 5)
expect(b.left).toBeGreaterThan(0)
})
test('buffer: the word before the cursor, with a qualifier', () => {
const b = new SqlBuffer('SELECT c.NA')
expect(b.wordBefore()).toEqual({ qualifier: 'c', prefix: 'NA', from: 9 })
b.set('SELECT ')
expect(b.wordBefore().prefix).toBe('')
})
test('statements: split at ; outside strings, comments and quoted names; the one under the cursor', () => {
const sql = "SELECT 'a;b' AS x; -- c;\nSELECT \"x;y\" FROM t;\n\n SELECT 3 /* ; */"
const all = splitStatements(sql)
expect(all.map((s) => s.text)).toEqual(["SELECT 'a;b' AS x", '-- c;\nSELECT "x;y" FROM t', 'SELECT 3 /* ; */'])
expect(statementAt(sql, 3)!.text).toBe("SELECT 'a;b' AS x")
expect(statementAt(sql, sql.indexOf('FROM'))!.text).toContain('FROM t')
expect(statementAt(sql, sql.length)!.text).toBe('SELECT 3 /* ; */')
// the cursor just after a ; belongs to the statement it ends
expect(statementAt('SELECT 1;\n', 10)!.text).toBe('SELECT 1')
expect(statementAt(' ; ', 1)).toBeUndefined()
expect(statementAt('SELECT 1', 0)!.start).toBe(0)
})
test('parameters: :name in order, not inside strings, comments or :: casts; typed coercion', () => {
expect(extractParameters("SELECT :a, ':b', x::int, :a, \"c:d\" -- :e\n FROM t WHERE y > :since /* :f */ AND z = $$:g$$")).toEqual(['a', 'since'])
expect(coerceParameter('', 'INTEGER')).toBeNull()
expect(coerceParameter('42', 'INTEGER')).toBe(42)
expect(coerceParameter('x', 'DECIMAL')).toBe('x')
expect(coerceParameter('yes', 'BOOLEAN')).toBe(true)
expect(coerceParameter('007')).toBe('007')
})
test('tokens: keywords, strings, numbers, comments and params for the tint; lines split', () => {
const kinds = tokenize("SELECT name, 1.5e3 FROM t WHERE x = 'it''s' AND y = :p -- note").filter((t) => t.kind !== 'space').map((t) => `${t.kind}:${t.text}`)
expect(kinds).toEqual(['keyword:SELECT', 'ident:name', 'punct:,', 'number:1.5e3', 'keyword:FROM', 'ident:t', 'keyword:WHERE', 'ident:x', 'punct:=', "string:'it''s'", 'keyword:AND', 'ident:y', 'punct:=', 'param::p', 'comment:-- note'])
const lines = tokenLines("SELECT /* a\nb */ 1\nFROM t")
expect(lines.length).toBe(3)
expect(lines[1]![0]).toMatchObject({ kind: 'comment', text: 'b */' })
expect(lines[2]![0]).toMatchObject({ kind: 'keyword', text: 'FROM' })
expect(tokenize('QUALIFY x', new Set(['QUALIFY']))[0]!.kind).toBe('keyword')
})
const schema: SqlSchema = {
schemas: [{ name: 'PUBLIC', tables: [
{ name: 'CUSTOMER', columns: [{ name: 'ID' }, { name: 'NAME' }, { name: 'EMAIL' }] },
{ name: 'CUSTOMER_NOTE', columns: [{ name: 'ID' }, { name: 'TEXT' }] },
{ name: 'ORDERS', columns: [{ name: 'ID' }, { name: 'CUSTOMER_ID' }, { name: 'STATUS' }] },
] }],
qqqTables: [{ name: 'order', sqlName: 'orders' }],
keywords: ['SELECT', 'ORDER BY', 'OFFSET'], functions: ['ordinal_fn'],
}
test('completion: tables, columns of the statement\'s tables, alias. columns, keywords in the typed case', () => {
expect(complete('SELECT * FROM CUST', 18, schema).candidates).toEqual(['CUSTOMER', 'CUSTOMER_NOTE'])
expect(commonPrefix(['CUSTOMER', 'CUSTOMER_NOTE'])).toBe('CUSTOMER')
const sql = 'SELECT o.ST FROM ORDERS o JOIN CUSTOMER c ON c.ID = o.CUSTOMER_ID'
expect(complete(sql, 11, schema)).toEqual({ from: 9, prefix: 'ST', candidates: ['STATUS'] })
expect(complete('SELECT c. FROM CUSTOMER AS c', 9, schema).candidates).toEqual(['ID', 'NAME', 'EMAIL'])
// columns of the named tables come first, then tables (QQQ SQL names deduplicated), keywords, functions
const mixed = complete('SELECT ord FROM ORDERS', 10, schema).candidates
expect(mixed).toEqual(['ORDERS', 'order', 'ordinal_fn'])
expect(complete('SELECT e', 8, schema).candidates).toContain('end')
expect(complete('SELECT ', 7, schema).candidates).toEqual([])
expect(complete('SELECT CU', 9).candidates).toEqual([])
expect([...referencedTables('SELECT * FROM PUBLIC.ORDERS o LEFT JOIN "CUSTOMER" WHERE 1=1').entries()]).toEqual([['ORDERS', 'ORDERS'], ['O', 'ORDERS'], ['CUSTOMER', 'CUSTOMER']])
})
test('error positions: H2 [*], an EXPLAIN prefix, PostgreSQL Position, line and column, MySQL line', () => {
const sql = 'SELECT *\nFRM X'
expect(errorPosition('Syntax error in SQL statement "SELECT *\nFRM[*] X"; SQL statement:', sql)).toEqual({ offset: 12, line: 2, col: 4 })
expect(errorPosition('Syntax error in SQL statement "EXPLAIN SELECT * [*]FRM X"; SQL statement:', 'SELECT * FRM X')).toEqual({ offset: 9, line: 1, col: 10 })
expect(errorPosition('ERROR: syntax error at or near "FRM"\n Position: 10', 'SELECT * FRM X')).toEqual({ offset: 9, line: 1, col: 10 })
expect(errorPosition('error at line 3, column 7', 'x')).toEqual({ line: 3, col: 7 })
expect(errorPosition("You have an error in your SQL syntax near 'FRM' at line 1", 'x')).toEqual({ line: 1 })
expect(errorPosition('Table "NOPE" not found', 'SELECT * FROM NOPE')).toBeUndefined()
})
test('history: newest first, multi-line SQL kept, Ctrl+↑↓ steps back to the draft', () => {
const lines: string[] = []
const h = new SqlHistory({ entries: () => [...lines].reverse(), add: (l) => { lines.push(l) } })
h.add('SELECT 1')
h.add('SELECT 2\nFROM t')
h.add(' ')
expect(h.entries()).toEqual(['SELECT 2\nFROM t', 'SELECT 1'])
expect(h.step(1, 'draft')).toBe('SELECT 2\nFROM t')
expect(h.step(1, 'ignored')).toBe('SELECT 1')
expect(h.step(1, 'x')).toBeUndefined()
expect(h.step(-1, 'x')).toBe('SELECT 2\nFROM t')
expect(h.step(-1, 'x')).toBe('draft')
expect(h.step(-1, 'x')).toBeUndefined()
})
test('notebooks: scratch, parameters, the save body, moving cells, summaries, markdown as text', () => {
const nb = scratchNotebook('SELECT * FROM t WHERE a = :a')
nb.parameters = [{ name: 'limit', type: 'INTEGER', defaultValue: '10' }]
nb.cells.push({ cellKey: 'k2', cellType: 'MARKDOWN', content: '## Notes\n- one' }, { cellKey: 'k3', cellType: 'SQL', content: 'SELECT :b, :a' })
expect(notebookParameters(nb)).toEqual(['limit', 'a', 'b'])
const body = notebookRequest(nb, { a: 'x' }, 'why')
expect(body.parameters).toEqual([{ name: 'limit', type: 'INTEGER', defaultValue: '10', label: null }, { name: 'a', type: 'STRING', defaultValue: 'x', label: null }, { name: 'b', type: 'STRING', defaultValue: null, label: null }])
expect((body.cells as Array<{ sortOrder: number; cellKey: string }>).map((c) => `${c.sortOrder}:${c.cellKey}`).slice(1)).toEqual(['1:k2', '2:k3'])
expect(body.title).toBe('Untitled')
expect(body.comment).toBe('why')
expect(moveCell(nb.cells, 2, -1)).toBe(1)
expect(nb.cells.map((c) => c.cellKey).slice(1)).toEqual(['k3', 'k2'])
expect(moveCell(nb.cells, 0, -1)).toBe(0)
expect(cellSummary(nb.cells[2]!)).toBe('Notes')
expect(cellSummary({ cellKey: 'x', cellType: 'SQL', content: '\n SELECT 1\n' })).toBe('SELECT 1')
expect(cellSummary({ cellKey: 'x', cellType: 'SQL', content: '', title: 'Totals' })).toBe('Totals')
expect(markdownLines('# Title\nSome **bold** and `code` and [a link](http://x)\n- item\n> quoted\n```\nraw *text*\n```')).toEqual([
{ text: 'Title', style: 'heading' }, { text: 'Some bold and code and a link (http://x)', style: 'text' }, { text: '• item', style: 'text' },
{ text: '│ quoted', style: 'quote' }, { text: ' raw *text*', style: 'code' },
])
})
test('absent extension: the Runner apps leave the metadata; installed, nothing changes', () => {
const meta = {
apps: { sqlWorkbench: { name: 'sqlWorkbench', children: [{ type: 'APP', name: 'sqlWorkbenchRunner' }, { type: 'TABLE', name: 't' }], childMap: { sqlWorkbenchRunner: {}, t: {} } }, sqlWorkbenchRunner: { name: 'sqlWorkbenchRunner', widgets: ['w'] } },
widgets: { w: { name: 'w', type: 'SQL_WORKBENCH' } },
appTree: [{ type: 'APP', name: 'sqlWorkbench', children: [{ type: 'APP', name: 'sqlWorkbenchRunner' }, { type: 'TABLE', name: 't' }] }],
} as never
expect(runnerApps(meta)).toEqual(['sqlWorkbenchRunner'])
expect(hideRunnerApps(meta, true)).toBe(meta)
const hidden = hideRunnerApps(meta, false) as unknown as { apps: Record<string, { children?: unknown[]; childMap?: Record<string, unknown> }>; appTree: Array<{ children: Array<{ name: string }> }> }
expect(Object.keys(hidden.apps)).toEqual(['sqlWorkbench'])
expect(hidden.apps.sqlWorkbench!.children).toEqual([{ type: 'TABLE', name: 't' }])
expect(Object.keys(hidden.apps.sqlWorkbench!.childMap!)).toEqual(['t'])
expect(hidden.appTree[0]!.children.map((c) => c.name)).toEqual(['t'])
expect(runnerApps(hidden as never)).toEqual([])
expect(isRunnerWidget(meta, 'w')).toBe(true)
expect(isRunnerWidget(hidden as never, 'w')).toBe(false)
})
+122
View File
@@ -0,0 +1,122 @@
/*
* Copyright 2026 QRun.IO, Inc.
* Licensed under the Apache License, Version 2.0 (see LICENSE).
*/
import { expect, test } from 'bun:test'
import { ResultPager, barLines, fullValueText, numericColumns, planLineText, planLines, sqlColumns, valueText, type SqlColumn } from '../src/sql/results'
const cols: SqlColumn[] = [{ name: 'ID', kind: 'number' }, { name: 'NAME', kind: 'string' }]
const ALL = Array.from({ length: 250 }, (_, i) => [i + 1, `n${String(250 - i).padStart(3, '0')}`])
function fakeRows(calls: Array<{ offset: number; limit: number; sort?: string }>) {
return async (offset: number, limit: number, sort?: { column: number; dir: 'asc' | 'desc' }) => {
calls.push({ offset, limit, sort: sort ? `${sort.column}:${sort.dir}` : undefined })
const rows = [...ALL]
if (sort) rows.sort((a, b) => (a[sort.column]! < b[sort.column]! ? -1 : 1) * (sort.dir === 'asc' ? 1 : -1))
return { rows: rows.slice(offset, offset + limit), rowCount: ALL.length }
}
}
test('paging: the first chunk from execute, later chunks on demand, each once', async () => {
const calls: Array<{ offset: number; limit: number; sort?: string }> = []
const p = new ResultPager({ executionUuid: 'u', status: 'SUCCEEDED', columns: cols, rows: ALL.slice(0, 100), rowCount: 250 }, fakeRows(calls), 100)
expect(p.total).toBe(250)
expect(p.has(0, 100)).toBe(true)
expect(p.has(90, 20)).toBe(false)
expect(p.window(98, 4).map((r) => r?.[0])).toEqual([99, 100, undefined, undefined])
await p.ensure(90, 20)
expect(calls).toEqual([{ offset: 100, limit: 100, sort: undefined }])
expect(p.get(150)?.[0]).toBe(151)
await p.ensure(120, 200)
expect(calls.map((c) => c.offset)).toEqual([100, 200])
expect(p.window(248, 10).map((r) => r?.[0])).toEqual([249, 250])
await p.ensure(0, 250)
expect(calls.length).toBe(2)
})
test('sorting: the server sorts; asc, desc, then the result order, from the first row again', async () => {
const calls: Array<{ offset: number; limit: number; sort?: string }> = []
const p = new ResultPager({ executionUuid: 'u', status: 'SUCCEEDED', columns: cols, rows: ALL.slice(0, 100), rowCount: 250 }, fakeRows(calls), 100)
await p.sortBy(1)
expect(p.sort).toEqual({ column: 1, dir: 'asc' })
expect(p.get(0)).toEqual([250, 'n001'])
expect(p.has(100, 1)).toBe(false)
await p.sortBy(1)
expect(p.get(0)).toEqual([1, 'n250'])
await p.sortBy(1)
expect(p.sort).toBeUndefined()
await p.sortBy(0)
expect(calls.map((c) => c.sort)).toEqual(['1:asc', '1:desc', undefined, '0:asc'])
})
test('paging: a failed chunk keeps the error and can be loaded again', async () => {
let fail = true
const p = new ResultPager({ executionUuid: 'u', status: 'SUCCEEDED', columns: cols, rows: [], rowCount: 10 }, async () => {
if (fail) throw new Error('result expired')
return { rows: [[1, 'a']], rowCount: 10 }
}, 100)
await p.ensure(0, 5)
expect(p.error).toBe('result expired')
fail = false
await p.ensure(0, 5)
expect(p.error).toBeUndefined()
expect(p.get(0)).toEqual([1, 'a'])
})
test('values by kind: NULL, binary, JSON, line breaks; whole values pretty', () => {
expect(valueText(null)).toBe('NULL')
expect(valueText({ $binary: true, length: 40, hexPreview: 'ff' })).toBe('<binary 40 bytes>')
expect(valueText('{"a": 1}', 'json')).toBe('{"a":1}')
expect(valueText([1, 2], 'array')).toBe('[1,2]')
expect(valueText('a\nb', 'string')).toBe('a b')
expect(valueText(true, 'boolean')).toBe('true')
expect(fullValueText('{"a":1}', 'json')).toBe('{\n "a": 1\n}')
expect(fullValueText({ $binary: true, length: 3, hexPreview: '0a0b0c' })).toBe('binary, 3 bytes\nfirst bytes: 0x0a0b0c')
})
test('column widths from kinds: capped per kind, numbers right-aligned, spare width to cut text', () => {
const columns: SqlColumn[] = [{ name: 'ID', kind: 'number' }, { name: 'OK', kind: 'boolean' }, { name: 'D', kind: 'date' }, { name: 'TXT', kind: 'string' }]
const rows = [[123456789012345678901234, true, '2026-11-01', 'x'.repeat(80)]]
const narrow = sqlColumns(columns, rows, 60)
expect(narrow.map((c) => c.width)).toEqual([20, 4, 10, 40])
expect(narrow.map((c) => c.numeric)).toEqual([true, false, false, false])
const wide = sqlColumns(columns, rows, 200)
expect(wide[3]!.width).toBe(60)
expect(sqlColumns([{ name: 'A_LONG_LABEL', kind: 'number' }], [[1]], 80)[0]!.width).toBe(13)
expect(numericColumns(columns)).toEqual([0])
})
test('plan tree: indented lines, costs and a relative bar, collapsing a subtree', () => {
const plan = { label: 'Limit', totalCost: 12.4, startupCost: 0, planRows: 100, children: [
{ label: 'Sort', totalCost: 10.3, startupCost: 10.1, planRows: 412, children: [{ label: 'Seq Scan', detail: 'web_user', totalCost: 7.1, planRows: 9120, actualTimeMs: 1.25, loops: 3 }] },
{ label: 'Filter', detail: null, children: [] },
] }
const lines = planLines(plan)
expect(lines.map((l) => `${l.depth}:${l.label}`)).toEqual(['0:Limit', '1:Sort', '2:Seq Scan web_user', '1:Filter'])
expect(lines[0]!.stats).toBe('cost 0..12.40 · rows 100')
expect(lines[2]!.stats).toBe('cost 7.10 · rows 9,120 · 1.25 ms × 3')
expect(lines[0]!.share).toBe(1)
expect(lines[3]!.share).toBeUndefined()
const g = { open: '▾', closed: '▸', bar: '█' }
const text = planLineText(lines[1]!, 60, g)
expect(text.length).toBe(60)
expect(text.startsWith(' ▾ Sort')).toBe(true)
expect(text.endsWith('cost 10.10..10.30 · rows 412 ████ ')).toBe(true)
expect(planLineText(lines[3]!, 60, g)).toBe(' Filter')
const folded = planLines(plan, new Set(['0.0']))
expect(folded.map((l) => l.label)).toEqual(['Limit', 'Sort', 'Filter'])
expect(planLineText(folded[1]!, 20, g)).toBe(' ▸ Sort')
// H2: a text plan with no costs is a plain indented tree
expect(planLines({ label: 'Plan', children: [{ label: 'SELECT', children: [{ label: 'X' }] }] }).map((l) => planLineText(l, 30, g))).toEqual(['▾ Plan', ' ▾ SELECT', ' X'])
})
test('quick chart bars: scaled to the largest value, labels cut, negatives marked', () => {
const lines = barLines([{ label: 'North', value: 10 }, { label: 'South region long name', value: 5 }, { label: 'West', value: -2.5 }], 40)
expect(lines.every((l) => l.length === 40)).toBe(true)
expect(lines[0]).toMatch(/^North\s+█+ +10$/)
expect((lines[0]!.match(/█/g) ?? []).length).toBe(2 * (lines[1]!.match(/█/g) ?? []).length)
expect(lines[1]!.startsWith('South region')).toBe(true)
expect(lines[2]).toMatch(/-█+ +-2\.50$/)
expect(barLines([], 40)).toEqual([])
})
+241
View File
@@ -0,0 +1,241 @@
/*
* Copyright 2026 QRun.IO, Inc.
* Licensed under the Apache License, Version 2.0 (see LICENSE).
*/
import { afterEach, beforeAll, expect, test } from 'bun:test'
import { mkdtempSync, readFileSync, readdirSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { testRender } from '@opentui/react/test-utils'
import { KeyCodes } from '@opentui/core/testing'
import { writeFilePreferences } from '@qrun-io/qqq-core'
import { App } from '../src/app'
import { boot, parseArgs } from '../src/boot'
import { SqlRunnerScreen } from '../src/sql/screen'
import type { FakeLog } from './fake-server'
import { sqlFakeFetch, type SqlFakeState } from './fake-sql'
import { command, isolate, press, sessionSecrets, waitFor, type Harness } from './helpers'
let h: Harness | undefined
beforeAll(() => isolate())
afterEach(() => {
h?.store.dispose()
h?.setup.renderer.destroy()
h = undefined
})
async function start(installed: boolean, width = 120, height = 36, state?: SqlFakeState): Promise<Harness> {
const log: FakeLog = { requests: [] }
const store = boot({ args: parseArgs(['--profile', 'fake']), quit: () => undefined, build: 'test', secrets: sessionSecrets, fetch: sqlFakeFetch(log, installed, state) })
const setup = await testRender(<App store={store} />, { width, height })
const harness: Harness = { setup, store, log, frame: () => setup.captureCharFrame() }
await waitFor(harness, (f) => f.includes('Home') && harness.store.screen?.kind === 'home' && Boolean(harness.store.meta))
return harness
}
const key = (k: keyof typeof KeyCodes | string, mods?: { ctrl?: boolean; shift?: boolean; meta?: boolean }) => press(h!, () => h!.setup.mockInput.pressKey(k as never, mods))
const type = (t: string) => press(h!, () => h!.setup.mockInput.typeText(t))
const paste = (t: string) => press(h!, () => h!.setup.mockInput.pasteBracketedText(t))
const runner = () => h!.store.screen as SqlRunnerScreen
/** No frame line is wider than the terminal (the clipping rule). */
const fits = (frame: string, width: number) => frame.split('\n').every((l) => [...l].length <= width)
test('without the sql-workbench extension: the Runner app is hidden, :sql says what is missing, no menu entry', async () => {
h = await start(false)
const apps = h.store.meta!.apps as Record<string, unknown>
expect(apps.sqlWorkbenchRunner).toBeUndefined()
expect(apps.sqlWorkbench).toBeDefined()
expect(JSON.stringify(h.store.meta!.appTree)).not.toContain('sqlWorkbenchRunner')
expect((h.store.meta!.widgets as Record<string, unknown>).sqlWorkbenchWidget).toBeUndefined()
expect(h.store.commands() && (h.store.commandsImpl!(h.store) as unknown as { entries(t: string): Array<{ label: string }> }).entries('').some((e) => e.label === 'SQL Runner')).toBe(false)
await command(h, 'sql')
const f = await waitFor(h, (x) => x.includes('needs the sql-workbench extension'))
expect(f).toContain('SQL Runner needs the sql-workbench')
expect(h.store.screen?.kind).toBe('home')
await command(h, 'app sqlWorkbenchRunner')
await waitFor(h, (x) => x.includes('no app named "sqlWorkbenchRunner"'))
expect(h.log.requests.some((r) => r.path.startsWith('/sql-workbench'))).toBe(false)
})
test('the Runner opens from its app, :sql, the palette and F9 › Work; SELECT 1 and a real table query with paging and sort', async () => {
const state: SqlFakeState = { executions: [], notebooks: [], rowsCalls: [] }
h = await start(true, 120, 36, state)
// F9 › Work and the palette list it
const entries = (h.store.commandsImpl!(h.store) as unknown as { entries(t: string): Array<{ label: string; section: string }> }).entries('')
expect(entries.find((e) => e.label === 'SQL Runner')?.section).toBe('Work')
// the search (F2 or /): the SQL Workbench widget hit opens the Runner (never `widget get`)
await key('F2')
await type('sql')
let f = await waitFor(h, (x) => x.includes('SQL Runner') && x.includes('SQL Workbench'))
await press(h, () => h!.setup.mockInput.pressEnter())
f = await waitFor(h, (x) => x.includes('SQL · cell 1/1 · h2') && x.includes('READ-ONLY'))
expect(h.store.screen?.kind).toBe('sql')
await key('ESCAPE')
expect(h.store.screen?.kind).toBe('home')
// the app tree: the Runner app opens the screen
await command(h, 'app sqlWorkbenchRunner')
await waitFor(h, () => h!.store.screen?.kind === 'sql')
await key('ESCAPE')
await command(h, 'sql')
await waitFor(h, (x) => x.includes('Write SQL above'))
await type('SELECT 1')
await key('F5')
f = await waitFor(h, (x) => x.includes('1 row · 2 ms · h2 · read-only · limit 10,000'))
expect(state.executions.at(-1)).toMatchObject({ sql: 'SELECT 1' })
// a real table: 250 rows, the first chunk with the execute, the rest paged from the server
runner().focus = 'editor'
runner().buffer.set('')
await paste('SELECT ID, NAME, EMAIL\nFROM CUSTOMER')
// Ctrl+J: what terminals without the kitty protocol can send for "run" (Ctrl+Enter arrives as Enter there)
await key('j', { ctrl: true })
f = await waitFor(h, (x) => x.includes('250 rows') && x.includes('Customer 001'))
expect(f).toContain('NULL')
expect(f).toMatch(/ID\s+NAME\s+EMAIL/)
expect(runner().focus).toBe('results')
for (let i = 0; i < 4; i++) await key('\x1b[6~')
f = await waitFor(h, (x) => x.includes('row 69') && x.includes('Customer 085'))
await key('END')
f = await waitFor(h, (x) => x.includes('row 250') && x.includes('Customer 250') && !x.includes('loading…'))
expect(state.rowsCalls.map((c) => c.offset)).toEqual(['200'])
await key('HOME')
// sort by NAME (server-side): descending puts NULL last
await key('ARROW_RIGHT')
await type('s')
await type('s')
f = await waitFor(h, (x) => x.includes('sort NAME desc') && x.includes('Customer 250'))
expect(state.rowsCalls.at(-1)).toMatchObject({ sort: '1', dir: 'desc', offset: '0' })
// V: the whole value
await type('V')
f = await waitFor(h, (x) => x.includes('NAME (VARCHAR), row 1'))
await key('ESCAPE')
// F1: the screen's keys first
await key('F1')
f = await waitFor(h, (x) => x.includes('run the statement under the cursor'))
await key('ESCAPE')
})
test('errors inline with the position, EXPLAIN as a tree, completion, schema insert, history, notebooks, export, cells, at 80×24', async () => {
const dir = mkdtempSync(join(tmpdir(), 'qqq-sqlexp-'))
writeFilePreferences({ downloadDir: dir, downloadMode: 'silent' })
const state: SqlFakeState = { executions: [], notebooks: [], rowsCalls: [] }
h = await start(true, 80, 24, state)
await command(h, 'sql SELECT * FRM CUSTOMER')
let f = await waitFor(h, (x) => x.includes('FAILED (SQLSTATE 42000) at line 1, col 10'))
expect(fits(f, 80)).toBe(true)
expect(runner().focus).toBe('editor')
// a 400 from the classifier is shown the same way
runner().buffer.set('SELEC 1')
await key('F5')
f = await waitFor(h, (x) => x.includes('Read-only sessions run exactly one'))
// completion: the table, then its columns through the alias
runner().buffer.set('SELECT * FROM CUST')
await key('TAB')
expect(runner().buffer.text).toBe('SELECT * FROM CUSTOMER')
runner().buffer.set('SELECT c.NA FROM CUSTOMER c')
runner().buffer.setOffset(11)
await key('TAB')
expect(runner().buffer.text).toBe('SELECT c.NAME FROM CUSTOMER c')
// EXPLAIN: the plan as an indented tree with costs
await key('F6')
f = await waitFor(h, (x) => x.includes('Plan') && x.includes('▾ SELECT') && x.includes('Seq Scan CUSTOMER'))
expect(f).toMatch(/Seq Scan CUSTOMER\s+cost 8 · rows 250/)
expect(fits(f, 80)).toBe(true)
await type('r')
f = await waitFor(h, (x) => x.includes('FROM CUSTOMER') && x.includes('raw text'))
// F3: the schema pane; filter, Enter on a column inserts it
runner().focus = 'editor'
runner().buffer.set('SELECT ')
await key('F3')
f = await waitFor(h, (x) => x.includes('Schema') && x.includes('ORDERS'))
expect(fits(f, 80)).toBe(true)
await type('STAT')
await key('ARROW_DOWN')
await key('ARROW_RIGHT')
await key('ARROW_DOWN')
await key('ARROW_DOWN')
await key('ARROW_DOWN')
await key('ARROW_DOWN')
await press(h, () => h!.setup.mockInput.pressEnter())
expect(runner().buffer.text).toBe('SELECT STATUS')
expect(runner().focus).toBe('editor')
// F7: history; Enter opens the SQL as a new cell
await key('F7')
f = await waitFor(h, (x) => x.includes('History') && x.includes('SELECT * FRM CUSTOMER'))
expect(fits(f, 80)).toBe(true)
await press(h, () => h!.setup.mockInput.pressEnter())
expect(runner().notebook.cells.length).toBe(2)
expect(runner().buffer.text).toBe('SELECT * FRM CUSTOMER')
// F4: cells; add a markdown cell, rendered as text below
await key('F4')
f = await waitFor(h, (x) => x.includes('Cells of Untitled') && x.includes('SELECT STATUS'))
expect(fits(f, 80)).toBe(true)
await type('m')
await paste('## Totals\n- per **customer**')
f = await waitFor(h, (x) => x.includes('Notes (markdown)') && x.includes('• per customer'))
// F2: save as a new notebook
await key('F2')
f = await waitFor(h, (x) => x.includes('Notebooks') && x.includes('[Mine]'))
expect(fits(f, 80)).toBe(true)
await type('a')
await type('Smoke book')
await press(h, () => h!.setup.mockInput.pressEnter())
f = await waitFor(h, (x) => x.includes('saved as Smoke book'))
expect(state.notebooks[0]).toMatchObject({ title: 'Smoke book' })
expect((state.notebooks[0]!.cells as unknown[]).length).toBe(3)
expect(runner().edited).toBe(false)
expect(f).toContain('Smoke book')
// run a real query, then export through the file flow (silent download)
runner().goCell(0)
runner().buffer.set('SELECT * FROM CUSTOMER')
await key('F5')
f = await waitFor(h, (x) => x.includes('250 rows'))
expect(fits(f, 80)).toBe(true)
expect(state.executions.at(-1)).toMatchObject({ sql: 'SELECT * FROM CUSTOMER' })
await type('x')
await press(h, () => h!.setup.mockInput.pressEnter())
await waitFor(h, (x) => x.includes('Wrote'))
const file = readdirSync(dir).find((n) => n.endsWith('.csv'))!
expect(readFileSync(join(dir, file), 'utf8')).toContain('Customer 001')
await key('ESCAPE')
// chart view: text bars of the number column
await type('c')
f = await waitFor(h, (x) => x.includes('Chart') && x.includes('█'))
expect(fits(f, 80)).toBe(true)
// the save is a new version (PUT) once the notebook exists
runner().focus = 'editor'
await type(' ')
await key('F2')
await type('s')
await waitFor(h, (x) => x.includes('saved Smoke book, version 2'))
// leaving with unsaved changes asks first
await type(' ')
await key('ESCAPE')
await waitFor(h, (x) => x.includes('Leave the SQL Runner?'))
await type('n')
expect(h.store.screen?.kind).toBe('sql')
})
test('parameters are asked for, bound as values and remembered; run all stops at a failing cell', async () => {
const state: SqlFakeState = { executions: [], notebooks: [], rowsCalls: [] }
h = await start(true, 100, 30, state)
await command(h, 'sql')
await waitFor(h, () => h!.store.screen?.kind === 'sql')
await type('SELECT * FROM CUSTOMER WHERE ID > :minId')
await key('F5')
await waitFor(h, (x) => x.includes('Value for :minId'))
await type('5')
await press(h, () => h!.setup.mockInput.pressEnter())
await waitFor(h, (x) => x.includes('250 rows'))
expect(state.executions.at(-1)!.params).toEqual({ minId: '5' })
runner().focus = 'editor'
await key('F5')
await waitFor(h, () => state.executions.length === 2)
expect(state.executions.at(-1)!.params).toEqual({ minId: '5' })
runner().addCell('SQL', 'SELECT * FRM X')
runner().addCell('SQL', 'SELECT 1')
runner().runAll()
await waitFor(h, (x) => x.includes('run all stopped at cell 2 (1 ran)'))
expect(runner().cellIndex).toBe(1)
expect(state.executions.map((e) => e.sql)).toEqual(['SELECT * FROM CUSTOMER WHERE ID > :minId', 'SELECT * FROM CUSTOMER WHERE ID > :minId', 'SELECT * FROM CUSTOMER WHERE ID > :minId', 'SELECT * FRM X'])
})