pgkiln 0.74.0 → 0.76.0

package/src/builder/document-view.ts

@@ -0,0 +1,117 @@
+import type { FastifyInstance, FastifyReply } from 'fastify';
+import { joinStatements, recordChanges } from '../changelog.ts';
+import { html, raw, type Raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import { childTables, documentViewDdl, ident, NAME, primaryKey, tableGrants } from '../json-sources.ts';
+import { clientIp, logActivity } from '../session.ts';
+import { readTable } from '../tabledef.ts';
+import { clearCompletions } from './code-editor.ts';
+import { tr } from './i18n.ts';
+import { SYSTEM_SCHEMAS } from './object-browser.ts';
+import { back, BASE, csrf, developer, flash, send, shell, workshopTabs, type Body, type Req } from './ui.ts';
+import { currentWorkspace, usableSchemas, workshopDb } from './workspaces.ts';
+
+// (sprint 142, AP-8; APEX: JSON Relational Duality Views) SQL Workshop › Table Properties › Document view: a view
+// with the table's key and a jsonb document of each row with lists of its child rows (tables whose foreign keys
+// reference it, the developer picks them). The view is security_invoker; its INSTEAD OF trigger
+// (meta.json_document_write, migration 142) writes a document back: the row's columns it names, the children it lists
+// (updated by key, or inserted), and deletes the children it leaves out. REST (AutoREST on the view) and MCP read and
+// write whole documents. Preview, Apply (one transaction with the workshop's connection, in the Change Log) and Open
+// in the worksheet, as Add full-text search. Names come from the catalog.
+
+async function page(req: Req, reply: FastifyReply) {
+  const s = await developer(req, reply);
+  if (!s) return;
+  const tx = tr(s);
+  const db = await workshopDb(s);
+  const isPost = req.method === 'POST';
+  const b: Body = (isPost ? req.body : req.query) ?? {};
+  const ref = String(b.o ?? '');
+  const t = ref ? await readTable(db, ref) : null;
+  const schemas = (await usableSchemas(db)).filter((n) => !SYSTEM_SCHEMAS.includes(n));
+  if (!t || !schemas.includes(t.schema)) return reply.code(404).send('Not found');
+  const table = `${ident(t.schema)}.${ident(t.name)}`;
+  const key = await primaryKey(db, t.schema, t.name);
+  const children = (await childTables(db, t.schema, t.name)).filter((c) => schemas.includes(c.schema));
+  // columns a document leaves out: full-text and vector columns (generated or kept by triggers)
+  const omitOf = async (schema: string, name: string) => (await db.query<{ n: string }>(
+    `select a.attname as n from pg_attribute a join pg_class c on c.oid = a.attrelid join pg_namespace s on s.oid = c.relnamespace join pg_type ty on ty.oid = a.atttypid
+      where s.nspname = $1 and c.relname = $2 and a.attnum > 0 and not a.attisdropped and ty.typname in ('tsvector', 'vector', 'halfvec', 'sparsevec')`, [schema, name])).rows.map((r) => r.n);
+  const view = isPost ? String(b.view ?? '').trim() : `${t.name}_doc`.toLowerCase().replace(/[^a-z0-9_]+/g, '_').slice(0, 63);
+  const document = isPost ? String(b.document ?? '').trim() : 'doc';
+  const picked = new Set<number>();
+  if (isPost) children.forEach((c, i) => b[`c.${i}.use`] === 'on' && b[`c.${i}.name`] === `${c.schema}.${c.table}` && picked.add(i));
+  else children.forEach((_, i) => picked.add(i));
+
+  const errors: string[] = [];
+  let ddl: string[] = [];
+  if (!key.length) errors.push(`${table} has no primary key: a document view finds its rows by it.`);
+  if (isPost && !errors.length) {
+    for (const n of [view, document]) if (!NAME.test(n)) errors.push(tx('fts.bad_name', { name: n }));
+    if (key.includes(document)) errors.push(`The document column may not have the name of a key column (${document}).`);
+    if (NAME.test(view) && (await db.one('select 1 as x from pg_class where relnamespace = $1::regnamespace and relname = $2', [ident(t.schema), view]))) errors.push(tx('fts.exists', { name: view }));
+    if (!errors.length) {
+      const kids = [];
+      for (const i of picked) kids.push({ ...children[i], omit: await omitOf(children[i].schema, children[i].table) });
+      ddl = documentViewDdl({ schema: t.schema, table: t.name, key, view, document, children: kids, omit: await omitOf(t.schema, t.name), grants: await tableGrants(db, t.schema, t.name) });
+    }
+    if (ddl.length && b.mode === 'worksheet') {
+      s.state.__SQLDRAFT = `${ddl.join(';\n\n')};`;
+      flash(s, tx('te.review'));
+      return back(reply, s, `${BASE}/sql/worksheet`);
+    }
+    if (ddl.length && b.mode === 'apply') {
+      const c = await db.pool.connect();
+      let failed = '';
+      try {
+        await c.query('begin');
+        for (const x of ddl) await c.query(x);
+        await c.query('commit');
+      } catch (e) {
+        failed = (e as Error).message;
+        await c.query('rollback').catch(() => {});
+      } finally {
+        c.release(true);
+      }
+      await logActivity({ username: s.username, event: 'sql_command', ip: clientIp(req), detail: ddl.join(';\n').slice(0, 2000) });
+      clearCompletions();
+      if (!failed) {
+        await recordChanges({ workspaceId: currentWorkspace(s), author: s.username ?? '?', source: 'table', defaultSchema: t.schema, statements: [joinStatements(ddl)] });
+        flash(s, `The document view ${t.schema}.${view} is made.`);
+        return back(reply, s, `${BASE}/sql/objects/table?${new URLSearchParams({ o: `${ident(t.schema)}.${ident(view)}` })}`);
+      }
+      errors.push(`${tx('te.nothing_changed')}: ${failed}`);
+    }
+  }
+
+  const title = `${tx('docv.add')}: ${table}`;
+  const form: Raw = key.length ? html`<form method="post" action="${BASE}/sql/objects/document" class="fts-form">${csrf(s)}
+      <input type="hidden" name="o" value="${table}">
+      <fieldset class="prop-group"><legend>Child tables in the document</legend>
+        ${children.length ? html`<div class="table-wrap"><table class="report"><thead><tr><th scope="col">${tx('fts.include')}</th><th scope="col">Table</th><th scope="col">List in the document</th><th scope="col">Foreign key</th></tr></thead><tbody>
+          ${children.map((c, i) => html`<tr><td class="te-c"><input type="hidden" name="c.${i}.name" value="${c.schema}.${c.table}"><input type="checkbox" id="dv-c${i}" name="c.${i}.use"${picked.has(i) ? raw(' checked') : ''}></td>
+            <td><label for="dv-c${i}">${c.schema}.${c.table}</label></td><td><code>${c.name}</code></td><td><code>${c.fk.map(([col, p]) => `${col} → ${p}`).join(', ')}</code></td></tr>`)}
+          </tbody></table></div>` : html`<p class="muted">No other table references ${table}: the document is the row alone.</p>`}
+        <small class="help">Each child row is an object in its list, without the foreign key columns. Writing a document updates the children it lists by their key, inserts the ones without a key, and deletes the ones it leaves out; a document without the list leaves the children alone.</small></fieldset>
+      <div class="form-grid u-mt1">
+        <div class="field"><label class="label" for="dv-view">View</label><input id="dv-view" name="view" value="${view}" required autocomplete="off" spellcheck="false" class="code"></div>
+        <div class="field"><label class="label" for="dv-doc">Document column</label><input id="dv-doc" name="document" value="${document}" required autocomplete="off" spellcheck="false" class="code"></div>
+      </div>
+      ${ddl.length ? html`<h2>DDL</h2><pre class="source te-ddl" data-code-view="sql" tabindex="0" aria-label="DDL">${ddl.map((x) => `${x};`).join('\n\n')}</pre>` : ''}
+      <div class="buttons te-buttons">
+        <button class="btn" name="mode" value="preview">${icon('eye')} ${tx('te.preview')}</button>
+        <button class="btn btn-hot" name="mode" value="apply">${icon('check')} ${tx('te.apply')}</button>
+        <button class="btn" name="mode" value="worksheet">${icon('code')} ${tx('te.open_ws')}</button>
+        <a class="btn" href="${BASE}/sql/objects/table?${new URLSearchParams({ o: table })}">${tx('common.cancel')}</a>
+      </div></form>` : html``;
+  const main = html`<h1 class="u-mb1">${title}</h1>${workshopTabs('objects', s)}
+    <p class="muted">A document view shows each row of ${table} with its child rows as one JSON document, like an Oracle JSON Relational Duality View. Reports, REST (AutoREST on the view) and MCP read whole documents; an update of the document column writes the row and its children back in one statement. The table's row level security and grants apply (the view is security_invoker and gets the table's grants).</p>
+    ${errors.length ? html`<div class="alert alert-error" role="alert"><ul>${errors.map((e) => html`<li>${e}</li>`)}</ul></div>` : ''}
+    ${form}`;
+  return send(reply, s, shell(s, title, [['SQL Workshop', `${BASE}/sql`], [tx('ob.title'), `${BASE}/sql/objects`], [tx('te.title_table', { table }), `${BASE}/sql/objects/table?${new URLSearchParams({ o: table })}`], [tx('docv.add')]], main, 'sql'));
+}
+
+export async function documentViewRoutes(app: FastifyInstance) {
+  app.get(`${BASE}/sql/objects/document`, page);
+  app.post(`${BASE}/sql/objects/document`, page);
+}

package/src/builder/i18n/de.ts

@@ -1077,6 +1077,7 @@ export const de: BuilderMessages = {
   'fts.added': "Volltextsuche zu {table} hinzugefügt: Spalte {column} mit Index {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Vektorspalte hinzufügen",
+  'docv.add': "Dokumentansicht",
   'vec.title': "Vektorspalte für {table}",
   'vec.intro': "Fügt eine Embedding-Spalte vector(n) hinzu (n: die Dimensionen des Vektoranbieters), einen HNSW-Index für die Distanz und einen Trigger, der eine Zeile neu einbettet, wenn sich ihre Quellspalten ändern. Eine Suchkonfiguration vom Typ vector oder hybrid oder das Retrieve-Werkzeug eines KI-Agenten findet Zeilen dann nach Bedeutung. Die vorhandenen Zeilen werden sofort für ihre Embeddings eingereiht.",
   'vec.existing': "Vektorspalten jetzt",

package/src/builder/i18n/en.ts

@@ -1081,6 +1081,7 @@ export const en = {
   'fts.added': "Added full-text search to {table}: column {column} with index {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Add vector column",
+  'docv.add': "Document view",
   'vec.title': "Vector column on {table}",
   'vec.intro': "Adds an embedding column vector(n) (n: the vector provider's dimensions), an HNSW index for the distance, and a trigger that re-embeds a row when its source columns change. A search configuration of type vector or hybrid, or an AI agent's Retrieve tool, then finds rows by meaning. The rows there are now are queued for their embeddings at once.",
   'vec.existing': "Vector columns now",

package/src/builder/i18n/es.ts

@@ -1077,6 +1077,7 @@ export const es: BuilderMessages = {
   'fts.added': "Búsqueda de texto completo añadida a {table}: columna {column} con el índice {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Añadir columna vectorial",
+  'docv.add': "Vista de documento",
   'vec.title': "Columna vectorial en {table}",
   'vec.intro': "Añade una columna de embedding vector(n) (n: las dimensiones del proveedor de vectores), un índice HNSW para la distancia y un disparador que vuelve a calcular el embedding de una fila cuando cambian sus columnas de origen. Una configuración de búsqueda de tipo vector o hybrid, o la herramienta Retrieve de un agente de IA, encuentra entonces las filas por su significado. Las filas que ya existen se ponen en cola enseguida para sus embeddings.",
   'vec.existing': "Columnas vectoriales actuales",

package/src/builder/i18n/fr.ts

@@ -1077,6 +1077,7 @@ export const fr: BuilderMessages = {
   'fts.added': "Recherche plein texte ajoutée à {table} : colonne {column} avec l'index {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Ajouter une colonne vectorielle",
+  'docv.add': "Vue document",
   'vec.title': "Colonne vectorielle sur {table}",
   'vec.intro': "Ajoute une colonne d'embedding vector(n) (n : les dimensions du fournisseur de vecteurs), un index HNSW pour la distance et un déclencheur qui recalcule l'embedding d'une ligne quand ses colonnes sources changent. Une configuration de recherche de type vector ou hybrid, ou l'outil Retrieve d'un agent IA, trouve alors les lignes par leur sens. Les lignes existantes sont mises en file d'attente tout de suite pour leurs embeddings.",
   'vec.existing': "Colonnes vectorielles actuelles",

package/src/builder/i18n/it.ts

@@ -1077,6 +1077,7 @@ export const it: BuilderMessages = {
   'fts.added': "Ricerca full-text aggiunta a {table}: colonna {column} con l'indice {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Aggiungi colonna vettoriale",
+  'docv.add': "Vista documento",
   'vec.title': "Colonna vettoriale su {table}",
   'vec.intro': "Aggiunge una colonna di embedding vector(n) (n: le dimensioni del provider di vettori), un indice HNSW per la distanza e un trigger che ricalcola l'embedding di una riga quando cambiano le sue colonne di origine. Una configurazione di ricerca di tipo vector o hybrid, o lo strumento Retrieve di un agente IA, trova allora le righe per significato. Le righe già presenti vengono messe subito in coda per i loro embedding.",
   'vec.existing': "Colonne vettoriali attuali",

package/src/builder/i18n/ja.ts

@@ -1077,6 +1077,7 @@ export const ja: BuilderMessages = {
   'fts.added': "{table} に全文検索を追加しました：列 {column}、索引 {index}。",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "ベクトル列を追加",
+  'docv.add': "ドキュメント・ビュー",
   'vec.title': "{table} のベクトル列",
   'vec.intro': "埋め込み列 vector(n)（n はベクトル・プロバイダの次元数）、距離用の HNSW 索引、およびソース列が変わったときに行を再埋め込みするトリガーを追加します。その後、検索タイプ vector または hybrid の検索構成や AI エージェントの Retrieve ツールで、意味によって行を検索できます。既存の行はすぐに埋め込みのキューに入れられます。",
   'vec.existing': "現在のベクトル列",

package/src/builder/i18n/ko.ts

@@ -1077,6 +1077,7 @@ export const ko: BuilderMessages = {
   'fts.added': "{table}에 전체 텍스트 검색을 추가했습니다: 열 {column}, 인덱스 {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "벡터 열 추가",
+  'docv.add': "문서 뷰",
   'vec.title': "{table}의 벡터 열",
   'vec.intro': "임베딩 열 vector(n)(n: 벡터 공급자의 차원 수), 거리용 HNSW 인덱스, 그리고 소스 열이 바뀌면 행을 다시 임베딩하는 트리거를 추가합니다. 그러면 검색 유형 vector 또는 hybrid의 검색 구성이나 AI 에이전트의 Retrieve 도구가 의미로 행을 찾습니다. 지금 있는 행은 바로 임베딩 대기열에 들어갑니다.",
   'vec.existing': "현재 벡터 열",

package/src/builder/i18n/nl.ts

@@ -1077,6 +1077,7 @@ export const nl: BuilderMessages = {
   'fts.added': "Volledige-tekstzoeken toegevoegd aan {table}: kolom {column} met index {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Vectorkolom toevoegen",
+  'docv.add': "Documentview",
   'vec.title': "Vectorkolom op {table}",
   'vec.intro': "Voegt een embeddingkolom vector(n) toe (n: de dimensies van de vectorprovider), een HNSW-index voor de afstand, en een trigger die een rij opnieuw embedt als de bronkolommen veranderen. Een zoekconfiguratie van het type vector of hybrid, of de Retrieve-tool van een AI-agent, vindt rijen dan op betekenis. De rijen die er nu zijn, komen meteen in de wachtrij voor hun embeddings.",
   'vec.existing': "Vectorkolommen nu",

package/src/builder/i18n/pt.ts

@@ -1077,6 +1077,7 @@ export const pt: BuilderMessages = {
   'fts.added': "Pesquisa de texto integral adicionada a {table}: coluna {column} com o índice {index}.",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "Adicionar coluna vetorial",
+  'docv.add': "Vista de documento",
   'vec.title': "Coluna vetorial em {table}",
   'vec.intro': "Adiciona uma coluna de embedding vector(n) (n: as dimensões do fornecedor de vetores), um índice HNSW para a distância e um gatilho que recalcula o embedding de uma linha quando as colunas de origem mudam. Uma configuração de pesquisa do tipo vector ou hybrid, ou a ferramenta Retrieve de um agente de IA, encontra então as linhas pelo significado. As linhas que já existem entram logo na fila para os seus embeddings.",
   'vec.existing': "Colunas vetoriais atuais",

package/src/builder/i18n/zh-cn.ts

@@ -1077,6 +1077,7 @@ export const zhCN: BuilderMessages = {
   'fts.added': "已为 {table} 添加全文搜索：列 {column}，索引 {index}。",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "添加向量列",
+  'docv.add': "文档视图",
   'vec.title': "{table} 的向量列",
   'vec.intro': "添加一个嵌入列 vector(n)（n：向量提供者的维数）、一个用于该距离的 HNSW 索引，以及在源列变化时重新嵌入该行的触发器。之后，搜索类型为 vector 或 hybrid 的搜索配置，或 AI 代理的 Retrieve 工具，就能按含义找到行。现有的行会立即进入嵌入队列。",
   'vec.existing': "当前的向量列",

package/src/builder/i18n/zh-tw.ts

@@ -1077,6 +1077,7 @@ export const zhTW: BuilderMessages = {
   'fts.added': "已為 {table} 新增全文檢索：欄位 {column}，索引 {index}。",
   // (sprint 136, AP-1) Table Properties › Add vector column
   'vec.add': "新增向量欄位",
+  'docv.add': "文件檢視",
   'vec.title': "{table} 的向量欄位",
   'vec.intro': "新增一個嵌入欄位 vector(n)（n：向量提供者的維度數）、一個用於該距離的 HNSW 索引，以及在來源欄位變更時重新嵌入該列的觸發程序。之後，搜尋類型為 vector 或 hybrid 的搜尋組態，或 AI 代理的 Retrieve 工具，就能依含意找到資料列。現有的資料列會立即進入嵌入佇列。",
   'vec.existing': "目前的向量欄位",