pgkiln 0.48.0 → 0.49.0

package/src/builder/ui.ts

@@ -53,7 +53,7 @@ export type Section = 'apps' | 'users' | 'sql' | 'developers' | 'gallery';
 // app.css / app.js (the runtime never loads them). Add new builder assets
 // here, and only here.
 export const BUILDER_STYLES = ['/static/builder.css', '/static/code-editor.css', '/static/worksheet.css', '/static/data-modeler.css'];
-export const BUILDER_SCRIPTS = ['/static/builder.js', '/static/code-editor.js', '/static/worksheet.js', '/static/palette.js', '/static/data-modeler.js'];
+export const BUILDER_SCRIPTS = ['/static/builder.js', '/static/code-editor.js', '/static/worksheet.js', '/static/palette.js', '/static/data-modeler.js', '/static/sql-monitor.js'];
 export const builderHead = () =>
   html`${BUILDER_STYLES.map((href) => html`<link rel="stylesheet" href="${href}">\n`)}${BUILDER_SCRIPTS.map((src) => html`<script src="${src}" defer></script>\n`)}`;
 
@@ -61,12 +61,14 @@ export const builderHead = () =>
 export const BUILDER_ICONS = [
   'builder', 'back', 'down', 'up', 'left', 'right', 'undo', 'redo', 'zoom-in', 'zoom-out', 'expand', 'help', 'wrench',
   'region', 'item', 'button', 'grip', 'arrow-up', 'arrow-down', 'narrow', 'wide', 'sun', 'moon', 'monitor',
-  'rendering', 'processing', 'shapes', 'save', 'dots', 'pages',
+  'rendering', 'processing', 'shapes', 'save', 'dots', 'pages', 'kiln',
 ] as const;
 export function bicon(name: string, cls = 'icon') {
   if (!(BUILDER_ICONS as readonly string[]).includes(name)) return icon(name, cls);
   return html`<svg class="${cls}" aria-hidden="true" focusable="false"><use href="/static/builder-icons.svg#b-${name}"></use></svg>`;
 }
+/** (sprint 105) the pgkiln brand mark (an ember flame) for the rail and the sign-in pages. */
+export const brandMark = () => bicon('kiln');
 
 // ------------------------------------------------------------------ theme
 // The builder's own light/dark choice (separate from the runtime's): kept in
