Tabelle e campi

Prima delle schermate ci sono i dati: le tabelle in cui l'applicazione conserva account, contatti, ordini o richieste di ferie. In Keplin questi dati vivono in un database collegato all'app (un datasource) e sono descritti in un modello — il disegno di tabelle, campi, chiavi e relazioni che tutto il resto della piattaforma legge.

Questa pagina riguarda la prima metà di quel lavoro: creare e modificare tabelle, scegliere i tipi, definire chiavi e indici. Le relazioni e i campi enumerati hanno una pagina propria in Relazioni ed enum.

Gli esempi vengono dall'app Gestione Clienti: un CRM con tre tabelle — contas, contactos e oportunidades.

#Due livelli: il database e il modello

Vale la pena separare fin da subito due cose che si assomigliano:

Livello	Che cos'è	Chi lo usa
Il database	Le tabelle, le colonne e gli indici che esistono davvero nel motore collegato all'app.	Il motore di database. Modificarlo significa eseguire comandi reali.
Il modello	La descrizione di quelle tabelle per la piattaforma: entità, campi, nomi descrittivi, descrizioni, relazioni ed enum.	Le API, le schermate, gli script e i report.

Una tabella entra nel modello soltanto quando la importi — e uscire dal modello non cancella nulla nel database. È per questo che la piattaforma distingue sempre Rimuovi dal modello da Elimina.

#Aprire il modello

1. Apri l'app e scegli la scheda Dati nella barra laterale.
2. In Origini dati, clicca sul nome del datasource — in Gestione Clienti, Dati CRM.
3. Si apre una scheda con il diagramma del modello al centro, la Console SQL in basso e l'albero degli oggetti del datasource espanso nella barra laterale.

Il diagramma si trascina con il mouse; i pulsanti nell'angolo in basso a sinistra fanno zoom e inquadrano tutto. La posizione di ogni entità resta salvata — sistemi il diagramma una volta ed è così che si riapre.

#L'albero degli oggetti

Sotto il datasource, l'albero mostra ciò che esiste nel database, raggruppato e con il conteggio di ogni gruppo:

Gruppo	Che cosa elenca
Tabelle	Le tabelle del motore. Ognuna ha un menu proprio (⋯).
Viste	Le viste (query salvate con un nome).
Programmazione	Funzioni / Procedure e Trigger — vedi Trigger.

Il campo Cerca ovunque… in cima alla barra laterale filtra l'albero; con la ricerca attiva i gruppi si aprono da soli e un gruppo senza risultati scompare.

#Creare una tabella

1. Passa il mouse sul datasource e apri il menu ⋯ (Azioni di …).
2. Scegli Nuova tabella.
3. Compila il Nome della tabella — è il nome che resta nel database (minuscole e underscore ti risparmiano mal di testa: actividades, linhas_encomenda).
4. Schema (opzionale) interessa solo nei motori con schemi; lascialo vuoto se non li usi.
5. In Descrizione della tabella, scrivi a che cosa serve. Non è decorazione: questa descrizione accompagna la tabella nella piattaforma ed è ciò che spiega la tabella a chi ci arriverà dopo di te.
6. Definisci le colonne (qui sotto) e conferma con Crea tabella.

#Le colonne

Il pannello sinistro della finestra è l'elenco delle colonne (Colonne (N)) e il pulsante + ne aggiunge una. Clicca su una colonna dell'elenco per modificarla a destra.

La tabella inizia sempre con una colonna id, di tipo integer, con Chiave primaria (PK) e Incremento automatico attivi — la partenza che va bene per 9 tabelle su 10.

Campo	Che cosa fa
Nome	Il nome della colonna nel database.
Tipo	Il tipo logico della colonna (elenco completo più sotto).
Lunghezza	Solo in text e char — quanti caratteri ci stanno.
Precisione · Scala	Solo in decimal — totale di cifre e quante restano a destra della virgola (18 · 2 per il denaro).
Elementi dell'enum	Solo in enum — vedi Relazioni ed enum.
Consente NULL	Se la colonna accetta di restare vuota. Disattivato, il database rifiuta i record senza valore.
Chiave primaria (PK)	Identifica il record in modo univoco.
Incremento automatico	Il motore genera il valore a ogni inserimento.
Descrizione	A che cosa serve questa colonna.

Il cestino che appare passando il mouse su una colonna dell'elenco la rimuove (in una tabella nuova, esce subito dall'elenco).

#I tipi di colonna

I tipi sono logici: descrivi che cosa contiene la colonna e la piattaforma traduce nel tipo giusto del motore collegato. Lo stesso disegno serve per qualsiasi database supportato.

Tipo	Per che cosa
text	Testo di lunghezza variabile — nomi, descrizioni, note.
char	Testo di lunghezza fissa — codici di paese, sigle.
integer	Numeri interi. Il tipo naturale di un id.
smallint	Interi piccoli.
bigint	Interi grandi — contatori, identificatori esterni.
decimal	Numeri esatti con decimali. È il tipo del denaro.
float	Numeri approssimati — misurazioni, percentuali scientifiche.
boolean	Sì/No.
date	Una data, senza ora.
time	Un'ora, senza data.
datetime	Data e ora.
uuid	Identificatori universali.
json	Strutture libere salvate come testo strutturato.
binary	Contenuto binario.
enum	Un insieme chiuso di valori, definito lì stesso — vedi Relazioni ed enum.

#Chiavi primarie

