Laboratorio de PostgreSQL y PostgREST: una base de datos y una API REST en el navegador

Qué aprenden los alumnos

Crear una tabla y hablar con una base de datos por el nombre de su servicio, como se encuentran los servicios entre sí en producción. Leer y escribir filas a través de una API REST con curl, incluido filtrar y ordenar. Qué sobrevive a un reinicio y qué no: la base de datos guarda sus archivos en un volumen con nombre, así que las notas siguen ahí la próxima vez, mientras que un archivo escrito fuera de un volumen desaparece cuando el laboratorio se detiene. Hacer una copia de seguridad con pg_dump y restaurarla desde el archivo.

Ejecútalo en tu navegador

Pruébalo tú primero. La contraseña del usuario de la base de datos shop es shop.

1. Abre la página Contenedor. Abre «Crear» en la barra y elige «Ejecutar un contenedor». Cualquiera puede abrir la página, y el laboratorio de Git y el de SQL se inician sin cuenta. Todos los demás laboratorios necesitan una cuenta gratuita: crea una, inicia sesión y pulsa «Iniciar».
2. Busca el laboratorio. La tarjeta «Laboratorios de ejemplo» lista todos los ejemplos. Busca la base de datos con una API web.
3. Pulsa «Iniciar». «Iniciar» lo ejecuta tal cual, con una sola pulsación. «Editar el archivo primero» abre el archivo compose para que lo cambies antes de iniciarlo.
4. Ábrelo. En la página del laboratorio, en «En tu navegador», pulsa «Una API web sobre cada tabla» y añade /notes a la dirección cuando hayas creado la tabla. En el terminal, psql -h db -U shop abre la base de datos y curl http://api:3000/notes llama a la API.

El código en GitHub

El laboratorio completo es un archivo compose en un repositorio público, que también contiene la lección para la que se escribió, paso a paso. También se ejecuta en tu propio ordenador: docker compose up. Haz un fork para adaptarlo.

• El repositorio en GitHub
• compose.yaml, el laboratorio completo
• El README, con la lección
• La licencia (MIT)

Una lección básica en este laboratorio

API Basics y API Basics 2 son lecciones breves hechas en este laboratorio, cada paso explicado y con un botón Ejecutar que escribe su comando en el terminal del alumno. En API Basics crean una tabla, ponen una nota en ella, la leen por la web con curl y añaden otra con una petición POST. En API Basics 2 cambian una nota, borran una y leen los códigos de estado con los que responde la API.

Una cuenta personal gratuita las recibe en el módulo Basics, que está en Inicio, cada centro puede copiarlas de la carpeta Basics de la Biblioteca, y un centro nuevo las tiene en un módulo llamado Lab Basics (Sample). Son deliberadamente breves: muestran a un docente lo que es una lección hecha en un laboratorio, y el laboratorio hace el resto. Copia una en un módulo propio para cambiarla.

Asígnalo como trabajo

Para dárselo a una clase, crea un laboratorio propio a partir del repositorio.

1. Crea el laboratorio. En tu módulo añade una tarea y elige la tarjeta «Laboratorio de contenedores», y después «En un repositorio de GitHub». Indica https://github.com/mitsurutech/lab-sample con la rama main. El archivo compose es el predeterminado, compose.yaml. Haz un fork del repositorio antes si quieres modificarlo.
2. Publica y pruébalo. «Publicar» fija el commit que te mostraron, así que un cambio posterior en el repositorio no altera un laboratorio que ya has asignado. Inicia primero tu propia copia.
3. Asígnalo. Asígnalo como cualquier tarea, con una fecha de entrega si quieres, e indica en la tarea qué hacer y qué entregar.
4. Califica lo entregado. Abre la copia de un alumno y el trabajo que ha entregado, califícalo y devuélvelo con un motivo si necesita más.

Preguntas frecuentes

¿Qué es PostgREST?

Un pequeño servidor que lee una base de datos Postgres y convierte cada tabla en endpoints REST, de modo que los alumnos ven cómo una base de datos queda detrás de una API web sin escribir ninguna. El laboratorio lo ejecuta para cada alumno junto a su propio Postgres.

¿Se conservan los datos entre sesiones?

Sí. La base de datos guarda sus archivos en el volumen con nombre pgdata, que la plataforma conserva, igual que la carpeta personal del alumno. Todo lo que está fuera de un volumen desaparece cuando el laboratorio se detiene, que es como se comportan los contenedores en producción.

¿Cómo se conectan los alumnos a la base de datos y a la API en este laboratorio?

En el terminal, psql -h db -U shop abre la base de datos, con la contraseña shop, y curl http://api:3000/notes lee la tabla notes una vez creada. Cada una se alcanza por el nombre de su servicio, como se encuentran los servicios entre sí en producción.