@@ -113,7 +115,7 @@ export function shell(s: Session, title: string, crumbs: [string, string?][], ma
     `${title} · Builder`,
     html`<a class="skip-link" href="#main">Skip to content</a>
     <nav class="ide-rail" aria-label="Builder">
-      <a class="rail-logo" href="${BASE}" title="pgkiln Builder"><span aria-hidden="true">pg</span><span class="sr-only">pgkiln Builder home</span></a>
+      <a class="rail-logo" href="${BASE}" title="pgkiln Builder">${brandMark()}<span class="sr-only">pgkiln Builder home</span></a>
       <ul class="rail-list">
         ${rail('apps', BASE, 'builder', 'App Builder')}
         ${s.workspace?.sql_workshop === false ? '' : rail('sql', `${BASE}/sql`, 'database', 'SQL Workshop')}
@@ -252,7 +254,7 @@ export const appHeader = (a: any, active: 'pages' | 'shared' | 'settings' | 'act
 };
 
 /** Tabs of the SQL Workshop. */
-export type WorkshopTab = 'home' | 'sql' | 'scripts' | 'quicksql' | 'query' | 'objects' | 'load' | 'unload' | 'sample' | 'ai' | 'ddl' | 'compare' | 'utilities' | 'charts' | 'modeler' | 'rest';
+export type WorkshopTab = 'home' | 'sql' | 'scripts' | 'quicksql' | 'query' | 'objects' | 'load' | 'unload' | 'sample' | 'ai' | 'ddl' | 'compare' | 'utilities' | 'charts' | 'modeler' | 'rest' | 'scheduling' | 'datapump' | 'monitor' | 'changes';
 export const workshopTabs = (active: WorkshopTab) => {
   const tab = (key: string, href: string, ic: string, label: string) =>
     html`<a class="ide-tab" href="${href}"${active === key ? raw(' aria-current="page"') : ''}>${icon(ic)}<span>${label}</span></a>`;

package/src/builder/worksheet.ts

@@ -14,8 +14,9 @@ import { currentWorkspace, inWorkspaceSql, sessionSchema, usableSchemas, worksho
 import { applySubstitutions, explainStatement, pickStatements, runStatements, substitutionNames, textTable, type RunMode, type WorksheetRun } from '../sqlworksheet.ts';
 import { applyBinds, bindNames } from '../binds.ts';
 import { formatSql } from '../sqlformat.ts';
-import type { Plan, PlanNode } from '../sqlplan.ts';
+import { planView } from './plan-view.ts';
 import { unloadStatement } from '../unload.ts';
+import { recordChanges } from '../changelog.ts';
 
 // (sprint 91, Database Actions DA-1/DA-2) The SQL Worksheet: one screen with a navigator (schema, object
 // type, filter; tables and views open to their columns and give SELECT / INSERT / UPDATE / DELETE
@@ -68,26 +69,6 @@ const HISTORY_SHOWN = 200;
 
 interface HistoryRow { id: string; sql: string; status: 'ok' | 'error'; rows: string | null; ms: number | null; error: string | null; runs: number; at: string }
 
-const fmtMs = (n: number) => (n >= 100 ? n.toFixed(0) : n >= 1 ? n.toFixed(1) : n.toFixed(3));
-
-/** (sprint 92, DA-4) A plan as a tree of steps (open), with the text plan behind a toggle. */
-function planView(plan: Plan, text: string): Raw {
-  const step = (n: PlanNode): Raw => html`<li><details open${n.slowest ? raw(' class="is-slowest"') : ''}>
-    <summary><span class="ws-plan-op">${n.op}</span>${n.target ? html` <span class="ws-plan-target">${n.target}</span>` : ''}
-      <span class="ws-plan-nums">cost ${n.startupCost.toFixed(2)}..${n.totalCost.toFixed(2)} · rows ${n.planRows} · width ${n.width}${plan.analyze
-        ? n.neverRun ? html` · <em>never executed</em>` : html` · <strong>${fmtMs(n.actualTotal ?? 0)} ms</strong> × ${n.loops} · ${n.actualRows} row${n.actualRows === 1 ? '' : 's'}${n.selfMs !== undefined ? ` · self ${fmtMs(n.selfMs)} ms` : ''}${n.sharedHit || n.sharedRead ? ` · buffers ${n.sharedHit ?? 0} hit${n.sharedRead ? `, ${n.sharedRead} read` : ''}` : ''}`
-        : ''}</span>
-      ${n.slowest ? html`<span class="tag tag-warn">slowest step</span>` : ''}
-      ${n.misestimate ? html`<span class="tag tag-warn" title="Estimated ${n.planRows} rows, got ${n.actualRows}: ANALYZE the table, or look at the statistics">estimate ${n.misestimate >= 1 ? `${Math.round(n.misestimate)}× too high` : `${Math.round(1 / n.misestimate)}× too low`}</span>` : ''}
-    </summary>
-    ${n.details.length ? html`<dl class="ws-plan-details">${n.details.map(([k, v]) => html`<dt>${k}</dt><dd><code>${v}</code></dd>`)}</dl>` : ''}
-    ${n.children.length ? html`<ul class="ws-plan-tree">${n.children.map(step)}</ul>` : ''}
-  </details></li>`;
-  return html`${plan.planningMs !== undefined || plan.executionMs !== undefined ? html`<p class="muted small ws-info">${plan.planningMs !== undefined ? `Planning ${fmtMs(plan.planningMs)} ms` : ''}${plan.executionMs !== undefined ? ` · execution ${fmtMs(plan.executionMs)} ms (rolled back)` : ''}</p>` : ''}
-    <ul class="ws-plan-tree ws-plan-root">${step(plan.root)}</ul>
-    <details class="ws-plan-text"><summary>Text plan</summary><pre class="ws-log ws-plan">${text}</pre></details>`;
-}
-
 /** (sprint 92, DA-5) Keep the statements of a run in SQL History: the same statement again right after counts on its row. */
 async function recordHistory(s: Session, run: WorksheetRun) {
   const ws = currentWorkspace(s);
@@ -406,6 +387,9 @@ async function worksheet(req: Req, reply: FastifyReply) {
       if (mode === 'statement' || mode === 'script') {
         clearCompletions(); // the statements may have changed tables or grants
         if (run) await recordHistory(s, run);
+        // (sprint 106, DA-17) the DDL that succeeded goes into the change log
+        if (run) await recordChanges({ workspaceId: currentWorkspace(s), author: s.username ?? '?', source: 'worksheet', defaultSchema: searchSchema ?? 'public',
+          statements: run.results.filter((r) => r.status === 'ok').map((r) => r.sql) });
         const detail = picked.map((x) => x.sql).join(';\n');
         await logActivity({ username: s.username, event: 'sql_command', ip: clientIp(req), elapsedMs: Math.round(performance.now() - started), detail: detail.length > 2000 ? `${detail.slice(0, 2000)}…` : detail });
       }

package/src/changelog.ts

@@ -0,0 +1,109 @@
+import { owner } from './db.ts';
+
+// (sprint 106, Database Actions DA-17; migration 118) A Liquibase-style change log: the DDL a developer runs from
+// the SQL Worksheet, Table Properties and Schema Comparison is recorded as change sets (meta.change_set: author,
+// time, SQL, schema, where it came from, a number per schema). SQL Workshop › Change Log (builder/changelog.ts)
+// lists them per schema and writes them as migration files: plain SQL, a Liquibase formatted SQL changelog
+// (--liquibase formatted sql, --changeset author:id) or Flyway versioned migrations (V0001__add_bonus.sql).
+
+export type ChangeSource = 'worksheet' | 'table' | 'compare';
+
+export interface ChangeSet {
+  id: number;
+  workspace_id: number;
+  schema_name: string;
+  seq: number;
+  name: string;
+  author: string;
+  source: ChangeSource;
+  sql: string;
+  object_name: string | null;
+  created_at: string;
+  exported_at: string | null;
+}
+
+/** Statements that change a schema's definition (as their first keyword says). */
+const DDL = /^(create|alter|drop|comment|grant|revoke)\b/i;
+/** DDL that is not about a schema: roles, databases, tablespaces, the server's settings, temporary objects. */
+const NOT_SCHEMA = /^(create|alter|drop)\s+(or\s+replace\s+)?(role|user|group|database|tablespace|system|server|user\s+mapping|subscription|publication|event\s+trigger)\b|^(create|alter)\s+(global\s+|local\s+)?(temp|temporary|unlogged\s+temp)\b|^alter\s+(system|default\s+privileges\s+for\s+role)\b|^(grant|revoke)\s+(?![\s\S]*\bon\b)/i;
+const LEAD = /^(\s*(--[^\n]*(\n|$)|\/\*[\s\S]*?\*\/))*\s*/;
+
+const IDENT = String.raw`(?:"(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*)`;
+const unquote = (s: string) => (s.startsWith('"') ? s.slice(1, -1).replace(/""/g, '"') : s.toLowerCase());
+
+/** Whether a statement is schema DDL a change log keeps. */
+export function isSchemaDdl(sql: string): boolean {
+  const s = sql.replace(LEAD, '');
+  return DDL.test(s) && !NOT_SCHEMA.test(s);
+}
+
+/** The schema and object a DDL statement is about: the first qualified name in it, else the default schema. */
+export function ddlTarget(sql: string, defaultSchema: string): { schema: string; object: string | null } {
+  const s = sql.replace(LEAD, '');
+  const m = new RegExp(`(${IDENT})\\s*\\.\\s*(${IDENT})`).exec(s.replace(/'(?:[^']|'')*'/g, "''"));
+  if (m && !/^\d/.test(m[1])) return { schema: unquote(m[1]), object: unquote(m[2]) };
+  const bare = new RegExp(`^(?:create|alter|drop)\\s+(?:or\\s+replace\\s+)?(?:unique\\s+)?(?:materialized\\s+)?(?:table|view|index|sequence|function|procedure|type|domain|trigger|policy)\\s+(?:concurrently\\s+)?(?:if\\s+(?:not\\s+)?exists\\s+)?(${IDENT})`, 'i').exec(s);
+  return { schema: defaultSchema, object: bare ? unquote(bare[1]) : null };
+}
+
+/** A change set's name from its first statement: add_bonus, drop_bonus, create_orders, create_index_orders_ix, … */
+export function changeName(sql: string): string {
+  const s = sql.replace(LEAD, '').replace(/\s+/g, ' ');
+  const clean = (x: string) => x.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '').slice(0, 60) || 'change';
+  const col = new RegExp(`^alter table (?:if exists )?(?:only )?${IDENT}(?:\\.${IDENT})? (add|drop) (?:column )?(?:if (?:not )?exists )?(${IDENT})`, 'i').exec(s);
+  if (col && !/^(constraint|primary|unique|foreign|check)$/i.test(col[2])) return clean(`${col[1]}_${unquote(col[2])}`);
+  const kind = new RegExp(`^(create|alter|drop)(?: or replace)?(?: unique)?(?: materialized)? (table|view|index|sequence|function|procedure|type|domain|trigger|policy|schema|extension)(?: concurrently)?(?: if (?:not )?exists)? (${IDENT})(?:\\s*\\.\\s*(${IDENT}))?`, 'i').exec(s);
+  const { object } = ddlTarget(sql, '');
+  if (kind) return clean(`${kind[1]}_${kind[2].toLowerCase() === 'table' ? '' : `${kind[2]}_`}${unquote(kind[4] ?? kind[3])}`);
+  const verb = /^(comment|grant|revoke)\b/i.exec(s);
+  return clean(`${verb ? verb[1] : 'change'}_${object ?? ''}`);
+}
+
+/** The SQL of statements as one script, each ending with a semicolon. */
+export const joinStatements = (statements: string[]) => statements.map((x) => x.trim().replace(/;*\s*$/, ';')).join('\n\n');
+
+/**
+ * Record statements that ran as change sets: those that are schema DDL, grouped by schema (one change set per
+ * schema, in the order they ran). Never fails the caller: a recording error is logged.
+ */
+export async function recordChanges(opts: { workspaceId: number; author: string; source: ChangeSource; statements: string[]; defaultSchema: string; name?: string }) {
+  const groups = new Map<string, { sql: string[]; object: string | null }>();
+  for (const st of opts.statements) {
+    if (!isSchemaDdl(st)) continue;
+    const t = ddlTarget(st, opts.defaultSchema);
+    const g = groups.get(t.schema) ?? { sql: [], object: t.object };
+    g.sql.push(st);
+    groups.set(t.schema, g);
+  }
+  const ids: number[] = [];
+  try {
+    for (const [schema, g] of groups) {
+      const sql = joinStatements(g.sql);
+      const r = await owner.one<{ id: number }>(
+        `insert into meta.change_set (workspace_id, schema_name, name, author, source, sql, object_name) values ($1, $2, $3, $4, $5, $6, $7) returning id`,
+        [opts.workspaceId, schema.slice(0, 63), opts.name ?? changeName(g.sql[0]), opts.author, opts.source, sql.slice(0, 1_000_000), g.object?.slice(0, 63) ?? null]);
+      ids.push(r!.id);
+    }
+  } catch (e) {
+    console.error('change log: could not record a change set:', (e as Error).message);
+  }
+  return ids;
+}
+
+/** Flyway's file name of a change set: V0001__add_bonus.sql. */
+export const flywayName = (c: Pick<ChangeSet, 'seq' | 'name'>) => `V${String(c.seq).padStart(4, '0')}__${c.name}.sql`;
+
+const header = (c: ChangeSet) => `-- ${c.schema_name} #${c.seq} ${c.name}: ${c.author}, ${c.created_at.slice(0, 19).replace('T', ' ')} (${c.source})`;
+
+/** Change sets as plain SQL: one script, a comment before each. */
+export const plainScript = (list: ChangeSet[]) => `${list.map((c) => `${header(c)}\n${c.sql.trim()}\n`).join('\n')}`;
+
+/** Change sets as a Liquibase formatted SQL changelog. */
+export function liquibaseChangelog(list: ChangeSet[]): string {
+  const author = (a: string) => a.replace(/[\s:]+/g, '_') || 'pgkiln';
+  return `--liquibase formatted sql\n\n${list.map((c) =>
+    `--changeset ${author(c.author)}:${String(c.seq).padStart(4, '0')}-${c.name}\n--comment: ${c.schema_name}, ${c.source}, ${c.created_at.slice(0, 19).replace('T', ' ')}\n${c.sql.trim()}\n`).join('\n')}`;
+}
+
+/** A Flyway migration file of one change set. */
+export const flywayFile = (c: ChangeSet) => `${header(c)}\n${c.sql.trim()}\n`;

package/src/cron-schedule.ts

@@ -0,0 +1,282 @@
+// (sprint 101, Database Actions DA-12) pg_cron schedules, without a database: parse, explain and compute the
+// next runs of a schedule as pg_cron understands it. SQL Workshop › Scheduling (src/builder/scheduling.ts) uses it
+// for the list's "next run" column and the schedule builder's preview; it never decides what pg_cron accepts
+// (cron.schedule does), it only explains.
+//
+// Supported, as in pg_cron (its parser comes from Vixie cron):
+//   - five fields "minute hour day-of-month month day-of-week": *, lists (1,15), ranges (1-5), steps (*/15, 0-30/10,
+//     5/20 = 5 to the end by 20), month names (jan … dec) and day names (sun … sat), 0 or 7 for Sunday
+//   - "$" in day-of-month: the last day of the month (also in a list: "15,$")
+//   - day-of-month and day-of-week both restricted (neither starts with "*"): a day matching either runs
+//   - "n seconds" (1 to 59): an interval rather than a time of day
+//   - macros @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly, and @reboot (no next runs)
+// pg_cron reads schedules in its cron.timezone (GMT unless set), so the next runs take a time zone.
+
+export interface CronFields {
+  minute: string;
+  hour: string;
+  day: string;
+  month: string;
+  weekday: string;
+}
+
+export type Schedule =
+  | { kind: 'cron'; minutes: Set<number>; hours: Set<number>; days: Set<number>; lastDay: boolean; months: Set<number>; weekdays: Set<number>; either: boolean; fields: CronFields }
+  | { kind: 'seconds'; seconds: number }
+  | { kind: 'reboot' };
+
+export class ScheduleError extends Error {}
+
+const MACROS: Record<string, string> = {
+  '@yearly': '0 0 1 1 *',
+  '@annually': '0 0 1 1 *',
+  '@monthly': '0 0 1 * *',
+  '@weekly': '0 0 * * 0',
+  '@daily': '0 0 * * *',
+  '@midnight': '0 0 * * *',
+  '@hourly': '0 * * * *',
+};
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+const DAYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+const MONTH_NAMES = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+const DAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+/** Ready-made schedules for the builder (label, expression). */
+export const PRESETS: [string, string][] = [
+  ['Every minute', '* * * * *'],
+  ['Every 30 seconds', '30 seconds'],
+  ['Every 5 minutes', '*/5 * * * *'],
+  ['Every 15 minutes', '*/15 * * * *'],
+  ['Every hour', '0 * * * *'],
+  ['Every day at 02:00', '0 2 * * *'],
+  ['Every day at midnight', '0 0 * * *'],
+  ['Weekdays at 07:00', '0 7 * * 1-5'],
+  ['Every Sunday at 03:00', '0 3 * * 0'],
+  ['First day of the month at 01:00', '0 1 1 * *'],
+  ['Last day of the month at 23:00', '0 23 $ * *'],
+  ['Every year on 1 January', '0 0 1 1 *'],
+];
+
+const MAX_LENGTH = 200;
+
+function field(text: string, min: number, max: number, label: string, names?: string[], allowLast = false): { set: Set<number>; last: boolean } {
+  const set = new Set<number>();
+  let last = false;
+  if (text === '') throw new ScheduleError(`${label}: empty`);
+  const num = (s: string) => {
+    const lower = s.toLowerCase();
+    const named = names ? names.indexOf(lower) : -1;
+    const n = named >= 0 ? named + (min === 1 ? 1 : 0) : /^\d{1,2}$/.test(s) ? Number(s) : NaN;
+    if (!Number.isInteger(n) || n < min || n > max) throw new ScheduleError(`${label}: "${s}" is not between ${min} and ${max}`);
+    return n;
+  };
+  for (const part of text.split(',')) {
+    if (allowLast && part === '$') {
+      last = true;
+      continue;
+    }
+    const pieces = part.split('/');
+    if (pieces.length > 2) throw new ScheduleError(`${label}: bad step in "${part}"`);
+    const [range, stepText] = pieces;
+    if (stepText !== undefined && !/^\d{1,2}$/.test(stepText)) throw new ScheduleError(`${label}: bad step in "${part}"`);
+    const step = stepText === undefined ? 1 : Number(stepText);
+    if (step < 1) throw new ScheduleError(`${label}: bad step in "${part}"`);
+    let [from, to] = [min, max];
+    if (range !== '*') {
+      const ends = range.split('-');
+      if (ends.length > 2 || ends.some((e) => e === '')) throw new ScheduleError(`${label}: "${part}" is not a number, range or *`);
+      from = num(ends[0]);
+      to = ends.length === 1 ? (stepText === undefined ? from : max) : num(ends[1]);
+      if (to < from) throw new ScheduleError(`${label}: "${range}" runs backwards`);
+    }
+    for (let n = from; n <= to; n += step) set.add(n);
+  }
+  return { set, last };
+}
+
+/** Parse a pg_cron schedule; throws ScheduleError with a message for people. */
+export function parseSchedule(input: string): Schedule {
+  const text = String(input ?? '').trim();
+  if (!text) throw new ScheduleError('Enter a schedule, for example "0 2 * * *" (every day at 02:00).');
+  if (text.length > MAX_LENGTH) throw new ScheduleError(`A schedule is at most ${MAX_LENGTH} characters.`);
+  const secs = /^(\d+)\s*seconds?$/i.exec(text);
+  if (secs) {
+    const n = Number(secs[1]);
+    if (n < 1 || n > 59) throw new ScheduleError('An interval in seconds is 1 to 59 seconds; use a cron schedule for longer intervals.');
+    return { kind: 'seconds', seconds: n };
+  }
+  if (text.toLowerCase() === '@reboot') return { kind: 'reboot' };
+  const expanded = MACROS[text.toLowerCase()];
+  if (!expanded && text.startsWith('@')) throw new ScheduleError(`Unknown shortcut "${text}" (use @hourly, @daily, @weekly, @monthly, @yearly or @reboot).`);
+  const parts = (expanded ?? text).split(/\s+/);
+  if (parts.length !== 5) throw new ScheduleError('A schedule has five fields: minute hour day-of-month month day-of-week (or "n seconds", or @daily, …).');
+  const [minute, hour, day, month, weekday] = parts;
+  const days = field(day, 1, 31, 'Day of month', undefined, true);
+  const weekdays = field(weekday, 0, 7, 'Day of week', DAYS).set;
+  if (weekdays.delete(7)) weekdays.add(0); // 7 is Sunday too
+  return {
+    kind: 'cron',
+    minutes: field(minute, 0, 59, 'Minute').set,
+    hours: field(hour, 0, 23, 'Hour').set,
+    days: days.set,
+    lastDay: days.last,
+    months: field(month, 1, 12, 'Month', MONTHS).set,
+    weekdays,
+    // Vixie cron: a field starting with * counts as unrestricted
+    either: !day.startsWith('*') && !weekday.startsWith('*'),
+    fields: { minute, hour, day, month, weekday },
+  };
+}
+
+/** Why a schedule is not usable, or null. */
+export function scheduleProblem(text: string): string | null {
+  try {
+    const s = parseSchedule(text);
+    if (s.kind === 'cron') nextRuns(s, new Date(), 1);
+    return null;
+  } catch (e) {
+    if (e instanceof ScheduleError) return e.message;
+    throw e;
+  }
+}
+
+/** The five fields of a cron schedule (macros expanded), or null for "n seconds", @reboot and bad input. */
+export function splitSchedule(text: string): CronFields | null {
+  try {
+    const s = parseSchedule(text);
+    return s.kind === 'cron' ? s.fields : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A schedule from the builder's five fields (blank fields are *). */
+export function joinSchedule(f: Partial<CronFields>): string {
+  const v = (x: string | undefined) => String(x ?? '').trim() || '*';
+  return [v(f.minute), v(f.hour), v(f.day), v(f.month), v(f.weekday)].join(' ');
+}
+
+export function validTimeZone(tz: string) {
+  try {
+    new Intl.DateTimeFormat('en', { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** pg_cron's time zone names (GMT, UTC, IANA names); unknown ones fall back to UTC. */
+export const cronTimeZone = (tz: string | null | undefined) => (tz && validTimeZone(tz) ? tz : 'UTC');
+
+const WEEKDAY: Record<string, number> = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+
+const formatter = (timeZone: string) =>
+  new Intl.DateTimeFormat('en-US', { timeZone, hourCycle: 'h23', year: 'numeric', month: 'numeric', day: 'numeric', hour: 'numeric', minute: 'numeric', weekday: 'short' });
+
+function wallClock(d: Date, fmt: Intl.DateTimeFormat) {
+  const p = Object.fromEntries(fmt.formatToParts(d).map((x) => [x.type, x.value]));
+  return { year: +p.year, month: +p.month, day: +p.day, hour: +p.hour % 24, minute: +p.minute, weekday: WEEKDAY[p.weekday] };
+}
+
+const daysInMonth = (year: number, month: number) => new Date(Date.UTC(year, month, 0)).getUTCDate();
+
+/**
+ * The next `count` runs after `after` (exclusive), in the time zone. "n seconds" counts on from `after`;
+ * @reboot has none. A schedule that never matches within five years (30 February) throws ScheduleError.
+ */
+export function nextRuns(schedule: Schedule, after: Date, count = 5, timeZone = 'UTC'): Date[] {
+  if (schedule.kind === 'reboot') return [];
+  if (schedule.kind === 'seconds') {
+    const start = Math.floor(after.getTime() / 1000) * 1000;
+    return Array.from({ length: count }, (_, i) => new Date(start + (i + 1) * schedule.seconds * 1000));
+  }
+  const fmt = formatter(timeZone);
+  const out: Date[] = [];
+  let lastKey = ''; // a wall-clock minute that comes twice (end of summer time) runs once
+  let t = Math.floor(after.getTime() / 60_000) * 60_000 + 60_000;
+  const limit = t + 5 * 366 * 86_400_000;
+  while (out.length < count && t < limit) {
+    const w = wallClock(new Date(t), fmt);
+    const domOk = schedule.days.has(w.day) || (schedule.lastDay && w.day === daysInMonth(w.year, w.month));
+    const dowOk = schedule.weekdays.has(w.weekday);
+    const dayOk = schedule.either ? domOk || dowOk : domOk && dowOk;
+    if (!schedule.months.has(w.month) || !dayOk) {
+      // to (nearly) the end of the wall-clock day: an hour short, for a day that daylight saving time shortens;
+      // then by quarters of an hour, which are the same instants in every time zone
+      const left = (24 * 60 - (w.hour * 60 + w.minute)) - 60;
+      t += left > 15 ? Math.floor(left / 15) * 15 * 60_000 : (15 - (w.minute % 15)) * 60_000;
+    } else if (!schedule.hours.has(w.hour)) t += (15 - (w.minute % 15)) * 60_000;
+    else if (schedule.minutes.has(w.minute)) {
+      const key = `${w.year}-${w.month}-${w.day} ${w.hour}:${w.minute}`;
+      if (key !== lastKey) out.push(new Date(t));
+      lastKey = key;
+      t += 60_000;
+    } else t += 60_000;
+  }
+  if (!out.length) throw new ScheduleError('The schedule never matches (for example 30 February).');
+  return out;
+}
+
+/** A run time as "2026-10-17 02:00" (with seconds for interval schedules) in the time zone. */
+export function formatRun(d: Date, timeZone = 'UTC', seconds = false): string {
+  const p = Object.fromEntries(new Intl.DateTimeFormat('en-CA', {
+    timeZone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit',
+  }).formatToParts(d).map((x) => [x.type, x.value]));
+  return `${p.year}-${p.month}-${p.day} ${p.hour}:${p.minute}${seconds ? `:${p.second}` : ''}`;
+}
+
+// ------------------------------------------------------------------ in words
+
+const pad = (n: number) => String(n).padStart(2, '0');
+const sorted = (s: Set<number>) => [...s].sort((a, b) => a - b);
+const isAll = (s: Set<number>, min: number, max: number) => s.size === max - min + 1;
+/** a list of numbers with runs as ranges: 1-5, 7 */
+function compact(values: number[], name: (n: number) => string = String) {
+  const out: string[] = [];
+  for (let i = 0; i < values.length; i++) {
+    let j = i;
+    while (j + 1 < values.length && values[j + 1] === values[j] + 1) j++;
+    out.push(j - i >= 2 ? `${name(values[i])} to ${name(values[j])}` : j > i ? `${name(values[i])}, ${name(values[j])}` : name(values[i]));
+    i = j;
+  }
+  return out.join(', ');
+}
+/** an evenly spaced set from 0: its step, else 0 */
+function stepOf(s: Set<number>, min: number, max: number) {
+  const v = sorted(s);
+  if (v.length < 2 || v[0] !== min) return 0;
+  const step = v[1] - v[0];
+  return v.every((x, i) => x === min + i * step) && v[v.length - 1] + step > max ? step : 0;
+}
+
+/** The schedule in words ("At 02:00, every day"). */
+export function describeSchedule(s: Schedule): string {
+  if (s.kind === 'reboot') return 'When the database server starts';
+  if (s.kind === 'seconds') return s.seconds === 1 ? 'Every second' : `Every ${s.seconds} seconds`;
+  const minutes = sorted(s.minutes);
+  const hours = sorted(s.hours);
+  let time: string;
+  if (isAll(s.minutes, 0, 59) && isAll(s.hours, 0, 23)) time = 'Every minute';
+  else if (isAll(s.hours, 0, 23)) {
+    const step = stepOf(s.minutes, 0, 59);
+    time = step ? `Every ${step} minutes` : minutes.length === 1 ? (minutes[0] === 0 ? 'Every hour' : `At minute ${minutes[0]} of every hour`) : `At minutes ${compact(minutes)} of every hour`;
+  } else if (hours.length * minutes.length <= 6) time = `At ${hours.flatMap((h) => minutes.map((m) => `${pad(h)}:${pad(m)}`)).join(', ')}`;
+  else {
+    const step = stepOf(s.hours, 0, 23);
+    const mins = isAll(s.minutes, 0, 59) ? 'Every minute' : minutes.length === 1 ? `At minute ${minutes[0]}` : `At minutes ${compact(minutes)}`;
+    time = `${mins} ${step ? `of every ${step} hours` : `past hours ${compact(hours)}`}`;
+  }
+  const parts = [time];
+  const domAll = isAll(s.days, 1, 31) && !s.lastDay;
+  const dowAll = isAll(s.weekdays, 0, 6);
+  const dom = s.lastDay ? (s.days.size ? `on day ${compact(sorted(s.days))} and the last day of the month` : 'on the last day of the month') : `on day ${compact(sorted(s.days))} of the month`;
+  const weekdays = sorted(s.weekdays);
+  const dow = weekdays.join() === '1,2,3,4,5' ? 'on weekdays' : `on ${compact(weekdays, (d) => DAY_NAMES[d])}`;
+  if (s.either) parts.push(`${dom} or ${dow}`);
+  else if (!domAll && !dowAll) parts.push(`${dom} if it is ${dow.replace(/^on /, 'a ')}`);
+  else if (!domAll) parts.push(dom);
+  else if (!dowAll) parts.push(dow);
+  else if (time !== 'Every minute' && !/^Every \d+ minutes$|hour$/.test(time)) parts.push('every day');
+  if (!isAll(s.months, 1, 12)) parts.push(`in ${compact(sorted(s.months), (m) => MONTH_NAMES[m - 1])}`);
+  return parts.join(', ');
+}