Durante seis módulos, Escena Viva ha vivido de un fichero: datos/eventos.json. Nos ha servido bien. Nos enseñó fs.promises, nos permitió construir un dominio rico con Evento y Sesion, nos dio de comer para el servidor node:http del módulo 4 y para la API Express del módulo 6. Pero al cerrar aquel módulo dejamos una promesa pendiente: el problema del aforo y la sobreventa no se resolvía con validación ni con errores bien tipados, porque no es un problema de forma ni de estado, sino de concurrencia y persistencia. Ese problema es la puerta de entrada a este módulo.

Aquí no vamos a escribir todavía ni un esquema de Mongoose ni una sentencia CREATE TABLE. Vamos a hacer algo más importante: entender qué nos falta, qué nos da un sistema gestor de bases de datos a cambio de qué, cómo se elige entre el mundo relacional y el documental sin caer en bandos, y cómo se diseña el modelo de datos de Escena Viva. Al final tendrás el plano completo de lo que construiremos en las cinco lecciones siguientes.

1. Por qué un fichero JSON deja de servir
2. Qué aporta realmente un SGBD
3. Relacional frente a documental
4. ACID, BASE y el teorema CAP aplicados a un aforo
5. El panorama de bases de datos para Node.js
6. Controlador nativo frente a ORM/ODM
7. Diseñar el modelo de datos de Escena Viva
8. El modelo definitivo en un diagrama
9. Aislar la persistencia: el patrón repositorio
10. Instalar MongoDB y comprobar la conexión

Seamos honestos y concretos. src/catalogo-datos.js no es un mal módulo: lee datos/eventos.json con fs.promises, memoriza el resultado y expone obtenerCatalogo() y obtenerEventoPorId(). El problema no es su código, es su modelo de almacenamiento. Estos son los fallos reales, no teóricos, que Escena Viva ya tiene hoy:

• Escrituras concurrentes que se pisan. Si dos peticiones venden entradas a la vez, ambas leen el fichero, ambas modifican su copia en memoria y ambas lo reescriben entero. La última escritura gana y la primera venta desaparece. No hay bloqueo, no hay arbitraje, no hay nadie que decida el orden. Es exactamente el escenario de sobreventa.
• Escrituras no atómicas. Un writeFile de un catálogo completo puede interrumpirse (fallo de disco, SIGKILL, contenedor reiniciado) dejando un JSON truncado. Un JSON truncado no es un catálogo con un evento menos: es un fichero que ya no parsea, y la aplicación no arranca.
• Todo el catálogo en memoria. Con 3 eventos y 7 sesiones es gratis. Con 40.000 eventos históricos, cada proceso Node carga megabytes que nunca consulta. La memoria de un proceso es un recurso caro y compartido con el bucle de eventos.
• Sin consultas eficientes. "Dame las sesiones del Teatro Almendra entre el 1 y el 15 de marzo con entradas libres" hoy se resuelve recorriendo el array entero en JavaScript. Es O(n) sobre todo el conjunto de datos, en el hilo principal, y no hay forma de mejorarlo sin escribir tú mismo un índice.
• Sin integridad. Nada impide que un pedido apunte a ses-999-9, una sesión que no existe. Nada impide que vendidas supere a aforo. Las invariantes viven solo en las clases del dominio, y si alguien escribe el JSON a mano o un script se salta el dominio, quedan datos corruptos para siempre.
• Sin historial. El fichero solo tiene el estado actual. ¿Cuántas entradas se vendieron el martes pasado? ¿Quién anuló el pedido? No hay respuesta: el estado anterior se sobrescribió.
• Sin acceso desde varios procesos. Este es el que más duele de cara al futuro. En el módulo 10 veremos cluster y arrancaremos varios procesos Node para aprovechar todos los núcleos de la máquina. Con un fichero JSON, cada proceso tendría su propia caché en memoria y su propia idea del aforo; ni siquiera se enterarían de las ventas de los demás. La persistencia en fichero impide escalar. Y en el módulo 11, al desplegar con PM2 o varias réplicas en contenedores, el problema se multiplica por el número de instancias.

