Cuando el enunciado pide "construir y desplegar una app con una base NoSQL
distinta de Redis, MongoDB, Neo4j y Prometheus", la decisión que más pesa no
es el lenguaje ni el framework: es cómo se modelan los datos. Con Cassandra
esa decisión se toma antes de escribir la primera línea de código, porque el
modelo no se descubre consultando: se diseña a partir de las consultas que la
aplicación va a hacer.
Este artículo cuenta esa decisión, el código que salió de ella y lo que
todavía queda pendiente.
Por qué Cassandra y no otro motor
Cassandra es una base columnar distribuida pensada para escritura intensiva y
alta disponibilidad: no tiene un nodo maestro, replica entre nodos y no
necesita un esquema rígido como el de una base relacional. A cambio impone una
restricción dura: toda consulta tiene que filtrar por la clave de
partición. Si no lo hace, o no devuelve resultados o hay que recurrir a
ALLOW FILTERING, que recorre todas las particiones y es exactamente lo que
hay que evitar en producción.
Eso significa que en Cassandra no se modela "la entidad", se modela "la
pregunta". La nuestra era concreta: listar los productos de una categoría.
El modelo: una tabla, dos claves
CREATE KEYSPACE IF NOT EXISTS inventario WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1}; CREATE TABLE IF NOT EXISTS inventario.productos_por_categoria ( categoria text, id uuid, nombre text, precio decimal, stock int, actualizado timestamp, PRIMARY KEY ((categoria), id) ); La clave primaria tiene dos partes y ninguna es decorativa:
-
categoriaes la partition key. Todos los productos de una categoría viven en la misma partición y en el mismo nodo. Listarlaptopses una lectura de una sola partición, sin coordinación entre nodos. -
ides la clustering key. Dentro de la partición, los productos quedan ordenados por ese UUID, lo que permite recorrer el rango sin ordenar en memoria.
Con ese modelo, la consulta de la aplicación es una sola línea y no necesita
ALLOW FILTERING:
SELECT * FROM productos_por_categoria WHERE categoria = ?; Si hubiéramos modelado "producto" con id como clave y categoria como
columna normal, esa misma consulta habría exigido ALLOW FILTERING o una
tabla secundaria. Esa es la trampa típica al llegar de SQL: la consulta que en
PostgreSQL es trivial, en Cassandra obliga a rediseñar la tabla.
La API
La aplicación es un servicio Node.js 20 con Express y el driver oficial
cassandra-driver. Cuatro rutas, todas con sentencias preparadas:
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /health | Ejecuta SELECT now() FROM system.local contra el motor |
| GET | /productos/:categoria | Lista una partición completa |
| PUT | /productos/:categoria/:id | Inserta o actualiza (upsert) |
| DELETE | /productos/:categoria/:id | Elimina un producto de la partición |
Dos detalles del código que vale la pena señalar:
El health no miente. No devuelve ok porque el proceso esté vivo:
ejecuta una consulta real contra Cassandra y solo responde 200 si el motor
contestó. Un health que no toca la base es un health que siempre está verde,
incluso cuando la base está caída.
app.get("/health", async (_req, res) => { try { await client.execute("SELECT now() FROM system.local"); res.json({ status: "ok", db: "cassandra" }); } catch (e) { res.status(500).json({ status: "error", message: e.message }); } }); PUT en lugar de POST no es un capricho. En Cassandra INSERT es un
upsert: si la fila existe, la sobrescribe; si no, la crea. Modelar la ruta
como PUT /productos/:categoria/:id refleja esa semántica en vez de fingir
que hay una creación con identidad generada por el servidor.
await client.execute( `INSERT INTO ${TABLE} (categoria, id, nombre, precio, stock, actualizado) VALUES (?, ?, ?, ?, ?, toTimestamp(now()))`, [categoria, cassandra.types.Uuid.fromString(id), nombre, precio, stock], { prepare: true } ); La automatización: Cassandra de verdad en cada push
El punto donde muchas entregas hacen trampa es la integración continua: se
prueba con un simulacro y se presenta como si se hubiera probado contra el
motor. Aquí el workflow levanta Cassandra 5 real como contenedor, espera a que
responda, aplica el esquema, siembra datos y recién ahí ejecuta la API:
- name: Levantar Cassandra run: | docker run -d --name cassandra -p 9042:9042 cassandra:5 for i in $(seq 1 40); do if docker exec cassandra cqlsh -e "describe keyspaces" >/dev/null 2>&1; then break; fi sleep 10 done - name: Crear esquema run: docker exec -i cassandra cqlsh < db/schema.cql && docker exec -i cassandra cqlsh < db/seed.cql - name: Arrancar API y probar run: | node src/server.js & sleep 8 curl -sf http://localhost:3000/health curl -sf http://localhost:3000/productos/laptops El bucle de espera no es relleno: Cassandra tarda en aceptar CQL después de
arrancar, y un sleep fijo habría hecho el workflow inestable. El curl -sf
falla el job si la ruta no responde 2xx, así que un modelo roto se ve en el
CI y no en la exposición.
Además de las pruebas, hay dos workflows más: uno construye la imagen
multi-etapa y la publica en GitHub Container Registry, y otro dispara el
despliegue con un webhook.
Lo que falta y por qué lo digo
La actividad pide publicar en una nube o SaaS público. Hoy el repositorio, el
CI y la imagen están listos, pero el servicio no está desplegado: el
workflow de despliegue necesita un webhook de la plataforma y credenciales de
un Cassandra gestionado (Astra DB), y sin esas credenciales el /health
respondería 500 desde el primer segundo. Publicar una URL que no conecta no
es desplegar; es maquillar el estado.
El camino está documentado en el README: crear una base Astra DB serverless,
descargar el Secure Connect Bundle, aplicar db/schema.cql en su consola y
levantar la imagen publicada con esas variables de entorno. Es el paso que
queda pendiente y el único que separa esta entrega de estar completa.
Lo que me llevo
- En Cassandra el modelo se deriva de las consultas, no de las entidades. Si la tabla no responde la pregunta con la partition key, la tabla está mal.
-
ALLOW FILTERINGes una señal de alarma de diseño, no una optimización. - Un
healthque no consulta la base no informa nada. - Probar contra el motor real en CI cuesta minutos y evita exponer un modelo que solo funciona en la máquina de quien lo escribió.
Enlaces
- Repositorio: https://github.com/dejameingresar/inventario-cassandra
- Esquema:
db/schema.cql - Workflows:
.github/workflows/ci.yml,build-image.yml,deploy.yml
