pgkiln 0.49.0 → 0.50.0

package/src/builder/worksheet.ts

@@ -17,6 +17,7 @@ import { formatSql } from '../sqlformat.ts';
 import { planView } from './plan-view.ts';
 import { unloadStatement } from '../unload.ts';
 import { recordChanges } from '../changelog.ts';
+import { accountRun, beginTxn, endAllTxns, endTxn, findTxn, outsideTxnOnly, txnIdleSeconds, txnNote, txnState, clearTxnNote, type WorksheetTxn } from '../worksheet-txn.ts';
 
 // (sprint 91, Database Actions DA-1/DA-2) The SQL Worksheet: one screen with a navigator (schema, object
 // type, filter; tables and views open to their columns and give SELECT / INSERT / UPDATE / DELETE
@@ -217,6 +218,47 @@ function outputPanes(run: WorksheetRun | null, mode: RunMode | null, history: Hi
   return { panes: { result, chart: chart ?? html`<p class="muted">Create Chart (Ctrl+F11) draws the last query: a label column and number columns.</p>`, output: log, notices, explain: planOf('explain', 'Explain Plan (F10) shows how PostgreSQL would run the statement at the cursor; nothing runs.'), autotrace: planOf('autotrace', 'Autotrace (F6) runs the statement at the cursor with EXPLAIN ANALYZE and rolls it back: actual rows, time and buffers per step.'), history: hist }, active, status };
 }
 