La Chiave primaria (PK) è ciò che identifica un record. Nella pratica non è opzionale: senza PK, una tabella può essere letta ma non può essere modificata né cancellata dalle schermate — la Tabella avvisa Il datastore ha bisogno di una chiave primaria., e il Kanban disattiva il trascinamento. Se la chiave è composta da più di una colonna, attiva Chiave primaria (PK) su ognuna.

L'Incremento automatico affida al motore il lavoro di numerare. Ha senso solo in colonne intere.

#Portare una tabella nel modello

Una tabella che esiste già nel database (creata da te qui, oppure già presente prima) deve entrare nel modello perché le API e le schermate la vedano. Ci sono due strade, e portano allo stesso risultato:

• Trascinare la tabella dall'albero al diagramma — cade nel punto in cui la lasci.
• Aprire il menu ⋯ della tabella e scegliere Importa nel modello.

La piattaforma legge la struttura della tabella e crea l'entità: un nome con l'iniziale maiuscola (contas → Contas), i campi, le chiavi e le relazioni che trova dichiarate nel database.

#La card di un'entità

Ogni entità è una card nel diagramma:

• Il nome dell'entità nell'intestazione, e due pulsanti: Individua nell'albero (evidenzia la tabella corrispondente nella barra laterale) e Rimuovi dal modello.
• Un campo per riga, con il nome a sinistra e il tipo a destra. Il segno PK indica la chiave primaria, e un ! dopo il tipo significa che il campo non accetta il vuoto.
• I campi enumerati appaiono in corsivo, con il nome dell'enum al posto del tipo.
• Con molti campi, la card si accorcia e offre Mostra altri N campi / Mostra meno.
• In fondo, la sezione Navigazione elenca i percorsi verso le entità collegate — argomento di Relazioni ed enum.

#Modificare una tabella

Il menu ⋯ di una tabella → Modifica struttura apre l'editor della struttura, con due schede: Colonne e Indici (N).

In alto ci sono le tre cose che descrivono la tabella:

Campo	Che cos'è
Nome nel DB	Il nome reale della tabella.
Nome descrittivo (app)	Il nome con cui la tabella è conosciuta nell'app.
Descrizione della tabella	A che cosa serve.

Il Nome descrittivo (app) è il ponte fra un database che hai ereditato e un'app leggibile: la colonna può chiamarsi cli_nm_fis nel database e nome nell'app. Esiste anche per colonna — ed è il nome descrittivo quello che appare nelle API, nei datastore e nelle schermate.

#Toccare le colonne

Clicca su una colonna dell'elenco di sinistra per modificarla. Le modifiche non sono immediate: si accumulano e avvengono solo quando premi Applica modifiche.

• Una colonna aggiunta con + appare contrassegnata come nuova e porta la nota Colonna nuova — viene creata applicando le modifiche.
• Eliminare una colonna esistente (il cestino a fine riga) la barra e mostra Contrassegnata per l'eliminazione (DROP) all'applicazione.; Annulla ripristina.
• Se non c'è nulla da applicare, la piattaforma dice Nessuna modifica.

#Indici

La scheda Indici (N) elenca gli indici della tabella — nome, marca unique e le colonne — e permette di crearli ed eliminarli.

Per creare un indice:

1. Scrivi il nome (la convenzione ix_qualcosa è buona ed è quella che il campo suggerisce).
2. Spunta unique se l'indice serve anche a impedire valori ripetuti — è così che si garantisce che non ci siano due clienti con la stessa partita IVA.
3. Clicca sulle colonne che fanno parte dell'indice (l'ordine in cui clicchi è l'ordine dell'indice).
4. Crea indice.

Una tabella senza indici propri dice Nessun indice (oltre alla PK). — la chiave primaria è già un indice, non serve crearla.

#Vedere i dati

Il menu ⋯ di una tabella → Visualizza dati apre la Console SQL in basso, già con la query pronta e il risultato a vista. È il modo rapido di controllare che cosa c'è dentro senza uscire dal modello.

La console accetta anche SQL scritto da te: scrivi a sinistra, Esegui, e il risultato appare a destra con il conteggio delle righe. La barra che separa la console dal diagramma si trascina, e la freccia nell'angolo la richiude.

#Eliminare una tabella

Il menu ⋯ di una tabella ha Elimina, con conferma: Questa operazione è permanente e rimuove l'oggetto dal database. Da non confondere con Rimuovi dal modello, che toglie soltanto l'entità dalla descrizione dell'app.

#Perché no…?

• Perché non vedo la mia tabella nelle API? Probabilmente non è ancora nel modello. Trascinala dall'albero al diagramma, oppure usa Importa nel modello.
• Perché ho creato una colonna e non appare? Verifica di aver premuto Applica modifiche — nell'editor di struttura, prima di quello non succede nulla.
• Perché la mia tabella nuova non lascia modificare i record nelle schermate? Manca la Chiave primaria (PK). Senza di essa, le schermate sanno solo leggere.
• Perché non riesco a cambiare il tipo di una colonna? Ci sono motori senza "modifica colonna". La piattaforma ti avvisa e la strada è colonna nuova → copiare i dati → eliminare la vecchia.
• Perché il nome del campo nell'app non è quello del database? È definito il Nome descrittivo (app) di quella colonna. È voluto — e si modifica nello stesso posto.
• Perché l'entità è sparita dal diagramma ma la tabella resta nell'albero? È stata rimossa dal modello. Trascinala di nuovo dall'albero al diagramma.