Connecter des bases de données

Un datasource est une base de données enregistrée dans une app : une connexion avec un nom, un type et des identifiants, qui devient disponible pour tout ce qui, dans cette app, a besoin de données réelles — les étapes SQL des APIs, les scripts, le modèle de données (et, à travers lui, l'API GraphQL et les écrans). La connexion s'enregistre une fois ; à partir de là, toute l'app s'y réfère par son nom.

Dans l'app d'exemple Gestion des Clients, le datasource s'appelle crm — une base PostgreSQL avec les tables de comptes, de contacts et d'opportunités. C'est lui que vous verrez sur toutes les figures de ce chapitre.

#Où trouver les datasources

Il y a deux portes d'entrée, et vous utiliserez les deux :

• Le panneau Données — dans la sidebar de l'espace de travail de l'app, onglet Données, section Datasources. C'est l'endroit du quotidien : chaque datasource se déplie en une arborescence avec les tables, les vues et la programmation de la base de données, et le menu de chacun donne accès à toutes les actions.
• La page Datasources — la liste complète de l'app, avec le type et la date de création de chaque connexion (« Bases de données accessibles aux APIs et aux scripts de cette app »). C'est aussi vers là que pointent les raccourcis de la plateforme — par exemple le lien Ajoutez le premier qui apparaît dans une étape SQL quand l'app n'a pas encore de datasources. Sur les petits écrans, la navigation de l'app affiche Datasources directement.

#Créer un datasource

Vous aurez besoin des données de connexion de la base de données : adresse du serveur, port, nom de la base, utilisateur et mot de passe — les champs exacts varient selon le type (la page Types pris en charge détaille chacun).

#Interne ou externe

La fenêtre de création a deux onglets, et le choix décide de ce qui vous est demandé :

Onglet	Pour quoi	Ce que vous saisissez
Interne	Une base de données créée et conservée par la plateforme pour cette app.	Seulement le Nom interne et le moteur : PostgreSQL (une nouvelle base sur le serveur de l'installation, avec ses propres identifiants) ou SQLite (un fichier conservé avec l'app, avec import facultatif d'un fichier existant).
Externe	Une base de données qui existe déjà, la vôtre ou celle d'un autre système.	Le type (PostgreSQL, MySQL, MariaDB, SQL Server ou Oracle) et les données de connexion ; le bouton Tester la connexion confirme avant d'enregistrer.

Avec une base interne, vous ne voyez ni ne saisissez jamais de données de connexion : la plateforme la crée, conserve les identifiants chiffrés et se connecte pour vous. Si l'option PostgreSQL de l'onglet Interne est désactivée, le serveur PostgreSQL de l'installation n'a pas encore été configuré ; demandez-le à l'administrateur de l'installation.

#Depuis le panneau Données

1. Ouvrez l'onglet Données de la sidebar.
2. Dans la section Datasources, cliquez sur le bouton + (Nouveau datasource). Une fenêtre s'ouvre — « Connectez une base de données à cette app. Tout est chiffré au repos. »
3. Remplissez le Nom interne et choisissez le Type.
4. Remplissez les champs de connexion du type choisi.
5. Cliquez sur Tester la connexion et attendez le « Connexion OK. » — la page Tester la connexion et sécurité explique ce que fait le test et comment lire les erreurs.
6. Cliquez sur Enregistrer. L'arborescence affiche désormais le datasource, et son écran Modèle s'ouvre à la suite — prêt à importer des tables.

#Depuis la page Datasources

1. Ouvrez la page Datasources et cliquez sur Ajouter un datasource.
2. La page Nouveau datasource s'ouvre — « Saisissez les identifiants et testez la connexion avant d'enregistrer. Tout est chiffré au repos. » Le formulaire a deux sections : Identification (Nom interne et type de base de données) et Connexion (identifiants et paramètres de connexion).
3. Remplissez, testez avec Tester la connexion, et cliquez sur Créer.
4. Vous revenez à la liste, avec la confirmation « Datasource créé. ».

#Le nom interne est l'identité

Le Nom interne (ex. : warehouse-prod, ou crm dans notre exemple) n'est pas une étiquette décorative — c'est l'identifiant par lequel les APIs et les scripts appellent la connexion :

• Dans un script Python : db("crm").query("select * from contas").
• Dans une étape SQL d'une API : le champ Datasource de l'étape liste les noms enregistrés.

C'est pourquoi :

Règle	Ce qui arrive si elle n'est pas respectée
Unique à l'intérieur de l'app	« Il existe déjà un datasource portant le nom … dans ce projet. »
Sans collision avec un autre datasource	« Le nom … entre en collision avec le datasource … »
Stable — ne le changez qu'à dessein	Voir « Renommer un datasource » plus bas

#Modifier la connexion

La base de données a changé de serveur, de mot de passe, ou vous voulez activer le SSL :

1. Dans le panneau Données, ouvrez le menu ⋯ du datasource et choisissez Modifier la connexion.
2. La fenêtre s'ouvre avec tout de rempli sauf le mot de passe — le champ s'appelle alors Mot de passe (vide = conserver). Laissez-le vide pour conserver le mot de passe actuel ; écrivez pour le remplacer.
3. Modifiez ce dont vous avez besoin, cliquez sur Tester la connexion pour confirmer, puis sur Enregistrer. La confirmation est « Connexion enregistrée. ».

#Renommer un datasource

Faites un double clic sur le nom du datasource dans l'arborescence du panneau Données et écrivez le nouveau nom (ou changez le Nom interne dans Modifier la connexion). Les tables déjà importées dans le modèle suivent le nouveau nom automatiquement.

#Supprimer un datasource

1. Sur la page Datasources, cliquez sur l'icône de corbeille sur la ligne du datasource — ou, dans le panneau Données, ouvrez le menu ⋯ et choisissez Supprimer le datasource.
2. Lisez la confirmation attentivement : « Les APIs et les scripts qui utilisent ce datasource ne pourront plus s'exécuter. Cette action est définitive. » Dans l'arborescence, l'avertissement ajoute que le modèle associé s'en va aussi.
3. Confirmez avec Supprimer le datasource.

Ce que la suppression retire — et ce à quoi elle ne touche pas :

S'en va	Reste
La connexion enregistrée (nom, type, identifiants)	La base de données elle-même — rien n'est effacé sur le serveur d'origine
Les tables de ce datasource dans le modèle de l'app	Les APIs et les scripts qui l'utilisaient (ils échouent jusqu'à ce qu'ils pointent vers un autre datasource)

#Où la connexion est utilisée

Enregistrer le datasource est la première étape ; la valeur est dans ce qu'il débloque :

• L'arborescence d'objets — dépliez le datasource dans le panneau Données pour voir Tables, Vues et Programmation (fonctions, procédures et triggers). Chaque table a Voir les données (ouvre la console avec un select tout prêt) et Importer au modèle.

• Le modèle de données — les tables importées deviennent des entités du modèle, avec relations et noms conviviaux. C'est le modèle qui alimente l'API GraphQL de l'app et les blocs Table des APIs. Le chapitre du modèle de données traite cela à fond.

• Les APIs — dans une étape SQL, choisissez la base dans le champ Datasource et écrivez la Requête SQL. Les arguments de l'API entrent sous la forme :nomDeLArg et le résultat de l'étape précédente sous la forme :prev — « Les valeurs sont toujours paramétrées — jamais concaténées. » Il y a un interrupteur Renvoyer seulement la première ligne pour les requêtes à enregistrement unique.

• Les scripts — en Python, importez l'accès et interrogez par le nom :

  from api_manager import db
  
  def main(input):
      contas = db("crm").query(
          "select id, nome from contas where cidade = $1", ["Lisboa"]
      )
      return {"total": len(contas)}
  

  Les marqueurs de paramètres ($1, ?, :1, …) varient selon le moteur — le tableau est sur la page Types pris en charge.

#Pourquoi je ne vois pas… ?

• …le bouton Ajouter un datasource ? Créer, modifier et supprimer des datasources est réservé à qui a le profil d'administrateur dans l'app. Avec le profil de développeur, vous consultez la liste et utilisez les datasources, mais vous ne touchez pas à la connexion.
• …de datasources dans l'étape SQL de mon API ? L'app n'en a encore aucun — l'étape affiche « Cette app n'a pas de datasources. » avec le lien Ajoutez le premier.
• …de tables dans le bloc Table de l'API ? Le bloc Table lit dans le modèle, pas dans le datasource directement : « Importez d'abord des tables dans l'onglet "Modèle" d'un datasource. »