Laboratorio — Entorno de trabajo

Todo el trabajo práctico del curso (ejemplos de clase, laboratorios y el proyecto Chasqui) se hace dentro de un contenedor Docker idéntico para todos, con PostgreSQL 18, el cliente psql y Node.js 26 ya instalados. Así evitamos el “en mi computadora sí funciona”: si las pruebas pasan en el contenedor, pasan en la revisión.

1. Requisitos

La imagen es nativa: en una laptop con procesador ARM (Apple Silicon, por ejemplo) corre como ARM, y en una con procesador Intel o AMD corre como x86-64. No hay emulación, así que PostgreSQL corre a velocidad normal.

Si no pueden instalar Docker, vean la sección 7.

2. Levantar el contenedor

Desde la carpeta del repositorio del curso (o la de su proyecto):

./env/run.sh                 # la primera vez construye la imagen (unos minutos)

Al entrar, el servidor PostgreSQL ya está corriendo dentro del contenedor. run.sh monta el directorio actual en /work: los archivos se editan con el editor de siempre en su computadora y se ejecutan en el contenedor. También acepta un comando:

./env/run.sh psql chasqui            # abre psql sobre la base de datos chasqui
./env/run.sh make test               # corre las pruebas del proyecto
./env/run.sh --rebuild               # reconstruye la imagen (si cambió el Dockerfile)

Si su proyecto está en otra carpeta, llamen a run.sh con su ruta desde esa carpeta: /ruta/al/curso/env/run.sh.

Dos terminales, un mismo servidor. Si el contenedor ya está abierto y corren run.sh en otra terminal, se abre una segunda shell en el mismo contenedor, conectada al mismo servidor. Es lo que necesitamos en las semanas 13 y 14 para intercalar dos transacciones. Cuando se cierra la primera terminal, el contenedor se detiene y la segunda también se cierra.

Los datos se quedan. Las bases de datos se guardan en un volumen de Docker llamado bd-pgdata, no dentro del contenedor: al salir y volver a entrar siguen ahí. Para empezar de cero, ./env/run.sh --reset-db borra el volumen (pide confirmación).

La imagen (env/Dockerfile, basada en la imagen oficial de PostgreSQL 18) incluye:

• PostgreSQL 18: el servidor, psql, pg_dump, createdb, dropdb y las extensiones de contrib que usamos (pageinspect, pg_buffercache, pg_walinspect)
• Node.js 26 (LTS) con npm, y el driver pg ya instalado: import pg from 'pg' funciona en cualquier carpeta, sin npm install
• los datos de ejemplo de Chasqui y el comando chasqui-load
• make, git, curl y los editores de terminal vim y nano

3. Los datos de ejemplo: Chasqui

datasets/chasqui/ tiene la base de datos de una empresa de encomiendas: 29 agencias, 1800 clientes, 120 rutas, unos 6000 viajes y 12 000 envíos entre enero y junio de 2026. Los datos son inventados y se generan con gen.mjs, siempre iguales.

make -C datasets/chasqui         # crea (o vuelve a crear) la base de datos chasqui
make -C datasets/chasqui big     # crea chasqui_big, con 2 millones de envíos (semanas 9-12)
chasqui-load chasqui_lab04       # otra copia, con otro nombre, desde cualquier carpeta

make vuelve a crear la base de datos desde cero: si en un laboratorio borraron o cambiaron datos, así vuelven al estado inicial. chasqui_big tarda alrededor de un minuto y ocupa unos 300 MB.

4. psql: el cliente de PostgreSQL

psql se conecta sin argumentos: dentro del contenedor, las variables PGHOST, PGUSER y PGDATABASE ya apuntan al servidor local, con el usuario postgres.

$ psql chasqui
chasqui=# SELECT name, city FROM agency WHERE region = 'Puno';
chasqui=# \d shipment

Una consulta termina con ;. Si psql muestra chasqui-# en lugar de chasqui=#, está esperando el resto de la sentencia: falta el ;. Si muestra chasqui=!#, una sentencia falló dentro de una transacción y hay que hacer ROLLBACK;.

5. Pruebas con node --test

Los ejemplos de clase, los laboratorios y el proyecto usan el runner de pruebas que trae Node.js: node --test busca los archivos *.test.mjs y los ejecuta. Un archivo de pruebas es un módulo normal:

import { test, after } from 'node:test';
import assert from 'node:assert/strict';
import pg from 'pg';

const pool = new pg.Pool();
after(() => pool.end());

test('hay 29 agencias', async () => {
  const { rows } = await pool.query('SELECT count(*)::int AS n FROM agency');
  assert.equal(rows[0].n, 29);
});

Cada carpeta de código (code/week-NN/) y cada entrega del proyecto trae un Makefile:

make           # prepara la base de datos que usan los ejemplos o las pruebas
make test      # la vuelve a crear y corre todos los *.test.mjs
make clean     # borra esa base de datos

En el proyecto, make test usa una base de datos aparte, chasqui_test, que se crea de nuevo en cada corrida; así las pruebas no dependen de lo que hayan cambiado a mano en chasqui.

6. Editar el código

Cualquier editor sirve, porque los archivos viven en su computadora. Con VS Code, abran la carpeta del curso o del proyecto y usen la terminal integrada para ./env/run.sh. Para escribir SQL con resaltado y autocompletado, las extensiones de PostgreSQL de VS Code se pueden conectar al servidor del contenedor, pero no hace falta: psql y un archivo .sql alcanzan para todo el curso.

7. Alternativa: PostgreSQL y Node.js locales

Si no pueden usar Docker, instalen PostgreSQL 18 (descargas oficiales) y Node.js 26 (nodejs.org). Comprueben las versiones:

psql --version       # debe decir 18
node --version       # debe decir v26

Luego, en la carpeta del curso:

npm install pg                                   # crea node_modules/ en la carpeta
export PGHOST=localhost PGUSER=postgres          # y PGPASSWORD si su instalación la pide
psql -c "ALTER DATABASE postgres SET timezone TO 'America/Lima'"
make -C datasets/chasqui

chasqui-load solo existe en el contenedor; en su lugar usen make -C /ruta/al/curso/datasets/chasqui DB=chasqui_test. Antes de entregar, corran las pruebas al menos una vez en el contenedor.

8. Solución de problemas