La conclusión no es que los ficheros sean malos. Un fichero JSON es perfecto para configuración, para semillas, para exportar un informe. Es malo como almacén de estado mutable compartido y concurrente. Y eso es precisamente lo que es el aforo de una sesión.

Un sistema gestor de bases de datos (SGBD) es un proceso especializado, normalmente en otra máquina o en otro contenedor, cuyo único trabajo es custodiar datos. A cambio de aprenderlo y de operarlo, te da seis cosas que tú no vas a reimplementar bien:

Fíjate en la última fila. Es la que resuelve el problema que arrastramos, y a ella le dedicaremos media lección 07-06.

Hay dos grandes familias que un desarrollador de Node se encuentra a diario. Ninguna es "moderna" y la otra "antigua"; ninguna es "seria" y la otra "de juguete". Son modelos con compromisos distintos.

La forma sana de leer esta tabla: elige el modelo que se parezca a tu patrón de acceso. Si tu aplicación casi siempre lee "un evento con todas sus sesiones", el documental te da eso en una sola lectura de disco. Si tu aplicación casi siempre cruza cinco entidades para sacar un informe, el relacional te lo da en una sola consulta optimizada.

Escena Viva, curiosamente, tiene las dos caras: el catálogo es documental por naturaleza (un evento contiene sus sesiones) y la venta es relacional por naturaleza (pedidos, entradas, usuarios y dinero). Por eso este módulo hace las dos cosas: MongoDB será la persistencia oficial en las lecciones 2 a 4, y en las lecciones 5 y 6 modelaremos lo mismo en PostgreSQL para ver qué cambia — y descubriremos que la sobreventa se resuelve de forma especialmente elegante allí.

ACID describe las garantías de una transacción. Atomicidad: la transacción ocurre entera o no ocurre. Consistencia: al terminar, todas las reglas del esquema siguen cumpliéndose. Aislamiento: dos transacciones simultáneas no se ven a medias, el resultado es como si se hubieran ejecutado en algún orden. Durabilidad: una vez confirmada, sobrevive al fallo del servidor. Los sistemas relacionales nacieron con ACID y los documentales han ido incorporándolo. BASE es el compromiso contrario, típico de sistemas distribuidos masivos: Basically Available (siempre responde), Soft state (el estado puede estar en tránsito), Eventually consistent (si dejas de escribir, en algún momento todas las réplicas coincidirán). BASE cambia corrección inmediata por disponibilidad y escala.

El teorema CAP explica por qué existe ese cambio. En un sistema distribuido en el que la red puede partirse (y siempre puede), no se pueden mantener a la vez consistencia fuerte (C) y disponibilidad total (A): cuando dos nodos dejan de verse, o rechazas escrituras para no divergir, o las aceptas y divergirás. Como la tolerancia a particiones (P) no es opcional en una red real, la decisión práctica es entre CP (rechazo escrituras dudosas, sigo siendo correcto) y AP (acepto todo, ya reconciliaré).

Aplicado a Escena Viva: un aforo exige garantías fuertes. Vender una entrada de más no es un detalle cosmético que se arregle "eventualmente"; es una persona con un código EV-2026-000431 de pie en la puerta del Teatro Almendra sin butaca, y un reembolso, y una reclamación. El contador vendidas es el ejemplo de libro de dato que necesita consistencia inmediata: preferimos rechazar una compra dudosa (CP) a aceptarla y descubrir después que no había sitio. En cambio, otros datos de la misma plataforma toleran perfectamente consistencia eventual: el número de visitas de la página de un evento, las recomendaciones, o la caché del catálogo que veremos con Redis en el módulo 10. La garantía se elige por dato, no por aplicación.