+/** (sprint 107) The idle timeout in words. */
+const idleLabel = () => {
+  const sec = txnIdleSeconds();
+  return sec % 60 ? `${sec} seconds` : `${sec / 60} minute${sec === 60 ? '' : 's'}`;
+};
+
+/** (sprint 107) The transaction badge's text (public/worksheet.js writes the same after a reload or a tab switch). */
+export function txnBadge(state: 'open' | 'aborted' | 'none', statements: number, startedMs: number | null, note: string | null): string {
+  if (state === 'none') return note ?? 'No open transaction';
+  const min = startedMs ? Math.floor((Date.now() - startedMs) / 60_000) : 0;
+  const age = min < 1 ? 'under a minute' : `${min} min`;
+  return `${state === 'aborted' ? 'Transaction failed' : 'Transaction open'} · ${statements} statement${statements === 1 ? '' : 's'} · ${age}`;
+}
+
+/** (sprint 107) Commit or Rollback a worksheet tab's transaction (the toolbar's buttons, and the JSON endpoint). */
+async function finishTxn(req: Req, s: Session, tab: string, t: WorksheetTxn | undefined, action: 'commit' | 'rollback'): Promise<{ ok: boolean; message: string; busy?: boolean }> {
+  if (!t) return { ok: false, message: 'This worksheet has no open transaction.' };
+  if (t.busy) return { ok: false, busy: true, message: 'A run is still going on in this worksheet: wait for it to finish.' };
+  const n = t.statements;
+  const failed = txnState(t) === 'aborted';
+  const ended = await endTxn(t, action);
+  clearTxnNote(s.id, tab);
+  if (ended.ddl.length) await recordChanges({ workspaceId: t.workspaceId, author: s.username ?? '?', source: 'worksheet', defaultSchema: t.defaultSchema, statements: ended.ddl });
+  await logActivity({ username: s.username, event: 'sql_command', ip: clientIp(req), detail: ended.tag.toLowerCase() });
+  if (ended.error) return { ok: false, message: `${action.toUpperCase()} failed: ${ended.error}. The connection was closed, so the transaction is rolled back.` };
+  if (action === 'commit' && ended.tag !== 'COMMIT') return { ok: false, message: 'The transaction had failed, so COMMIT rolled it back: nothing was saved.' };
+  const what = `${n} statement${n === 1 ? '' : 's'}`;
+  return { ok: true, message: action === 'commit' ? `Committed (${what}).` : `Rolled back (${what} undone${failed ? '; the transaction had failed' : ''}).` };
+}
+
+/** (sprint 107) A tab's transaction as JSON, for the badge after a reload or a tab switch. */
+function txnStatus(s: Session, tab: string) {
+  const t = findTxn(s.id, tab);
+  const state = t && t.workspaceId === currentWorkspace(s) ? txnState(t) : 'none';
+  const note = state === 'none' ? txnNote(s.id, tab) : null;
+  return {
+    state, statements: t?.statements ?? 0, startedMs: t?.startedMs ?? null, lastMs: t?.lastMs ?? null, idleSeconds: txnIdleSeconds(),
+    runsAs: t?.runsAs ?? null, note, badge: txnBadge(state, t?.statements ?? 0, t?.startedMs ?? null, note), now: Date.now(),
+  };
+}
+
 /** The applications whose database role a run can take (the developer's workspace). */
 async function runAsApps(s: Session) {
   return (await owner.query<{ id: number; name: string; db_role: string }>(
@@ -339,7 +381,22 @@ async function worksheet(req: Req, reply: FastifyReply) {
       return {};
     }
   })();
-  if (isPost && text.trim() && !['nav', 'save', 'save_as', 'rename', 'download'].includes(String(body.mode ?? ''))) {
+  // (sprint 107, DA-2) transaction mode: the worksheet tab's open transaction (bound to this session)
+  const txnAsked = isPost && body.txn === 'on';
+  let txn: WorksheetTxn | undefined = tabKey ? findTxn(s.id, tabKey) : undefined;
+  let txnError = '';
+  let txnInfo = '';
+  if (txn && txn.workspaceId !== currentWorkspace(s)) {
+    await endTxn(txn, 'rollback', 'You switched workspaces: the transaction was rolled back.');
+    txn = undefined;
+  }
+  if (isPost && (body.mode === 'commit' || body.mode === 'rollback')) {
+    const done = await finishTxn(req, s, tabKey, txn, body.mode === 'commit' ? 'commit' : 'rollback');
+    if (!done.busy) txn = undefined;
+    if (done.ok) txnInfo = done.message;
+    else txnError = done.message;
+  }
+  if (isPost && text.trim() && !['nav', 'save', 'save_as', 'rename', 'download', 'commit', 'rollback'].includes(String(body.mode ?? ''))) {
     const m: RunMode = MODES.find((x) => x === body.mode) ?? 'statement';
     const allRows = body.mode === 'statement_all';
     chartAsked = body.mode === 'chart';
@@ -362,34 +419,88 @@ async function worksheet(req: Req, reply: FastifyReply) {
       ...x,
       sql: applyBinds(applySubstitutions(x.sql, Object.fromEntries(subs.map((n) => [n, value('sub', n)]))), Object.fromEntries(binds.map((n) => [n, value('bind', n)]))),
     }));
+    const explaining = m === 'explain' || m === 'autotrace';
+    // (sprint 107) which connection: the tab's transaction (open, or opened now), or one of its own
+    const useTxn = statements.length > 0 && txnAsked && (!explaining || (!!txn && txnState(txn) !== 'none'));
     if (statements.length) {
+      const blocked = txnAsked && !explaining ? statements.find((x) => !x.psql && outsideTxnOnly(x.sql)) : undefined;
+      if (txn && !txnAsked) txnError = 'This worksheet has an open transaction: Commit or Rollback it first, or switch back to Transaction.';
+      else if (txnAsked && !tabKey) txnError = 'Transaction mode needs JavaScript (the worksheet tab it belongs to); this run was refused.';
+      else if (txn && (asApp?.id ?? null) !== txn.asAppId) txnError = `This worksheet's transaction runs as ${txn.runsAs}: Commit or Rollback it before changing Run as.`;
+      else if (txn?.busy) txnError = 'A run is still going on in this worksheet: wait for it to finish.';
+      else if (blocked) txnError = `Line ${blocked.line}: ${outsideTxnOnly(blocked.sql)} can't run inside a transaction. Switch the worksheet to Autocommit to run it.`;
+    }
+    if (statements.length && !txnError) {
       ran = { start: statements[0].start, end: statements[statements.length - 1].end };
-      // a connection of its own, closed afterwards: the SQL may SET ROLE or change settings, which must not
-      // leak into the builder's pooled connections
-      const c = await (asApp ? await devDbForApp(asApp.id) : db).pool.connect();
       const started = performance.now();
-      try {
-        if (searchSchema) await c.query(`select set_config('search_path', $1, false)`, [`${pg.escapeIdentifier(searchSchema)}, public`]);
-        if (asApp) {
-          await c.query(`select set_config('pgkiln.app_id', $1, false)`, [String(asApp.id)]);
-          await c.query(`set role ${pg.escapeIdentifier(asApp.db_role)}`);
+      const runOn = (c: pg.ClientBase, inTxn: boolean) => explaining
+        ? explainStatement(c, statements[0], m === 'autotrace', inTxn)
+        : runStatements(c, text, statements, { continueOnError: m === 'script' && continueOnError, gridRows: allRows ? ALL_ROWS : GRID_ROWS });
+      const failedRun = (e: unknown): WorksheetRun => ({ results: [{ n: 1, line: statements[0].line, sql: statements[0].sql, start: 0, end: 0, status: 'error', error: (e as Error).message, ms: 0 }], notices: [], failed: 1, ms: 0 });
+      if (useTxn) {
+        if (!txn) {
+          const note = txnNote(s.id, tabKey);
+          const began = await beginTxn({ sessionId: s.id, username: s.username!, workspaceId: currentWorkspace(s), tab: tabKey, db: asApp ? await devDbForApp(asApp.id) : db,
+            asApp: asApp ?? null, runsAs: asApp ? `the role ${asApp.db_role} of ${asApp.name}` : workshopRunsAs(db), searchSchema });
+          if (typeof began === 'string') txnError = began;
+          else {
+            txn = began;
+            if (note) txnInfo = `${note} A new transaction started.`;
+          }
+        }
+        if (txn) {
+          const t = txn;
+          t.busy = true;
+          try {
+            run = await runOn(t.client, true);
+          } catch (e) {
+            run = failedRun(e);
+          } finally {
+            t.busy = false;
+            t.lastMs = Date.now();
+          }
+        }
+      } else {
+        // a connection of its own, closed afterwards: the SQL may SET ROLE or change settings, which must not
+        // leak into the builder's pooled connections
+        const c = await (asApp ? await devDbForApp(asApp.id) : db).pool.connect();
+        try {
+          if (searchSchema) await c.query(`select set_config('search_path', $1, false)`, [`${pg.escapeIdentifier(searchSchema)}, public`]);
+          if (asApp) {
+            await c.query(`select set_config('pgkiln.app_id', $1, false)`, [String(asApp.id)]);
+            await c.query(`set role ${pg.escapeIdentifier(asApp.db_role)}`);
+          }
+          run = await runOn(c, false);
+          // (sprint 107) a BEGIN typed in Autocommit lasts for the run only: say so when it was left open
+          if (!explaining && c.getTransactionStatus() !== 'I') {
+            await c.query('rollback').catch(() => {});
+            run.notices.push({ level: 'WARNING', message: 'The transaction started with BEGIN was still open at the end of the run and was rolled back. Switch the worksheet to Transaction to keep a transaction open between runs.', n: run.results.filter((r) => r.status !== 'not_run').length, at: new Date().toISOString().slice(11, 23) });
+          }
+        } catch (e) {
+          run = failedRun(e);
+        } finally {
+          c.release(true);
         }
-        run = m === 'explain' || m === 'autotrace'
-          ? await explainStatement(c, statements[0], m === 'autotrace')
-          : await runStatements(c, text, statements, { continueOnError: m === 'script' && continueOnError, gridRows: allRows ? ALL_ROWS : GRID_ROWS });
-      } catch (e) {
-        run = { results: [{ n: 1, line: statements[0].line, sql: statements[0].sql, start: 0, end: 0, status: 'error', error: (e as Error).message, ms: 0 }], notices: [], failed: 1, ms: 0 };
-      } finally {
-        c.release(true);
       }
       // the log and history show the statements as written (with :NAME), not with the values
       if (run) for (const r of run.results) r.sql = picked[r.n - 1]?.sql ?? r.sql;
-      if (mode === 'statement' || mode === 'script') {
+      // (sprint 107) the transaction's statements and DDL; a COMMIT / ROLLBACK typed in the editor ended it
+      let committedDdl: string[] | null = null;
+      if (txn && run && !explaining) {
+        committedDdl = accountRun(txn, run.results);
+        if (txnState(txn) === 'none' && findTxn(s.id, tabKey) === txn) {
+          await endTxn(txn, 'rollback'); // nothing open: just closes the connection
+          txn = undefined;
+          txnInfo = 'The transaction ended with the COMMIT or ROLLBACK in the editor; the next run starts a new one.';
+        }
+      }
+      if (txn && findTxn(s.id, tabKey) !== txn) txn = undefined; // the database ended the connection
+      if (run && (mode === 'statement' || mode === 'script')) {
         clearCompletions(); // the statements may have changed tables or grants
-        if (run) await recordHistory(s, run);
-        // (sprint 106, DA-17) the DDL that succeeded goes into the change log
-        if (run) await recordChanges({ workspaceId: currentWorkspace(s), author: s.username ?? '?', source: 'worksheet', defaultSchema: searchSchema ?? 'public',
-          statements: run.results.filter((r) => r.status === 'ok').map((r) => r.sql) });
+        await recordHistory(s, run);
+        // (sprint 106, DA-17) the DDL that succeeded goes into the change log (in a transaction: when it commits)
+        await recordChanges({ workspaceId: currentWorkspace(s), author: s.username ?? '?', source: 'worksheet', defaultSchema: searchSchema ?? 'public',
+          statements: committedDdl ?? run.results.filter((r) => r.status === 'ok').map((r) => r.sql) });
         const detail = picked.map((x) => x.sql).join(';\n');
         await logActivity({ username: s.username, event: 'sql_command', ip: clientIp(req), elapsedMs: Math.round(performance.now() - started), detail: detail.length > 2000 ? `${detail.slice(0, 2000)}…` : detail });
       }
@@ -435,6 +546,12 @@ async function worksheet(req: Req, reply: FastifyReply) {
       <div class="buttons"><button class="btn btn-hot" name="mode" value="${askValues.mode}">${icon('play')} Run</button><button class="btn" name="mode" value="nav" data-ws-binds-cancel>Cancel</button></div>
     </dialog>` : '';
   const runsAs = asApp ? `the role ${asApp.db_role} of ${asApp.name}` : workshopRunsAs(db);
+  // (sprint 107) the transaction badge: the real state of the tab's transaction on the server
+  const tState = txnState(txn);
+  const tNote = !txn && tabKey ? txnNote(s.id, tabKey) : null;
+  if (tState === 'aborted' && !txnError) txnError = 'A statement failed, so the transaction is aborted: Rollback ends it (COMMIT would roll it back too).';
+  const txnOn = txnAsked || !!txn;
+  const badge = txnBadge(tState, txn?.statements ?? 0, txn?.startedMs ?? null, tNote);
 
   const toolBtn = (m: RunMode, ic: string, label: string, key: string, hot = false) =>
     html`<button class="btn btn-sm${hot ? ' btn-hot' : ''}" name="mode" value="${m}" title="${label} (${key})" data-ws-key="${key}">${icon(ic)}<span>${label}</span></button>`;
@@ -506,6 +623,13 @@ async function worksheet(req: Req, reply: FastifyReply) {
             </dl>
             <label class="ws-kwcase" hidden>Format keywords in <select data-ws-kwcase><option value="lower">lower case</option><option value="upper">UPPER CASE</option></select></label>
             <a href="https://github.com/pgkiln/pgkiln/blob/main/docs/guide/03-builder.md#sql-workshop" target="_blank" rel="noopener" data-ws-help>Help on the SQL Worksheet</a></div></div></details>
+          <span class="ws-txn" data-ws-txn data-state="${tState}" data-statements="${txn?.statements ?? 0}" data-started="${txn?.startedMs ?? ''}" data-last="${txn?.lastMs ?? ''}" data-idle="${txnIdleSeconds()}" data-note="${tNote ?? ''}" data-now="${Date.now()}" hidden>
+            <label class="ws-runas"><span>Commit</span><select name="txn" data-ws-txn-mode title="Autocommit: each statement commits on its own. Transaction: the statements stay in one transaction until Commit or Rollback.">
+              <option value="">Autocommit</option><option value="on"${txnOn ? raw(' selected') : ''}>Transaction</option></select></label>
+            <span class="ws-txn-badge" data-ws-txn-badge data-state="${tState}" role="status" title="${tState === 'none' ? '' : `Runs as ${txn?.runsAs ?? ''}`}">${badge}</span>
+            <button class="btn btn-sm" name="mode" value="commit" data-ws-txn-commit title="Commit the worksheet's transaction"${txn ? '' : raw(' disabled')}>${icon('check')}<span>Commit</span></button>
+            <button class="btn btn-sm" name="mode" value="rollback" data-ws-txn-rollback title="Roll back the worksheet's transaction"${txn ? '' : raw(' disabled')}>${icon('undo')}<span>Rollback</span></button>
+          </span>
           <label class="ws-runas"><span>Run as</span>
             <select name="as_app" title="Who the statements run as">
               <option value="">${db === owner ? 'Owner connection' : 'Workspace login'}</option>
@@ -514,9 +638,12 @@ async function worksheet(req: Req, reply: FastifyReply) {
           <button type="button" class="btn btn-sm btn-icon" data-ws-clear title="Clear the editor" hidden>${icon('trash')}<span class="sr-only">Clear</span></button>
           <button type="button" class="btn btn-sm btn-icon" data-ws-fullscreen title="Fullscreen (Escape leaves)" aria-pressed="false" hidden>${bicon('expand')}<span class="sr-only">Fullscreen</span></button>
         </div>
-        <p class="ws-runs-as muted small">Runs as ${runsAs}${searchSchema ? html`; <code>${searchSchema}</code> first in the search path (<a href="${BASE}/sql">change</a>)` : ''}. Each statement commits on its own.</p>
+        <p class="ws-runs-as muted small">Runs as ${runsAs}${searchSchema ? html`; <code>${searchSchema}</code> first in the search path (<a href="${BASE}/sql">change</a>)` : ''}. <span data-ws-commit-note>${txnOn
+          ? `The statements stay in one transaction until Commit or Rollback; it is rolled back after ${idleLabel()} without a run.`
+          : 'Each statement commits on its own.'}</span></p>
         ${fileError ? html`<p class="alert alert-error ws-file-error" role="alert">${fileError}</p>` : ''}
-        <div class="ws-wtabs" role="tablist" aria-label="Worksheets" hidden></div>
+        ${txnError ? html`<p class="alert alert-error ws-txn-alert" role="alert">${txnError}</p>` : txnInfo ? html`<p class="alert alert-info ws-txn-alert" role="status">${txnInfo}</p>` : ''}
+        <div class="ws-wtabs" role="group" aria-label="Worksheets" hidden></div>
         <div class="ws-findbar" hidden>
           <label class="sr-only" for="ws-find-q">Find</label><input id="ws-find-q" type="search" placeholder="Find" autocomplete="off" data-ws-find-q>
           <label class="sr-only" for="ws-find-r">Replace with</label><input id="ws-find-r" placeholder="Replace with" autocomplete="off" data-ws-find-r>
@@ -553,6 +680,27 @@ export async function worksheetRoutes(app: FastifyInstance) {
   // (before sprint 61 SQL Commands was /builder/sql: a post there still runs)
   app.post(`${BASE}/sql`, worksheet);
 
+  // (sprint 107, DA-2) transaction mode: a tab's transaction (the badge), Commit / Rollback without a reload (closing a
+  // worksheet tab, switching to Autocommit). Always the caller's own session: another developer's tab doesn't exist here.
+  app.get(`${BASE}/sql/worksheet/txn`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const tab = String(req.query?.tab ?? '');
+    if (!/^[a-z0-9]{1,20}$/.test(tab)) return reply.code(400).send({ error: 'Which worksheet?' });
+    return reply.header('Cache-Control', 'no-store').send(txnStatus(s, tab));
+  });
+  app.post(`${BASE}/sql/worksheet/txn`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const tab = String(req.body?.tab ?? '');
+    const action = req.body?.action;
+    if (!/^[a-z0-9]{1,20}$/.test(tab) || (action !== 'commit' && action !== 'rollback')) return reply.code(400).send({ error: 'Which worksheet, and commit or rollback?' });
+    const t = findTxn(s.id, tab);
+    const done = await finishTxn(req, s, tab, t && t.workspaceId === currentWorkspace(s) ? t : undefined, action);
+    return reply.code(done.busy ? 409 : 200).header('Cache-Control', 'no-store').send({ ...done, ...txnStatus(s, tab) });
+  });
+  app.addHook('onClose', async () => endAllTxns());
+
   // (sprint 93, DA-9) Format: the worksheet's text laid out, keywords in the case asked for
   app.post(`${BASE}/sql/worksheet/format`, async (req: Req, reply) => {
     const s = await developer(req, reply);

package/src/session.ts

@@ -91,8 +91,13 @@ export async function saveState(s: Session) {
 export async function destroySession(reply: FastifyReply, s: Session, path: string) {
   await runtime.query('delete from meta.session where id = $1', [s.id]);
   reply.clearCookie(cookieName(s.app_id), { path });
+  for (const fn of endHooks) await fn(s.id).catch(() => {});
 }
 
+/** (sprint 107) Called when a session is destroyed (sign-out, a new sign-in): the worksheet's transactions end with it. */
+const endHooks: ((sessionId: string) => Promise<unknown>)[] = [];
+export const onSessionEnd = (fn: (sessionId: string) => Promise<unknown>) => endHooks.push(fn);
+
 /** Take (and clear) a one-shot flash message stored in session state. */
 export function takeFlash(s: Session, key = '__FLASH') {
   const msg = s.state[key] ?? null;

package/src/sqlworksheet.ts

@@ -3,7 +3,6 @@ import { isNumeric } from './runtime/report.ts';
 import { parsePlan, planText, type Plan } from './sqlplan.ts';
 import { splitScript, type ScriptStatement } from './sqlscript.ts';
 import { skipQuoted } from './binds.ts';
-import type { Client } from './db.ts';
 
 // (sprint 91, Database Actions DA-1/DA-2) The SQL Workshop's worksheet: which statements a run takes
 // (the one at the cursor, a selection, or all of them), and running them on one connection with a log
@@ -144,9 +143,10 @@ export interface RunOptions {
 
 /**
  * Run statements on `c` (a connection of its own, destroyed by the caller: the SQL may change the role or
- * settings). Each statement autocommits, like Database Actions. Notices are collected per statement.
+ * settings). Each statement autocommits, like Database Actions, unless the caller opened a transaction on `c`
+ * (sprint 107, the worksheet's transaction mode). Notices are collected per statement.
  */
-export async function runStatements(c: Client, text: string, statements: ScriptStatement[], opts: RunOptions = {}): Promise<WorksheetRun> {
+export async function runStatements(c: pg.ClientBase, text: string, statements: ScriptStatement[], opts: RunOptions = {}): Promise<WorksheetRun> {
   const started = performance.now();
   const notices: Notice[] = [];
   let current = 0;
@@ -206,7 +206,7 @@ export async function runStatements(c: Client, text: string, statements: ScriptS
  * EXPLAIN the statement (Explain Plan: nothing runs) or EXPLAIN ANALYZE it inside a transaction that is
  * rolled back (Autotrace: it runs, its changes don't stay).
  */
-export async function explainStatement(c: Client, s: ScriptStatement, analyze: boolean): Promise<WorksheetRun> {
+export async function explainStatement(c: pg.ClientBase, s: ScriptStatement, analyze: boolean, inTransaction = false): Promise<WorksheetRun> {
   const started = performance.now();
   const r: WorksheetResult = { n: 1, line: s.line, sql: s.sql, start: s.start, end: s.end, status: 'not_run', ms: 0 };
   let plan: string | undefined;
@@ -216,7 +216,9 @@ export async function explainStatement(c: Client, s: ScriptStatement, analyze: b
     r.error = 'Only SQL statements have a plan.';
   } else {
     try {
-      await c.query('begin');
+      // (sprint 107) in a worksheet's open transaction: a savepoint, so the plan sees the transaction's changes and
+      // Autotrace's own are undone while the transaction's stay (a failing EXPLAIN doesn't abort it either)
+      await c.query(inTransaction ? 'savepoint pgkiln_explain' : 'begin');
       const out = await c.query<{ 'QUERY PLAN': unknown }>(`explain (format json, ${analyze ? 'analyze, buffers, ' : ''}verbose, costs) ${s.sql}`);
       const json = out.rows[0]?.['QUERY PLAN'];
       tree = parsePlan(typeof json === 'string' ? JSON.parse(json) : json, analyze);
@@ -229,7 +231,8 @@ export async function explainStatement(c: Client, s: ScriptStatement, analyze: b
       r.error = `${err.message}${err.code ? ` (${err.code})` : ''}`;
       r.errorLine = s.line;
     } finally {
-      await c.query('rollback').catch(() => {});
+      if (inTransaction) await c.query('rollback to savepoint pgkiln_explain').then(() => c.query('release savepoint pgkiln_explain')).catch(() => {});
+      else await c.query('rollback').catch(() => {});
     }
   }
   r.ms = Math.round(performance.now() - started);

package/src/worksheet-txn.ts

@@ -0,0 +1,270 @@
+import { randomBytes } from 'node:crypto';
+import pg from 'pg';
+import { onClosePools, owner, type Db } from './db.ts';
+import { onSessionEnd, sessionLimits } from './session.ts';
+import { isSchemaDdl } from './changelog.ts';
+
+// (sprint 107, DA-2) Transaction mode of the SQL Worksheet. Database Actions autocommits every statement;
+// in transaction mode a worksheet tab keeps one connection of its own with an open transaction between
+// runs, until Commit, Rollback, a COMMIT / ROLLBACK typed in the editor, or an idle timeout.
+//
+// The registry lives in this process only (no table): a transaction is a live connection, so it can't
+// outlive the server anyway. Each open transaction is bound to the builder session that started it, its
+// developer, workspace and worksheet tab, and has a random id; a lookup always starts from the caller's own
+// session id, so one developer can never reach another one's connection. Limits: a few per developer and
+// per instance (each holds a database connection outside the pools), an idle timeout (rolled back by a
+// sweeper) and the connection's idle_in_transaction_session_timeout a little later as the backstop. The
+// connection is a plain pg.Client made from the workshop's (or the "Run as" application's) pool settings,
+// never a pooled one: SET ROLE and settings typed by the developer die with it.
+
+const intEnv = (name: string, dflt: number, min: number, max: number) => {
+  const n = Number(process.env[name]);
+  return Number.isFinite(n) && n >= min && n <= max ? Math.floor(n) : dflt;
+};
+/** Seconds without a run before an open transaction is rolled back (WORKSHEET_TXN_IDLE_SECONDS, default 5 minutes). */
+export const txnIdleSeconds = () => intEnv('WORKSHEET_TXN_IDLE_SECONDS', 300, 10, 86_400);
+/** Open transactions per developer (WORKSHEET_TXN_MAX_PER_DEVELOPER, default 3) and per server (WORKSHEET_TXN_MAX, default 20). */
+export const txnMaxPerDeveloper = () => intEnv('WORKSHEET_TXN_MAX_PER_DEVELOPER', 3, 1, 100);
+export const txnMax = () => intEnv('WORKSHEET_TXN_MAX', 20, 1, 1000);
+/** The database's own backstop: this much after the idle timeout it ends the connection itself. */
+const BACKSTOP_SECONDS = 60;
+/** How long the note of a transaction the server ended (timeout, workspace switch) stays for the worksheet. */
+const NOTE_MS = 60 * 60 * 1000;
+
+export interface WorksheetTxn {
+  /** random handle (shown to the page, never trusted for a lookup on its own) */
+  id: string;
+  sessionId: string;
+  username: string;
+  workspaceId: number;
+  tab: string;
+  client: pg.Client;
+  /** the application whose role the transaction runs as (Run as), or null */
+  asAppId: number | null;
+  /** who it runs as, for the badge */
+  runsAs: string;
+  startedMs: number;
+  lastMs: number;
+  /** statements run in the current transaction */
+  statements: number;
+  /** a run (or commit / rollback) is going on */
+  busy: boolean;
+  /** DDL that succeeded in the transaction: it goes into the Change Log at COMMIT, not before */
+  pendingDdl: string[];
+  defaultSchema: string;
+}
+
+export type TxnState = 'open' | 'aborted' | 'none';
+
+const open = new Map<string, WorksheetTxn>();
+const notes = new Map<string, { message: string; at: number }>();
+const keyOf = (sessionId: string, tab: string) => `${sessionId}\u0000${tab}`;
+
+/** A worksheet tab's key as the page sends it (src/builder/worksheet.ts uses the same rule). */
+export const validTab = (tab: unknown) => typeof tab === 'string' && /^[a-z0-9]{1,20}$/.test(tab);
+
+/** The open transaction of this session's worksheet tab. */
+export function findTxn(sessionId: string, tab: string): WorksheetTxn | undefined {
+  return validTab(tab) ? open.get(keyOf(sessionId, tab)) : undefined;
+}
+
+/** Open, aborted (a statement failed: only ROLLBACK helps) or none (committed or rolled back by a typed statement). */
+export function txnState(t: WorksheetTxn | undefined): TxnState {
+  const s = t?.client.getTransactionStatus();
+  return s === 'T' ? 'open' : s === 'E' ? 'aborted' : 'none';
+}
+
+/** Why the server ended this tab's last transaction (idle timeout, …), if it did. */
+export function txnNote(sessionId: string, tab: string): string | null {
+  const n = notes.get(keyOf(sessionId, tab));
+  if (!n) return null;
+  if (Date.now() - n.at > NOTE_MS) {
+    notes.delete(keyOf(sessionId, tab));
+    return null;
+  }
+  return n.message;
+}
+export const clearTxnNote = (sessionId: string, tab: string) => notes.delete(keyOf(sessionId, tab));
+
+/** Open transactions (tests and the instance's monitor). */
+export const openTxnCount = (username?: string) => [...open.values()].filter((t) => username === undefined || t.username === username).length;
+
+/** Statements PostgreSQL refuses inside a transaction block (refused before they abort it): the command, or ''. */
+export const outsideTxnOnly = (sql: string): string => {
+  const s = sql.replace(/^(\s|--[^\n]*\n|\/\*[\s\S]*?\*\/)+/, '').toLowerCase();
+  return /^(vacuum|alter\s+system|(create|drop)\s+(database|tablespace)|(create|drop)\s+(unique\s+)?index\s+concurrently|reindex\b[^;]*\bconcurrently|alter\s+table\b[^;]*\bdetach\s+partition\b[^;]*\bconcurrently|prepare\s+transaction|commit\s+prepared|rollback\s+prepared)\b/.exec(s)?.[0].replace(/\s+/g, ' ').toUpperCase() ?? '';
+};
+
+export interface BeginOptions {
+  sessionId: string;
+  username: string;
+  workspaceId: number;
+  tab: string;
+  /** the pool whose login the connection uses (the workshop's, or the Run as application's) */
+  db: Db;
+  asApp?: { id: number; db_role: string } | null;
+  runsAs: string;
+  searchSchema: string | null;
+}
+
+/** Start a transaction for a worksheet tab: a connection of its own, BEGIN. A string is a refusal. */
+export async function beginTxn(o: BeginOptions): Promise<WorksheetTxn | string> {
+  if (!validTab(o.tab)) return 'Transaction mode needs the worksheet tab (JavaScript).';
+  const key = keyOf(o.sessionId, o.tab);
+  if (open.has(key)) return 'This worksheet already has an open transaction.';
+  const mine = openTxnCount(o.username);
+  if (mine >= txnMaxPerDeveloper())
+    return `You have ${mine} worksheets with an open transaction, the most allowed: commit or roll back one of them first.`;
+  if (open.size >= txnMax()) return 'The server has as many open worksheet transactions as it allows: try again later, or use Autocommit.';
+  const idle = txnIdleSeconds();
+  const opts = o.db.pool.options;
+  const client = new pg.Client({
+    connectionString: opts.connectionString,
+    password: opts.password,
+    ssl: opts.ssl,
+    application_name: 'pgkiln-worksheet-txn',
+    connectionTimeoutMillis: 10_000,
+    idle_in_transaction_session_timeout: (idle + BACKSTOP_SECONDS) * 1000,
+  });
+  const now = Date.now();
+  const t: WorksheetTxn = {
+    id: randomBytes(16).toString('hex'), sessionId: o.sessionId, username: o.username, workspaceId: o.workspaceId, tab: o.tab, client,
+    asAppId: o.asApp?.id ?? null, runsAs: o.runsAs, startedMs: now, lastMs: now, statements: 0, busy: true, pendingDdl: [], defaultSchema: o.searchSchema ?? 'public',
+  };
+  open.set(key, t); // before the first await: the limits count it at once
+  notes.delete(key);
+  // the database ended the connection (its backstop timeout, a restart, pg_terminate_backend)
+  const gone = () => {
+    if (open.get(key) !== t) return;
+    open.delete(key);
+    notes.set(key, { message: 'The database ended the transaction\'s connection: its changes were rolled back.', at: Date.now() });
+  };
+  client.on('error', gone);
+  client.on('end', gone);
+  try {
+    await client.connect();
+    if (o.searchSchema) await client.query(`select set_config('search_path', $1, false)`, [`${pg.escapeIdentifier(o.searchSchema)}, public`]);
+    if (o.asApp) {
+      await client.query(`select set_config('pgkiln.app_id', $1, false)`, [String(o.asApp.id)]);
+      await client.query(`set role ${pg.escapeIdentifier(o.asApp.db_role)}`);
+    }
+    await client.query('begin');
+  } catch (e) {
+    open.delete(key);
+    await client.end().catch(() => {});
+    return `The transaction could not start: ${(e as Error).message}`;
+  } finally {
+    t.busy = false;
+  }
+  startSweeper();
+  return t;
+}
+
+/** BEGIN again on the transaction's connection after a COMMIT / ROLLBACK typed in the editor. */
+export async function beginAgain(t: WorksheetTxn) {
+  await t.client.query('begin');
+  t.startedMs = Date.now();
+  t.statements = 0;
+  t.pendingDdl = [];
+}
+
+/**
+ * End a transaction: COMMIT or ROLLBACK, then close its connection. The tag is what the database answered
+ * (COMMIT of a failed transaction answers ROLLBACK). `note` is kept for the worksheet (the server ended it).
+ */
+export async function endTxn(t: WorksheetTxn, action: 'commit' | 'rollback', note?: string): Promise<{ tag: string; error?: string; ddl: string[] }> {
+  const key = keyOf(t.sessionId, t.tab);
+  if (open.get(key) === t) open.delete(key);
+  if (note) {
+    notes.set(key, { message: note, at: Date.now() });
+    if (notes.size > 1000) notes.delete(notes.keys().next().value!); // the oldest
+  }
+  let tag = action.toUpperCase();
+  let error: string | undefined;
+  try {
+    if (t.client.getTransactionStatus() !== 'I') {
+      const r = await t.client.query(action);
+      tag = (r.command ?? tag).toUpperCase();
+    }
+  } catch (e) {
+    error = (e as Error).message;
+    tag = 'ROLLBACK';
+  } finally {
+    await t.client.end().catch(() => {});
+  }
+  return { tag, error, ddl: action === 'commit' && tag === 'COMMIT' ? t.pendingDdl : [] };
+}
+
+/**
+ * Count a run's statements in the transaction and keep its DDL for the Change Log until COMMIT. A COMMIT
+ * (or END) typed in the editor hands back the DDL it committed; a ROLLBACK (or ABORT, or COMMIT of a failed
+ * transaction, which answers ROLLBACK) drops it.
+ */
+export function accountRun(t: WorksheetTxn, results: { status: string; sql: string; tag?: string }[]): string[] {
+  const committed: string[] = [];
+  for (const r of results) {
+    if (r.status !== 'ok') continue;
+    const tag = (r.tag ?? '').toUpperCase();
+    if (tag === 'COMMIT') {
+      committed.push(...t.pendingDdl);
+      t.pendingDdl = [];
+      t.statements = 0;
+    } else if (tag === 'ROLLBACK' && !/^\s*rollback\s+(work\s+|transaction\s+)?to\b/i.test(r.sql)) {
+      t.pendingDdl = [];
+      t.statements = 0;
+    } else if (tag !== 'BEGIN' && tag !== 'START') {
+      t.statements++;
+      if (isSchemaDdl(r.sql)) t.pendingDdl.push(r.sql);
+    }
+  }
+  return committed;
+}
+
+/** Roll back and close every transaction of a session (it ended: sign-out, a new sign-in). */
+export async function endSessionTxns(sessionId: string, note: string) {
+  await Promise.all([...open.values()].filter((t) => t.sessionId === sessionId).map((t) => endTxn(t, 'rollback', note)));
+}
+
+/** The idle timeout and ended sessions: roll back. `now` lets tests move the clock. */
+export async function sweepTxns(now = Date.now()) {
+  const idleMs = txnIdleSeconds() * 1000;
+  const minutes = Math.round(txnIdleSeconds() / 6) / 10;
+  const ended: Promise<unknown>[] = [];
+  for (const t of open.values())
+    if (!t.busy && now - t.lastMs > idleMs)
+      ended.push(endTxn(t, 'rollback', `The transaction was rolled back after ${minutes} minute${minutes === 1 ? '' : 's'} without a run (${t.statements} statement${t.statements === 1 ? '' : 's'} undone).`));
+  await Promise.all(ended);
+  const sessions = [...new Set([...open.values()].map((t) => t.sessionId))];
+  if (sessions.length) {
+    // a session that ended or expired (its row may stay a while after it expires)
+    const { idleMinutes, maxHours } = sessionLimits();
+    const alive = new Set((await owner.query<{ id: string }>(
+      `select id::text as id from meta.session where id::text = any ($1)
+          and last_seen > now() - make_interval(mins => $2) and created_at > now() - make_interval(hours => $3)`, [sessions, idleMinutes, maxHours])
+      .catch(() => ({ rows: sessions.map((id) => ({ id })) }))).rows.map((r) => r.id));
+    await Promise.all(sessions.filter((id) => !alive.has(id)).map((id) => endSessionTxns(id, 'The builder session ended: the transaction was rolled back.')));
+  }
+  for (const [k, n] of notes) if (now - n.at > NOTE_MS) notes.delete(k);
+  if (!open.size) stopSweeper();
+}
+
+let sweeper: NodeJS.Timeout | null = null;
+function startSweeper() {
+  if (sweeper) return;
+  const every = Math.max(1000, Math.min(15_000, (txnIdleSeconds() * 1000) / 4));
+  sweeper = setInterval(() => void sweepTxns().catch((e) => console.error('worksheet transactions:', (e as Error).message)), every);
+  sweeper.unref();
+}
+function stopSweeper() {
+  if (sweeper) clearInterval(sweeper);
+  sweeper = null;
+}
+
+/** Everything rolled back (the server stops). */
+export async function endAllTxns(note = 'The server stopped: the transaction was rolled back.') {
+  stopSweeper();
+  await Promise.all([...open.values()].map((t) => endTxn(t, 'rollback', note)));
+}
+
+onClosePools(() => endAllTxns());
+onSessionEnd((sessionId) => endSessionTxns(sessionId, 'You signed out: the transaction was rolled back.'));