Tables et champs

Avant les écrans, il y a les données : les tables où l'application conserve les comptes, les contacts, les commandes ou les demandes de congés. Dans Keplin, ces données vivent dans une base de données reliée à l'app (un datasource) et sont décrites dans un modèle — le dessin des tables, des champs, des clés et des relations que tout le reste de la plateforme lit.

Cette page porte sur la première moitié de ce travail : créer et modifier des tables, choisir des types, définir des clés et des index. Les relations et les champs énumérés ont leur propre page dans Relations et enums.

Les exemples viennent de l'app Gestion des Clients : un CRM avec trois tables — contas, contactos et oportunidades.

#Deux couches : la base de données et le modèle

Cela vaut la peine de séparer d'emblée deux choses qui se ressemblent :

Couche	Ce que c'est	Qui s'en sert
La base de données	Les tables, les colonnes et les index qui existent vraiment dans le moteur relié à l'app.	Le moteur de base de données. La modifier, c'est exécuter de vraies commandes.
Le modèle	La description de ces tables pour la plateforme : entités, champs, noms conviviaux, descriptions, relations et enums.	Les APIs, les écrans, les scripts et les rapports.

Une table n'entre dans le modèle que lorsque vous l'importez — et sortir du modèle n'efface rien dans la base de données. C'est pour cela que la plateforme distingue toujours Retirer du modèle de Supprimer.

#Ouvrir le modèle

1. Ouvrez l'app et choisissez l'onglet Données dans la sidebar.
2. Dans Datasources, cliquez sur le nom du datasource — dans Gestion des Clients, Dados CRM.
3. Un onglet s'ouvre avec le diagramme du modèle au centre, la console SQL en bas, et l'arborescence d'objets du datasource dépliée dans la sidebar.

Le diagramme se déplace à la souris ; les boutons dans le coin inférieur gauche règlent le zoom et cadrent l'ensemble. La position de chaque entité est conservée — vous rangez le diagramme une fois et c'est ainsi qu'il se rouvre.

#L'arborescence d'objets

Sous le datasource, l'arborescence montre ce qui existe dans la base de données, groupé et avec le décompte de chaque groupe :

Groupe	Ce qu'il liste
Tables	Les tables du moteur. Chacune a son propre menu (⋯).
Vues	Les vues (requêtes enregistrées sous un nom).
Programmation	Fonctions / Procédures et Triggers — voir Triggers.

Le champ Rechercher partout… en haut de la sidebar filtre l'arborescence ; avec une recherche active, les groupes s'ouvrent tout seuls et un groupe sans résultat disparaît.

#Créer une table

1. Passez la souris sur le datasource et ouvrez le menu ⋯ (Actions de …).
2. Choisissez Nouvelle table.
3. Remplissez le Nom de la table — c'est le nom qui restera dans la base de données (minuscules et underscore vous épargnent des maux de tête : actividades, linhas_encomenda).
4. Schéma (facultatif) n'a d'intérêt que sur les moteurs à schémas ; laissez vide si vous n'en utilisez pas.
5. Dans Description de la table, écrivez à quoi elle sert. Ce n'est pas de la décoration : cette description accompagne la table dans la plateforme et c'est elle qui expliquera la table à celui qui y arrivera après vous.
6. Définissez les colonnes (voir plus bas) et confirmez avec Créer la table.

#Les colonnes

Le panneau gauche de la boîte de dialogue est la liste des colonnes (Colonnes (N)) et le bouton + en ajoute une. Cliquez sur une colonne de la liste pour la modifier à droite.

La table commence toujours par une colonne id, de type integer, avec Clé primaire (PK) et Auto-incrément activés — le point de départ qui convient à 9 tables sur 10.