Redis merece una aclaración porque se malinterpreta mucho: no es "una base de datos más rápida", es una base de datos en memoria con un modelo de durabilidad distinto. Se usa delante de la base de datos principal, no en su lugar. En el módulo 10 la usaremos para cachear el catálogo y para encolar los correos de confirmación.

Entre tu código y el motor hay siempre un controlador (driver): habla el protocolo binario de la base de datos y expone una API de bajo nivel. Encima puede haber un ORM (Object-Relational Mapper, mundo SQL) o un ODM (Object-Document Mapper, mundo documental), que traduce entre filas o documentos y objetos de JavaScript.

Lo que te da un ORM/ODM: menos código repetitivo, validación declarativa, tipos coherentes, hooks, migraciones y un modelo mental uniforme para todo el equipo. Lo que te quita: transparencia. Una línea inocente puede generar 200 consultas (el problema N+1 que veremos en la lección 07-04). La regla profesional es: usa el ORM para el 95 % del código y no tengas miedo de bajar a consultas en crudo para el 5 % que importa, midiendo antes de decidir. En este módulo usaremos Mongoose (ODM) y Sequelize (ORM), y en ambos casos veremos cómo escapar a la consulta cruda.

Antes de escribir un esquema hay que decidir qué es una entidad. Una entidad es algo que tiene identidad propia y ciclo de vida propio: existe antes y después de la operación que la creó, y tiene sentido buscarla por sí misma. Un evento es una entidad. Un pedido es una entidad. El nombre de la sala, en cambio, es un atributo.

La segunda decisión es qué se agrupa y qué se separa. En el mundo documental esto se llama incrustar frente a referenciar y lo estudiaremos a fondo en la lección 07-04, pero el criterio ya podemos aplicarlo con dos preguntas:

1. ¿Se leen siempre juntos? Si nunca pides una sesión sin su evento, agrúpalos.
2. ¿Crece sin límite? Si la colección hija crece indefinidamente, sepárala.

Apliquémoslo a nuestras entidades:

• Evento con sus sesiones incrustadas. Un evento tiene entre 1 y 7 sesiones en nuestro catálogo; una obra en cartel podría tener 60. Es un número acotado y conocido de antemano. Además, la pantalla de detalle del evento y la propia API (GET /eventos/:id) las piden siempre juntas: ya hoy el controlador listarSesionesDelEvento parte de un Evento cargado. Y su tamaño es minúsculo. Se incrustan.
• Pedido como colección aparte. Los pedidos crecen sin techo: un evento popular puede acumular decenas de miles. Tienen ciclo de vida propio (pendiente → pagado → emitido | anulado) y se consultan por su cuenta ("mis pedidos"). Meterlos dentro del evento haría crecer el documento hasta reventar el límite y obligaría a reescribirlo entero en cada compra. Se separan.
• Entrada como colección aparte. Cada entrada tiene su código único EV-2026-000431, su estado (valida → usada | anulada) y se valida individualmente en la puerta, escaneando. Es la unidad de acceso más pequeña del sistema y la de mayor volumen. Se separa, con referencias al pedido y a la sesión.
• Usuario como colección aparte, con su rol (asistente, organizador, administrador). En este módulo lo creamos sin contraseñas ni autenticación: eso es íntegramente el módulo 8. Aquí solo dejamos el hueco preparado.

Y una tercera decisión, deliberadamente incómoda: el contador vendidas vive dentro de la sesión, aunque podría calcularse contando entradas válidas. Es una desnormalización a propósito, para que comprobar el aforo sea una lectura de un campo y no una agregación. El precio es mantener la coherencia entre el contador y las entradas reales; ese precio lo pagamos con las técnicas de la lección 07-06.

