pgkiln 0.78.0 → 0.80.0

package/src/builder/remote-databases.ts

@@ -0,0 +1,215 @@
+import type { FastifyInstance } from 'fastify';
+import { owner } from '../db.ts';
+import { html, raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import { applicationRoles, applyRemote, disconnect, dropRemote, fdwStatus, MAX_TABLES, remoteDbProblems, serverNameOf, type RemoteDb } from '../remote-db.ts';
+import { clientIp, logActivity, type Session } from '../session.ts';
+import { administrator, back, BASE, csrf, flash, input, region, send, shell, type Req } from './ui.ts';
+
+// (sprint 150, AP-7 leftover; APEX: REST Enabled SQL services) Workspace utilities → Remote databases
+// (administrators): another PostgreSQL database's tables as foreign tables in a local schema (src/remote-db.ts).
+//
+//   GET  /builder/remote-databases                 postgres_fdw's state, the remote databases, the form (?edit=<id>, ?new=1)
+//   POST /builder/remote-databases                 save and import (mode=test: import in a transaction that is rolled back)
+//   POST /builder/remote-databases/:rid/refresh    import the tables again (new or changed remote tables)
+//   POST /builder/remote-databases/:rid/delete     drop the local schema and the server
+//   POST /builder/remote-databases/extension       create extension postgres_fdw (a superuser connection)
+
+const PAGE = `${BASE}/remote-databases`;
+const TITLE = 'Remote databases';
+const crumbs: [string, string?][] = [['App Builder', BASE], ['Workspace utilities', `${BASE}/utilities`], [TITLE]];
+const rid = (v: unknown) => (/^\d{1,9}$/.test(String(v ?? '')) ? Number(v) : null);
+const when = (d: Date | string | null) => (d ? new Date(d).toISOString().slice(0, 16).replace('T', ' ') : '');
+const list = (v: unknown) => (Array.isArray(v) ? v.map(String) : typeof v === 'string' && v ? [v] : []);
+
+interface Row extends RemoteDb { id: number; imported_at: Date | null; imported: number | null; error: string | null; updated_by: string }
+
+const rows = async () => (await owner.query<Row>('select * from meta.remote_database order by name')).rows;
+
+function fromBody(b: Record<string, unknown>): RemoteDb {
+  const text = (k: string) => String(b[k] ?? '').trim();
+  return {
+    name: text('name').toUpperCase(), description: text('description') || null, host: text('host'), port: Number(text('port') || '5432'),
+    dbname: text('dbname'), user_name: text('user_name'), remote_schema: text('remote_schema') || 'public', local_schema: text('local_schema').toLowerCase(),
+    tables: text('tables').split(/[,\n]/).map((t) => t.trim()).filter(Boolean), grant_roles: list(b.grant_roles), writable: b.writable === 'true',
+  };
+}
+
+function form(s: Session, x: Partial<Row>, roles: string[]) {
+  const editing = !!x.id;
+  return region(editing ? `Edit ${x.name}` : 'Add a remote database', html`<form method="post" action="${PAGE}" id="rdb-form">${csrf(s)}
+    ${editing ? html`<input type="hidden" name="id" value="${x.id}">` : ''}
+    <div class="form-grid">
+      ${input('name', 'Name', x.name ?? '', { help: 'A static id, e.g. CRM. The server is pgkiln_rdb_<name>.', required: true })}
+      ${input('description', 'Description', x.description ?? '')}
+      ${input('host', 'Host', x.host ?? '', { help: 'As the database server reaches it (it makes the connection, not pgkiln).', required: true })}
+      ${input('port', 'Port', String(x.port ?? 5432), { type: 'number' })}
+      ${input('dbname', 'Database', x.dbname ?? '', { required: true })}
+      ${input('user_name', 'User', x.user_name ?? '', { required: true, help: 'A user of the remote database: what it may read or change there is what the applications may.' })}
+      ${input('password', 'Password', '', { type: 'password', auto: 'new-password', help: editing ? 'Kept by PostgreSQL in the user mapping and never shown; type a new one to replace it.' : 'Kept by PostgreSQL in the user mapping (pgkiln never stores it).' })}
+      ${input('remote_schema', 'Remote schema', x.remote_schema ?? 'public')}
+      ${input('local_schema', 'Local schema', x.local_schema ?? '', { required: true, help: 'A new schema here for the foreign tables, e.g. crm: regions query crm.<table>.' })}
+      ${input('tables', 'Tables', (x.tables ?? []).join(', '), { help: `Remote tables and views to import, separated by commas (at most ${MAX_TABLES}); empty: all of the remote schema's.` })}
+    </div>
+    <fieldset class="prop-group u-mt1"><legend>Grant to the applications' database roles</legend>
+      ${roles.length
+        ? html`<div class="check-list">${roles.map((r) => html`<label><input type="checkbox" name="grant_roles" value="${r}"${(x.grant_roles ?? []).includes(r) ? raw(' checked') : ''}> ${r}</label>`)}</div>`
+        : html`<p class="muted">No application has a database role yet (Application settings → Database role).</p>`}
+      <label class="u-mt1"><input type="checkbox" name="writable" value="true"${x.writable ? raw(' checked') : ''}> Also INSERT, UPDATE and DELETE (else SELECT only)</label>
+    </fieldset>
+    <div class="buttons u-mt1">
+      <button class="btn btn-hot" name="mode" value="save">${editing ? 'Save and import again' : 'Add and import'}</button>
+      <button class="btn" name="mode" value="test">Test the connection</button>
+      <a class="btn" href="${PAGE}">Cancel</a>
+    </div></form>`);
+}
+
+export async function remoteDatabaseRoutes(app: FastifyInstance) {
+  app.get(PAGE, async (req: Req, reply) => {
+    const s = await administrator(req, reply, TITLE);
+    if (!s) return;
+    const q = (req.query ?? {}) as Record<string, string>;
+    const st = await fdwStatus(owner);
+    const all = await rows();
+    const roles = await applicationRoles(owner);
+    const edit = rid(q.edit) ? all.find((r) => r.id === rid(q.edit)) : undefined;
+    const main = html`<h1 class="u-mb1">${TITLE}</h1>
+      <p class="muted u-mt0">Another PostgreSQL database's tables as foreign tables (postgres_fdw) in a local schema: regions, reports, forms and lists
+        of values use them like the application's own tables, as its database role, with the grants given here.</p>
+      ${st.installed
+        ? html`<p class="muted">${icon('check')} postgres_fdw is installed.</p>`
+        : html`<div class="alert alert-info" role="status"><p><strong>postgres_fdw is not installed in this database.</strong></p>
+            ${st.available && st.canCreate
+              ? html`<form method="post" action="${PAGE}/extension">${csrf(s)}<button class="btn">Create extension postgres_fdw</button></form>`
+              : html`<p>${st.available ? 'A superuser runs' : 'The server needs PostgreSQL\'s contrib package, then a superuser runs'} <code>create extension postgres_fdw;</code>
+                  and <code>grant usage on foreign data wrapper postgres_fdw to</code> pgkiln's owner role.</p>`}</div>`}
+      ${region('Remote databases', html`<div class="table-wrap"><table class="report report-reflow"><thead><tr><th>Name</th><th>Connection</th><th>Local schema</th>
+          <th class="num">Tables</th><th>Granted to</th><th>Imported</th><th><span class="sr-only">Actions</span></th></tr></thead><tbody>
+        ${all.length ? all.map((r) => html`<tr>
+            <td data-label="Name"><strong>${r.name}</strong>${r.description ? html`<br><small class="muted">${r.description}</small>` : ''}</td>
+            <td data-label="Connection"><code>${r.user_name}@${r.host}:${r.port}/${r.dbname}</code> (${r.remote_schema})</td>
+            <td data-label="Local schema"><code>${r.local_schema}</code></td>
+            <td class="num" data-label="Tables">${r.imported ?? '—'}</td>
+            <td data-label="Granted to">${r.grant_roles.join(', ') || '—'}${r.writable ? ' (read and write)' : ''}</td>
+            <td data-label="Imported">${when(r.imported_at)}${r.error ? html`<br><span class="wf-problem">${r.error}</span>` : ''}</td>
+            <td data-label="Actions"><a class="btn btn-sm" href="${PAGE}?edit=${r.id}#rdb-form">Edit</a>
+              <form method="post" action="${`${PAGE}/${r.id}/refresh`}" class="inline">${csrf(s)}<button class="btn btn-sm">Import again</button></form>
+              <form method="post" action="${`${PAGE}/${r.id}/delete`}" class="inline">${csrf(s)}<button class="btn btn-sm btn-danger" data-confirm="${`Delete ${r.name}? Its schema ${r.local_schema} and its foreign tables are dropped.`}">Delete</button></form></td>
+          </tr>`) : html`<tr><td colspan="7" class="empty">No remote databases yet.</td></tr>`}
+        </tbody></table></div>`)}
+      ${st.installed ? form(s, edit ?? {}, roles) : ''}`;
+    return send(reply, s, shell(s, TITLE, crumbs, main));
+  });
+
+  app.post(PAGE, async (req: Req, reply) => {
+    const s = await administrator(req, reply, TITLE);
+    if (!s) return;
+    const b = (req.body ?? {}) as Record<string, unknown>;
+    const x = fromBody(b);
+    const editId = rid(b.id);
+    const password = typeof b.password === 'string' && b.password ? b.password : null;
+    const retry = editId ? `${PAGE}?edit=${editId}#rdb-form` : `${PAGE}#rdb-form`;
+    const problems = remoteDbProblems(x, await applicationRoles(owner));
+    if (password && password.length > 1000) problems.push('The password has at most 1000 characters.');
+    if (problems.length) {
+      flash(s, problems.join(' '), 'error');
+      return back(reply, s, retry);
+    }
+    const test = b.mode === 'test';
+    try {
+      const count = await owner.tx(async (c) => {
+        const old = editId ? (await c.query<Row>('select * from meta.remote_database where id = $1 for update', [editId])).rows[0] : undefined;
+        if (editId && !old) throw new Error('No such remote database.');
+        // a renamed one, or a new local schema: the old server and schema go first
+        if (old && (old.name !== x.name || old.local_schema !== x.local_schema)) {
+          if (!password) throw new Error('Renaming it, or moving it to another local schema, needs the password again.');
+          await dropRemote(c, old);
+        }
+        const n = await applyRemote(c, x, password, old && old.name === x.name && old.local_schema === x.local_schema ? old.grant_roles : []);
+        if (test) throw Object.assign(new Error('rolled back'), { tested: n });
+        if (old)
+          await c.query(
+            `update meta.remote_database set name = $2, description = $3, host = $4, port = $5, dbname = $6, user_name = $7, remote_schema = $8, local_schema = $9,
+                    tables = $10, grant_roles = $11, writable = $12, server_name = $13, imported_at = now(), imported = $14, error = null, updated_by = $15, updated_at = now()
+              where id = $1`,
+            [editId, x.name, x.description, x.host, x.port, x.dbname, x.user_name, x.remote_schema, x.local_schema, x.tables, x.grant_roles, x.writable, serverNameOf(x.name), n, s.username]);
+        else
+          await c.query(
+            `insert into meta.remote_database (name, description, host, port, dbname, user_name, remote_schema, local_schema, tables, grant_roles, writable, server_name,
+                                               imported_at, imported, created_by, updated_by)
+             values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, now(), $13, $14, $14)`,
+            [x.name, x.description, x.host, x.port, x.dbname, x.user_name, x.remote_schema, x.local_schema, x.tables, x.grant_roles, x.writable, serverNameOf(x.name), n, s.username]);
+        return n;
+      });
+      await disconnect(owner);
+      await logActivity({ username: s.username, event: 'workspace', ip: clientIp(req),
+        detail: `remote database ${x.name} ${editId ? 'changed' : 'added'}: ${x.user_name}@${x.host}:${x.port}/${x.dbname} into ${x.local_schema} (${count} tables)`.slice(0, 1000) });
+      flash(s, `${x.name}: ${count} table(s) imported into ${x.local_schema}.`);
+      return back(reply, s, PAGE);
+    } catch (e) {
+      const tested = (e as { tested?: number }).tested;
+      if (tested !== undefined) {
+        flash(s, `The connection works: ${tested} table(s) would be imported into ${x.local_schema}. Nothing was saved.`);
+      } else {
+        const msg = (e as Error).message.includes('remote_database_name_key') ? `There is a remote database ${x.name} already.`
+          : (e as Error).message.includes('remote_database_local_schema_key') ? `Another remote database uses schema ${x.local_schema}.` : (e as Error).message;
+        flash(s, `${test ? 'The test failed' : 'Nothing was changed'}: ${msg}`, 'error');
+      }
+      return back(reply, s, retry);
+    }
+  });
+
+  app.post(`${PAGE}/:rid/refresh`, async (req: Req, reply) => {
+    const s = await administrator(req, reply, TITLE);
+    if (!s) return;
+    const r = (await rows()).find((x) => x.id === rid(req.params.rid));
+    if (!r) {
+      flash(s, 'No such remote database.', 'error');
+      return back(reply, s, PAGE);
+    }
+    try {
+      const n = await owner.tx(async (c) => applyRemote(c, r, null, r.grant_roles));
+      await owner.query('update meta.remote_database set imported_at = now(), imported = $2, error = null, updated_by = $3, updated_at = now() where id = $1', [r.id, n, s.username]);
+      await logActivity({ username: s.username, event: 'workspace', ip: clientIp(req), detail: `remote database ${r.name} imported again (${n} tables)` });
+      flash(s, `${r.name}: ${n} table(s) imported into ${r.local_schema}.`);
+    } catch (e) {
+      await owner.query('update meta.remote_database set error = $2 where id = $1', [r.id, (e as Error).message.slice(0, 1000)]);
+      flash(s, `${r.name}: nothing was changed: ${(e as Error).message}`, 'error');
+    }
+    return back(reply, s, PAGE);
+  });
+
+  app.post(`${PAGE}/:rid/delete`, async (req: Req, reply) => {
+    const s = await administrator(req, reply, TITLE);
+    if (!s) return;
+    const r = (await rows()).find((x) => x.id === rid(req.params.rid));
+    if (!r) {
+      flash(s, 'No such remote database.', 'error');
+      return back(reply, s, PAGE);
+    }
+    try {
+      await owner.tx(async (c) => {
+        await dropRemote(c, r);
+        await c.query('delete from meta.remote_database where id = $1', [r.id]);
+      });
+      await logActivity({ username: s.username, event: 'workspace', ip: clientIp(req), detail: `remote database ${r.name} deleted (schema ${r.local_schema})` });
+      flash(s, `${r.name} deleted with its schema ${r.local_schema}.`);
+    } catch (e) {
+      flash(s, `${r.name} was not deleted: ${(e as Error).message}`, 'error');
+    }
+    return back(reply, s, PAGE);
+  });
+
+  app.post(`${PAGE}/extension`, async (req: Req, reply) => {
+    const s = await administrator(req, reply, TITLE);
+    if (!s) return;
+    try {
+      await owner.query('create extension if not exists postgres_fdw');
+      await logActivity({ username: s.username, event: 'sql_command', ip: clientIp(req), detail: 'create extension if not exists postgres_fdw' });
+      flash(s, 'The postgres_fdw extension is installed.');
+    } catch (e) {
+      flash(s, `create extension postgres_fdw failed: ${(e as Error).message}`, 'error');
+    }
+    return back(reply, s, PAGE);
+  });
+}

package/src/builder/search.ts

@@ -43,6 +43,20 @@ const asText = (v: unknown) => (v === null || v === undefined ? '' : Array.isArr
 /** Every component of an application with its searchable fields. */
 export async function appEntries(appId: number, query: (sql: string, params?: unknown[]) => Promise<{ rows: any[] }> = (sql, params) => owner.query(sql, params)): Promise<Entry[]> {
   const pages = (await query('select * from meta.page where app_id = $1 order by page_no', [appId])).rows;
+  const rows = new Map<string, any[]>();
+  for (const [kind, spec] of Object.entries(COMPONENTS))
+    rows.set(kind, spec.scope === 'page'
+      ? (await query(`select t.* from ${spec.table} t join meta.page p on p.id = t.page_id where p.app_id = $1 order by p.page_no, t.seq, t.id`, [appId])).rows
+      : (await query(`select * from ${spec.table} where app_id = $1 order by id`, [appId])).rows);
+  return entriesOf(appId, pages, rows);
+}
+
+/**
+ * (sprint 147) The entries of pages and component rows however they were read: from the database (appEntries) or
+ * from an export's files (`pgkiln advise --offline`). A page row has `id` and `page_no`; a page component's row has
+ * `page_id`; rows are per kind of COMPONENTS, in order.
+ */
+export function entriesOf(appId: number, pages: any[], rows: Map<string, any[]>): Entry[] {
   const pageById = new Map(pages.map((p) => [p.id, p]));
   const out: Entry[] = pages.map((p) => ({
     kind: 'page', id: p.id, label: `Page ${p.page_no}: ${p.name}`, kindLabel: 'Page', icon: 'file', pageNo: p.page_no,
@@ -50,10 +64,7 @@ export async function appEntries(appId: number, query: (sql: string, params?: un
     fields: PAGE_FIELDS.map((f) => ({ ...f, value: asText(p[f.name]) })),
   }));
   for (const [kind, spec] of Object.entries(COMPONENTS)) {
-    const rows = spec.scope === 'page'
-      ? (await query(`select t.* from ${spec.table} t join meta.page p on p.id = t.page_id where p.app_id = $1 order by p.page_no, t.seq, t.id`, [appId])).rows
-      : (await query(`select * from ${spec.table} where app_id = $1 order by id`, [appId])).rows;
-    for (const row of rows) {
+    for (const row of rows.get(kind) ?? []) {
       const page = spec.scope === 'page' ? pageById.get(row.page_id) : null;
       out.push({
         kind, id: row.id, label: spec.summary(row), kindLabel: spec.label, icon: spec.icon, pageNo: page?.page_no ?? null,

package/src/builder/workflow-migrate.ts

@@ -35,7 +35,8 @@ interface Running {
   version: string;
   state: string;
   current_step: string | null;
-  branches: boolean;
+  /** (144) the steps its open parallel branches are at */
+  branch_steps: string[];
 }
 
 const ID = /^\d{1,9}$/;
@@ -101,7 +102,8 @@ export async function workflowMigrateRoutes(app: FastifyInstance) {
     const running = (
       await owner.query<Running>(
         `select w.id::text, w.title, coalesce(w.version, '1') as version, w.state, w.current_step,
-                exists (select 1 from meta.workflow_branch b where b.workflow_id = w.id and b.state in ('active', 'waiting', 'faulted')) as branches
+                array(select b.current_step from meta.workflow_branch b where b.workflow_id = w.id and b.state in ('active', 'waiting', 'faulted')
+                       and b.current_step is not null order by b.id) as branch_steps
            from meta.workflow w where w.definition_id = $1 and w.state in ('active', 'waiting', 'faulted') order by w.id`,
         [d.id],
       )
@@ -117,16 +119,17 @@ export async function workflowMigrateRoutes(app: FastifyInstance) {
     const targetSteps = (target?.steps ?? []).filter((x) => x && typeof x.name === 'string' && x.type !== 'draft');
     const asked = mappingOf(q);
     // each step a chosen instance is at: the mapping asked for, or the step of the same name
-    const current = [...new Set(chosen.map((w) => w.current_step).filter((x): x is string => !!x && STEP.test(x)))].sort();
+    // (144) and each step its open parallel branches are at
+    const current = [...new Set(chosen.flatMap((w) => [w.current_step, ...w.branch_steps]).filter((x): x is string => !!x && STEP.test(x)))].sort();
     const mapping = Object.fromEntries(current.map((st) => [st, st in asked ? asked[st] : targetSteps.some((x) => x.name === st) ? st : '']));
 
-    let preview: { workflow_id: string; from_version: string | null; from_step: string | null; to_step: string | null; problem: string | null }[] | null = null;
+    let preview: { workflow_id: string; branch: string | null; from_version: string | null; from_step: string | null; to_step: string | null; problem: string | null }[] | null = null;
     let previewError: string | null = null;
     if (q.preview && to) {
       if (!chosen.length) previewError = 'Choose the instances to migrate.';
       else {
         try {
-          preview = (await owner.query('select workflow_id::text, from_version, from_step, to_step, problem from meta.migrate_workflows($1, $2, $3::bigint[], $4, false, $5)',
+          preview = (await owner.query('select workflow_id::text, branch, from_version, from_step, to_step, problem from meta.migrate_workflows($1, $2, $3::bigint[], $4, false, $5)',
             [d.id, to, chosen.map((w) => w.id), mapping, s.username])).rows;
         } catch (e) {
           previewError = (e as Error).message;
@@ -134,6 +137,7 @@ export async function workflowMigrateRoutes(app: FastifyInstance) {
       }
     }
     const ready = !!preview && preview.every((r) => !r.problem);
+    const instances = preview ? new Set(preview.map((r) => r.workflow_id)).size : 0;
     const self = `${url(d)}/migrate`;
     const hidden = html`<input type="hidden" name="to" value="${to ?? ''}">${chosen.map((w) => html`<input type="hidden" name="wf" value="${w.id}">`)}${Object.entries(mapping).map(([k, v]) => html`<input type="hidden" name="${`m.${k}`}" value="${v}">`)}`;
     const body = !running.length
@@ -144,7 +148,8 @@ export async function workflowMigrateRoutes(app: FastifyInstance) {
         : html`${region('Migrate running instances', html`<form method="get" action="${self}">
             <input type="hidden" name="preview" value="1">
             <p class="muted u-mt0">Move running instances to a newer version: each goes on at the step of the new version its current step is mapped to,
-              keeping its variables and the task it waits for. Every instance must have a mapping, or nothing moves. Instances inside parallel branches move once their branches have joined.</p>
+              keeping its variables and the task it waits for. An instance inside parallel branches moves as a whole: its main path at its join and each open
+              branch at its own step, each mapped (a join stays a join). Every position must have a mapping, or nothing moves.</p>
             <div class="form-grid">
               <div class="field"><label class="label" for="wf-to">To version</label>
                 <select id="wf-to" name="to">${targets.map((v) => html`<option value="${v}"${v === to ? raw(' selected') : ''}>${v}${v === d.version ? ' (active)' : ' (inactive)'}</option>`)}</select>
@@ -155,7 +160,7 @@ export async function workflowMigrateRoutes(app: FastifyInstance) {
                 ? html`<div class="table-wrap"><table class="report report-reflow"><thead><tr><th>Migrate</th><th class="num">Id</th><th>Title</th><th>Version</th><th>State</th><th>At</th></tr></thead><tbody>
                     ${older.map((w) => html`<tr><td data-label="Migrate"><input type="checkbox" name="wf" value="${w.id}" id="${`wf-${w.id}`}"${picked.includes(w.id) ? raw(' checked') : ''} aria-label="${`Migrate instance ${w.id}`}"></td>
                       <td class="num" data-label="Id"><label for="${`wf-${w.id}`}">${w.id}</label></td><td data-label="Title">${w.title}</td><td data-label="Version">${w.version}</td>
-                      <td data-label="State">${w.state}</td><td data-label="At">${w.branches ? 'parallel branches' : (w.current_step ?? '—')}</td></tr>`)}
+                      <td data-label="State">${w.state}</td><td data-label="At">${w.current_step ?? '—'}${w.branch_steps.length ? html`<br><small class="muted">branches at ${w.branch_steps.join(', ')}</small>` : ''}</td></tr>`)}
                   </tbody></table></div>`
                 : html`<p class="muted">No running instance is older than version ${to}.</p>`}
             </fieldset>
@@ -169,14 +174,14 @@ export async function workflowMigrateRoutes(app: FastifyInstance) {
           </form>`)}
           ${previewError ? html`<div class="alert alert-error u-mt1" role="alert">${previewError}</div>` : ''}
           ${preview
-            ? region('Preview', html`<div class="table-wrap"><table class="report report-reflow"><thead><tr><th class="num">Id</th><th>From</th><th>To</th><th>Result</th></tr></thead><tbody>
-                  ${preview.map((r) => html`<tr><td class="num" data-label="Id">${r.workflow_id}</td><td data-label="From">${r.from_version ? `${r.from_version}: ${r.from_step ?? '—'}` : '—'}</td>
+            ? region('Preview', html`<div class="table-wrap"><table class="report report-reflow"><thead><tr><th class="num">Id</th><th>Path</th><th>From</th><th>To</th><th>Result</th></tr></thead><tbody>
+                  ${preview.map((r) => html`<tr><td class="num" data-label="Id">${r.workflow_id}</td><td data-label="Path">${r.branch ? `branch ${r.branch}` : 'main'}</td><td data-label="From">${r.from_version ? `${r.from_version}: ${r.from_step ?? '—'}` : '—'}</td>
                     <td data-label="To">${r.to_step ? `${to}: ${r.to_step}` : '—'}</td><td data-label="Result">${r.problem ? html`<span class="wf-problem">${r.problem}</span>` : html`<span class="tag tag-info">ready</span>`}</td></tr>`)}
                 </tbody></table></div>
                 ${ready
                   ? html`<form method="post" action="${self}" class="u-mt1">${csrf(s)}${hidden}
-                      <button class="btn btn-hot" data-confirm="${`Migrate ${preview.length} instance(s) to version ${to}?`}">Migrate ${preview.length} instance(s)</button></form>`
-                  : html`<p class="wf-problem">Map a step for every instance (or leave the others out) and preview again: nothing is migrated while one can't move.</p>`}`)
+                      <button class="btn btn-hot" data-confirm="${`Migrate ${instances} instance(s) to version ${to}?`}">Migrate ${instances} instance(s)</button></form>`
+                  : html`<p class="wf-problem">Map a step for every instance and branch (or leave the instances out) and preview again: nothing is migrated while one can't move.</p>`}`)
             : ''}
           ${target ? region(`Version ${to}`, html`<div class="wf-wrap">${workflowDiagram(target.steps, { id: 'target' })}</div>`) : ''}`;
     const main = html`${appHeader(a, 'shared', s)}<div class="ide-body">${body}</div>`;
@@ -198,8 +203,9 @@ export async function workflowMigrateRoutes(app: FastifyInstance) {
       if (!to) throw new Error('Choose the version to migrate to.');
       const rows = await owner.tx(async (c) =>
         (await c.query('select workflow_id::text, from_step, to_step from meta.migrate_workflows($1, $2, $3::bigint[], $4, true, $5)', [d.id, to, ids, mapping, s.username])).rows);
-      logActivity({ appId: d.app_id, username: s.username, event: 'workflow', ip: clientIp(req), detail: `${d.name}: ${rows.length} instance(s) migrated to version ${to}` });
-      flash(s, `${rows.length} instance(s) of ${d.name} migrated to version ${to}.`);
+      const moved = new Set(rows.map((r) => r.workflow_id)).size;
+      logActivity({ appId: d.app_id, username: s.username, event: 'workflow', ip: clientIp(req), detail: `${d.name}: ${moved} instance(s) migrated to version ${to}` });
+      flash(s, `${moved} instance(s) of ${d.name} migrated to version ${to}.`);
       return back(reply, s, `${BASE}/apps/${d.app_id}/shared?c=workflow_definition-${d.id}`);
     } catch (e) {
       flash(s, (e as Error).message, 'error');

package/src/cli/advise.ts

@@ -9,6 +9,7 @@ import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { docToFiles, slug, type FileMap } from '../appfiles.ts';
 import { exportDoc, importDoc, readSource, UsageError, type Db } from './apps.ts';
+import type { Finding } from '../builder/advisor.ts';
 
 export type Severity = 'error' | 'warning' | 'info';
 export const SEVERITIES: Severity[] = ['error', 'warning', 'info'];
@@ -33,6 +34,8 @@ export interface AdviseResult {
   dir: string | null;
   checked: number;
   findings: AdviseFinding[];
+  /** (sprint 147) checked from the files alone, without a database */
+  offline?: boolean;
 }
 
 const pad = (n: number) => String(n).padStart(4, '0');
@@ -52,6 +55,39 @@ export function fileOf(files: string[], f: { pageNo: number | null; kind: string
   return shared ?? yaml.find((p) => /^app\.(ya?ml|json)$/.test(p)) ?? null;
 }
 
+/** An Advisor finding as the report's: where, the component's kind and page. */
+function toAdvise(f: Finding): AdviseFinding {
+  const kind = f.entry?.kind ?? null;
+  const pageNo = f.entry?.pageNo ?? (/^Page (\d+)\b/.exec(f.field) ? Number(/^Page (\d+)\b/.exec(f.field)![1]) : null);
+  return {
+    severity: f.severity,
+    where: f.entry ? (kind === 'page' ? f.entry.label : `${f.entry.pageNo !== null ? `page ${f.entry.pageNo}, ` : ''}${f.entry.kindLabel.toLowerCase()} ${f.entry.label}`) : pageNo !== null ? `page ${pageNo}` : 'application',
+    field: f.field,
+    message: f.message,
+    kind,
+    label: f.entry?.label ?? '',
+    pageNo,
+    file: null,
+  };
+}
+
+/**
+ * (sprint 147) Check an export's files alone, with no database: references, the login page and page groups, the
+ * pages' security defaults, workflow steps, process settings and JSON source profiles (adviseDoc). SQL is not
+ * planned and nothing is read from a catalog; the report says so.
+ */
+export async function adviseOffline(target: string): Promise<AdviseResult> {
+  if (!existsSync(target)) throw new UsageError(`${target} not found (--offline checks an export: a directory, a .zip or a JSON file)`);
+  const { adviseDoc } = await import('../builder/advisor.ts');
+  const source = await readSource(target);
+  const files = source.files ?? docToFiles(source.doc);
+  const r = await adviseDoc(source.doc);
+  const findings = r.findings.map(toAdvise);
+  const paths = [...files.keys()];
+  for (const f of findings) f.file = fileOf(paths, f);
+  return { alias: String(source.doc?.app?.alias ?? 'app'), dir: source.files ? target : null, checked: 0, findings, offline: true };
+}
+
 /**
  * Check an export (path) or an application in the database (alias). Nothing is ever committed: an export is
  * imported under a temporary alias in a transaction that is rolled back.
@@ -67,20 +103,7 @@ export async function adviseTarget(db: Db, target: string): Promise<AdviseResult
   const collect = async (appId: number) => {
     const r = await advise(appId, db);
     checked = r.checked;
-    for (const f of r.findings) {
-      const kind = f.entry?.kind ?? null;
-      const pageNo = f.entry?.pageNo ?? (/^Page (\d+)\b/.exec(f.field) ? Number(/^Page (\d+)\b/.exec(f.field)![1]) : null);
-      findings.push({
-        severity: f.severity,
-        where: f.entry ? (kind === 'page' ? f.entry.label : `${f.entry.pageNo !== null ? `page ${f.entry.pageNo}, ` : ''}${f.entry.kindLabel.toLowerCase()} ${f.entry.label}`) : pageNo !== null ? `page ${pageNo}` : 'application',
-        field: f.field,
-        message: f.message,
-        kind,
-        label: f.entry?.label ?? '',
-        pageNo,
-        file: null,
-      });
-    }
+    for (const f of r.findings) findings.push(toAdvise(f));
   };
   if (existsSync(target)) {
     const source = await readSource(target);
@@ -133,13 +156,14 @@ export function formatText(r: AdviseResult, base: string | null = null) {
   return r.findings.map((f) => {
     const path = pathOf(r, f, base);
     return `${f.severity.toUpperCase().padEnd(7)} ${f.where}${f.field ? ` (${f.field})` : ''}: ${f.message}${path ? `\n        ${path}` : ''}\n`;
-  }).join('') + `${r.alias}: ${r.checked} SQL fragment(s) checked; ${count('error')} error(s), ${count('warning')} warning(s), ${count('info')} note(s).\n`;
+  }).join('') + `${r.alias}: ${r.offline ? 'checked offline (references and security; SQL not planned without a database)' : `${r.checked} SQL fragment(s) checked`}; ${count('error')} error(s), ${count('warning')} warning(s), ${count('info')} note(s).\n`;
 }
 
 export function formatJson(r: AdviseResult, base: string | null = null) {
   return JSON.stringify({
     alias: r.alias,
     checked: r.checked,
+    offline: !!r.offline,
     counts: Object.fromEntries(SEVERITIES.map((s) => [s, r.findings.filter((f) => f.severity === s).length])),
     findings: r.findings.map((f) => ({ severity: f.severity, where: f.where, field: f.field, message: f.message, page: f.pageNo, kind: f.kind, file: pathOf(r, f, base) })),
   }, null, 2) + '\n';

package/src/cli/main.ts

@@ -332,7 +332,7 @@ const COMMANDS: Record<string, Command> = {
   },
 
   advise: {
-    usage: 'pgkiln advise <path | alias> [--format text|json|sarif] [--fail-on error|warning|info|never] [-o <file>]',
+    usage: 'pgkiln advise <path | alias> [--offline] [--format text|json|sarif] [--fail-on error|warning|info|never] [-o <file>]',
     summary: 'check an export or an application with the Advisor (for CI: text, JSON or SARIF)',
     details:
       'Runs the builder\'s Advisor: every SQL fragment is planned as the application\'s database role (unknown\n' +
@@ -342,10 +342,13 @@ const COMMANDS: Record<string, Command> = {
       'A path (an export directory, a .zip or a JSON export) is imported into a transaction that is rolled back:\n' +
       'nothing changes. It needs a database with pgkiln\'s migrations and the application\'s own tables (in CI, a\n' +
       'PostgreSQL service, pgkiln migrate and your migrations). An alias checks the application in the database.\n\n' +
+      'With --offline a path is checked from its files alone, without a database: references, the login page, page\n' +
+      'groups, security defaults, workflow steps and JSON source profiles; SQL is not planned.\n\n' +
       'SARIF points every finding at the file of its page or component in the export, so GitHub code scanning\n' +
       'annotates the pull request. Exit code 1 when a finding is at or above --fail-on (default: error).',
-    options: { format: { type: 'string', short: 'f' }, 'fail-on': { type: 'string' }, output: { type: 'string', short: 'o' }, base: { type: 'string' } },
+    options: { format: { type: 'string', short: 'f' }, 'fail-on': { type: 'string' }, output: { type: 'string', short: 'o' }, base: { type: 'string' }, offline: { type: 'boolean' } },
     optionHelp: [
+      ['--offline', 'check an export\'s files without a database (no SQL planning)'],
       ['-f, --format <format>', 'text (default), json or sarif'],
       ['--fail-on <level>', 'exit code 1 from this level: error (default), warning, info or never'],
       ['-o, --output <file>', 'write the report to a file (the summary still goes to standard error)'],
@@ -358,10 +361,10 @@ const COMMANDS: Record<string, Command> = {
       if (!['text', 'json', 'sarif'].includes(format)) throw new UsageError(`--format: text, json or sarif, not ${format}`);
       if (!['error', 'warning', 'info', 'never'].includes(failOn)) throw new UsageError(`--fail-on: error, warning, info or never, not ${failOn}`);
       process.env.RUNTIME_DATABASE_URL ??= process.env.DATABASE_URL;
-      const { adviseTarget, fails, formatJson, formatSarif, formatText } = await import('./advise.ts');
+      const { adviseOffline, adviseTarget, fails, formatJson, formatSarif, formatText } = await import('./advise.ts');
       const { closePools } = await import('../db.ts');
       try {
-        const r = await withDb((db) => adviseTarget(db, target));
+        const r = v.offline ? await adviseOffline(target) : await withDb((db) => adviseTarget(db, target));
         const base = (v.base as string) ?? null;
         const report = format === 'sarif' ? formatSarif(r, version(), base) : format === 'json' ? formatJson(r, base) : formatText(r, base);
         if (v.output) {

package/src/cli/mcp.ts

@@ -438,15 +438,23 @@ export const TOOLS: Tool[] = [
       'unrestricted page protection, long sessions, administrators without a second factor). Each finding names its file in the export.',
     inputSchema: {
       type: 'object',
-      properties: { ...aliasProp, path: { type: 'string', description: 'an export directory, .zip or .json instead of the application in the database' } },
+      properties: {
+        ...aliasProp,
+        path: { type: 'string', description: 'an export directory, .zip or .json instead of the application in the database' },
+        offline: { type: 'boolean', description: 'with path: check the files alone, without the database (references and security; no SQL planning)' },
+      },
     },
     annotations: { readOnlyHint: true },
     async run(a) {
       const path = str(a, 'path');
       const alias = str(a, 'alias');
       if (!path && !alias) throw new ToolError('give an alias or a path');
+      const { adviseOffline, adviseTarget, formatText } = await import('./advise.ts');
+      if (a.offline === true) {
+        if (!path) throw new ToolError('offline needs a path (an export)');
+        return cap(formatText(await adviseOffline(resolve(path))));
+      }
       process.env.RUNTIME_DATABASE_URL ??= process.env.DATABASE_URL;
-      const { adviseTarget, formatText } = await import('./advise.ts');
       return cap(formatText(await withDb((db) => adviseTarget(db, path ? resolve(path) : alias!))));
     },
   },

package/src/json-sources.ts

@@ -242,6 +242,18 @@ export function proposeProfile(docs: unknown[], o: { key: string[]; view: string
 export interface Grant { grantee: string; privileges: string[] }
 
 const triggerArg = (o: object) => lit(JSON.stringify(o));
+const argColumns = (cols: JsonColumn[]) => cols.map((c) => ({ name: c.name, path: c.path, ...(c.readonly ? { readonly: true } : {}) }));
+/** (sprint 146) the argument of a source's view trigger, meta.json_source_write: what the view writes back */
+export const viewTriggerArg = (x: JsonSource) =>
+  ({ name: x.name, schema: x.schema, table: x.table, key: x.key, column: x.column, rows: !!x.rows, columns: argColumns(x.columns) });
+/** (sprint 146) the argument of an array view's trigger, meta.json_array_write */
+export const arrayTriggerArg = (x: JsonSource, a: JsonArray) =>
+  ({ name: x.name, schema: x.schema, table: x.table, key: x.key, column: x.column, array: a.path, row_key: ROW_KEY, position: POSITION, columns: argColumns(a.columns) });
+/** (sprint 146) a profile type as format_type() names it in the catalog */
+export const CATALOG_TYPE: Record<JsonType, string> = {
+  text: 'text', integer: 'integer', bigint: 'bigint', numeric: 'numeric', boolean: 'boolean', date: 'date',
+  timestamp: 'timestamp without time zone', timestamptz: 'timestamp with time zone', jsonb: 'jsonb',
+};
 const grantsSql = (view: string, grants: Grant[]) =>
   grants.filter((g) => g.privileges.length).map((g) => `grant ${g.privileges.join(', ')} on ${view} to ${g.grantee === 'PUBLIC' ? 'public' : pg.escapeIdentifier(g.grantee)}`);
 
@@ -260,20 +272,14 @@ export function jsonSourceDdl(x: JsonSource, o: { app: string; grants: Grant[];
   const cols = x.columns.map((c) => `${columnSql(doc, c)} as ${ident(c.name)}`);
   out.push(`create view ${view} with (security_invoker = true) as\nselect ${[keySel, ...cols].join(',\n       ')}\n  from ${table} t`);
   out.push(`comment on view ${view} is ${lit(`JSON source ${x.name} of application ${o.app}: ${x.schema}.${x.table}.${x.column} (made by pgkiln; Shared Components → JSON sources makes it again)`)}`);
-  out.push(`create trigger json_source_write\n  instead of insert or update or delete on ${view}\n  for each row execute function meta.json_source_write(${triggerArg({
-    name: x.name, schema: x.schema, table: x.table, key: x.key, column: x.column, rows: !!x.rows,
-    columns: x.columns.map((c) => ({ name: c.name, path: c.path, ...(c.readonly ? { readonly: true } : {}) })),
-  })})`);
+  out.push(`create trigger json_source_write\n  instead of insert or update or delete on ${view}\n  for each row execute function meta.json_source_write(${triggerArg(viewTriggerArg(x))})`);
   out.push(...grantsSql(view, o.grants));
   for (const { a, view: av } of arrays) {
     const arr = `${doc} #> ${pathSql(a.path)}`;
     const ecols = a.columns.map((c) => `${columnSql('e.v', c)} as ${ident(c.name)}`);
     out.push(`create view ${av} with (security_invoker = true) as\nselect ${[keySel, `k.key as ${ROW_KEY}`, `k.idx + 1 as ${POSITION}`, ...ecols].join(',\n       ')}\n  from ${table} t\n  cross join lateral meta.jsonb_element_keys(${arr}) k\n  cross join lateral (select (${arr}) -> k.idx as v) e`);
     out.push(`comment on view ${av} is ${lit(`JSON source ${x.name} of application ${o.app}: the array ${a.path.join('.')} of ${x.schema}.${x.table}.${x.column}, one row per element (made by pgkiln)`)}`);
-    out.push(`create trigger json_source_write\n  instead of insert or update or delete on ${av}\n  for each row execute function meta.json_array_write(${triggerArg({
-      name: x.name, schema: x.schema, table: x.table, key: x.key, column: x.column, array: a.path, row_key: ROW_KEY, position: POSITION,
-      columns: a.columns.map((c) => ({ name: c.name, path: c.path, ...(c.readonly ? { readonly: true } : {}) })),
-    })})`);
+    out.push(`create trigger json_source_write\n  instead of insert or update or delete on ${av}\n  for each row execute function meta.json_array_write(${triggerArg(arrayTriggerArg(x, a))})`);
     out.push(...grantsSql(av, o.grants));
   }
   return out;