@kazurolabs/psql-explorer 0.1.0 → 0.3.1

package/dist/web/server.js

@@ -7,13 +7,34 @@ import { readFile } from 'node:fs/promises';
 import { extname, join, normalize, resolve, sep } from 'node:path';
 import { ResolveError } from '../config/resolvers/index.js';
 import { addressOf, findEnvironment, forgetAnswers, listEnvironments } from '../environments.js';
-import { connectEntry, LoginError } from '../explorer/connect-entry.js';
-import { describeCatalog, describeErd, describeFunction, describeRelation, describeSequence, describeType, listObjects, listSchemas, serverInfo, } from '../explorer/catalog.js';
-import { explainQuery } from '../explorer/explain.js';
-import { browseRows, runPage } from '../explorer/rows.js';
+import { connectEntries, LoginError } from '../explorer/connect-entry.js';
+import { describeCatalog, describeFunctionCatalog, describeErd, describeFunction, describeRelation, describeSequence, describeType, listColumns, listObjects, listSchemas, serverInfo, } from '../explorer/catalog.js';
+import { applyEdit, buildEdit, EditError } from '../explorer/edit.js';
+import { listDependents } from '../explorer/dependents.js';
+import { describeFunctionSecurity, describeSecurity, listRoles } from '../explorer/security.js';
+import { explainAnalyze, explainQuery } from '../explorer/explain.js';
+import { browseRows, browseSql, canExport, EXPORT_MAX_ROWS, exportRows, runPage, } from '../explorer/rows.js';
+import { buildWhere, FilterError, parseFilters } from '../explorer/filter.js';
+import { buildGraph, expandNode, GraphError, parseExpandRequest, parseGraphRequest, } from '../explorer/graph.js';
+import { CypherError, parseCypherRequest, runCypher } from '../explorer/cypher.js';
+import { profileColumn } from '../explorer/profile.js';
+import { countReferences, listForeignKeys, listSchemaForeignKeys } from '../explorer/references.js';
+import { buildSearchIndex, searchValues } from '../explorer/search.js';
+import { describeSeedColumns, generators, MAX_SEED_ROWS, parseSeedRequest, previewSeed, runSeed, SeedError, seedLocales, } from '../explorer/seed.js';
+import { compareSchemas } from '../explorer/schema-diff.js';
+import { AlterError, diffDesigns, dropTableStatement, parseAlterOptions, splitPlan, } from '../explorer/alter.js';
+import { buildDdl, DdlError, parseTableDesign } from '../explorer/ddl.js';
+import { DesignRunError, runPlan, runStatements } from '../explorer/design.js';
+import { loadDesign } from '../explorer/design-load.js';
 import { describeQueryError } from '../explorer/session.js';
+import { applyGucs, GucError, parseGucs } from '../explorer/gucs.js';
+import { databaseStats, listIndexStats, listTableStats } from '../explorer/stats.js';
 export const DEFAULT_WEB_PORT = 7878;
 const MAX_BODY_BYTES = 1_000_000;