Léelo así: SESION aparece como entidad en el diagrama porque conceptualmente lo es, pero físicamente vive dentro del documento EVENTO como subdocumento. PEDIDO y ENTRADA son colecciones independientes que se relacionan por referencia. Este es el plano que implementaremos en la lección 07-02 con Mongoose y que traduciremos a tablas en la 07-05 con Sequelize — donde SESION sí será una tabla propia, y veremos por qué.

Aquí va la advertencia de arquitectura más importante del módulo. Si los controladores llaman directamente a Evento.find(...), tu aplicación queda casada con MongoDB para siempre. Cambiar de motor, o probar con datos falsos, o consultar dos fuentes distintas, exigiría reescribir todos los controladores.

La solución es una capa fina: src/repositorios/. Un repositorio expone operaciones en el lenguaje del negocio (obtenerCatalogo, obtenerEventoPorId, reservarAforo, crearPedido) y esconde por completo cómo se cumplen. Por encima de él, controladores y dominio no saben si debajo hay Mongo, Postgres o un array.

Fíjate en el detalle decisivo: es exactamente la firma pública de src/catalogo-datos.js. Por eso podremos sustituir el módulo entero sin tocar src/controladores/eventos.js. Y por eso, en la lección 07-05, escribiremos una segunda implementación sobre Sequelize sin cambiar una línea de la aplicación. El repositorio devuelve objetos del dominio (Evento, Sesion), no documentos de Mongoose: así el dominio conserva sus getters (ocupacion, agotado) y sus invariantes, tal como los dejamos en el módulo 2.

Tres caminos, todos válidos. Elige uno.

Opción A: servicio local. Instala MongoDB Community Server desde el sitio oficial y arráncalo como servicio del sistema:

Opción B: Docker. La más limpia porque no ensucia tu máquina y se borra en un comando. En el módulo 11 formalizaremos esto con docker compose:

Opción C: MongoDB Atlas. El servicio gestionado en la nube. Tiene una capa gratuita suficiente para este curso; te dará una URL del tipo mongodb+srv://usuario:[email protected]/escena_viva. Es lo que usarás en producción si no quieres operar el motor tú mismo.

Sea cual sea la opción, comprueba la conexión con el cliente oficial mongosh:

Y dentro del intérprete:

Una peculiaridad que sorprende: MongoDB no crea la base de datos ni la colección hasta el primer documento. Si show dbs no lista escena_viva recién conectado, no es un error.

La URL de conexión no se escribirá nunca a mano en el código. Irá en .env y se leerá desde src/config/index.js, que ya es el único punto de la aplicación que toca process.env:

Y con la conexión comprobada, conviene fijar de antemano qué preguntas hará la aplicación, porque el modelo de datos se diseña desde las consultas hacia atrás. Estas son las cinco consultas más frecuentes de Escena Viva, y son las que gobernarán los índices de la lección 07-02:

• Elegir el motor por moda. "Usamos Mongo porque es JavaScript" no es un criterio. El criterio es el patrón de acceso, las garantías que necesitas y lo que tu equipo sabe operar.
• Creer que "sin esquema" significa "sin diseño". MongoDB no te obliga a declarar una forma, pero tus datos la tienen igual. Si no la decides tú, la decidirá cada insert que escribas, y acabarás con siete variantes del mismo documento.
• Meter la URL de conexión en el código. Con credenciales dentro y subida a git. Va en la configuración, siempre. Ya tienes el sitio: src/config/index.js.
• Dejar la base de datos sin autenticación "porque es desarrollo". Un MongoDB expuesto en el 27017 sin usuario es de los blancos favoritos de los escáneres automáticos. En local, al menos no publiques el puerto fuera de localhost.
• Consejo: antes de modelar, escribe las cinco consultas que tu aplicación hará más veces. El modelo de datos se diseña desde las consultas hacia atrás, no desde las entidades hacia delante.
• Consejo: conserva datos/eventos.json. No lo borraremos: en la lección 07-06 se convertirá en la semilla que carga la base de datos. Se jubila como almacén, no como fuente.

Abre src/catalogo-datos.js y src/controladores/pedidos.js y localiza, sin ejecutar nada, los puntos exactos donde dos peticiones simultáneas pueden corromper el estado. Escribe para cada uno: qué línea lee, qué línea escribe, y qué pasa si otra petición se cuela entre ambas.

Escena Viva quiere añadir dos cosas: (a) las reseñas que los asistentes dejan sobre un evento, y (b) el plano de butacas de cada sala. Para cada una, decide si se incrusta o se separa y justifica la decisión con los dos criterios de esta lección (lectura conjunta y crecimiento).

Clasifica estos cuatro datos según necesiten consistencia fuerte o eventual, y justifica: (1) vendidas de una sesión, (2) el contador de visitas de la ficha de un evento, (3) el estado de un pedido, (4) el listado de "eventos recomendados para ti".

Ejercicio 1. El patrón peligroso es siempre leer-modificar-escribir sin exclusión mutua. En el flujo de compra: se lee el catálogo memorizado, se comprueba sesion.libres >= cantidad, se llama a sesion.vender() y se persiste. Si dos peticiones ejecutan la comprobación antes de que cualquiera de las dos escriba, ambas la superan aunque solo quede una entrada. La memorización empeora las cosas: la copia en memoria puede llevar minutos desactualizada respecto al fichero. Y como Node es monohilo, el hueco se abre exactamente en cada await — el bucle de eventos del módulo 2 cede el turno justo ahí.

Ejercicio 2. (a) Las reseñas se separan: crecen sin límite (un festival puede acumular miles), no se necesitan para renderizar el catálogo, se paginan y se ordenan por fecha, y se moderan con ciclo de vida propio. (b) El plano de butacas se incrusta en la sala (o se referencia como catálogo aparte si varias salas comparten plantilla), porque es de tamaño acotado, cambia casi nunca y siempre se lee junto con la sala. Ojo: la ocupación de cada butaca en una sesión concreta sí es volátil y de alta escritura, así que ese estado no debe vivir en el plano estático.

Ejercicio 3. (1) vendidas: fuerte, es la definición misma del problema de sobreventa. (3) Estado del pedido: fuerte, decide si se cobra y si se emiten entradas; una lectura obsoleta puede duplicar un cobro. (2) Visitas: eventual, un error de un 2 % durante unos segundos no perjudica a nadie y a cambio permite contar en memoria y volcar por lotes. (4) Recomendaciones: eventual, se calculan en diferido y nadie nota que llevan una hora de retraso.

Hemos cerrado la etapa del fichero. Sabes ahora, con nombres concretos, qué le falta a datos/eventos.json: atomicidad, concurrencia, consultas, índices, integridad, historial y acceso multiproceso. Sabes qué te da un SGBD a cambio, qué separa al modelo relacional del documental sin necesidad de tomar partido, y por qué un aforo pertenece al territorio de las garantías fuertes según ACID y CAP. Has visto el panorama real de motores para Node y el compromiso entre bajar al controlador nativo o apoyarte en un ORM/ODM. Y, sobre todo, tienes el modelo de datos de Escena Viva decidido y razonado: Evento con sus sesiones incrustadas, Pedido, Entrada y Usuario como colecciones separadas, con el contador vendidas desnormalizado a propósito.

También tienes la pieza de arquitectura que sostiene todo el módulo: src/repositorios/, la frontera que impedirá que el motor de base de datos se filtre a los controladores y al dominio.

En la lección siguiente bajamos al código. Conectaremos con MongoDB desde src/config/index.js, escribiremos src/db/conexion.js con su apertura al arrancar y su cierre en el apagado ordenado que ya existe en src/servidor.js, y traduciremos este diagrama a esquemas y modelos de Mongoose en src/modelos/: tipos, validadores, virtuals, middleware de esquema e índices. El plano se convierte en estructura.