Champ	Ce qu'il fait
Nom	Le nom de la colonne dans la base de données.
Type	Le type logique de la colonne (liste complète plus bas).
Longueur	Uniquement pour text et char — combien de caractères tiennent.
Précision · Échelle	Uniquement pour decimal — total de chiffres et combien restent à droite de la virgule (18 · 2 pour l'argent).
Éléments de l'enum	Uniquement pour enum — voir Relations et enums.
Autorise NULL	Si la colonne accepte de rester vide. Désactivé, la base de données refuse les enregistrements sans valeur.
Clé primaire (PK)	Identifie l'enregistrement de façon unique.
Auto-incrément	Le moteur génère la valeur à chaque insertion.
Description	À quoi sert cette colonne.

La corbeille qui apparaît au survol d'une colonne de la liste la retire (dans une table nouvelle, elle sort aussitôt de la liste).

#Les types de colonne

Les types sont logiques : vous décrivez ce que la colonne conserve et la plateforme traduit vers le type juste du moteur relié. Le même dessin sert pour n'importe quelle base de données prise en charge.

Type	Pour quoi
text	Texte de longueur variable — noms, descriptions, notes.
char	Texte de longueur fixe — codes de pays, sigles.
integer	Nombres entiers. Le type naturel d'un id.
smallint	Petits entiers.
bigint	Grands entiers — compteurs, identifiants externes.
decimal	Nombres exacts avec décimales. C'est le type de l'argent.
float	Nombres approchés — mesures, pourcentages scientifiques.
boolean	Oui/Non.
date	Une date, sans heure.
time	Une heure, sans date.
datetime	Date et heure.
uuid	Identifiants universels.
json	Structures libres conservées sous forme de texte structuré.
binary	Contenu binaire.
enum	Un ensemble fermé de valeurs, défini sur place — voir Relations et enums.

#Clés primaires

La Clé primaire (PK) est ce qui identifie un enregistrement. Ce n'est pas facultatif en pratique : sans PK, une table peut être lue mais ne peut être ni modifiée ni supprimée depuis les écrans — la Table avertit Le datastore a besoin d'une clé primaire, et le Kanban désactive le glisser-déposer. Si la clé est composée de plus d'une colonne, activez Clé primaire (PK) sur chacune d'elles.

L'Auto-incrément confie au moteur le travail de numéroter. Cela n'a de sens que sur des colonnes entières.

#Faire entrer une table dans le modèle

Une table qui existe déjà dans la base de données (créée par vous ici, ou qui s'y trouvait déjà avant) doit entrer dans le modèle pour que les APIs et les écrans la voient. Il y a deux chemins, et ils reviennent au même :

• Faire glisser la table de l'arborescence vers le diagramme — elle tombe à l'endroit où vous la lâchez.
• Ouvrir le menu ⋯ de la table et choisir Importer au modèle.

La plateforme lit la structure de la table et crée l'entité : un nom avec une majuscule initiale (contas → Contas), les champs, les clés et les relations qu'elle trouve déclarées dans la base de données.

#La carte d'une entité

Chaque entité est une carte dans le diagramme :

• Le nom de l'entité dans l'en-tête, et deux boutons : Localiser dans l'arborescence (marque la table correspondante dans la sidebar) et Retirer du modèle.
• Un champ par ligne, avec le nom à gauche et le type à droite. La marque PK signale la clé primaire, et un ! après le type signifie que le champ n'accepte pas le vide.
• Les champs énumérés apparaissent en italique, avec le nom de l'enum à la place du type.
• Avec beaucoup de champs, la carte se rétrécit et propose Afficher N champs de plus / Afficher moins.
• En bas, la section Navigation liste les chemins vers les entités liées — sujet de Relations et enums.

#Modifier une table

Le menu ⋯ d'une table → Modifier la structure ouvre l'éditeur de structure, avec deux onglets : Colonnes et Index (N).

En haut se trouvent les trois choses qui décrivent la table :

Champ	Ce que c'est
Nom dans la BD	Le nom réel de la table.
Nom convivial (apps)	Le nom sous lequel la table est connue dans l'app.
Description de la table	À quoi elle sert.

Le Nom convivial (apps) est le pont entre une base de données dont vous avez hérité et une app lisible : la colonne peut s'appeler cli_nm_fis dans la base de données et nome dans l'app. Il existe aussi par colonne — et c'est le nom convivial qui apparaît dans les APIs, dans les datastores et dans les écrans.

#Toucher aux colonnes

Cliquez sur une colonne de la liste de gauche pour la modifier. Les modifications ne sont pas immédiates : elles s'accumulent et n'ont lieu que lorsque vous cliquez sur Appliquer les modifications.

• Une colonne ajoutée avec + est marquée comme nouvelle et porte la note Nouvelle colonne — elle est créée lorsque les modifications sont appliquées.
• Supprimer une colonne existante (la corbeille au bout de la ligne) la barre et affiche Marquée pour suppression (DROP) lors de l'application ; Annuler revient en arrière.
• S'il n'y a rien à appliquer, la plateforme dit Aucune modification.

#Index

L'onglet Index (N) liste les index de la table — nom, marque unique et colonnes — et permet d'en créer et d'en supprimer.

Pour créer un index :

1. Écrivez le nom (la convention ix_quelque_chose est bonne et c'est celle que le champ suggère).
2. Cochez unique si l'index sert aussi à empêcher les valeurs répétées — c'est ainsi que l'on garantit qu'il n'y a pas deux clients avec le même numéro fiscal.
3. Cliquez sur les colonnes qui font partie de l'index (l'ordre dans lequel vous cliquez est l'ordre de l'index).
4. Créer l'index.

Une table sans index propres affiche Aucun index (hormis la PK) — la clé primaire est déjà un index, elle n'a pas besoin d'être créée.

#Voir les données

Le menu ⋯ d'une table → Voir les données ouvre la console SQL en bas, avec la requête déjà faite et le résultat sous les yeux. C'est la façon rapide de confirmer ce qui s'y trouve sans quitter le modèle.

La console accepte aussi du SQL écrit par vous : écrivez à gauche, Exécuter, et le résultat apparaît à droite avec le décompte de lignes. La barre qui sépare la console du diagramme se déplace, et la flèche du coin la replie.

#Supprimer une table

Le menu ⋯ d'une table contient Supprimer, avec confirmation : Cette opération est définitive et retire l'objet de la base de données. À ne pas confondre avec Retirer du modèle, qui ne fait qu'ôter l'entité de la description de l'app.

#Pourquoi ne… ?

• Pourquoi je ne vois pas ma table dans les APIs ? Elle n'est probablement pas encore dans le modèle. Faites-la glisser de l'arborescence vers le diagramme, ou utilisez Importer au modèle.
• Pourquoi ai-je créé une colonne et elle n'apparaît pas ? Vérifiez que vous avez cliqué sur Appliquer les modifications — dans l'éditeur de structure, rien ne se passe avant cela.
• Pourquoi ma nouvelle table ne laisse-t-elle pas modifier les enregistrements dans les écrans ? Il manque la Clé primaire (PK). Sans elle, les écrans ne savent que lire.
• Pourquoi n'arrivé-je pas à changer le type d'une colonne ? Il y a des moteurs sans « modifier colonne ». La plateforme vous prévient et le chemin est nouvelle colonne → copier les données → supprimer l'ancienne.
• Pourquoi le nom du champ dans l'app n'est-il pas celui de la base de données ? Le Nom convivial (apps) de cette colonne est défini. C'est exprès — et cela se modifie au même endroit.
• Pourquoi l'entité a-t-elle disparu du diagramme alors que la table reste dans l'arborescence ? Elle a été retirée du modèle. Faites-la glisser à nouveau de l'arborescence vers le diagramme.