firstly 0.10.5 → 0.10.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # firstly
 
+## 0.10.7
+
+### Patch Changes
+
+- [#388](https://github.com/jycouet/firstly/pull/388) [`7eca18a`](https://github.com/jycouet/firstly/commit/7eca18af4a55e2481dc81d38ba9e4f7f0d0f01a0) Thanks [@jycouet](https://github.com/jycouet)! - sqlAdmin: reads now run as a read-only Postgres role upserted at boot (`readPool`, default `'auto'`, `false` to opt out, or your own pool); `tokens.pool` is removed. SQL and results now travel encoded (`ffsql1:`) from `<SqlAdmin />` and `ff-sql`, so WAF rules stop blocking them; plain SQL still works.
+
+## 0.10.6
+
+### Patch Changes
+
+- [#383](https://github.com/jycouet/firstly/pull/383) [`3d0353b`](https://github.com/jycouet/firstly/commit/3d0353b176afd765883c50f6bc10c352b752df28) Thanks [@jycouet](https://github.com/jycouet)! - sqlAdmin drift: entities in a non-`public` schema (e.g. `ff_auth.ba-accounts`) are checked in their own schema, a table not created yet is reported as `missing` instead of failing the whole apply, and errors show the real message and failing statement (no more `[object Object]`).
+
 ## 0.10.5
 
 ### Patch Changes

package/bin/args.d.ts

@@ -1,10 +1,11 @@
 /**
  * @param {string[]} argv
- * @returns {{ help: boolean, json: boolean, origin?: string, apiPath?: string, sql: string, error?: string }}
+ * @returns {{ help: boolean, json: boolean, raw: boolean, origin?: string, apiPath?: string, sql: string, error?: string }}
  */
 export function parseArgs(argv: string[]): {
     help: boolean;
     json: boolean;
+    raw: boolean;
     origin?: string;
     apiPath?: string;
     sql: string;

package/bin/args.js

@@ -2,7 +2,7 @@
 // the cli. Plain JS like its caller: bin/ ships unbuilt.
 
 /** Flags that take no value. */
-const BOOLEAN = ['json', 'help']
+const BOOLEAN = ['json', 'help', 'raw']
 /** Flags that need one, as `--x=y` or `--x y`. */
 const VALUED = ['origin', 'api-path']
 
@@ -13,11 +13,11 @@ const FLAG = /^--[a-z][\w-]*(=|$)/
 
 /**
  * @param {string[]} argv
- * @returns {{ help: boolean, json: boolean, origin?: string, apiPath?: string, sql: string, error?: string }}
+ * @returns {{ help: boolean, json: boolean, raw: boolean, origin?: string, apiPath?: string, sql: string, error?: string }}
  */
 export function parseArgs(argv) {
 	/** @type {any} */
-	const out = { help: false, json: false, sql: '' }
+	const out = { help: false, json: false, raw: false, sql: '' }
 	const positional = []
 	const seen = new Set()
 

package/bin/ff-sql.js

@@ -15,6 +15,7 @@ const HELP = `ff-sql - run SQL through a firstly sql token
   SQL
 
   --json          raw JSON instead of a table
+  --raw           send plain SQL, not ffsql1: (servers older than the encoding)
   --              end of flags, everything after is SQL
   --origin=URL    the app to query (or FF_SQL_ORIGIN)
   --api-path=P    remult api root (default /api)
@@ -27,6 +28,13 @@ camelCase and need double quotes: "createdAt", not created_at. A heredoc avoids
 fighting the shell over single quotes, and keeps the token out of the line.`
 
 const TRAILING_SLASH = /\/$/
+// Same scheme as `sqlWire.ts`: keeps WAF rules from matching SQL in transit.
+const WIRE = 'ffsql1:'
+const encode = (s) => WIRE + Buffer.from(s, 'utf8').toString('base64')
+const decode = (s) =>
+	typeof s === 'string' && s.startsWith(WIRE)
+		? Buffer.from(s.slice(WIRE.length), 'base64').toString('utf8')
+		: s
 
 const cli = parseArgs(process.argv.slice(2))
 
@@ -65,7 +73,7 @@ try {
 	res = await fetch(`${origin.replace(TRAILING_SLASH, '')}${apiPath}/ff/sqlAdmin/exec`, {
 		method: 'POST',
 		headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
-		body: JSON.stringify({ args: [cmd] }),
+		body: JSON.stringify({ args: [cli.raw ? cmd : encode(cmd)] }),
 	})
 } catch (err) {
 	console.error(`${origin} unreachable: ${err.message}`)
@@ -75,11 +83,13 @@ try {
 const body = await res.json().catch(() => null)
 if (!res.ok) {
 	// 403 here is almost always a dead token: expired, revoked, or minted elsewhere.
-	console.error(`${res.status} ${body?.message ?? res.statusText}`)
+	console.error(`${res.status} ${decode(body?.message) ?? res.statusText}`)
 	process.exit(1)
 }
 
-const { rows, rowCount, took } = body.data ?? body
+let data = body.data ?? body
+if (typeof data === 'string') data = JSON.parse(decode(data))
+const { rows, rowCount, took } = data
 // Table and rows on stdout, the summary on stderr, so `| jq` and `> file` stay clean.
 const out = new Console(process.stdout)
 if (cli.json) out.log(JSON.stringify(rows, null, 2))

package/esm/mail/ui/LastMails.svelte

@@ -3,6 +3,7 @@
 
 	import { remult, repo } from 'remult'
 
+	import { errorMessage } from '../../core/helper.js'
 	import { Mail } from '../Mail'
 	import { Roles_Mail } from '../Roles_Mail'
 
@@ -28,7 +29,7 @@
 		try {
 			mails = await repo(Mail).find({ limit })
 		} catch (e) {
-			error = e instanceof Error ? e.message : String(e)
+			error = errorMessage(e)
 		} finally {
 			isLoading = false
 		}

package/esm/sqlAdmin/SqlAdminController.d.ts

@@ -47,17 +47,19 @@ export type SqlTokensOptions = {
     apiPath?: string;
     /** @default 30 */
     callLogRetentionDays?: number;
-    /** Override the pool used by `read` tokens. Defaults to the Postgres pool behind the data provider. */
-    pool?: SqlTokenPool;
 };
 export declare const SERVER_ONLY = "sqlAdmin: server-only";
 export declare const SQL_ADMINS: ("FF_Role.Admin" | "SqlAdmin.Admin")[];
+export declare function getDb(): SqlDatabase;
+/** The pg pool remult wraps, if any. `_getSourceSql` is internal but has been stable since remult 1. */
+export declare function poolFrom(db: SqlDatabase): SqlTokenPool | undefined;
 export declare class SqlAdminController {
     /** Optional override set by the `sqlAdmin()` module's `initApi`. Falls back to `SqlDatabase.getDb()`. */
     static dp?: SqlDatabase;
     /** Set by the `sqlAdmin()` module's `initApi`. */
     static options: {
         tokens?: SqlTokensOptions;
+        readPool?: SqlTokenPool;
     };
     /**
      * @param cmd SQL to run.
@@ -67,8 +69,11 @@ export declare class SqlAdminController {
      *   want to mutate - the UI gates this behind an explicit checkbox.
      *
      * With a sql token the token decides, not the caller.
+     *
+     * A `cmd` sent through `encodeSqlWire` gets its result (or error message)
+     * back encoded the same way, as a string; plain SQL gets plain JSON.
      */
-    static exec(cmd: string, capabilities?: SqlCapability[]): Promise<SqlResult>;
+    static exec(cmd: string, capabilities?: SqlCapability[]): Promise<SqlResult | string>;
     private static run;
     private static execAsToken;
     /**

package/esm/sqlAdmin/SqlAdminController.js

@@ -5,21 +5,25 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { BackendMethod, remult, repo, SqlDatabase } from 'remult';
+import { Log } from '@kitql/helpers';
 import { FF_Role } from '../core/common';
 import { Roles_SqlAdmin } from './Roles_SqlAdmin';
 import { SQL_CAPABILITIES, SQL_TOKEN_TTLS, SqlToken, SqlTokenCall, } from './sqlTokenEntities';
+import { decodeSqlWire, encodeSqlWire, isSqlWire } from './sqlWire';
 // Thrown when a server-only body runs on the client (its `import.meta.env.SSR` block is gone there).
 export const SERVER_ONLY = 'sqlAdmin: server-only';
 export const SQL_ADMINS = [Roles_SqlAdmin.SqlAdmin_Admin, FF_Role.FF_Role_Admin];
 const CALL_LOG_CMD_MAX = 4000;
+// Not `log` from '../index': that barrel pulls the svelte components into the server.
+const log = new Log('sqlAdmin');
 /** Retention is a housekeeping sweep, not something to pay for on every query. */
 const CALL_LOG_SWEEP_EVERY_MS = 3_600_000;
 let lastCallLogSweep = 0;
-function getDb() {
+export function getDb() {
     return SqlAdminController.dp ?? SqlDatabase.getDb();
 }
 /** The pg pool remult wraps, if any. `_getSourceSql` is internal but has been stable since remult 1. */
-function poolFrom(db) {
+export function poolFrom(db) {
     const pool = db._getSourceSql?.()?.pool;
     return typeof pool?.connect === 'function' ? pool : undefined;
 }
@@ -36,12 +40,35 @@ export class SqlAdminController {
      *   want to mutate - the UI gates this behind an explicit checkbox.
      *
      * With a sql token the token decides, not the caller.
+     *
+     * A `cmd` sent through `encodeSqlWire` gets its result (or error message)
+     * back encoded the same way, as a string; plain SQL gets plain JSON.
      */
     static async exec(cmd, capabilities = ['read']) {
-        const token = remult.context.sqlToken;
-        if (token)
-            return SqlAdminController.execAsToken(token, cmd);
-        return SqlAdminController.run(cmd, capabilities);
+        const wire = isSqlWire(cmd);
+        if (wire)
+            cmd = decodeSqlWire(cmd);
+        try {
+            const token = remult.context.sqlToken;
+            const res = token
+                ? await SqlAdminController.execAsToken(token, cmd)
+                : await SqlAdminController.run(cmd, capabilities);
+            return wire ? encodeSqlWire(JSON.stringify(res)) : res;
+        }
+        catch (err) {
+            if (!wire)
+                throw err;
+            const msg = err instanceof Error ? err.message : String(err);
+            // remult logs the message it sends, so the clear one goes to the server log here.
+            log.error(msg);
+            // No stack: it repeats the message in clear. Status flags kept, or a 403 turns into a 400.
+            const { httpStatusCode, isForbiddenError } = (err ?? {});
+            throw Object.assign(new Error(encodeSqlWire(msg)), {
+                stack: undefined,
+                httpStatusCode,
+                isForbiddenError,
+            });
+        }
     }
     static async run(cmd, capabilities) {
         if (import.meta.env.SSR) {
@@ -54,7 +81,8 @@ export class SqlAdminController {
                     return { rows, rowCount: rows.length, took: performance.now() - start };
                 }
                 const { readOnlySql } = await import('./server/readOnlySql');
-                return await readOnlySql(db, SqlAdminController.options.tokens?.pool ?? poolFrom(db), cmd);
+                const o = SqlAdminController.options;
+                return await readOnlySql(db, o.readPool ?? poolFrom(db), cmd);
             }
             catch (err) {
                 const { enrichSqlError } = await import('./server/sqlError');

package/esm/sqlAdmin/index.d.ts

@@ -3,6 +3,7 @@ export { Roles_SqlAdmin } from './Roles_SqlAdmin';
 export { SqlAdminController, type SqlResult, type SqlTokensOptions } from './SqlAdminController';
 export { SqlDriftController, type SqlDriftFlag } from './SqlDriftController';
 export { SQL_CAPABILITIES, SQL_TOKEN_TTLS, SqlToken, SqlTokenCall, type SqlCapability, type SqlTokenTtl, } from './sqlTokenEntities';
+export { decodeSqlWire, encodeSqlWire, isSqlWire, SQL_WIRE_PREFIX } from './sqlWire';
 export { default as SqlAdmin } from './ui/SqlAdmin.svelte';
 export { default as SqlDrift } from './ui/SqlDrift.svelte';
 export { default as SqlTokens } from './ui/SqlTokens.svelte';

package/esm/sqlAdmin/index.js

@@ -3,6 +3,7 @@ export { Roles_SqlAdmin } from './Roles_SqlAdmin';
 export { SqlAdminController } from './SqlAdminController';
 export { SqlDriftController } from './SqlDriftController';
 export { SQL_CAPABILITIES, SQL_TOKEN_TTLS, SqlToken, SqlTokenCall, } from './sqlTokenEntities';
+export { decodeSqlWire, encodeSqlWire, isSqlWire, SQL_WIRE_PREFIX } from './sqlWire';
 export { default as SqlAdmin } from './ui/SqlAdmin.svelte';
 export { default as SqlDrift } from './ui/SqlDrift.svelte';
 export { default as SqlTokens } from './ui/SqlTokens.svelte';

package/esm/sqlAdmin/server/drift/catalog.d.ts

@@ -0,0 +1,4 @@
+import type { SqlDatabase } from 'remult';
+export declare function execStmt(db: SqlDatabase, sql: string): Promise<import("remult").SqlResult>;
+/** Live tables as `tableKey`s: an entity's table may never have been created (no migration run yet). */
+export declare function liveTables(db: SqlDatabase): Promise<Set<string>>;

package/esm/sqlAdmin/server/drift/catalog.js

@@ -0,0 +1,25 @@
+import { enrichSqlError } from '../sqlError';
+import { tableKeySql, USER_SCHEMA_SQL } from './ident';
+// A drift apply runs many statements in one transaction: without the statement, a
+// bare "could not create unique index" can't be traced back to its table.
+export async function execStmt(db, sql) {
+    try {
+        return await db.createCommand().execute(sql);
+    }
+    catch (err) {
+        const enriched = await enrichSqlError(db, err, sql);
+        const msg = enriched instanceof Error ? enriched.message : String(enriched);
+        throw new Error(`${msg}\n\nWhile running: ${sql.trim()}\nNothing was applied (rolled back).`, {
+            cause: err,
+        });
+    }
+}
+/** Live tables as `tableKey`s: an entity's table may never have been created (no migration run yet). */
+export async function liveTables(db) {
+    const res = await db.createCommand().execute(`
+		SELECT ${tableKeySql('table_schema', 'table_name')} AS table_key
+		FROM information_schema.tables
+		WHERE ${USER_SCHEMA_SQL('table_schema')} AND table_type = 'BASE TABLE';
+	`);
+    return new Set(res.rows.map((r) => r.table_key));
+}

package/esm/sqlAdmin/server/drift/createIndex.d.ts

@@ -14,6 +14,8 @@ export type IndexOptions = {
 export declare function formatCreateIndex(o: {
     name: string;
     table: string;
+    /** Omit for the search path (usually `public`). */
+    schema?: string;
     columns: string[];
     unique?: boolean;
     concurrently?: boolean;

package/esm/sqlAdmin/server/drift/createIndex.js

@@ -14,7 +14,8 @@ export function formatCreateIndex(o) {
         parts.push('CONCURRENTLY');
     if (o.ifNotExists)
         parts.push('IF NOT EXISTS');
-    parts.push(wrap(o.name), 'ON', wrap(o.table), `(${o.columns.map(wrap).join(', ')})`);
+    const table = o.schema ? `${wrap(o.schema)}.${wrap(o.table)}` : wrap(o.table);
+    parts.push(wrap(o.name), 'ON', table, `(${o.columns.map(wrap).join(', ')})`);
     return parts.join(' ') + ';';
 }
 /**

package/esm/sqlAdmin/server/drift/ident.d.ts

@@ -1,2 +1,18 @@
 /** pg catalog / metadata names can come back quoted or schema-qualified. */
 export declare const stripIdent: (name: string) => string;
+/**
+ * Table key shared by metadata and catalog sides of every diff: bare name in `public`,
+ * `schema.name` elsewhere - so an entity in another schema is neither lost nor
+ * mistaken for a same-named `public` table.
+ */
+export declare function tableKey(dbName: string): string;
+/** Same key, computed in SQL from a schema and a table column. */
+export declare const tableKeySql: (schema: string, table: string) => string;
+export declare function splitKey(key: string): {
+    schema?: string;
+    table: string;
+};
+/** Quoted, schema-qualified SQL reference for a `tableKey`. */
+export declare function quoteTable(key: string): string;
+/** Schemas the drift checks read: every user schema, not the system ones. */
+export declare const USER_SCHEMA_SQL: (schema: string) => string;

package/esm/sqlAdmin/server/drift/ident.js

@@ -1,2 +1,24 @@
 /** pg catalog / metadata names can come back quoted or schema-qualified. */
 export const stripIdent = (name) => name.replaceAll('"', '').split('.').pop();
+/**
+ * Table key shared by metadata and catalog sides of every diff: bare name in `public`,
+ * `schema.name` elsewhere - so an entity in another schema is neither lost nor
+ * mistaken for a same-named `public` table.
+ */
+export function tableKey(dbName) {
+    const [name, schema] = dbName.replaceAll('"', '').split('.').toReversed();
+    return schema && schema !== 'public' ? `${schema}.${name}` : name;
+}
+/** Same key, computed in SQL from a schema and a table column. */
+export const tableKeySql = (schema, table) => `CASE WHEN ${schema} = 'public' THEN ${table} ELSE ${schema} || '.' || ${table} END`;
+export function splitKey(key) {
+    const dot = key.indexOf('.');
+    return dot === -1 ? { table: key } : { schema: key.slice(0, dot), table: key.slice(dot + 1) };
+}
+/** Quoted, schema-qualified SQL reference for a `tableKey`. */
+export function quoteTable(key) {
+    const { schema, table } = splitKey(key);
+    return schema ? `"${schema}"."${table}"` : `"${table}"`;
+}
+/** Schemas the drift checks read: every user schema, not the system ones. */
+export const USER_SCHEMA_SQL = (schema) => `${schema} NOT IN ('pg_catalog', 'information_schema') AND ${schema} NOT LIKE 'pg\\_toast%'`;

package/esm/sqlAdmin/server/drift/nullable.js

@@ -1,6 +1,7 @@
 import { repo } from 'remult';
 import { getRelationFieldInfo } from 'remult/internals';
-import { stripIdent } from './ident';
+import { execStmt } from './catalog';
+import { quoteTable, stripIdent, tableKey, tableKeySql, USER_SCHEMA_SQL } from './ident';
 import { planNullableDrift, } from './planNullableDrift';
 // Only a text column has an empty value that is unambiguously "unset". A numeric or
 // boolean default (0 / false) may be genuine data, so those columns get their
@@ -31,7 +32,7 @@ export async function syncNullable(db, entities, opts) {
         const meta = repo(ent).metadata;
         if (meta.options.sqlExpression)
             continue; // views: no real table
-        const table = stripIdent(meta.dbName);
+        const table = tableKey(meta.dbName);
         for (const field of meta.fields.toArray()) {
             if (getRelationFieldInfo(field))
                 continue; // FK scalars are declared by their own field
@@ -41,13 +42,13 @@ export async function syncNullable(db, entities, opts) {
         }
     }
     const res = await db.createCommand().execute(`
-		SELECT table_name, column_name, is_nullable, column_default, data_type
+		SELECT ${tableKeySql('table_schema', 'table_name')} AS table_key, column_name, is_nullable, column_default, data_type
 		FROM information_schema.columns
-		WHERE table_schema = 'public'
-		ORDER BY table_name, ordinal_position;
+		WHERE ${USER_SCHEMA_SQL('table_schema')}
+		ORDER BY table_key, ordinal_position;
 	`);
     const current = res.rows.map((row) => ({
-        table: row.table_name,
+        table: row.table_key,
         column: row.column_name,
         isNullable: row.is_nullable === 'YES',
         hasDefault: row.column_default != null,
@@ -63,15 +64,13 @@ export async function syncNullable(db, entities, opts) {
             .map((c) => drifted.get(`${c.table}.${c.column}`))
             .filter((p) => !!p);
         for (const p of fixed) {
-            const col = `ALTER TABLE "${p.table}" ALTER COLUMN "${p.column}"`;
+            const col = `ALTER TABLE ${quoteTable(p.table)} ALTER COLUMN "${p.column}"`;
             if (p.dropDefault)
-                await db.createCommand().execute(`${col} DROP DEFAULT;`);
+                await execStmt(db, `${col} DROP DEFAULT;`);
             if (p.dropNotNull)
-                await db.createCommand().execute(`${col} DROP NOT NULL;`);
+                await execStmt(db, `${col} DROP NOT NULL;`);
             if (p.blankToNull) {
-                await db
-                    .createCommand()
-                    .execute(`UPDATE "${p.table}" SET "${p.column}" = NULL WHERE "${p.column}" = '';`);
+                await execStmt(db, `UPDATE ${quoteTable(p.table)} SET "${p.column}" = NULL WHERE "${p.column}" = '';`);
             }
         }
     }

package/esm/sqlAdmin/server/drift/orphanColumns.js

@@ -1,6 +1,7 @@
 import { repo } from 'remult';
 import { getRelationFieldInfo } from 'remult/internals';
-import { stripIdent } from './ident';
+import { execStmt } from './catalog';
+import { quoteTable, stripIdent, tableKey, tableKeySql, USER_SCHEMA_SQL } from './ident';
 import { planDropColumns } from './planDropColumns';
 /**
  * Audit - and optionally drop a selected subset of - orphan columns: live DB
@@ -45,20 +46,20 @@ export async function dropColumns(db, entities, opts) {
                 continue; // computed, no stored column
             columns.push(stripIdent(field.dbName));
         }
-        known.push({ table: stripIdent(meta.dbName), columns });
+        known.push({ table: tableKey(meta.dbName), columns });
     }
     // Live columns per table from the catalog, in ordinal order.
     const res = await db.createCommand().execute(`
-		SELECT table_name, column_name
+		SELECT ${tableKeySql('table_schema', 'table_name')} AS table_key, column_name
 		FROM information_schema.columns
-		WHERE table_schema = 'public'
-		ORDER BY table_name, ordinal_position;
+		WHERE ${USER_SCHEMA_SQL('table_schema')}
+		ORDER BY table_key, ordinal_position;
 	`);
     const liveByTable = new Map();
     for (const row of res.rows) {
-        const list = liveByTable.get(row.table_name) ?? [];
+        const list = liveByTable.get(row.table_key) ?? [];
         list.push(row.column_name);
-        liveByTable.set(row.table_name, list);
+        liveByTable.set(row.table_key, list);
     }
     const current = Array.from(liveByTable, ([table, columns]) => ({ table, columns }));
     const plans = planDropColumns(current, known);
@@ -69,7 +70,7 @@ export async function dropColumns(db, entities, opts) {
         // raw client input, so the interpolated identifiers are trusted.
         dropped = opts.columns.filter((c) => orphan.has(`${c.table}.${c.column}`));
         for (const { table, column } of dropped) {
-            await db.createCommand().execute(`ALTER TABLE "${table}" DROP COLUMN "${column}";`);
+            await execStmt(db, `ALTER TABLE ${quoteTable(table)} DROP COLUMN "${column}";`);
         }
     }
     return { applied: opts?.apply ?? false, plans, dropped };

package/esm/sqlAdmin/server/drift/planPkSync.d.ts

@@ -17,7 +17,7 @@ export type PkDesired = {
     table: string;
     cols: string[];
 };
-type PkAction = 'ok' | 'create' | 'migrate';
+type PkAction = 'ok' | 'create' | 'migrate' | 'missing';
 export type PkPlan = {
     table: string;
     before: string[];
@@ -30,7 +30,8 @@ export type PkPlan = {
  * in `desired` (firstly infra, views, etc.) are left alone - we only manage what
  * an entity's `id` config describes. Several entities can share one table (a
  * light projection + the full row on the same `dbName`) - one plan per table,
- * first declaration wins, so the UI can key rows by table.
+ * first declaration wins, so the UI can key rows by table. `tables` is every live
+ * table: an entity whose table was never created is `missing`, not a PK to add.
  */
-export declare function planPkSync(current: PkCurrent[], desired: PkDesired[]): PkPlan[];
+export declare function planPkSync(current: PkCurrent[], desired: PkDesired[], tables: ReadonlySet<string>): PkPlan[];
 export {};

package/esm/sqlAdmin/server/drift/planPkSync.js

@@ -1,11 +1,4 @@
-/**
- * Pure planner: diff the live PRIMARY KEYs against what the entity `id` config
- * wants, and emit the minimal ALTER plan. No DB access here - the controller
- * feeds it the catalog snapshot + the metadata-derived target, runs the SQL.
- *
- * Why this exists: Remult only sets a table's PK on first creation and never
- * ALTERs it, so a later `id` change is silently ignored on long-lived DBs.
- */
+import { quoteTable } from './ident';
 const ident = (name) => `"${name}"`;
 const cols = (names) => names.map(ident).join(', ');
 const sameOrder = (a, b) => a.length === b.length && a.every((c, i) => c === b[i]);
@@ -14,21 +7,24 @@ const sameOrder = (a, b) => a.length === b.length && a.every((c, i) => c === b[i
  * in `desired` (firstly infra, views, etc.) are left alone - we only manage what
  * an entity's `id` config describes. Several entities can share one table (a
  * light projection + the full row on the same `dbName`) - one plan per table,
- * first declaration wins, so the UI can key rows by table.
+ * first declaration wins, so the UI can key rows by table. `tables` is every live
+ * table: an entity whose table was never created is `missing`, not a PK to add.
  */
-export function planPkSync(current, desired) {
+export function planPkSync(current, desired, tables) {
     const byTable = new Map(current.map((c) => [c.table, c]));
     const seen = new Set();
     return desired.flatMap(({ table, cols: after }) => {
         if (seen.has(table))
             return [];
         seen.add(table);
+        if (!tables.has(table))
+            return [{ table, before: [], after, action: 'missing', sql: [] }];
         return [planTable(byTable.get(table), table, after)];
     });
 }
 function planTable(cur, table, after) {
     const before = cur?.cols ?? [];
-    const addPk = `ALTER TABLE ${ident(table)} ADD PRIMARY KEY (${cols(after)});`;
+    const addPk = `ALTER TABLE ${quoteTable(table)} ADD PRIMARY KEY (${cols(after)});`;
     if (!cur)
         return { table, before, after, action: 'create', sql: [addPk] };
     if (sameOrder(cur.cols, after))
@@ -38,6 +34,6 @@ function planTable(cur, table, after) {
         before,
         after,
         action: 'migrate',
-        sql: [`ALTER TABLE ${ident(table)} DROP CONSTRAINT ${ident(cur.constraintName)};`, addPk],
+        sql: [`ALTER TABLE ${quoteTable(table)} DROP CONSTRAINT ${ident(cur.constraintName)};`, addPk],
     };
 }

package/esm/sqlAdmin/server/drift/primaryKeys.js

@@ -1,5 +1,6 @@
 import { repo } from 'remult';
-import { stripIdent } from './ident';
+import { execStmt, liveTables } from './catalog';
+import { stripIdent, tableKey, tableKeySql, USER_SCHEMA_SQL } from './ident';
 import { planPkSync } from './planPkSync';
 /**
  * Audit - and optionally fix - PRIMARY KEY drift between the live DB and each
@@ -19,21 +20,22 @@ import { planPkSync } from './planPkSync';
 export async function reindexPrimaryKeys(db, entities, opts) {
     // Live PKs from the catalog, columns kept in constraint order.
     const res = await db.createCommand().execute(`
-		SELECT tc.table_name, tc.constraint_name, kcu.column_name
+		SELECT ${tableKeySql('tc.table_schema', 'tc.table_name')} AS table_key,
+			tc.constraint_name, kcu.column_name
 		FROM information_schema.table_constraints tc
 		JOIN information_schema.key_column_usage kcu
 			ON tc.constraint_name = kcu.constraint_name
 			AND tc.table_schema = kcu.table_schema
 		WHERE tc.constraint_type = 'PRIMARY KEY'
-			AND tc.table_schema = 'public'
-		ORDER BY tc.table_name, kcu.ordinal_position;
+			AND ${USER_SCHEMA_SQL('tc.table_schema')}
+		ORDER BY table_key, kcu.ordinal_position;
 	`);
     const byTable = new Map();
     for (const row of res.rows) {
-        let cur = byTable.get(row.table_name);
+        let cur = byTable.get(row.table_key);
         if (!cur) {
-            cur = { table: row.table_name, constraintName: row.constraint_name, cols: [] };
-            byTable.set(row.table_name, cur);
+            cur = { table: row.table_key, constraintName: row.constraint_name, cols: [] };
+            byTable.set(row.table_key, cur);
         }
         cur.cols.push(row.column_name);
     }
@@ -46,14 +48,15 @@ export async function reindexPrimaryKeys(db, entities, opts) {
         const cols = meta.idMetadata.fields.map((f) => stripIdent(f.dbName));
         if (cols.length === 0)
             continue;
-        desired.push({ table: stripIdent(meta.dbName), cols });
+        desired.push({ table: tableKey(meta.dbName), cols });
     }
-    const plans = planPkSync([...byTable.values()], desired);
+    const tables = await liveTables(db);
+    const plans = planPkSync([...byTable.values()], desired, tables);
     if (opts?.apply) {
         for (const plan of plans) {
             // Fail-fast: any throw aborts the shared transaction -> full rollback.
             for (const stmt of plan.sql)
-                await db.createCommand().execute(stmt);
+                await execStmt(db, stmt);
         }
     }
     return { applied: opts?.apply ?? false, plans };

package/esm/sqlAdmin/server/drift/relationIndexes.d.ts

@@ -13,7 +13,7 @@ export type RelIndexPlan = {
     table: string;
     columns: string[];
     name: string;
-    action: 'ok' | 'create';
+    action: 'ok' | 'create' | 'missing';
     /** name of the index already covering these columns (when action is 'ok'). */
     coveredBy: string | null;
     sql: string | null;
@@ -22,9 +22,9 @@ export type RelIndexPlan = {
  * Pure: for each (deduped) relation FK, decide whether an index is missing.
  * A relation is already covered if any existing index - including the PRIMARY KEY -
  * has those columns as its leftmost prefix, so we never propose redundant indexes
- * (e.g. an `a` index on an `(a, b)` PK table).
+ * (e.g. an `a` index on an `(a, b)` PK table). A table never created is `missing`.
  */
-export declare function planRelationIndexes(desired: RelIndexDesired[], existing: Map<string, ExistingIndex[]>): RelIndexPlan[];
+export declare function planRelationIndexes(desired: RelIndexDesired[], existing: Map<string, ExistingIndex[]>, tables: ReadonlySet<string>): RelIndexPlan[];
 /** FK columns of each entity's `toOne` relations - the indexes we'd like to exist. */
 export declare function relationIndexTargets(entities: ClassType<unknown>[]): Promise<RelIndexDesired[]>;
 /**

package/esm/sqlAdmin/server/drift/relationIndexes.js

@@ -1,16 +1,17 @@
 import { dbNamesOf, repo } from 'remult';
 import { getRelationFieldInfo } from 'remult/internals';
+import { execStmt, liveTables } from './catalog';
 import { formatCreateIndex } from './createIndex';
-import { stripIdent } from './ident';
+import { splitKey, stripIdent, tableKey, tableKeySql, USER_SCHEMA_SQL } from './ident';
 /** `want` is covered if it's a leftmost prefix of `have` (so the PK covers its own prefix). */
 const isPrefix = (want, have) => have.length >= want.length && want.every((c, i) => have[i] === c);
 /**
  * Pure: for each (deduped) relation FK, decide whether an index is missing.
  * A relation is already covered if any existing index - including the PRIMARY KEY -
  * has those columns as its leftmost prefix, so we never propose redundant indexes
- * (e.g. an `a` index on an `(a, b)` PK table).
+ * (e.g. an `a` index on an `(a, b)` PK table). A table never created is `missing`.
  */
-export function planRelationIndexes(desired, existing) {
+export function planRelationIndexes(desired, existing, tables) {
     const seen = new Set();
     const plans = [];
     for (const d of desired) {
@@ -19,6 +20,10 @@ export function planRelationIndexes(desired, existing) {
             continue;
         seen.add(key);
         const name = `FF_IX_${d.table}_${d.columns.join('_')}`;
+        if (!tables.has(d.table)) {
+            plans.push({ ...d, name, action: 'missing', coveredBy: null, sql: null });
+            continue;
+        }
         const cover = (existing.get(d.table) ?? []).find((e) => isPrefix(d.columns, e.cols));
         plans.push(cover
             ? { table: d.table, columns: d.columns, name, action: 'ok', coveredBy: cover.name, sql: null }
@@ -28,7 +33,12 @@ export function planRelationIndexes(desired, existing) {
                 name,
                 action: 'create',
                 coveredBy: null,
-                sql: formatCreateIndex({ name, table: d.table, columns: d.columns, ifNotExists: true }),
+                sql: formatCreateIndex({
+                    name,
+                    ...splitKey(d.table),
+                    columns: d.columns,
+                    ifNotExists: true,
+                }),
             });
     }
     return plans;
@@ -41,7 +51,7 @@ export async function relationIndexTargets(entities) {
         if (meta.options.sqlExpression)
             continue; // views: no real table
         const names = await dbNamesOf(ent);
-        const table = stripIdent(names.$entityName);
+        const table = tableKey(names.$entityName);
         for (const field of meta.fields.toArray()) {
             const fi = getRelationFieldInfo(field);
             if (!fi || fi.type !== 'toOne')
@@ -75,28 +85,29 @@ export async function createRelationIndexes(db, entities, opts) {
     const desired = await relationIndexTargets(entities);
     // Every existing index (incl. PK), columns in order, per table.
     const res = await db.createCommand().execute(`
-		SELECT c.relname AS table_name, i.relname AS index_name,
+		SELECT ${tableKeySql('ns.nspname', 'c.relname')} AS table_key, i.relname AS index_name,
 			array_agg(a.attname::text ORDER BY k.ord) AS cols
 		FROM pg_class c
-		JOIN pg_namespace ns ON ns.oid = c.relnamespace AND ns.nspname = 'public'
+		JOIN pg_namespace ns ON ns.oid = c.relnamespace AND ${USER_SCHEMA_SQL('ns.nspname')}
 		JOIN pg_index ix ON ix.indrelid = c.oid
 		JOIN pg_class i ON i.oid = ix.indexrelid
 		JOIN unnest(ix.indkey) WITH ORDINALITY AS k(attnum, ord) ON true
 		JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = k.attnum
 		WHERE c.relkind = 'r' AND k.attnum > 0
-		GROUP BY c.relname, i.relname;
+		GROUP BY ns.nspname, c.relname, i.relname;
 	`);
     const existing = new Map();
     for (const row of res.rows) {
-        const list = existing.get(row.table_name) ?? [];
+        const list = existing.get(row.table_key) ?? [];
         list.push({ name: row.index_name, cols: row.cols });
-        existing.set(row.table_name, list);
+        existing.set(row.table_key, list);
     }
-    const plans = planRelationIndexes(desired, existing);
+    const tables = await liveTables(db);
+    const plans = planRelationIndexes(desired, existing, tables);
     if (opts?.apply) {
         for (const plan of plans)
             if (plan.sql)
-                await db.createCommand().execute(plan.sql);
+                await execStmt(db, plan.sql);
     }
     return { applied: opts?.apply ?? false, plans };
 }

package/esm/sqlAdmin/server/index.d.ts

@@ -1,6 +1,6 @@
 import { type ClassType, type SqlDatabase } from 'remult';
 import { Module } from 'remult/server';
-import { type SqlTokensOptions } from '../SqlAdminController';
+import { type SqlTokenPool, type SqlTokensOptions } from '../SqlAdminController';
 import { type SqlDriftOptions } from '../SqlDriftController';
 export type { SqlTokensOptions, SqlTokenPool } from '../SqlAdminController';
 export type { SqlDriftFlag, SqlDriftOptions } from '../SqlDriftController';
@@ -33,6 +33,16 @@ export type SqlAdminOptions = {
      * @default true
      */
     sqlAdmin?: boolean;
+    /**
+     * Run `read` queries (console and tokens) as a read-only role instead of the
+     * app role. `'auto'` upserts `ff_readonly_<db>` at boot through the app's own
+     * pool (needs CREATEROLE), or pass a pool you connected yourself. `false`, or a
+     * database other than Postgres, leaves reads to the READ ONLY transaction alone.
+     *
+     * @default 'auto'
+     * @example readPool: new pg.Pool({ connectionString: env.DATABASE_URL_READONLY, max: 2 })
+     */
+    readPool?: 'auto' | false | SqlTokenPool;
     /**
      * Bearer tokens that can run SQL from outside a browser session (a script,
      * an AI on a dev machine). Nothing is registered unless set - no entities,

package/esm/sqlAdmin/server/index.js

@@ -2,7 +2,7 @@ import { remult, repo } from 'remult';
 import { Module } from 'remult/server';
 import { yellow } from '@kitql/helpers';
 import { log } from '..';
-import { SqlAdminController } from '../SqlAdminController';
+import { getDb, poolFrom, SqlAdminController, } from '../SqlAdminController';
 import { SqlDriftController } from '../SqlDriftController';
 import { isSqlTokenLive, SqlToken, sqlTokenEntities } from '../sqlTokenEntities';
 import { hashToken } from './token';
@@ -30,6 +30,27 @@ function readPathname(req) {
         return '';
     }
 }
+async function resolveReadPool(opt = 'auto') {
+    if (opt !== 'auto')
+        return opt || undefined;
+    const app = poolFrom(getDb());
+    // Not Postgres (or a custom `dp`): nothing to create, the transaction guard applies.
+    if (!app)
+        return undefined;
+    try {
+        const { ensureReadOnlyPool } = await import('./readOnlyRole');
+        const ro = await ensureReadOnlyPool(app);
+        if (ro.updated)
+            log.info(`reads run as ${yellow(ro.role)} (role created or updated).`);
+        return ro.pool;
+    }
+    catch (err) {
+        // Boot must survive: the READ ONLY transaction still guards reads.
+        const msg = err instanceof Error ? err.message : String(err);
+        log.error(`readPool: 'auto' failed (${msg}) - reads use the app role. ${yellow('readPool: false')} silences this.`);
+        return undefined;
+    }
+}
 /**
  * Drop-in SQL admin endpoint + companion `<SqlAdmin />` component (`firstly/sqlAdmin`).
  *
@@ -76,7 +97,10 @@ export const sqlAdmin = (opts) => {
                 SqlAdminController.dp = await opts.dp();
                 SqlDriftController.dp = SqlAdminController.dp;
             }
-            SqlAdminController.options = { tokens };
+            SqlAdminController.options = {
+                tokens,
+                readPool: enabled ? await resolveReadPool(opts?.readPool) : undefined,
+            };
             SqlDriftController.options = driftOn ? drift : undefined;
             if (enabled)
                 log.info(`AI Hint: visit ${yellow(path)} to query raw SQL.`);

package/esm/sqlAdmin/server/readOnlyRole.d.ts

@@ -0,0 +1,15 @@
+import type { SqlTokenPool } from '../SqlAdminController';
+export declare const readOnlyRoleName: (db: string) => string;
+/**
+ * Returns a pool connected as a login role that can only SELECT in this
+ * database. Per-database grants rather than `pg_read_all_data`: that one
+ * reaches every database of the cluster. A boot where the role is already
+ * right costs one login and one catalog query; anything off (new schema,
+ * rotated app password, missing grant) re-runs the full setup. Needs
+ * CREATEROLE on the app role.
+ */
+export declare function ensureReadOnlyPool(app: SqlTokenPool): Promise<{
+    pool: SqlTokenPool;
+    role: string;
+    updated: boolean;
+}>;

package/esm/sqlAdmin/server/readOnlyRole.js

@@ -0,0 +1,123 @@
+import { createHmac, randomBytes } from 'node:crypto';
+const NON_IDENT = /[^a-z0-9_]/g;
+const MAX_IDENT = 63;
+const DUPLICATE_OBJECT = '42710';
+const STATEMENT_TIMEOUT = '30s';
+/** Schemas the app can grant on: it owns them, or is a member of their owner. */
+const GRANTABLE_SCHEMA = `n.nspname !~ '^pg_' and n.nspname <> 'information_schema' and pg_has_role(n.nspowner, 'USAGE')`;
+/** One round trip: is the role still exactly what setup would leave behind? */
+const STATE_SQL = `
+select
+  r.rolsuper or r.rolcreaterole or r.rolcreatedb or r.rolreplication or r.rolbypassrls as extra,
+  coalesce(r.rolconfig @> array['default_transaction_read_only=on', 'statement_timeout=${STATEMENT_TIMEOUT}'], false)
+  and not exists (
+    select 1 from pg_namespace n
+    where ${GRANTABLE_SCHEMA}
+      and (not has_schema_privilege(r.oid, n.oid, 'USAGE')
+        or not exists (
+          select 1 from pg_default_acl d, aclexplode(d.defaclacl) a
+          where d.defaclnamespace = n.oid and d.defaclobjtype = 'r'
+            and d.defaclrole = (select oid from pg_roles where rolname = current_user)
+            and a.grantee = r.oid and a.privilege_type = 'SELECT')))
+  and not exists (
+    select 1 from pg_class c join pg_namespace n on n.oid = c.relnamespace
+    where ${GRANTABLE_SCHEMA} and c.relkind in ('r', 'v', 'm', 'p', 'f')
+      and pg_has_role(c.relowner, 'USAGE')
+      and not has_table_privilege(r.oid, c.oid, 'SELECT')) as ready
+from pg_roles r where r.rolname = $1`;
+const quote = (s) => `"${s.replaceAll('"', '""')}"`;
+export const readOnlyRoleName = (db) => `ff_readonly_${db.toLowerCase().replace(NON_IDENT, '_')}`.slice(0, MAX_IDENT);
+/** The app's own password: every instance derives the same role password, nothing to store. */
+function appSecret(options) {
+    if (options.connectionString) {
+        const url = new URL(options.connectionString);
+        const pw = url.searchParams.get('password') || decodeURIComponent(url.password);
+        if (pw)
+            return pw;
+    }
+    if (typeof options.password === 'string' && options.password)
+        return options.password;
+    return process.env.PGPASSWORD || undefined;
+}
+function withCredentials(options, user, password) {
+    const { connectionString, ...rest } = options;
+    // pg lets the connection string win over `user`/`password`, so rewrite the URL itself.
+    // Query params, not userinfo: a hostless URL (unix socket) silently drops userinfo, and pg reads params first.
+    if (connectionString) {
+        const url = new URL(connectionString);
+        url.username = '';
+        url.password = '';
+        url.searchParams.set('user', user);
+        url.searchParams.set('password', password);
+        return { ...rest, connectionString: url.toString(), max: 2 };
+    }
+    return { ...rest, user, password, max: 2 };
+}
+/**
+ * Returns a pool connected as a login role that can only SELECT in this
+ * database. Per-database grants rather than `pg_read_all_data`: that one
+ * reaches every database of the cluster. A boot where the role is already
+ * right costs one login and one catalog query; anything off (new schema,
+ * rotated app password, missing grant) re-runs the full setup. Needs
+ * CREATEROLE on the app role.
+ */
+export async function ensureReadOnlyPool(app) {
+    const pool = app;
+    if (typeof pool.query !== 'function' || !pool.options)
+        throw new Error('not a pg pool');
+    const { rows } = await pool.query('select current_database() as db');
+    const db = rows[0].db;
+    const role = readOnlyRoleName(db);
+    const secret = appSecret(pool.options);
+    const password = secret
+        ? createHmac('sha256', secret).update(role).digest('hex')
+        : randomBytes(32).toString('hex');
+    const Pool = pool.constructor;
+    const ro = new Pool(withCredentials(pool.options, role, password));
+    const state = await readState(pool, ro, role);
+    // A role with the same name made by someone else must not become our reader.
+    if (state?.extra)
+        throw new Error(`role ${role} has more than read rights, refusing it`);
+    if (state?.ready)
+        return { pool: ro, role, updated: false };
+    await setup(pool, db, role, password);
+    // Handing back a pool that cannot log in would break every read instead of falling back.
+    if (!(await connectsAs(ro, role))) {
+        await ro.end?.().catch(() => { });
+        throw new Error(`role ${role} was set up but cannot log in (pg_hba, pooler user naming?)`);
+    }
+    return { pool: ro, role, updated: true };
+}
+async function readState(app, ro, role) {
+    const row = (await app.query(STATE_SQL, [role])).rows[0];
+    if (!row)
+        return undefined;
+    // Logging in proves the derived password still matches (the app's may have rotated).
+    const loggedIn = !row.extra && (await connectsAs(ro, role));
+    return { extra: row.extra, ready: loggedIn && row.ready === true };
+}
+/** As `role`, not merely connected: a dropped credential would log in as the app. */
+const connectsAs = (ro, role) => ro.query('select current_user as u').then((r) => r.rows[0]?.u === role, () => false);
+async function setup(pool, db, role, password) {
+    const r = quote(role);
+    try {
+        await pool.query(`CREATE ROLE ${r} LOGIN`);
+    }
+    catch (err) {
+        if (err?.code !== DUPLICATE_OBJECT)
+            throw err;
+    }
+    // Only a superuser may set NOSUPERUSER & co, hence the `extra` check instead.
+    await pool.query(`ALTER ROLE ${r} WITH LOGIN PASSWORD '${password}'`);
+    await pool.query(`ALTER ROLE ${r} SET default_transaction_read_only = on`);
+    await pool.query(`ALTER ROLE ${r} SET statement_timeout = '${STATEMENT_TIMEOUT}'`);
+    await pool.query(`GRANT CONNECT ON DATABASE ${quote(db)} TO ${r}`);
+    const schemas = await pool.query(`select n.nspname from pg_namespace n where ${GRANTABLE_SCHEMA}`);
+    for (const { nspname } of schemas.rows) {
+        const s = quote(nspname);
+        await pool.query(`GRANT USAGE ON SCHEMA ${s} TO ${r}`);
+        await pool.query(`GRANT SELECT ON ALL TABLES IN SCHEMA ${s} TO ${r}`);
+        // Tables the app creates later (remult ensureSchema, migrations).
+        await pool.query(`ALTER DEFAULT PRIVILEGES IN SCHEMA ${s} GRANT SELECT ON TABLES TO ${r}`);
+    }
+}

package/esm/sqlAdmin/sqlWire.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reversible wire encoding for SQL and its results. Not a secret (TLS + roles
+ * are the security): it only keeps WAF rule sets from pattern-matching
+ * `SELECT ... FROM` or Postgres error text in requests and responses.
+ * The version suffix leaves room for another scheme if a WAF learns to decode this one.
+ */
+export declare const SQL_WIRE_PREFIX = "ffsql1:";
+export declare const isSqlWire: (s: unknown) => s is string;
+export declare function encodeSqlWire(s: string): string;
+/** Anything without the prefix passes through: plain SQL keeps working. */
+export declare function decodeSqlWire(s: string): string;

package/esm/sqlAdmin/sqlWire.js

@@ -0,0 +1,28 @@
+/**
+ * Reversible wire encoding for SQL and its results. Not a secret (TLS + roles
+ * are the security): it only keeps WAF rule sets from pattern-matching
+ * `SELECT ... FROM` or Postgres error text in requests and responses.
+ * The version suffix leaves room for another scheme if a WAF learns to decode this one.
+ */
+export const SQL_WIRE_PREFIX = 'ffsql1:';
+/** Spreading a huge array into fromCharCode overflows the stack. */
+const CHUNK = 0x8000;
+export const isSqlWire = (s) => typeof s === 'string' && s.startsWith(SQL_WIRE_PREFIX);
+export function encodeSqlWire(s) {
+    const bytes = new TextEncoder().encode(s);
+    let bin = '';
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return SQL_WIRE_PREFIX + btoa(bin);
+}
+/** Anything without the prefix passes through: plain SQL keeps working. */
+export function decodeSqlWire(s) {
+    if (!isSqlWire(s))
+        return s;
+    const bin = atob(s.slice(SQL_WIRE_PREFIX.length));
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        bytes[i] = bin.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+}

package/esm/sqlAdmin/ui/SqlAdmin.svelte

@@ -11,14 +11,15 @@
 	 * can read them with `list_console_messages`.
 	 */
 	import { log } from '../index'
-	import { SqlAdminController } from '../SqlAdminController'
+	import { SqlAdminController, type SqlResult } from '../SqlAdminController'
+	import { decodeSqlWire, encodeSqlWire } from '../sqlWire'
 
 	const defaultQuery = `SELECT *
 FROM "public"."users"
 LIMIT 10`
 
 	let sqlInput = $state(defaultQuery)
-	let result: { rows: any[]; rowCount: number; took: number } | undefined = $state()
+	let result: SqlResult | undefined = $state()
 	let error = $state('')
 	let isLoading = $state(false)
 	let allowWrites = $state(false)
@@ -64,10 +65,19 @@ ORDER BY tablename, indexname`,
 		try {
 			error = ''
 			isLoading = true
-			result = await SqlAdminController.exec(sqlInput, allowWrites ? ['read', 'write'] : ['read'])
-			log.info('for AI:', JSON.stringify(result.rows))
-			log.info('for humans:', result)
-		} catch (e) {
+			// Encoded both ways: WAF rules block SQL text in requests and Postgres errors in responses.
+			const res = await SqlAdminController.exec(
+				encodeSqlWire(sqlInput),
+				allowWrites ? ['read', 'write'] : ['read'],
+			)
+			const r: SqlResult = typeof res === 'string' ? JSON.parse(decodeSqlWire(res)) : res
+			result = r
+			log.info('for AI:', JSON.stringify(r.rows))
+			log.info('for humans:', r)
+		} catch (e: any) {
+			if (typeof e?.message === 'string') e.message = decodeSqlWire(e.message)
+			// A stale table under a new error reads as this query's result.
+			result = undefined
 			error = JSON.stringify(e, null, 2)
 		} finally {
 			isLoading = false
@@ -171,13 +181,6 @@ ORDER BY tablename, indexname`,
 					Allow writes
 				</label>
 
-				{#if error}
-					<pre
-						class="flex-1 overflow-auto border border-destructive bg-destructive/10 p-3 text-sm text-destructive">{error.replaceAll(
-							'\\n',
-							'\n',
-						)}</pre>
-				{/if}
 				{#if result}
 					<div
 						class="flex flex-1 items-center justify-between gap-3 border border-border bg-muted p-3 text-sm text-muted-foreground"
@@ -187,6 +190,13 @@ ORDER BY tablename, indexname`,
 					</div>
 				{/if}
 			</div>
+			{#if error}
+				<pre
+					class="overflow-auto border border-destructive bg-destructive/10 p-3 text-sm text-destructive">{error.replaceAll(
+						'\\n',
+						'\n',
+					)}</pre>
+			{/if}
 		</form>
 		{#if result}
 			{#if result.rows && result.rows.length > 0}

package/esm/sqlAdmin/ui/SqlDrift.svelte

@@ -8,6 +8,7 @@
 	import { onMount } from 'svelte'
 	import { SvelteSet } from 'svelte/reactivity'
 
+	import { errorMessage } from '../../core/helper.js'
 	import { SqlDriftController, type SqlDriftFlag } from '../SqlDriftController'
 
 	// Inferred from the BackendMethods, so this never imports from `server/`.
@@ -22,7 +23,7 @@
 		try {
 			flags = await SqlDriftController.driftFlags()
 		} catch (e) {
-			flagsError = e instanceof Error ? e.message : String(e)
+			flagsError = errorMessage(e)
 		}
 	})
 
@@ -31,14 +32,15 @@
 	let pkError = $state('')
 	let pkResult = $state<PkResult | null>(null)
 
+	const PK_ORDER = { migrate: 0, create: 0, missing: 1, ok: 2 } as const
 	const pkPlans = $derived(
-		(pkResult?.plans ?? []).toSorted((a, b) => {
-			if (a.action === 'ok' && b.action !== 'ok') return 1
-			if (a.action !== 'ok' && b.action === 'ok') return -1
-			return a.table.localeCompare(b.table)
-		}),
+		(pkResult?.plans ?? []).toSorted(
+			(a, b) => PK_ORDER[a.action] - PK_ORDER[b.action] || a.table.localeCompare(b.table),
+		),
+	)
+	const pkDrift = $derived(
+		pkPlans.filter((p) => p.action === 'migrate' || p.action === 'create').length,
 	)
-	const pkDrift = $derived(pkPlans.filter((p) => p.action !== 'ok').length)
 
 	async function runPk(apply: boolean) {
 		if (
@@ -52,7 +54,7 @@
 			pkResult = await SqlDriftController.primaryKeys({ apply })
 			console.info('for AI:', JSON.stringify(pkResult))
 		} catch (e) {
-			pkError = e instanceof Error ? e.message : String(e)
+			pkError = errorMessage(e)
 		} finally {
 			pkLoading = false
 		}
@@ -63,12 +65,11 @@
 	let relError = $state('')
 	let relResult = $state<RelResult | null>(null)
 
+	const REL_ORDER = { create: 0, missing: 1, ok: 2 } as const
 	const relPlans = $derived(
-		(relResult?.plans ?? []).toSorted((a, b) => {
-			if (a.action === 'ok' && b.action !== 'ok') return 1
-			if (a.action !== 'ok' && b.action === 'ok') return -1
-			return a.name.localeCompare(b.name)
-		}),
+		(relResult?.plans ?? []).toSorted(
+			(a, b) => REL_ORDER[a.action] - REL_ORDER[b.action] || a.name.localeCompare(b.name),
+		),
 	)
 	const relMissing = $derived(relPlans.filter((p) => p.action === 'create').length)
 
@@ -80,7 +81,7 @@
 			relResult = await SqlDriftController.relationIndexes({ apply })
 			console.info('for AI:', JSON.stringify(relResult))
 		} catch (e) {
-			relError = e instanceof Error ? e.message : String(e)
+			relError = errorMessage(e)
 		} finally {
 			relLoading = false
 		}
@@ -127,7 +128,7 @@
 			selected.clear()
 			console.info('for AI:', JSON.stringify(dropResult))
 		} catch (e) {
-			dropError = e instanceof Error ? e.message : String(e)
+			dropError = errorMessage(e)
 		} finally {
 			dropLoading = false
 		}
@@ -175,7 +176,7 @@
 			nullSelected.clear()
 			console.info('for AI:', JSON.stringify(nullResult))
 		} catch (e) {
-			nullError = e instanceof Error ? e.message : String(e)
+			nullError = errorMessage(e)
 		} finally {
 			nullLoading = false
 		}
@@ -282,9 +283,10 @@
 							</td>
 							<td
 								class="border-border border-b px-3 py-2 font-mono"
-								class:text-primary={p.action !== 'ok'}
+								class:text-primary={p.action === 'migrate' || p.action === 'create'}
+								class:text-muted-foreground={p.action === 'missing'}
 							>
-								{p.action}
+								{p.action === 'missing' ? 'table missing · run migrations first' : p.action}
 							</td>
 						</tr>
 					{/each}
@@ -339,7 +341,11 @@
 								class="border-border border-b px-3 py-2 font-mono"
 								class:text-primary={p.action === 'create'}
 							>
-								{p.action === 'create' ? 'create' : `covered · ${p.coveredBy}`}
+								{p.action === 'ok'
+									? `covered · ${p.coveredBy}`
+									: p.action === 'missing'
+										? 'table missing · run migrations first'
+										: 'create'}
 							</td>
 						</tr>
 					{/each}

package/esm/sqlAdmin/ui/SqlTokens.svelte

@@ -6,6 +6,7 @@
 	 */
 	import { repo } from 'remult'
 
+	import { errorMessage } from '../../core/helper.js'
 	import { log } from '../index'
 	import { SqlAdminController } from '../SqlAdminController'
 	import {
@@ -73,7 +74,7 @@
 			name = ''
 			await refresh()
 		} catch (err) {
-			error = err instanceof Error ? err.message : String(err)
+			error = errorMessage(err)
 		} finally {
 			busy = false
 		}
@@ -86,7 +87,7 @@
 			await repo(SqlToken).update(t.id, { revokedAt: new Date() })
 			await refresh()
 		} catch (err) {
-			error = err instanceof Error ? err.message : String(err)
+			error = errorMessage(err)
 		} finally {
 			busy = false
 		}
@@ -100,7 +101,7 @@
 			await repo(SqlToken).delete(t)
 			await refresh()
 		} catch (err) {
-			error = err instanceof Error ? err.message : String(err)
+			error = errorMessage(err)
 		} finally {
 			busy = false
 		}
@@ -114,7 +115,7 @@
 			await SqlAdminController.purgeTokens()
 			await refresh()
 		} catch (err) {
-			error = err instanceof Error ? err.message : String(err)
+			error = errorMessage(err)
 		} finally {
 			busy = false
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firstly",
-  "version": "0.10.5",
+  "version": "0.10.7",
   "type": "module",
   "description": "Firstly, an opinionated Remult setup!",
   "bin": {