+// Editing a row can carry a dropped file: up to 20 MB of it, written as hex.
+const MAX_EDIT_BODY_BYTES = 48_000_000;
+// Connections a value search reads tables on at once.
+const SEARCH_CONNECTIONS = 4;
 const contentTypes = {
     '.html': 'text/html; charset=utf-8',
     '.js': 'text/javascript; charset=utf-8',
@@ -27,9 +48,13 @@ const contentTypes = {
 /** A request that cannot be answered as sent: the status says why. */
 class HttpError extends Error {
     status;
-    constructor(status, message) {
+    extra;
+    constructor(status, message, 
+    // More to send along with the message, e.g. which statement failed.
+    extra = {}) {
         super(message);
         this.status = status;
+        this.extra = extra;
     }
 }
 const sendJson = (res, status, body) => {
@@ -42,13 +67,41 @@ const requiredParam = (url, key) => {
         throw new HttpError(400, `${url.pathname.split('/').pop()} needs ?${key}=`);
     return value;
 };
+/** A query parameter holding JSON, e.g. the filters of the row grid; undefined when absent. */
+const jsonParam = (url, key) => {
+    const text = url.searchParams.get(key);
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new HttpError(400, `${key} is not valid JSON`);
+    }
+};
+const parseSort = (raw) => {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        throw new HttpError(400, 'sort is a list of {column, descending}');
+    return raw.slice(0, 10).map((item) => {
+        if (typeof item?.column !== 'string')
+            throw new HttpError(400, 'sort is a list of {column, descending}');
+        return { column: item.column, descending: item.descending === true };
+    });
+};
+/** A saved query's name: what was typed, or else the start of the statement. */
+const savedName = (given, sql) => {
+    const text = typeof given === 'string' ? given.trim() : '';
+    return (text || sql.trim().replace(/\s+/g, ' ')).slice(0, 80);
+};
 const isLoopbackHost = (host) => {
     if (!host)
         return false;
     const name = host.startsWith('[') ? host.slice(0, host.indexOf(']') + 1) : host.split(':')[0];
     return name === 'localhost' || name === '127.0.0.1' || name === '[::1]';
 };
-async function readJson(req) {
+async function readJson(req, maxBytes = MAX_BODY_BYTES) {
     if (!req.headers['content-type']?.startsWith('application/json')) {
         throw new HttpError(415, 'send application/json');
     }
@@ -56,7 +109,7 @@ async function readJson(req) {
     let size = 0;
     for await (const chunk of req) {
         size += chunk.length;
-        if (size > MAX_BODY_BYTES)
+        if (size > maxBytes)
             throw new HttpError(413, 'request body is too large');
         chunks.push(chunk);
     }
@@ -73,18 +126,20 @@ export function createWebServer(options) {
     const environmentNamed = (name) => {
         const entry = findEnvironment(services, name);
         if (!entry)
-            throw new HttpError(404, `no environment named "${name}"`);
+            throw new HttpError(404, `you do not have access to "${name}": it is not in your config`);
         return entry;
     };
     // Protected environments the person has switched to read write, by entry key. In memory only, so
     // a restart is read only again.
     const writable = new Set();
-    // One connection per request keeps the scaffold simple; pooling comes with the real UI.
-    async function withSession(name, work, signal) {
+    // Opens up to `count` connections with one lookup of the credentials (one Vault read, one
+    // prompt), so queries can run side by side. Nothing is kept between requests: the next request
+    // looks everything up again, so a changed password is never held onto.
+    async function withSessions(name, count, work, signal) {
         const entry = environmentNamed(name);
-        let session;
+        let sessions;
         try {
-            session = await connectEntry(entry, services, {
+            sessions = await connectEntries(entry, services, count, {
                 signal,
                 ...(writable.has(entry.key) ? { readOnly: false } : {}),
             });
@@ -95,18 +150,23 @@ export function createWebServer(options) {
                 forgetAnswers(entry, services);
             throw error;
         }
+        // A request the browser gave up on (Cancel, or a closed page) stops its statements on the server.
+        const stop = () => void Promise.all(sessions.map((session) => session.cancel()));
+        signal?.addEventListener('abort', stop);
         try {
-            return await work(session);
+            return await work(sessions);
         }
         finally {
-            await session.close();
-            await services.groups?.release(entry.name);
+            signal?.removeEventListener('abort', stop);
+            await Promise.all(sessions.map((session) => session.close().catch(() => undefined)));
         }
     }
+    const withSession = (name, work, signal) => withSessions(name, 1, ([session]) => work(session), signal);
     async function api(req, url, signal) {
         const withSessionFor = (name, work) => withSession(name, work, signal);
+        const withSessionsFor = (name, count, work) => withSessions(name, count, work, signal);
         const parts = url.pathname.split('/').slice(2).map(decodeURIComponent);
-        const [resource, name, sub] = parts;
+        const [resource, name, sub, id] = parts;
         if (resource === 'prompt' && !name && req.method === 'GET') {
             const pending = services.prompts?.current();
             return {
@@ -143,6 +203,8 @@ export function createWebServer(options) {
                     tier: entry.tier,
                     protected: entry.protected,
                     readOnly: entry.readOnly,
+                    seeder: entry.seeder,
+                    designer: entry.designer,
                     address: addressOf(entry),
                     tls: entry.tlsMode,
                 })),
@@ -189,9 +251,96 @@ export function createWebServer(options) {
         if (resource === 'envs' && name && sub === 'catalog' && req.method === 'GET') {
             return withSessionFor(name, (session) => describeCatalog(session));
         }
+        if (resource === 'envs' && name && sub === 'functions' && req.method === 'GET') {
+            return withSessionFor(name, (session) => describeFunctionCatalog(session));
+        }
+        if (resource === 'envs' && name && sub === 'search-index' && req.method === 'GET') {
+            return withSessionFor(name, (session) => buildSearchIndex(session));
+        }
+        if (resource === 'envs' && name && sub === 'find' && req.method === 'GET') {
+            const text = requiredParam(url, 'q').trim();
+            if (!text)
+                throw new HttpError(400, 'find needs ?q=');
+            const schema = url.searchParams.get('schema') || undefined;
+            try {
+                return await withSessionsFor(name, SEARCH_CONNECTIONS, (sessions) => searchValues(sessions, { text, ...(schema ? { schema } : {}) }));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
         if (resource === 'envs' && name && sub === 'info' && req.method === 'GET') {
             return withSessionFor(name, (session) => serverInfo(session));
         }
+        if (resource === 'envs' && name && sub === 'stats' && req.method === 'GET') {
+            const schema = url.searchParams.get('schema');
+            const table = url.searchParams.get('table');
+            if (!schema || !table)
+                return withSessionFor(name, (session) => databaseStats(session));
+            const ref = { schema, name: table };
+            const found = await withSessionFor(name, async (session) => {
+                const [stats] = await listTableStats(session, ref).catch(() => []);
+                return stats && { table: stats, indexes: await listIndexStats(session, ref) };
+            });
+            if (!found)
+                throw new HttpError(404, `no table ${schema}.${table}`);
+            return found;
+        }
+        if (resource === 'envs' && name && sub === 'schema-diff' && req.method === 'GET') {
+            const other = requiredParam(url, 'with');
+            const schema = url.searchParams.get('schema') || undefined;
+            const withSchema = url.searchParams.get('withSchema') || undefined;
+            environmentNamed(other);
+            try {
+                return await withSessionFor(name, (session) => withSession(other, (otherSession) => compareSchemas(session, otherSession, { schema, withSchema }), signal));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'dependents' && req.method === 'GET') {
+            const kind = requiredParam(url, 'kind');
+            const schema = requiredParam(url, 'schema');
+            const object = requiredParam(url, 'name');
+            let target;
+            if (kind === 'function') {
+                target = { kind, schema, name: object, args: url.searchParams.get('args') ?? '' };
+            }
+            else if (kind === 'table' || kind === 'sequence' || kind === 'type') {
+                target = { kind, schema, name: object };
+            }
+            else if (kind === 'column' || kind === 'constraint') {
+                target = { kind, schema, table: requiredParam(url, 'table'), name: object };
+            }
+            else if (kind === 'index') {
+                target = { kind, schema, name: object };
+            }
+            else
+                throw new HttpError(400, `unknown kind "${kind}"`);
+            const found = await withSessionFor(name, (session) => listDependents(session, target));
+            if (!found)
+                throw new HttpError(404, `no ${kind} ${schema}.${object}`);
+            return found;
+        }
+        if (resource === 'envs' && name && sub === 'security' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            const table = requiredParam(url, 'name');
+            const args = url.searchParams.get('args');
+            const found = await withSessionFor(name, (session) => args === null
+                ? describeSecurity(session, { schema, name: table })
+                : describeFunctionSecurity(session, { schema, name: table, args }));
+            if (!found)
+                throw new HttpError(404, `no ${args === null ? 'table' : 'function'} ${schema}.${table}`);
+            return found;
+        }
+        if (resource === 'envs' && name && sub === 'roles' && req.method === 'GET') {
+            // Not every role may read the catalog of roles; the page then just has none to show.
+            return withSessionFor(name, (session) => listRoles(session).then((roles) => ({ roles, available: true }), () => ({ roles: [], available: false })));
+        }
         if (resource === 'envs' && name && sub === 'objects' && req.method === 'GET') {
             const schema = requiredParam(url, 'schema');
             return withSessionFor(name, (session) => listObjects(session, schema));
@@ -222,7 +371,107 @@ export function createWebServer(options) {
             const limit = Math.min(Math.max(Number(url.searchParams.get('limit')) || 100, 1), 1000);
             const offset = Math.max(Number(url.searchParams.get('offset')) || 0, 0);
             try {
-                return await withSessionFor(name, (session) => browseRows(session, { schema, name: table }, { limit, offset }));
+                const filters = parseFilters(jsonParam(url, 'filters'));
+                const sort = parseSort(jsonParam(url, 'sort'));
+                return await withSessionFor(name, async (session) => {
+                    const ref = { schema, name: table };
+                    const columns = await listColumns(session, ref);
+                    for (const { column } of sort) {
+                        if (!columns.some((known) => known.name === column)) {
+                            throw new FilterError(`no column "${column}"`);
+                        }
+                    }
+                    const where = buildWhere(columns, filters);
+                    const result = await browseRows(session, ref, { limit, offset, orderBy: sort, where });
+                    // The same statement with its values written in, for the SQL box.
+                    const shown = browseSql(ref, {
+                        orderBy: sort,
+                        where: buildWhere(columns, filters, { inline: true }),
+                    })
+                        .replace(/LIMIT \$\d+ OFFSET \$\d+$/, `LIMIT ${limit} OFFSET ${offset}`)
+                        .replace(/ OFFSET 0$/, '');
+                    return { ...result, sql: shown };
+                });
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof FilterError || error instanceof GucError) {
+                    throw new HttpError(400, error.message);
+                }
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' &&
+            name &&
+            sub === 'graph' &&
+            (!id || id === 'expand') &&
+            req.method === 'POST') {
+            try {
+                const body = (await readJson(req));
+                if (id === 'expand') {
+                    const request = parseExpandRequest(body);
+                    return await withSessionFor(name, (session) => expandNode(session, request));
+                }
+                const request = parseGraphRequest(body, parseFilters(body?.filters));
+                return await withSessionFor(name, (session) => buildGraph(session, request));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof GraphError || error instanceof FilterError) {
+                    throw new HttpError(400, error.message);
+                }
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'cypher' && req.method === 'POST') {
+            try {
+                const request = parseCypherRequest(await readJson(req));
+                return await withSessionFor(name, (session) => runCypher(session, request));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof CypherError)
+                    throw new HttpError(400, error.message);
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'profile' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            const table = requiredParam(url, 'table');
+            const column = requiredParam(url, 'column');
+            try {
+                return await withSessionFor(name, (session) => profileColumn(session, { schema, name: table }, column));
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'foreign-keys' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            const table = requiredParam(url, 'table');
+            return withSessionFor(name, (session) => listForeignKeys(session, { schema, name: table }));
+        }
+        if (resource === 'envs' && name && sub === 'schema-foreign-keys' && req.method === 'GET') {
+            const schema = requiredParam(url, 'schema');
+            return withSessionFor(name, (session) => listSchemaForeignKeys(session, schema));
+        }
+        if (resource === 'envs' && name && sub === 'references' && req.method === 'POST') {
+            const body = (await readJson(req));
+            if (typeof body?.schema !== 'string' ||
+                typeof body.table !== 'string' ||
+                typeof body.values !== 'object' ||
+                body.values === null) {
+                throw new HttpError(400, 'send {"schema", "table", "values": {column: value}}');
+            }
+            const { schema, table } = body;
+            const values = body.values;
+            try {
+                return await withSessionFor(name, (session) => countReferences(session, { schema, name: table }, values));
             }
             catch (error) {
                 if (error instanceof HttpError)
@@ -233,32 +482,416 @@ export function createWebServer(options) {
         if (resource === 'envs' && name && sub === 'query' && req.method === 'POST') {
             const body = (await readJson(req));
             if (typeof body?.sql !== 'string' || body.sql.trim() === '') {
-                throw new HttpError(400, 'send {"sql": "..."}');
+                throw new HttpError(400, 'send {"sql": "...", "asWritten"?: true}');
             }
             const sql = body.sql;
             const limit = Math.min(Math.max(Number(body.limit) || 100, 1), 1000);
             const offset = Math.max(Math.floor(Number(body.offset)) || 0, 0);
+            const envName = environmentNamed(name).name;
+            const started = performance.now();
+            try {
+                const gucs = parseGucs(body.settings);
+                const result = await withSessionFor(name, async (session) => {
+                    await applyGucs(session, gucs);
+                    return runPage(session, sql, { limit, offset, asWritten: body.asWritten === true });
+                });
+                // Later pages of a result are the same statement again, not a new one to remember.
+                if (offset === 0) {
+                    services.store.recordQuery({
+                        envName,
+                        sql,
+                        durationMs: result.durationMs,
+                        rowCount: result.rowCount ?? result.rows.length,
+                    });
+                }
+                return result;
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                const message = error instanceof GucError ? error.message : describeQueryError(error);
+                if (offset === 0) {
+                    services.store.recordQuery({
+                        envName,
+                        sql,
+                        durationMs: performance.now() - started,
+                        error: message,
+                    });
+                }
+                throw new HttpError(400, message);
+            }
+        }
+        if (resource === 'envs' && name && sub === 'export' && req.method === 'POST') {
+            const body = (await readJson(req));
+            try {
+                if (typeof body?.table === 'string' && typeof body.schema === 'string') {
+                    const ref = { schema: body.schema, name: body.table };
+                    const filters = parseFilters(body.filters);
+                    const sort = parseSort(body.sort);
+                    return await withSessionFor(name, async (session) => {
+                        const columns = await listColumns(session, ref);
+                        for (const { column } of sort) {
+                            if (!columns.some((known) => known.name === column)) {
+                                throw new FilterError(`no column "${column}"`);
+                            }
+                        }
+                        const where = buildWhere(columns, filters);
+                        const result = await browseRows(session, ref, {
+                            limit: EXPORT_MAX_ROWS,
+                            orderBy: sort,
+                            where,
+                        });
+                        return { columns: result.columns, rows: result.rows, truncated: result.truncated };
+                    });
+                }
+                if (typeof body?.sql !== 'string' || !canExport(body.sql)) {
+                    throw new HttpError(400, 'send {"sql": "SELECT ..."} or {"schema", "table"}: only queries that return rows can be exported');
+                }
+                const sql = body.sql;
+                const gucs = parseGucs(body.settings);
+                const result = await withSessionFor(name, async (session) => {
+                    await applyGucs(session, gucs);
+                    return exportRows(session, sql);
+                });
+                return { columns: result.columns, rows: result.rows, truncated: result.truncated };
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof FilterError)
+                    throw new HttpError(400, error.message);
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'edit' && req.method === 'POST') {
+            const body = (await readJson(req, MAX_EDIT_BODY_BYTES));
+            if (typeof body?.schema !== 'string' || typeof body.table !== 'string') {
+                throw new HttpError(400, 'send {"schema", "table", "action", "key"?, "values"?, "apply"?}');
+            }
+            const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+            const cells = (value) => {
+                if (value === undefined)
+                    return {};
+                if (!isRecord(value))
+                    throw new HttpError(400, 'values is {column: text or null}');
+                for (const cell of Object.values(value)) {
+                    if (cell !== null && typeof cell !== 'string') {
+                        throw new HttpError(400, 'values is {column: text or null}');
+                    }
+                }
+                return value;
+            };
+            const keyed = (value) => {
+                const key = cells(value);
+                if (Object.values(key).some((cell) => cell === null)) {
+                    throw new HttpError(400, 'a key has no NULL values');
+                }
+                return key;
+            };
+            let request;
+            if (body.action === 'insert')
+                request = { action: 'insert', values: cells(body.values) };
+            else if (body.action === 'update') {
+                request = { action: 'update', key: keyed(body.key), values: cells(body.values) };
+            }
+            else if (body.action === 'delete')
+                request = { action: 'delete', key: keyed(body.key) };
+            else
+                throw new HttpError(400, 'action is insert, update or delete');
+            const ref = { schema: body.schema, name: body.table };
+            try {
+                return await withSessionFor(name, async (session) => {
+                    const edit = buildEdit(ref, await listColumns(session, ref), request);
+                    if (body.apply !== true)
+                        return { sql: edit.display, applied: false };
+                    if (session.readOnly) {
+                        throw new HttpError(400, 'this environment is read only: turn on write mode first');
+                    }
+                    const result = await applyEdit(session, edit);
+                    const entry = environmentNamed(name);
+                    services.store.recordQuery({
+                        envName: entry.name,
+                        sql: edit.display,
+                        durationMs: result.durationMs,
+                        rowCount: 1,
+                    });
+                    return { sql: edit.display, applied: true };
+                });
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof EditError)
+                    throw new HttpError(400, error.message);
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'seed') {
+            const entry = environmentNamed(name);
+            if (!entry.seeder) {
+                throw new HttpError(403, `the seeder is turned off for ${entry.name}: set seeder: true in its explorer.yaml to use it`);
+            }
+            if (req.method === 'GET') {
+                const schema = requiredParam(url, 'schema');
+                const table = requiredParam(url, 'table');
+                try {
+                    const ref = { schema, name: table };
+                    const [columns, foreignKeys] = await withSessionFor(name, async (session) => [
+                        await describeSeedColumns(session, ref),
+                        (await listForeignKeys(session, ref)).outgoing,
+                    ]);
+                    return {
+                        columns,
+                        foreignKeys,
+                        generators,
+                        locales: seedLocales,
+                        maxRows: MAX_SEED_ROWS,
+                    };
+                }
+                catch (error) {
+                    throw new HttpError(400, describeQueryError(error));
+                }
+            }
+            if (req.method === 'POST') {
+                const body = (await readJson(req));
+                if (typeof body?.schema !== 'string' || typeof body.table !== 'string') {
+                    throw new HttpError(400, 'send {"schema", "table", "count", "columns", "apply"?}');
+                }
+                const ref = { schema: body.schema, name: body.table };
+                try {
+                    const request = parseSeedRequest(body);
+                    return await withSessionFor(name, async (session) => {
+                        if (body.apply !== true)
+                            return { preview: await previewSeed(session, ref, request) };
+                        if (session.readOnly) {
+                            throw new HttpError(400, 'this environment is read only: turn on write mode first');
+                        }
+                        const result = await runSeed(session, ref, request);
+                        services.store.recordQuery({
+                            envName: entry.name,
+                            sql: `-- seeder: ${result.inserted} generated rows\n${result.sql}`,
+                            durationMs: result.durationMs,
+                            rowCount: result.inserted,
+                        });
+                        return { result };
+                    });
+                }
+                catch (error) {
+                    if (error instanceof HttpError)
+                        throw error;
+                    if (error instanceof SeedError)
+                        throw new HttpError(400, error.message);
+                    throw new HttpError(400, describeQueryError(error));
+                }
+            }
+        }
+        if (resource === 'envs' && name && sub === 'design' && req.method === 'GET') {
+            environmentNamed(name);
+            const schema = requiredParam(url, 'schema');
+            const table = requiredParam(url, 'name');
+            const loaded = await withSessionFor(name, (session) => loadDesign(session, { schema, name: table }));
+            if (!loaded)
+                throw new HttpError(404, `no table ${schema}.${table}`);
+            return loaded;
+        }
+        if (resource === 'envs' && name && (sub === 'alter' || sub === 'drop-table') && req.method === 'POST') {
+            const entry = environmentNamed(name);
+            const body = (await readJson(req));
+            const lockTimeoutMs = typeof body?.lockTimeoutMs === 'number' ? body.lockTimeoutMs : 5000;
+            let statements;
+            let estimatedRows = null;
+            try {
+                if (sub === 'drop-table') {
+                    const schema = body?.schema;
+                    const table = body?.name;
+                    if (typeof schema !== 'string' || typeof table !== 'string') {
+                        throw new AlterError('send {"schema", "name", "cascade"?, "apply"?}');
+                    }
+                    statements = [dropTableStatement({ schema, name: table }, body?.cascade === true)];
+                }
+                else {
+                    const before = parseTableDesign(body?.original);
+                    const after = parseTableDesign(body?.design);
+                    const options = parseAlterOptions(body?.options);
+                    const loaded = await withSessionFor(name, (session) => loadDesign(session, before));
+                    if (!loaded)
+                        throw new HttpError(404, `no table ${before.schema}.${before.name}`);
+                    estimatedRows = loaded.estimatedRows;
+                    statements = diffDesigns(before, after, {
+                        ...options,
+                        estimatedRows,
+                        serverMajor: loaded.serverMajor,
+                    });
+                }
+                const plan = splitPlan(statements, lockTimeoutMs);
+                if (body?.apply !== true) {
+                    return { statements, lockTimeout: plan.transactional[0]?.startsWith('SET LOCAL') ? plan.transactional[0] : null, estimatedRows };
+                }
+                if (!entry.designer) {
+                    throw new HttpError(403, `the designer is turned off for ${entry.name}: set designer: true in its explorer.yaml to change tables`);
+                }
+                if (statements.length === 0)
+                    throw new HttpError(400, 'there is nothing to change');
+                const session = await withSessionFor(name, (opened) => Promise.resolve(opened.readOnly));
+                if (session)
+                    throw new HttpError(400, 'this environment is read only: turn on write mode first');
+                if (statements.some((statement) => statement.drop)) {
+                    // Asked every time, like switching on write mode: it drops something that cannot come back.
+                    const prompt = services.resolvers.get('prompt');
+                    if (!prompt)
+                        throw new HttpError(400, 'there is no way to ask for confirmation');
+                    try {
+                        await prompt.confirm({ envName: entry.name, interactive: true, signal, purpose: 'drop' });
+                    }
+                    catch (error) {
+                        if (error instanceof ResolveError)
+                            throw new HttpError(400, error.message);
+                        throw error;
+                    }
+                }
+                return await withSessionFor(name, async (opened) => {
+                    const result = await runPlan(opened, plan, describeQueryError);
+                    services.store.recordQuery({
+                        envName: entry.name,
+                        sql: [...plan.transactional, ...plan.concurrent].map((statement) => `${statement};`).join('\n'),
+                        durationMs: result.durationMs,
+                    });
+                    return { statements, applied: true };
+                });
+            }
+            catch (error) {
+                if (error instanceof HttpError)
+                    throw error;
+                if (error instanceof DdlError)
+                    throw new HttpError(400, error.message);
+                if (error instanceof DesignRunError) {
+                    throw new HttpError(400, error.message, { statement: error.statement });
+                }
+                throw new HttpError(400, describeQueryError(error));
+            }
+        }
+        if (resource === 'envs' && name && sub === 'design' && req.method === 'POST') {
+            const entry = environmentNamed(name);
+            const body = (await readJson(req));
+            let statements;
             try {
-                return await withSessionFor(name, (session) => runPage(session, sql, { limit, offset }));
+                const design = parseTableDesign(body?.design);
+                // The statements are built from the design alone; the server's own version only matters when
+                // they run, where it refuses what it lacks with its own message.
+                statements = buildDdl(design);
+            }
+            catch (error) {
+                if (error instanceof DdlError)
+                    throw new HttpError(400, error.message);
+                throw error;
+            }
+            if (body?.apply !== true)
+                return { statements };
+            if (!entry.designer) {
+                throw new HttpError(403, `the designer is turned off for ${entry.name}: set designer: true in its explorer.yaml to create tables`);
+            }
+            try {
+                return await withSessionFor(name, async (session) => {
+                    if (session.readOnly) {
+                        throw new HttpError(400, 'this environment is read only: turn on write mode first');
+                    }
+                    const result = await runStatements(session, statements, describeQueryError);
+                    services.store.recordQuery({
+                        envName: entry.name,
+                        sql: statements.map((statement) => `${statement};`).join('\n'),
+                        durationMs: result.durationMs,
+                    });
+                    return { statements, applied: true };
+                });
             }
             catch (error) {
                 if (error instanceof HttpError)
                     throw error;
+                if (error instanceof DesignRunError) {
+                    throw new HttpError(400, error.message, { statement: error.statement });
+                }
                 throw new HttpError(400, describeQueryError(error));
             }
         }
+        if (resource === 'envs' && name && sub === 'history' && req.method === 'GET') {
+            const entry = environmentNamed(name);
+            const text = (url.searchParams.get('q') ?? '').trim().toLowerCase();
+            const limit = Math.min(Math.max(Number(url.searchParams.get('limit')) || 100, 1), 500);
+            // Newest first; the search runs over all that is kept, not only what is shown.
+            return services.store
+                .historyFor(entry.name, 5000)
+                .filter((record) => !text || record.sql.toLowerCase().includes(text))
+                .slice(0, limit);
+        }
+        if (resource === 'envs' && name && sub === 'saved' && !id && req.method === 'GET') {
+            return services.store.savedQueries(environmentNamed(name).name);
+        }
+        if (resource === 'envs' && name && sub === 'saved' && !id && req.method === 'POST') {
+            const entry = environmentNamed(name);
+            const body = (await readJson(req));
+            if (typeof body?.sql !== 'string' || body.sql.trim() === '') {
+                throw new HttpError(400, 'send {"name", "sql", "folder"?, "pinned"?}');
+            }
+            return services.store.saveQuery({
+                envName: entry.name,
+                name: savedName(body.name, body.sql),
+                folder: typeof body.folder === 'string' ? body.folder.trim().slice(0, 60) : '',
+                sql: body.sql,
+                pinned: body.pinned === true,
+            });
+        }
+        if (resource === 'envs' &&
+            name &&
+            sub === 'saved' &&
+            id &&
+            (req.method === 'POST' || req.method === 'DELETE')) {
+            const entry = environmentNamed(name);
+            const savedId = Number(id);
+            // Only a query saved for this environment can be changed through it.
+            const found = services.store.savedQueries(entry.name).find((saved) => saved.id === savedId);
+            if (!found)
+                throw new HttpError(404, 'no such saved query');
+            if (req.method === 'DELETE') {
+                services.store.deleteSavedQuery(savedId);
+                return {};
+            }
+            const body = (await readJson(req));
+            return services.store.updateSavedQuery(savedId, {
+                ...(typeof body?.name === 'string' && body.name.trim()
+                    ? { name: savedName(body.name, found.sql) }
+                    : {}),
+                ...(typeof body?.folder === 'string' ? { folder: body.folder.trim().slice(0, 60) } : {}),
+                ...(typeof body?.sql === 'string' && body.sql.trim() ? { sql: body.sql } : {}),
+                ...(typeof body?.pinned === 'boolean' ? { pinned: body.pinned } : {}),
+            });
+        }
         if (resource === 'envs' && name && sub === 'explain' && req.method === 'POST') {
             const body = (await readJson(req));
             if (typeof body?.sql !== 'string' || body.sql.trim() === '') {
-                throw new HttpError(400, 'send {"sql": "..."}');
+                throw new HttpError(400, 'send {"sql": "...", "analyze"?: true}');
             }
             const sql = body.sql;
             try {
-                return { plan: await withSessionFor(name, (session) => explainQuery(session, sql)) };
+                const gucs = parseGucs(body.settings);
+                // Analyzing runs the statement (and rolls it back) to measure each step.
+                if (body.analyze === true) {
+                    return await withSessionFor(name, async (session) => {
+                        await applyGucs(session, gucs);
+                        return explainAnalyze(session, sql);
+                    });
+                }
+                return {
+                    plan: await withSessionFor(name, async (session) => {
+                        await applyGucs(session, gucs);
+                        return explainQuery(session, sql);
+                    }),
+                };
             }
             catch (error) {
                 if (error instanceof HttpError)
                     throw error;
+                if (error instanceof GucError)
+                    throw new HttpError(400, error.message);
                 throw new HttpError(400, describeQueryError(error));
             }
         }
@@ -306,7 +939,7 @@ export function createWebServer(options) {
             }
             catch (error) {
                 if (error instanceof HttpError) {
-                    sendJson(res, error.status, { error: error.message });
+                    sendJson(res, error.status, { ...error.extra, error: error.message });
                 }
                 else {
                     sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });