feat: implement metadata catalog database management

2026-08-27 22:43:54 +02:00
parent 705af3aeb2
commit 79c4c925b5
86 changed files with 12566 additions and 135 deletions
@@ -0,0 +1,88 @@
+# Catalog schema snapshot RPC
+
+Il percorso preferito per un binding `rest_api` espone al catalogo un'unica fotografia tipizzata
+dello schema:
+
+```http
+POST /rpc/schema_snapshot
+Content-Type: application/json
+
+{"schema_name":"datawarehouse"}
+```
+
+La risposta è un oggetto JSON con `schemaVersion: 1`, capability esplicite e tre collezioni. Una
+capability non disponibile deve essere dichiarata `unavailable`: non deve essere simulata con una
+lista vuota.
+
+```json
+{
+  "schemaVersion": 1,
+  "capabilities": {
+    "tables": "available",
+    "columns": "available",
+    "relationships": "available"
+  },
+  "tables": [
+    { "name": "patients", "sourceComment": "Clinical patients" }
+  ],
+  "columns": [
+    {
+      "tableName": "patients",
+      "name": "id",
+      "ordinalPosition": 1,
+      "dataType": "bigint",
+      "isNullable": false,
+      "defaultExpression": null,
+      "primaryKeyPosition": 1,
+      "sourceComment": "Patient identifier"
+    }
+  ],
+  "relationships": [
+    {
+      "constraintName": "visits_patient_id_fkey",
+      "sourceTableName": "visits",
+      "targetTableName": "patients",
+      "updateRule": "NO ACTION",
+      "deleteRule": "CASCADE",
+      "deferrable": false,
+      "initiallyDeferred": false,
+      "columns": [
+        { "position": 1, "sourceColumnName": "patient_id", "targetColumnName": "id" }
+      ]
+    }
+  ]
+}
+```
+
+## Fallback compatibile tramite `run_query`
+
+Se e soltanto se il server non espone `POST /rpc/schema_snapshot`, il catalogo può ottenere la
+stessa fotografia mediante una singola istruzione read-only inviata all'RPC già esistente:
+
+```http
+POST /rpc/run_query
+Content-Type: application/json
+
+{"query_text":"WITH ... SELECT ..."}
+```
+
+La query è costruita dal catalogo, interroga soltanto il catalogo PostgreSQL dello schema
+configurato e aggrega tabelle, colonne, primary key e foreign key nella stessa istruzione. Non sono
+ammessi più round trip, query per tabella o assemblaggi client-side di osservazioni effettuate in
+momenti diversi. Il nome schema deve essere validato come identificatore e quotato come valore SQL,
+non interpolato come SQL libero.
+
+`run_query` restituisce un array JSON di righe. Per questo fallback l'array deve contenere
+esattamente una riga e quella riga deve essere esattamente l'oggetto snapshot v1 sopra descritto,
+con `schemaVersion`, `capabilities`, `tables`, `columns` e `relationships`; campi mancanti,
+aggiuntivi o di tipo diverso rendono invalida l'intera fotografia. La risposta non è un contratto
+alternativo o più permissivo: cambia soltanto il trasporto della stessa snapshot stretta.
+
+`position` e `primaryKeyPosition` sono uno-based. Le coppie ordinate permettono foreign key
+composte. Il catalogo rifiuta l'intera fotografia se il JSON non rispetta il contratto o se la
+capability richiesta dal tipo di sincronizzazione è `unavailable`; in entrambi i casi non applica
+alcuna modifica. Il fallback viene tentato soltanto quando l'RPC preferito risulta assente, non per
+nascondere una snapshot malformata o un errore operativo del server. Se anche `run_query` non è
+disponibile, la query viene rifiutata, la risposta non contiene una singola snapshot v1 valida o una
+capability richiesta è `unavailable`, il run fallisce senza aggiornamenti parziali e senza esporre
+il corpo remoto.