Vai al contenuto
Kaiross

Database e gestionali: SQL Server, PostgreSQL, MySQL e tunnel VPN

L’agente interroga il database del gestionale in sola lettura, con una login dedicata, e impara la struttura grazie alla mappatura. Qui trovi gli script da consegnare all’IT.

Ultimo aggiornamento:

Sola lettura, sempre

Kaiross esegue solo query SELECT: controlla ogni query prima di eseguirla, usa i permessi della login (solo lettura) e applica timeout e limite di righe. I dati per grafici ed export vengono riletti dal database, senza passare dal modello.

SQL Server: login dedicata

Chiedi al DBA di creare una login usata solo da Kaiross. Script da eseguire come amministratore del server (sostituisci i segnaposti tra < >):

Login e permessi di sola lettura (SQL Server)
USE [master];
CREATE LOGIN [<login_kaiross>] WITH PASSWORD = N'<password>', CHECK_POLICY = ON, DEFAULT_DATABASE = [<database>];
GO
USE [<database>];
CREATE USER [<login_kaiross>] FOR LOGIN [<login_kaiross>];
GRANT SELECT ON SCHEMA::[dbo] TO [<login_kaiross>];
GRANT VIEW DEFINITION TO [<login_kaiross>];
GRANT VIEW DATABASE STATE TO [<login_kaiross>];
GO
  • Non aggiungere la login a db_owner, db_datawriter o a ruoli di server.
  • VIEW DATABASE STATE è facoltativo: rende più precisi e veloci i conteggi delle righe.
  • Per escludere tabelle sensibili (es. dati del personale) usa DENY:
Escludere una tabella
DENY SELECT ON OBJECT::[dbo].[<table>] TO [<login_kaiross>];

La password si inserisce solo nel connettore di Kaiross, che la salva nel Vault: non scriverla in email o ticket.

PostgreSQL: ruolo dedicato

Ruolo di sola lettura su tutto il database
CREATE ROLE kaiross LOGIN PASSWORD '<password>';
GRANT pg_read_all_data TO kaiross;

Oppure concedi la lettura solo alle tabelle utili:

Lettura di singole tabelle
GRANT USAGE ON SCHEMA public TO kaiross;
GRANT SELECT ON public.<table> TO kaiross;

Kaiross apre la sessione in modalità READ ONLY con statement_timeout e limite di righe.

MySQL e MariaDB: utente dedicato

Chiedi al DBA un utente usato solo da Kaiross, con il solo privilegio SELECT:

Utente di sola lettura su tutto il database (MySQL / MariaDB)
CREATE USER 'kaiross'@'%' IDENTIFIED BY '<password>';
GRANT SELECT ON <database>.* TO 'kaiross'@'%';

Oppure concedi la lettura solo alle tabelle utili:

Lettura di singole tabelle
GRANT SELECT ON <database>.<table> TO 'kaiross'@'%';

Kaiross apre sessione e query in sola lettura (READ ONLY), con un tempo massimo imposto dal server e un limite di righe. Funziona con MySQL 5.7+ e MariaDB 10.3+.

In SSL lascia Richiesto o scegli Richiesto + verifica certificato: Disattivato (solo in VPN) solo dentro un tunnel.

Creare la connessione

  1. Apri Integrazioni → SQL Server (o PostgreSQL, MySQL / MariaDB) e premi Nuova connessione.
  2. Inserisci host, porta, database, utente e password. Se il server è nella rete aziendale, in Raggiungibile tramite scegli il tunnel VPN.
  3. Con il certificato generato da SQL Server (autofirmato) attiva Accetta certificato self-signed.
  4. Premi Prova connessione e salva. Poi collega la connessione all’agente dalla scheda MCP e database.

Dettagli dei campi e degli strumenti: SQL Server, PostgreSQL, MySQL / MariaDB.

Tunnel VPN WireGuard

Per raggiungere un server nella rete dell’azienda serve un server WireGuard lato azienda (router o firewall con WireGuard, oppure una piccola VM) raggiungibile su una porta UDP.

  1. In Kaiross apri Impostazioni → Rete / VPN e premi Nuovo tunnel.
  2. In Modalità scegli Incolla configurazione (il file .conf preparato dall’IT) oppure Genera chiavi: indichi Indirizzo assegnato a Kaiross, Endpoint del server, Chiave pubblica del server, Reti raggiungibili e, se serve, il DNS interno.
  3. Premi Salva e verifica. Con Genera chiavi consegna all’IT la Chiave pubblica Kaiross da aggiungere al server WireGuard.
  4. Con Verifica raggiungibilità indica la porta del server (es. 1433) e premi Test: deve comparire Handshake riuscito.
