Lab PostgreSQL et PostgREST : une base de données et une API REST dans le navigateur

Ce lab donne à chaque élève sa propre base PostgreSQL et son propre PostgREST, qui transforme chaque table de la base en API REST. Un terminal à côté des deux dispose de psql et de curl : l’élève crée une table en SQL, puis la lit et l’écrit par HTTP.

C’est un seul fichier compose, qui s’exécute aussi sur votre propre machine.

Ce que les élèves apprennent

Créer une table et parler à une base par le nom de son service, comme les services se trouvent entre eux en production. Lire et écrire des lignes par une API REST avec curl, y compris le filtrage et le tri. Ce qui survit à un redémarrage et ce qui ne survit pas : la base garde ses fichiers dans un volume nommé, les notes sont donc encore là la fois suivante, alors qu’un fichier écrit hors d’un volume disparaît à l’arrêt du lab. Sauvegarder avec pg_dump et restaurer depuis le fichier.

Le lancer dans votre navigateur

Essayez-le d’abord vous-même. Le mot de passe de l’utilisateur de la base shop est shop.

  1. Ouvrir la page Conteneur. Ouvrez « Créer » dans la barre et choisissez « Lancer un conteneur ». Tout le monde peut ouvrir la page, et le lab Git et le lab SQL se lancent sans compte. Tous les autres labs demandent un compte gratuit : créez-en un, connectez-vous, puis appuyez sur « Démarrer ».
  2. Trouver le lab. La carte « Laboratoires d’exemple » liste tous les exemples. Trouvez la base de données avec une API web.
  3. Appuyer sur Démarrer. « Démarrer » le lance tel quel, en un clic. « Modifier le fichier d’abord » ouvre le fichier compose pour que vous puissiez le changer avant de démarrer.
  4. L’ouvrir. Sur la page du lab, sous « Dans votre navigateur », appuyez sur A web API over every table et ajoutez /notes à l’adresse une fois la table créée. Dans le terminal, psql -h db -U shop ouvre la base et curl http://api:3000/notes appelle l’API.

Le code sur GitHub

Le lab entier est un fichier compose dans un dépôt public, qui contient aussi la leçon pour laquelle il a été écrit, pas à pas. Il s’exécute aussi sur votre propre machine : docker compose up. Faites-en un fork pour l’adapter.

Une leçon de base sur ce lab

API Basics et API Basics 2 sont de petites leçons qui se font dans ce lab, chaque étape étant expliquée et accompagnée d’un bouton Exécuter qui tape sa commande dans le terminal de l’élève. Dans API Basics, elles créent une table, y mettent une note, la lisent par le web avec curl et en ajoutent une avec une requête POST. Dans API Basics 2, elles modifient une note, en suppriment une et lisent les codes d’état avec lesquels l’API répond.

Un compte personnel gratuit les reçoit dans le module Basics, qui se trouve sur l’« Accueil », chaque établissement peut les copier depuis le dossier Basics de la Bibliothèque, et un nouvel établissement les a dans un module appelé Lab Basics (Sample). Elles sont volontairement petites : elles montrent à un enseignant ce qu’est une leçon qui se fait dans un lab, et le lab fait le reste. Copiez-en une dans un module à vous pour la modifier.

En faire un travail

Pour le donner à une classe, créez un lab à vous à partir du dépôt.

  1. Créer le lab. Dans votre module, ajoutez une tâche et choisissez la carte « Lab de conteneurs », puis « Dans un dépôt GitHub ». Indiquez https://github.com/mitsurutech/lab-sample avec la branche main. Le fichier compose par défaut est compose.yaml. Faites d’abord un fork du dépôt si vous voulez le modifier.
  2. Publier et l’essayer. « Publier » fige le commit qui vous a été montré : un changement ultérieur dans le dépôt ne modifie donc pas un lab que vous avez déjà proposé. Démarrez d’abord votre propre copie.
  3. Le distribuer. Attribuez-le comme n’importe quelle tâche, avec une échéance si vous le souhaitez, et indiquez dans la tâche ce qu’il faut faire et ce qu’il faut rendre.
  4. Noter ce qui est rendu. Ouvrez la copie d’un élève et le travail rendu, notez-le et renvoyez-le avec un motif s’il demande un complément.

Questions fréquentes

Qu’est-ce que PostgREST ?
Un petit serveur qui lit une base Postgres et transforme chaque table en points d’accès REST : les élèves voient comment une base se place derrière une API web sans en écrire une. Le lab le lance pour chaque élève à côté de son propre Postgres.
Les données sont-elles conservées d’une session à l’autre ?
Oui. La base garde ses fichiers dans le volume nommé pgdata, que la plateforme enregistre, tout comme le dossier personnel de l’élève. Tout ce qui est hors d’un volume disparaît à l’arrêt du lab, comme se comportent les conteneurs en production.
Comment les élèves se connectent-ils à la base et à l’API dans ce lab ?
Dans le terminal, psql -h db -U shop ouvre la base, avec le mot de passe shop, et curl http://api:3000/notes lit la table notes une fois créée. Chacune s’atteint par le nom de son service, comme les services se trouvent entre eux en production.