@deckbuilderkit/sql-ui 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@deckbuilderkit/sql-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adrianogpena/deckbuilder.git",
+    "directory": "packages/sql-ui"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@deckbuilderkit/editor": "0.1.1",
+    "@deckbuilderkit/ui": "0.1.1"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "@types/react-dom": "^18.3.1"
+  }
+}

package/src/PlanView.tsx

@@ -0,0 +1,96 @@
+import { copyText, Icon, useToast } from '@deckbuilderkit/ui';
+import { t } from './i18n';
+import type { DbPlanRow } from './types';
+
+const operationOf = (r: DbPlanRow) => (r.options ? `${r.operation} ${r.options}` : r.operation);
+const objectOf = (r: DbPlanRow) => (r.objectName ? (r.objectOwner ? `${r.objectOwner}.${r.objectName}` : r.objectName) : '');
+const num = (n: number | null) => (n === null ? '' : String(n));
+
+/** The id of the step with the highest cost, leaving out the root (its cost is the total). */
+export function costliestStep(rows: DbPlanRow[]): number | undefined {
+  let best: DbPlanRow | undefined;
+  for (const r of rows) {
+    if (r.parentId === null || r.cost === null) continue;
+    if (!best || r.cost > (best.cost ?? -1)) best = r;
+  }
+  return best?.id;
+}
+
+/** A fixed-width text plan in the style of DBMS_XPLAN, with the predicates below the table. */
+export function planText(rows: DbPlanRow[]): string {
+  const head = [t('workbench.plan.id'), t('workbench.plan.operation'), t('workbench.plan.object'), t('workbench.plan.rows'), t('workbench.plan.bytes'), t('workbench.plan.cost')];
+  const body = rows.map((r) => [String(r.id), `${' '.repeat(r.depth)}${operationOf(r)}`, objectOf(r), num(r.cardinality), num(r.bytes), num(r.cost)]);
+  const widths = head.map((h, i) => Math.max(h.length, ...body.map((cells) => cells[i].length)));
+  const right = new Set([0, 3, 4, 5]);
+  const line = (cells: string[]) => `| ${cells.map((c, i) => (right.has(i) ? c.padStart(widths[i]) : c.padEnd(widths[i]))).join(' | ')} |`;
+  const rule = `${'-'.repeat(widths.reduce((sum, w) => sum + w + 3, 1))}`;
+  const out = [rule, line(head), rule, ...body.map(line), rule];
+  const predicates = rows.flatMap((r) => [
+    ...(r.accessPredicates ? [`${String(r.id).padStart(3)} - access(${r.accessPredicates})`] : []),
+    ...(r.filterPredicates ? [`${String(r.id).padStart(3)} - filter(${r.filterPredicates})`] : []),
+  ]);
+  if (predicates.length > 0) out.push('', `${t('workbench.plan.predicates')}:`, ...predicates);
+  return out.join('\n');
+}
+
+interface Props {
+  rows: DbPlanRow[];
+  onClose?: () => void;
+}
+
+/** An EXPLAIN PLAN as an indented tree, the costliest step marked. */
+export function PlanView({ rows, onClose }: Props) {
+  const toast = useToast();
+  const hot = costliestStep(rows);
+  const copy = async () => {
+    const ok = await copyText(planText(rows));
+    toast({ message: t(ok ? 'workbench.plan.copied' : 'workbench.log.copyFailed') });
+  };
+  return (
+    <div className="wb-plan">
+      <div className="row wb-plan-bar">
+        <span className="mono-label">{t('workbench.plan.title')}</span>
+        <button className="btn btn-sm" onClick={copy} disabled={rows.length === 0}>
+          <Icon name="copy" /> {t('workbench.plan.copy')}
+        </button>
+        {onClose && <button className="btn btn-sm" onClick={onClose}>{t('workbench.plan.close')}</button>}
+      </div>
+      {rows.length === 0 ? (
+        <p className="muted wb-plan-empty">{t('workbench.plan.empty')}</p>
+      ) : (
+        <div className="wb-plan-scroll">
+          <table className="wb-plan-table">
+            <thead>
+              <tr>
+                <th className="num">{t('workbench.plan.id')}</th>
+                <th>{t('workbench.plan.operation')}</th>
+                <th>{t('workbench.plan.object')}</th>
+                <th className="num">{t('workbench.plan.rows')}</th>
+                <th className="num">{t('workbench.plan.bytes')}</th>
+                <th className="num">{t('workbench.plan.cost')}</th>
+              </tr>
+            </thead>
+            <tbody>
+              {rows.map((r) => {
+                const predicates = [r.accessPredicates && `access(${r.accessPredicates})`, r.filterPredicates && `filter(${r.filterPredicates})`].filter(Boolean).join('\n');
+                return (
+                  <tr key={r.id} className={r.id === hot ? 'wb-plan-hot' : undefined} title={r.id === hot ? [t('workbench.plan.costliest'), predicates].filter(Boolean).join('\n') : predicates || undefined}>
+                    <td className="num">{r.id}</td>
+                    <td style={{ paddingLeft: 6 + r.depth * 16 }}>
+                      {operationOf(r)}
+                      {predicates && <span className="wb-plan-pred"> *</span>}
+                    </td>
+                    <td>{objectOf(r)}</td>
+                    <td className="num">{num(r.cardinality)}</td>
+                    <td className="num">{num(r.bytes)}</td>
+                    <td className="num">{num(r.cost)}</td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/SqlResults.tsx

@@ -0,0 +1,43 @@
+import { DataTable, OutputPanel, SplitView } from '@deckbuilderkit/ui';
+import { PlanView } from './PlanView';
+import { type useSqlRunner } from './useSqlRunner';
+
+export const DEFAULT_RESULTS: [number, number] = [0.65, 0.35];
+
+type Runner = ReturnType<typeof useSqlRunner>;
+
+interface Props {
+  runner: Pick<Runner, 'shown' | 'cols' | 'tableRows' | 'selection' | 'setSelection' | 'lines' | 'clearLog'> & Partial<Pick<Runner, 'plan' | 'closePlan'>>;
+  sizes: [number, number];
+  onSizes: (sizes: [number, number]) => void;
+  widths?: Record<string, number>;
+  onWidths?: (widths: Record<string, number>) => void;
+}
+
+/** The result table (or the latest execution plan) beside the output log. Column widths are only passed for the demo rows; database results size per run. */
+export function SqlResults({ runner, sizes, onSizes, widths, onWidths }: Props) {
+  const { shown, cols, tableRows, selection, setSelection, lines, clearLog, plan, closePlan } = runner;
+  return (
+    <SplitView direction="row" sizes={sizes} defaultSizes={DEFAULT_RESULTS} onResize={(s) => onSizes([s[0], s[1]])}>
+      <div key="table" className="wb-pane">
+        {plan ? (
+          <PlanView rows={plan} onClose={closePlan} />
+        ) : (
+          <DataTable
+            key={shown.kind === 'db' ? shown.run : 'demo'}
+            columns={cols}
+            rows={tableRows}
+            rowKey={(r) => r.key}
+            selection={selection}
+            onSelectionChange={setSelection}
+            widths={widths}
+            onWidthsChange={onWidths}
+          />
+        )}
+      </div>
+      <div key="output" className="wb-pane">
+        <OutputPanel lines={lines} onClear={clearLog} />
+      </div>
+    </SplitView>
+  );
+}

package/src/copy-format.ts

@@ -0,0 +1,68 @@
+import { toCsv, toTsv } from '@deckbuilderkit/ui/table';
+
+export const COPY_FORMATS = ['tsv', 'csv', 'markdown', 'json', 'insert'] as const;
+export type CopyFormat = (typeof COPY_FORMATS)[number];
+
+export interface CopyColumn<T> {
+  label: string;
+  /** The cell as displayed (used by tsv, csv and markdown). */
+  text: (row: T) => string;
+  /** The raw cell value (used by json and insert). */
+  raw: (row: T) => unknown;
+  /** `'number'` columns are written unquoted by `insert`; unknown types are quoted. */
+  type?: string;
+}
+
+export const DEFAULT_TABLE_NAME = 'table_name';
+
+const SIMPLE_SELECT = /^\s*select\b[\s\S]*?\bfrom\s+((?:"[^"]+"|[\w$#]+)(?:\s*\.\s*(?:"[^"]+"|[\w$#]+))?)\s*(?:where\b|order\b|group\b|having\b|fetch\b|;|$)/i;
+
+/** The table of a simple `select ... from <name>` statement, else `table_name`. */
+export function tableOf(sql: string | undefined): string {
+  if (!sql) return DEFAULT_TABLE_NAME;
+  const m = SIMPLE_SELECT.exec(sql);
+  return m ? m[1]!.replace(/\s*\.\s*/g, '.') : DEFAULT_TABLE_NAME;
+}
+
+const mdCell = (text: string) => text.replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\r\n|\r|\n/g, '<br>');
+
+const toMarkdown = <T>(cols: CopyColumn<T>[], rows: readonly T[]): string => {
+  const line = (cells: string[]) => `| ${cells.map(mdCell).join(' | ')} |`;
+  return [line(cols.map((c) => c.label)), line(cols.map(() => '---')), ...rows.map((r) => line(cols.map((c) => c.text(r))))].join('\n');
+};
+
+const toJson = <T>(cols: CopyColumn<T>[], rows: readonly T[]): string =>
+  JSON.stringify(rows.map((r) => Object.fromEntries(cols.map((c) => [c.label, c.raw(r) ?? null]))), null, 2);
+
+const NUMERIC = /^[+-]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i;
+
+/** One SQL literal: null → NULL, numbers bare only in a number column, anything else single-quoted. */
+export function sqlLiteral(value: unknown, type?: string): string {
+  if (value === null || value === undefined) return 'NULL';
+  if (typeof value === 'boolean') return value ? '1' : '0';
+  const text = typeof value === 'object' ? JSON.stringify(value) : String(value);
+  if (type === 'number' && NUMERIC.test(text)) return text;
+  return `'${text.replace(/'/g, "''")}'`;
+}
+
+const toInserts = <T>(cols: CopyColumn<T>[], rows: readonly T[], table: string): string => {
+  const names = cols.map((c) => c.label).join(', ');
+  return rows.map((r) => `INSERT INTO ${table} (${names}) VALUES (${cols.map((c) => sqlLiteral(c.raw(r), c.type)).join(', ')});`).join('\n');
+};
+
+/** The clipboard text of `rows` in `format`. */
+export function formatCopy<T>(format: CopyFormat, cols: CopyColumn<T>[], rows: readonly T[], sql?: string): string {
+  const display = cols.map((c) => ({ label: c.label, value: c.text }));
+  switch (format) {
+    case 'csv':
+      return toCsv(display, rows);
+    case 'markdown':
+      return toMarkdown(cols, rows);
+    case 'json':
+      return toJson(cols, rows);
+    case 'insert':
+      return toInserts(cols, rows, tableOf(sql));
+    default:
+      return toTsv(display, rows);
+  }
+}

package/src/destructive.ts

@@ -0,0 +1,14 @@
+const stripNoise = (sql: string) =>
+  sql
+    .replace(/--[^\n]*/g, ' ')
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/'(?:[^']|'')*'/g, "''")
+    .replace(/"(?:[^"]|"")*"/g, '""');
+
+/** True when a statement drops or truncates, or deletes or updates without a WHERE. Comments and string contents are ignored. */
+export function isDestructive(sql: string): boolean {
+  const text = stripNoise(sql).trim().replace(/;+\s*$/, '');
+  if (/^(drop|truncate)\b/i.test(text)) return true;
+  if (/^(delete|update)\b/i.test(text)) return !/\bwhere\b/i.test(text);
+  return false;
+}

package/src/export-results.ts

@@ -0,0 +1,25 @@
+import { type ExportColumn, toCsv } from '@deckbuilderkit/ui';
+import { t } from './i18n';
+import type { SqlClient } from './types';
+
+export type ExportFormat = 'csv' | 'json';
+
+export const EXPORT_ROWS = 10_000;
+
+export function toJson<T>(columns: ExportColumn<T>[], rows: T[]): string {
+  const objects = rows.map((row) => Object.fromEntries(columns.map((c) => [c.label, c.value(row) ?? null])));
+  return JSON.stringify(objects, null, 2);
+}
+
+/**
+ * Asks where to save, then writes the first `EXPORT_ROWS` rows as CSV or JSON.
+ * Returns the toast message, or undefined when the dialog was cancelled.
+ */
+export async function exportResults<T>(client: SqlClient, format: ExportFormat, columns: ExportColumn<T>[], rows: T[], truncated: boolean): Promise<string | undefined> {
+  const { path } = await client.saveTarget(format);
+  if (!path) return undefined;
+  const slice = rows.slice(0, EXPORT_ROWS);
+  await client.saveDemo(path, format === 'json' ? toJson(columns, slice) : toCsv(columns, slice));
+  const partial = truncated || rows.length > EXPORT_ROWS;
+  return t(partial ? 'workbench.exported.partial' : 'workbench.exported', { count: slice.length, path });
+}

package/src/i18n.ts

@@ -0,0 +1,78 @@
+import { createT, type Messages } from '@deckbuilderkit/ui';
+
+export const en = {
+  'workbench.destructive.title': 'Run destructive statement?',
+  'workbench.destructive.body': 'This statement drops data or changes every row:',
+  'workbench.destructive.run': 'Run',
+  'workbench.log.timeout': 'No answer after {seconds} s; stopped waiting. The statement may still be running on the server.',
+  'workbench.log.explain': 'Explaining: {query}',
+  'workbench.log.explained': 'Plan: {count} steps',
+  'workbench.log.explainDemo': 'Explain needs a database connection.',
+  'workbench.plan.title': 'Execution plan',
+  'workbench.plan.id': 'Id',
+  'workbench.plan.operation': 'Operation',
+  'workbench.plan.object': 'Object',
+  'workbench.plan.cost': 'Cost',
+  'workbench.plan.rows': 'Rows',
+  'workbench.plan.bytes': 'Bytes',
+  'workbench.plan.predicates': 'Predicates',
+  'workbench.plan.costliest': 'Costliest step',
+  'workbench.plan.empty': 'The plan is empty.',
+  'workbench.plan.copy': 'Copy as text',
+  'workbench.plan.copied': 'Plan copied',
+  'workbench.plan.close': 'Show rows',
+  'workbench.exported': 'Exported {count} rows to {path}',
+  'workbench.exported.partial': 'Exported only the first {count} loaded rows to {path}',
+  'workbench.log.copied': 'Copied {count} rows',
+  'workbench.log.copyFailed': 'The clipboard refused the copy.',
+  'workbench.log.start': 'Running: {query}',
+  'workbench.log.progress': '{count} rows received',
+  'workbench.log.done': 'Done: {count} rows',
+  'workbench.log.cancelled': 'Cancelled after {count} rows',
+  'workbench.log.truncated': 'Showing the first {count} rows; the result has more.',
+  'workbench.log.affected': '{count} rows affected',
+  'workbench.log.executed': 'Statement executed',
+  'workbench.log.committed': 'Committed',
+  'workbench.log.rolledBack': 'Rolled back',
+  'workbench.log.disconnected': 'Disconnected',
+};
+
+export type SqlMessageKey = keyof typeof en;
+export const t = createT<SqlMessageKey>();
+
+export const ptBR: Messages<typeof en> = {
+  'workbench.destructive.title': 'Rodar comando destrutivo?',
+  'workbench.destructive.body': 'Este comando apaga dados ou altera todas as linhas:',
+  'workbench.destructive.run': 'Rodar',
+  'workbench.log.timeout': 'Sem resposta após {seconds} s; parei de esperar. O comando pode continuar rodando no servidor.',
+  'workbench.log.explain': 'Explicando: {query}',
+  'workbench.log.explained': 'Plano: {count} passos',
+  'workbench.log.explainDemo': 'Explicar exige uma conexão com banco de dados.',
+  'workbench.plan.title': 'Plano de execução',
+  'workbench.plan.id': 'Id',
+  'workbench.plan.operation': 'Operação',
+  'workbench.plan.object': 'Objeto',
+  'workbench.plan.cost': 'Custo',
+  'workbench.plan.rows': 'Linhas',
+  'workbench.plan.bytes': 'Bytes',
+  'workbench.plan.predicates': 'Predicados',
+  'workbench.plan.costliest': 'Passo mais caro',
+  'workbench.plan.empty': 'O plano está vazio.',
+  'workbench.plan.copy': 'Copiar como texto',
+  'workbench.plan.copied': 'Plano copiado',
+  'workbench.plan.close': 'Mostrar linhas',
+  'workbench.exported': '{count} linhas exportadas para {path}',
+  'workbench.exported.partial': 'Apenas as primeiras {count} linhas carregadas foram exportadas para {path}',
+  'workbench.log.copied': '{count} linhas copiadas',
+  'workbench.log.copyFailed': 'A área de transferência recusou a cópia.',
+  'workbench.log.start': 'Executando: {query}',
+  'workbench.log.progress': '{count} linhas recebidas',
+  'workbench.log.done': 'Concluído: {count} linhas',
+  'workbench.log.cancelled': 'Cancelado após {count} linhas',
+  'workbench.log.truncated': 'Mostrando as primeiras {count} linhas; o resultado tem mais.',
+  'workbench.log.affected': '{count} linhas afetadas',
+  'workbench.log.executed': 'Comando executado',
+  'workbench.log.committed': 'Confirmado (commit)',
+  'workbench.log.rolledBack': 'Desfeito (rollback)',
+  'workbench.log.disconnected': 'Desconectado',
+};

package/src/index.ts

@@ -0,0 +1,9 @@
+export { COPY_FORMATS, type CopyColumn, type CopyFormat, formatCopy } from './copy-format';
+export { isDestructive } from './destructive';
+export { EXPORT_ROWS, type ExportFormat, exportResults } from './export-results';
+export { en as sqlEn, ptBR as sqlPtBR, type SqlMessageKey } from './i18n';
+export { PlanView } from './PlanView';
+export { DEFAULT_RESULTS, SqlResults } from './SqlResults';
+export * from './types';
+export { type Shown, type SqlRunnerSettings, type TableRow, useSqlRunner } from './useSqlRunner';
+export { type TableDetailsEntry, useSqlSchema, useTableDetails } from './useSqlSchema';

package/src/types.ts

@@ -0,0 +1,98 @@
+export interface DemoRow {
+  id: number;
+  name: string;
+  amount: number;
+  date: string;
+}
+
+export interface DbStatus {
+  connected: boolean;
+  /** Uncommitted changes may exist. */
+  pending: boolean;
+  busy: boolean;
+}
+
+export interface DbColumn {
+  name: string;
+  type: 'number' | 'text' | 'date' | 'binary';
+  /** A TIMESTAMP column (also reported as type `date`). */
+  timestamp?: boolean;
+}
+
+export interface DbSchemaTable {
+  name: string;
+  kind: 'table' | 'view';
+  columns: Array<{ name: string; type: string; nullable: boolean }>;
+}
+
+export interface DbSchema {
+  owner: string;
+  owners: string[];
+  tables: DbSchemaTable[];
+  truncated: boolean;
+}
+
+export interface DbTableIndex {
+  name: string;
+  unique: boolean;
+  columns: string[];
+}
+
+export interface DbTableConstraint {
+  name: string;
+  /** Primary key, unique, foreign key (references), check. */
+  type: 'P' | 'U' | 'R' | 'C';
+  columns: string[];
+  condition?: string;
+  references?: { owner: string; table: string; constraint: string; columns: string[] };
+}
+
+export interface DbTableDetails {
+  owner: string;
+  name: string;
+  indexes: DbTableIndex[];
+  constraints: DbTableConstraint[];
+  ddl: string | null;
+}
+
+/** One step of an EXPLAIN PLAN, as PLAN_TABLE holds it. */
+export interface DbPlanRow {
+  id: number;
+  parentId: number | null;
+  depth: number;
+  operation: string;
+  options: string | null;
+  objectOwner: string | null;
+  objectName: string | null;
+  cost: number | null;
+  cardinality: number | null;
+  bytes: number | null;
+  accessPredicates: string | null;
+  filterPredicates: string | null;
+}
+
+export type DbRunResult = { kind: 'rows'; run: string; columns: DbColumn[] } | { kind: 'done'; rowsAffected?: number };
+
+/** A saved database connection; the password is never returned, only whether one is stored. */
+export interface DbConnection {
+  id: string;
+  name: string;
+  url: string;
+  user: string;
+  password?: { hasSecret: true };
+}
+
+/** The server calls the SQL hooks make; the app builds it from its api and passes it to each hook. */
+export interface SqlClient {
+  connections: () => Promise<DbConnection[]>;
+  saveTarget: (format: 'csv' | 'json') => Promise<{ path: string | null }>;
+  saveDemo: (path: string, text: string) => Promise<unknown>;
+  dbRun: (id: string, sql: string, maxRows?: number) => Promise<DbRunResult>;
+  dbExplain: (id: string, sql: string) => Promise<DbPlanRow[]>;
+  dbTable: (id: string, owner: string, name: string) => Promise<DbTableDetails>;
+  dbSchema: (id: string, owner?: string) => Promise<DbSchema>;
+  dbCommit: (id: string) => Promise<DbStatus>;
+  dbRollback: (id: string) => Promise<DbStatus>;
+  dbDisconnect: (id: string) => Promise<DbStatus>;
+  dbStatus: (id: string) => Promise<DbStatus>;
+}

package/src/useSqlRunner.ts

@@ -0,0 +1,306 @@
+import { createElement, useEffect, useMemo, useRef, useState } from 'react';
+import { type RunMode, splitStatements } from '@deckbuilderkit/editor';
+import { type ApiError, type DataTableColumn, type OutputLine, type ResultFormat, copyText, errorMessage, errorOf, formatCell, useStream } from '@deckbuilderkit/ui';
+import { type CopyColumn, type CopyFormat, formatCopy } from './copy-format';
+import { isDestructive } from './destructive';
+import { t } from './i18n';
+import type { DbColumn, DbPlanRow, DbStatus, DemoRow, SqlClient } from './types';
+
+const ROW_COUNT = 50_000;
+const MAX_STREAM_ITEMS = 100_001;
+const PROGRESS_EVERY = 10_000;
+const BANNER_CODES = ['dbLogin', 'dbUnreachable'];
+
+export interface TableRow {
+  key: string;
+  cells: unknown[];
+}
+
+/** What the table shows: nothing yet, the demo rows, or the columns of one database result. */
+export type Shown = { kind: 'none' } | { kind: 'demo' } | { kind: 'db'; run: string; columns: DbColumn[] };
+
+const demoColumns = (): DataTableColumn<TableRow>[] => [
+  { id: 'id', label: 'id', width: 80, value: (r) => r.cells[0], align: 'right' },
+  { id: 'name', label: 'name', width: 200, value: (r) => r.cells[1] },
+  { id: 'amount', label: 'amount', width: 120, value: (r) => r.cells[2], align: 'right' },
+  { id: 'date', label: 'date', width: 140, value: (r) => r.cells[3] },
+];
+
+const dbTableColumns = (columns: DbColumn[], format: ResultFormat): DataTableColumn<TableRow>[] =>
+  columns.map((c, i) => {
+    const cell = (r: TableRow) => formatCell(r.cells[i], c.type, format, c.timestamp ? 'timestamp' : 'date');
+    return {
+      id: `c${i}`,
+      label: c.name,
+      width: c.type === 'number' ? 120 : 160,
+      value: (r) => r.cells[i],
+      render: (r) => {
+        const { text, dim } = cell(r);
+        return dim ? createElement('span', { className: 'dtable-null' }, text) : text;
+      },
+      copy: (r) => cell(r).text,
+      align: c.type === 'number' ? 'right' : 'left',
+    };
+  });
+
+const demoCells = (r: DemoRow) => [r.id, r.name, r.amount, r.date];
+const isTruncatedMarker = (item: unknown) => typeof item === 'object' && item !== null && !Array.isArray(item) && '$truncated' in item;
+
+type Confirm = (opts: { title: string; body?: string; okLabel?: string; danger?: boolean }) => Promise<boolean>;
+
+/** Rejects with a timeout error after `seconds` (never, when 0), leaving `promise` running. */
+function withTimeout<T>(promise: Promise<T>, seconds: number): Promise<T> {
+  if (seconds <= 0) return promise;
+  let timer: ReturnType<typeof setTimeout>;
+  const limit = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(t('workbench.log.timeout', { seconds }))), seconds * 1000);
+  });
+  return Promise.race([promise, limit]).finally(() => clearTimeout(timer));
+}
+
+/** What the runner reads from the app's settings; the app resolves the defaults. */
+export interface SqlRunnerSettings {
+  /** Most rows a database query returns. */
+  maxRows: number;
+  results: ResultFormat;
+  /** Format of `copy`; TSV when omitted. */
+  copyFormat?: CopyFormat;
+  /** Ask `confirm` before a destructive statement; needs `confirm`. */
+  confirmDestructive?: boolean;
+  /** Seconds to wait for a database statement; 0 or omitted means no limit. */
+  queryTimeout?: number;
+}
+
+/** Runs SQL on connection `db` (the demo rows when undefined) and holds the result table, the log and the transaction state. */
+export function useSqlRunner(client: SqlClient, db: string | undefined, settings: SqlRunnerSettings, confirm?: Confirm) {
+  const [lines, setLines] = useState<OutputLine[]>([]);
+  const [actionError, setActionError] = useState<ApiError>();
+  const [selection, setSelection] = useState<string[]>([]);
+  const [shown, setShown] = useState<Shown>({ kind: 'none' });
+  const [starting, setStarting] = useState(false);
+  const [status, setStatus] = useState<DbStatus>();
+  const [plan, setPlan] = useState<DbPlanRow[]>();
+  const [explaining, setExplaining] = useState(false);
+  const rows = useStream<unknown>({ maxItems: MAX_STREAM_ITEMS });
+  const cancelled = useRef(false);
+  const reported = useRef(0);
+  const wasRunning = useRef(false);
+  const lastSql = useRef<string>();
+
+  const maxRows = settings.maxRows;
+
+  const log = (text: string, tone?: OutputLine['tone']) => setLines((l) => [...l, { text, tone, at: Date.now() }]);
+
+  const truncated = rows.items.length > 0 && isTruncatedMarker(rows.items[rows.items.length - 1]);
+  const tableRows = useMemo<TableRow[]>(() => {
+    if (shown.kind === 'none') return [];
+    const body = truncated ? rows.items.slice(0, -1) : rows.items;
+    return body.map((item, i) => ({ key: String(i), cells: shown.kind === 'demo' ? demoCells(item as DemoRow) : (item as unknown[]) }));
+  }, [rows.items, shown, truncated]);
+
+  const cols = useMemo(() => (shown.kind === 'db' ? dbTableColumns(shown.columns, settings.results) : demoColumns()), [shown, settings.results]);
+
+  const refreshStatus = () => {
+    if (db) client.dbStatus(db).then(setStatus, () => {});
+  };
+
+  useEffect(() => {
+    setStatus(undefined);
+    refreshStatus();
+    window.addEventListener('focus', refreshStatus);
+    return () => window.removeEventListener('focus', refreshStatus);
+    // Deps are deliberately partial.
+  }, [db]);
+
+  const fail = (err: unknown) => {
+    const error = errorOf(err);
+    log(errorMessage(error), 'err');
+    if (error.code && BANNER_CODES.includes(error.code)) setActionError(error);
+  };
+
+  const begin = () => {
+    cancelled.current = false;
+    reported.current = 0;
+    setActionError(undefined);
+    setSelection([]);
+    setPlan(undefined);
+  };
+
+  const runDemo = (sql: string) => {
+    begin();
+    log(t('workbench.log.start', { query: sql.trim() }));
+    setShown({ kind: 'demo' });
+    rows.start('/api/demo/rows', { count: ROW_COUNT });
+  };
+
+  /** Runs the statements in order, each logged; stops at the first error. Only the last result set is shown. */
+  const runDb = async (id: string, statements: string[]) => {
+    begin();
+    setStarting(true);
+    try {
+      for (const [i, sql] of statements.entries()) {
+        log(t('workbench.log.start', { query: sql.trim() }));
+        lastSql.current = sql;
+        const last = i === statements.length - 1;
+        const result = await withTimeout(client.dbRun(id, sql, maxRows), settings.queryTimeout ?? 0);
+        if (result.kind === 'rows' && last) {
+          setShown({ kind: 'db', run: result.run, columns: result.columns });
+          rows.start('/api/db/rows', { run: result.run });
+        } else if (result.kind === 'rows') {
+          log(t('workbench.log.executed'), 'ok');
+        } else {
+          if (last) setShown({ kind: 'none' });
+          log(result.rowsAffected === undefined ? t('workbench.log.executed') : t('workbench.log.affected', { count: result.rowsAffected }), 'ok');
+        }
+      }
+      refreshStatus();
+    } catch (err) {
+      fail(err);
+      refreshStatus();
+    } finally {
+      setStarting(false);
+    }
+  };
+
+  const run = async (text: string, mode: RunMode) => {
+    if (rows.running || starting) return;
+    if (!db) {
+      runDemo(text);
+      return;
+    }
+    const statements = mode === 'all' ? splitStatements(text).map((s) => s.text) : [text];
+    if (statements.length === 0 || statements.every((s) => !s.trim())) return;
+    const risky = statements.filter(isDestructive);
+    if (risky.length > 0 && confirm && settings.confirmDestructive) {
+      const ok = await confirm({
+        title: t('workbench.destructive.title'),
+        body: `${t('workbench.destructive.body')}\n${risky.map((s) => s.trim()).join('\n')}`.slice(0, 600),
+        okLabel: t('workbench.destructive.run'),
+        danger: true,
+      });
+      if (!ok) return;
+    }
+    void runDb(db, statements);
+  };
+
+  /** Shows the execution plan of `text` without running it: no rows, no history entry, no transaction change. */
+  const explain = async (text: string) => {
+    if (rows.running || starting || explaining || !text.trim()) return;
+    if (!db) {
+      log(t('workbench.log.explainDemo'), 'warn');
+      return;
+    }
+    setActionError(undefined);
+    setExplaining(true);
+    log(t('workbench.log.explain', { query: text.trim() }));
+    try {
+      const steps = await withTimeout(client.dbExplain(db, text), settings.queryTimeout ?? 0);
+      setPlan(steps);
+      log(t('workbench.log.explained', { count: steps.length }), 'ok');
+    } catch (err) {
+      fail(err);
+    } finally {
+      setExplaining(false);
+    }
+  };
+
+  const cancel = () => {
+    cancelled.current = true;
+    rows.cancel();
+  };
+
+  /** Cancels and empties the table, e.g. when the connection changes. */
+  const reset = () => {
+    cancel();
+    setActionError(undefined);
+    setSelection([]);
+    setPlan(undefined);
+    setShown({ kind: 'none' });
+  };
+
+  // Progress lines every 10 000 rows, then one line when the stream ends.
+  useEffect(() => {
+    while (rows.running && tableRows.length >= reported.current + PROGRESS_EVERY) {
+      reported.current += PROGRESS_EVERY;
+      log(t('workbench.log.progress', { count: reported.current }));
+    }
+    if (wasRunning.current && !rows.running) {
+      if (cancelled.current) log(t('workbench.log.cancelled', { count: tableRows.length }), 'warn');
+      else if (rows.error) fail(rows.error);
+      else {
+        log(t('workbench.log.done', { count: tableRows.length }), 'ok');
+        if (truncated) log(t('workbench.log.truncated', { count: tableRows.length }), 'warn');
+      }
+      refreshStatus();
+    }
+    wasRunning.current = rows.running;
+    // Deps are deliberately partial.
+  }, [tableRows.length, rows.running]);
+
+  const finishTransaction = async (op: 'commit' | 'rollback') => {
+    if (!db) return;
+    setActionError(undefined);
+    try {
+      setStatus(await (op === 'commit' ? client.dbCommit(db) : client.dbRollback(db)));
+      log(t(op === 'commit' ? 'workbench.log.committed' : 'workbench.log.rolledBack'), 'ok');
+    } catch (err) {
+      fail(err);
+    }
+  };
+
+  /** Copies the selected rows (all when none is selected) in the copy format setting, and logs the outcome. */
+  const copy = async () => {
+    const chosen = new Set(selection);
+    const picked = selection.length > 0 ? tableRows.filter((r) => chosen.has(r.key)) : tableRows;
+    const columns: CopyColumn<TableRow>[] = cols.map((c, i) => ({
+      label: c.label,
+      text: (r) => String((c.copy ?? c.value)(r) ?? ''),
+      raw: (r) => r.cells[i],
+      type: shown.kind === 'db' ? shown.columns[i]?.type : undefined,
+    }));
+    if (await copyText(formatCopy(settings.copyFormat ?? 'tsv', columns, picked, lastSql.current))) log(t('workbench.log.copied', { count: picked.length }), 'ok');
+    else log(t('workbench.log.copyFailed'), 'err');
+  };
+
+  /** Cancels the running query and closes the connection; the caller confirms a pending transaction first. */
+  const disconnect = async () => {
+    if (!db) return;
+    cancel();
+    try {
+      setStatus(await client.dbDisconnect(db));
+      log(t('workbench.log.disconnected'), 'ok');
+    } catch (err) {
+      fail(err);
+    }
+  };
+
+  return {
+    run,
+    explain,
+    explaining,
+    plan,
+    closePlan: () => setPlan(undefined),
+    cancel,
+    reset,
+    busy: rows.running || starting,
+    running: rows.running,
+    starting,
+    shown,
+    cols,
+    tableRows,
+    truncated,
+    selection,
+    setSelection,
+    lines,
+    log,
+    clearLog: () => setLines([]),
+    actionError,
+    setActionError,
+    status,
+    refreshStatus,
+    commit: () => finishTransaction('commit'),
+    rollback: () => finishTransaction('rollback'),
+    disconnect,
+    copy,
+  };
+}

package/src/useSqlSchema.ts

@@ -0,0 +1,134 @@
+import { useEffect, useMemo, useState, useSyncExternalStore } from 'react';
+import { type ApiError, errorOf } from '@deckbuilderkit/ui';
+import type { DbSchema, DbTableDetails, SqlClient } from './types';
+
+interface Entry {
+  data?: DbSchema;
+  error?: ApiError;
+  loading: boolean;
+}
+
+const IDLE: Entry = { loading: false };
+const entries = new Map<string, Entry>();
+const requests = new Map<string, number>();
+const listeners = new Set<() => void>();
+
+const keyOf = (db: string, owner: string | undefined) => `${db}\n${owner ?? ''}`;
+
+const subscribe = (listener: () => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+const store = (key: string, entry: Entry) => {
+  entries.set(key, entry);
+  listeners.forEach((listener) => listener());
+};
+
+/** Fetches the schema into the cache; a newer request for the same key wins. The old data stays until the new one arrives. */
+const fetchSchema = (client: SqlClient, db: string, owner: string | undefined) => {
+  const key = keyOf(db, owner);
+  const request = (requests.get(key) ?? 0) + 1;
+  requests.set(key, request);
+  store(key, { data: entries.get(key)?.data, loading: true });
+  client.dbSchema(db, owner).then(
+    (data) => {
+      if (requests.get(key) === request) store(key, { data, loading: false });
+    },
+    (err) => {
+      if (requests.get(key) === request) store(key, { data: entries.get(key)?.data, error: errorOf(err), loading: false });
+    },
+  );
+};
+
+const ensure = (client: SqlClient, db: string, owner: string | undefined) => {
+  const entry = entries.get(keyOf(db, owner));
+  if (!entry || (!entry.data && !entry.loading)) fetchSchema(client, db, owner);
+};
+
+/** Schema of connection `db` (which connects), cached per connection and owner, shared by every consumer. */
+export function useSqlSchema(client: SqlClient, db: string | undefined) {
+  const [owner, setOwner] = useState<string>();
+  const key = db ? keyOf(db, owner) : undefined;
+  const entry = useSyncExternalStore(subscribe, () => (key ? (entries.get(key) ?? IDLE) : IDLE));
+
+  useEffect(() => {
+    if (db) ensure(client, db, owner);
+  }, [db, owner]);
+
+  const sqlSchema = useMemo(() => {
+    const out: Record<string, string[]> = {};
+    for (const table of entry.data?.tables ?? []) out[table.name] = table.columns.map((c) => c.name);
+    return out;
+  }, [entry.data]);
+
+  return {
+    schema: entry.data,
+    loading: !!db && (entry.loading || (!entry.data && !entry.error)),
+    error: entry.error,
+    owner,
+    setOwner,
+    reload: () => {
+      if (!db) return;
+      dropDetails(db);
+      fetchSchema(client, db, owner);
+    },
+    sqlSchema,
+  };
+}
+
+export interface TableDetailsEntry {
+  data?: DbTableDetails;
+  error?: ApiError;
+  loading: boolean;
+}
+
+const details = new Map<string, TableDetailsEntry>();
+const inflight = new Map<string, Promise<DbTableDetails | undefined>>();
+let detailsVersion = 0;
+const detailsKey = (db: string, owner: string, name: string) => `${db}\n${owner}\n${name}`;
+
+const storeDetails = (key: string, entry: TableDetailsEntry) => {
+  details.set(key, entry);
+  detailsVersion++;
+  listeners.forEach((listener) => listener());
+};
+
+const dropDetails = (db: string) => {
+  for (const key of details.keys()) if (key.startsWith(`${db}\n`)) details.delete(key);
+  detailsVersion++;
+  listeners.forEach((listener) => listener());
+};
+
+/** Indexes, constraints and DDL per table of connection `db`, fetched once on `load` and cached until the schema reloads. */
+export function useTableDetails(client: SqlClient, db: string | undefined) {
+  useSyncExternalStore(subscribe, () => detailsVersion);
+  return {
+    get: (owner: string, name: string) => (db ? details.get(detailsKey(db, owner, name)) : undefined),
+    /** Resolves with the details, or undefined when they failed (the entry then holds the error). */
+    load: (owner: string, name: string): Promise<DbTableDetails | undefined> => {
+      if (!db) return Promise.resolve(undefined);
+      const key = detailsKey(db, owner, name);
+      const entry = details.get(key);
+      if (entry?.data) return Promise.resolve(entry.data);
+      const pending = inflight.get(key);
+      if (pending) return pending;
+      storeDetails(key, { loading: true });
+      const request = client.dbTable(db, owner, name).then(
+        (data) => {
+          storeDetails(key, { data, loading: false });
+          return data;
+        },
+        (err) => {
+          storeDetails(key, { error: errorOf(err), loading: false });
+          return undefined;
+        },
+      );
+      inflight.set(key, request);
+      void request.finally(() => inflight.delete(key));
+      return request;
+    },
+  };
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.