Esempio di configurazione con i valori consigliati
[Interface]
PrivateKey = <Kaiross private key>
Address = 10.0.0.2/32
MTU = 1280

[Peer]
PublicKey = <server public key>
Endpoint = <vpn.example.ch>:51820
AllowedIPs = 10.0.0.5/32
  • AllowedIPs limitato all’indirizzo del server SQL: il tunnel serve solo al connettore.
  • MTU = 1280 nella sezione [Interface]: con valori più alti le query lunghe possono bloccarsi.
  • SQL Server su una porta TCP fissa: il servizio SQL Browser non passa dal tunnel, quindi indica la porta nel connettore.

«Mappa il database»

I gestionali hanno migliaia di tabelle. La mappatura (solo SQL Server) le legge una volta e scrive nella knowledge di un agente la struttura: tabelle, colonne, chiavi, relazioni, viste e query di esempio. Nella knowledge finisce solo la struttura: nessun valore delle tabelle viene salvato.

  1. Apri Integrazioni → SQL Server, scheda delle connessioni, riquadro Mappa del database e premi Mappa il database.
  2. Scegli l’Agente di destinazione (meglio un agente dedicato, es. «Analista gestionale»). Alla prima mappatura Campiona le tabelle (TOP 100 righe) è attivo, Tabelle da campionare al massimo è 300 (le più grandi; la struttura si legge per tutte) e Tempo massimo (minuti) è 20, fino a 25. Le volte dopo il modulo riprende le opzioni dell’ultima mappatura. Premi Avvia la mappatura.
  3. Segui l’avanzamento: puoi chiudere la pagina, la mappatura continua sul server. Poi attendi che tutti i file nella knowledge siano Pronti.
  4. Apri 00_panoramica.sql e controlla la riga Gestionale riconosciuto.
FileContenuto
00_panoramica.sqlRiepilogo, gestionale riconosciuto, tabelle e colonne non standard, avvisi.
10_tabelle_<area>.sqlTabelle per area con colonne, tipi e chiavi.
20_relazioni.sqlRelazioni dichiarate e dedotte, con la percentuale di affidabilità.
30_viste.sql, 40_procedure_funzioni.sqlViste, procedure e funzioni.
50_cross_database.sqlRiferimenti ad altri database.
60_query_esempio.sql, 65_query_standard.sqlQuery di esempio; quelle standard solo con un gestionale riconosciuto.
90_personalizzazioni.sqlLe regole della tua azienda: creato una volta, mai sovrascritto, prevale sul resto.

Se la mappatura segnala Permessi mancanti (ad esempio su altri database), premi Copia lo script: contiene le GRANT esatte di sola lettura da far eseguire al DBA. Poi premi Riprova.

Profilo Mago4

Per Mago4 (Microarea, gruppo Zucchetti) Kaiross riconosce il gestionale, conosce le relazioni standard e aggiunge 65_query_standard.sql con le query più comuni. La corrispondenza attesa in 00_panoramica.sql è oltre il 90%.

Le voci «da verificare» di 65_query_standard.sql (tipo di documento della nota di credito, criterio di costo per il margine) vanno confermate con chi conosce il gestionale.

90_personalizzazioni.sql: le regole della tua azienda

Questo file insegna all’agente come la tua azienda usa il gestionale. Si compila in una sessione di circa 30 minuti con chi conosce i dati: Agenti → agente → Knowledge → 90_personalizzazioni.sql → Modifica. Sostituisci i TODO con le risposte e cancella le righe di esempio.

  • Codici e significati: quali tipi di documento sono fattura, nota di credito, DDT; a cosa servono tabelle e colonne aggiuntive.
  • Regole di business: cosa include il fatturato, quale costo usare per il margine, quali depositi contano nelle giacenze, quando un ordine è aperto o in ritardo.
  • Relazioni delle tabelle personalizzate e le 3 estrazioni che fate più spesso.

Ripeti la mappatura dopo ogni aggiornamento del gestionale o almeno ogni 6 mesi: il file delle personalizzazioni resta com’è. Una sola mappatura alla volta per connessione.