Tamaño de letra
Tema
Ancho de lectura
Tipografía

Apuntes · Capítulo 9Datos y sistemas distribuidos

Los datos como decisión de arquitectura

Los datos como decisión de arquitectura

Ruta de lectura.

  • Antes de clase (obligatorio, unos 20 minutos): de Por qué los datos son lo que más cuesta cambiar, todo; de Transaccional y analítico, Dos formas de usar los mismos datos y El reporte compite con la venta; de Por qué la evolución es un problema de arquitectura, Versiones que conviven y Hacia atrás y hacia adelante; y de Expandir, migrar y contraer, El ejemplo: cambiar el nombre de una columna.
  • En clase: Sesión A: Por qué los datos son lo que más cuesta cambiar, Transaccional y analítico, Sistema de registro y datos derivados, Un nodo o muchos, Servicio administrado o propio y La escalabilidad es una pregunta. Sesión B: El modelo de datos decide qué preguntas son fáciles, Por qué la evolución es un problema de arquitectura, Formatos, Evolucionar una API y Expandir, migrar y contraer. Laboratorio: Laboratorio: cambiar un contrato sin romper a quien lo usa.
  • Después de clase: el Resumen y los Ejercicios. Antes de avanzar con P3 vale la pena releer Las tres fases y sus condiciones, Migrar los datos sin detener a nadie y Cuándo contraer. Opcionales: Grafos y clave-valor, Binarios con esquema: etiquetas en vez de nombres, La cola de locks y El código de la semana.

La primera mitad del curso trató sobre código: cómo se parte en módulos, qué puede depender de qué, en cuántas unidades se despliega y cómo se decide todo eso con escenarios de calidad en la mano. En casi todos los ejemplos había una base de datos, y casi siempre la tratamos como una caja al final del diagrama: el lugar donde las cosas se guardan.

La segunda mitad abre esa caja. La razón es práctica. Los problemas que Tinkuy mostró en la primera mitad (el catálogo que se vuelve lento durante una venta, el asiento que se vende cincuenta veces, la compra que queda cobrada y sin entrada) no se arreglan moviendo código de un módulo a otro. Se arreglan decidiendo dónde viven los datos, cuántas copias hay, quién puede escribirlos y qué se promete sobre ellos. Esas son las decisiones de las semanas 9 a 13.

Este capítulo pone el vocabulario y las preguntas. En la primera sesión vemos por qué los datos son la parte de una arquitectura que más cuesta cambiar, y los trade-offs que aparecen en todo sistema que guarda algo: transaccional o analítico, sistema de registro o dato derivado, un nodo o muchos, servicio administrado o propio. En la segunda vemos cómo se elige un modelo de datos, y después el problema que ocupa el laboratorio y una parte de P3: cómo se cambia un esquema o un contrato que otros ya usan, sin detener nada y sin romper a nadie. La respuesta tiene nombre, expandir, migrar y contraer, y la vamos a recorrer con un ejemplo completo.

Una advertencia sobre las palabras, la misma de la semana 5. En Tinkuy un evento es un concierto o un partido. En este capítulo casi no hablamos de mensajes, así que cuando aparece la palabra es en ese sentido: un evento de Tinkuy.

Lectura. Sesión A: Kleppmann y Riccomini, Designing Data-Intensive Applications (2.ª ed.), cap. 1 Trade-Offs in Data Systems Architecture y cap. 2 Defining Nonfunctional Requirements (el caso de las líneas de tiempo de una red social y la sección Scalability); Martin Kleppmann, apuntes del curso Concurrent and Distributed Systems de Cambridge, sección 1, Introduction. Complementarias: Martin Fowler, PolyglotPersistence; Software Architecture in Practice, cap. 17 The Cloud and Distributed Computing.

Sesión B: Designing Data-Intensive Applications (2.ª ed.), cap. 3 Data Models and Query Languages (las secciones sobre el modelo relacional y el de documentos) y cap. 5 Encoding and Evolution; Danilo Sato, ParallelChange (expandir y contraer), y Martin Fowler, TolerantReader. Complementarias: Designing Data-Intensive Applications (2.ª ed.), cap. 4 Storage and Retrieval; Hyrum’s Law; Protocol Buffers, Language Guide, la sección sobre cómo actualizar un tipo de mensaje.

El código de este capítulo está en code/week-09/. Todas las salidas que se muestran son de ejecuciones reales en el contenedor del curso, en una laptop con Apple Silicon, dentro de Docker. Los números cambian de una máquina a otra y de una corrida a otra; lo que se traslada es la comparación entre dos diseños medidos en la misma.

Por qué los datos son lo que más cuesta cambiar

El código se reemplaza; los datos se quedan

Piensen en lo que hace falta para poner en producción una versión nueva del servidor de Tinkuy. Se levanta un proceso con el código nuevo, se le empieza a enviar tráfico y se apaga el proceso anterior. Si la versión nueva tiene un error, se hace lo contrario. El proceso no recuerda nada entre una petición y la siguiente, así que cualquier copia suya vale lo mismo que otra: se puede reemplazar, se puede duplicar para atender más carga y se puede matar sin perder nada. A eso se le llama un servicio sin estado, y la semana 11 le dedica una sesión.

Con los datos, ninguna de esas tres cosas es cierta:

  • No se reemplazan. La base de datos de la versión nueva tiene que ser la misma que la de la versión anterior, con todo lo que se vendió hasta ayer. Un cambio en el código se revierte volviendo al código anterior; un cambio que ya transformó las filas de una tabla no se revierte desplegando nada.
  • No se copian gratis. Una segunda copia del proceso es idéntica a la primera desde que arranca. Una segunda copia de los datos empieza a diferenciarse de la primera con la siguiente escritura, y mantenerlas de acuerdo es un problema con nombre propio: replicación, la semana que viene.
  • No se pierden sin consecuencias. Si un proceso muere a mitad de una petición, alguien recibe un error y reintenta. Si se pierde la tabla de órdenes, se perdió el negocio.

Hay una cuarta diferencia, que es la que más pesa en la segunda sesión: los datos viven más que el código que los escribió. Una orden guardada en 2024 la escribió una versión del servidor que ya nadie recuerda, y el servidor de hoy tiene que poder leerla. El código de hace dos años se puede borrar; sus datos no.

Idea clave. Las decisiones sobre dónde viven los datos, cuántas copias hay y quién puede escribirlos son las que más cuesta deshacer. Por eso se toman con más cuidado, y más tarde, que las decisiones sobre el código: una frontera entre módulos mal puesta se corrige con un refactoring; una frontera entre bases de datos mal puesta se corrige con una migración.

Esto ya apareció una vez en el curso, sin este nombre. En la semana 5, lo que hacía caro pasar de un monolito a microservicios no era partir el código, sino partir la base de datos: cada servicio es owner de sus datos, y lo que antes era un JOIN y una transacción pasa a ser una llamada por la red y un protocolo.

Sistemas intensivos en datos

Un sistema es intensivo en datos cuando su dificultad está en los datos: en cuántos son, en lo complejos que son o en lo rápido que cambian. Lo contrario es un sistema intensivo en cómputo, cuya dificultad está en el procesador: simular el clima o entrenar un modelo. Casi todos los sistemas que van a construir en su vida profesional son del primer tipo. Tinkuy lo es: no calcula nada difícil. Su problema es que muchas personas quieren leer y cambiar los mismos datos a la vez.

Un sistema así casi nunca se escribe desde cero. Se arma con piezas estándar, cada una buena para una cosa:

Pieza Para qué sirve En el contenedor del curso
Base de datos Guardar los datos y volver a encontrarlos PostgreSQL
Cache Recordar el resultado de algo caro Redis
Índice de búsqueda Encontrar por palabras o por filtros (no se usa)
Cola o log de mensajes Pasar trabajo a otro proceso, para después NATS JetStream
Proceso por lotes Recorrer muchos datos cada cierto tiempo un script con node

Ninguna de las piezas es el problema de arquitectura. El problema es lo que pasa entre ellas. PostgreSQL promete que una transacción ocurre completa o no ocurre. Redis promete responder rápido. En cuanto un dato está en los dos, la pregunta es qué se le promete a quien lo lee: ¿el valor de PostgreSQL, el de Redis, cualquiera de los dos? La arquitectura de un sistema de datos es cómo se combinan las piezas y qué garantías sobreviven a la combinación. Las semanas que siguen son, cada una, una combinación con su garantía: varias copias de una base de datos (semana 10), una base de datos y una cache (semana 11), una base de datos y un servicio externo (semana 12), una base de datos y un log de mensajes (semana 13).

Transaccional y analítico

Dos formas de usar los mismos datos

A una tabla de órdenes se le hacen dos clases de preguntas, tan distintas que tienen nombres propios.

La primera clase: ¿existe la orden 150 000?, ¿de quién es?, registra esta orden nueva. Son operaciones pequeñas, que encuentran unas pocas filas por su clave, y las hace una persona que está esperando la respuesta frente a una pantalla. A esta forma de uso se le llama transaccional, u OLTP (online transaction processing). Lo que importa es que cada operación sea rápida y exacta: la latencia de cada una, y que nadie vea una orden a medio escribir.

La segunda clase: ¿cuánto se vendió en marzo?, ¿quiénes son los cinco compradores que más gastaron? Son pocas consultas, cada una recorre una parte grande de la tabla, y quien las hace es un analista o un proceso que corre de madrugada. A esta forma de uso se le llama analítica, u OLAP (online analytical processing). Lo que importa es cuántos datos se procesan por segundo, el throughput, y no si una consulta tarda 300 ms o 3 s.

Transaccional (OLTP) Analítico (OLAP)
Quién pregunta Un usuario, a través de la aplicación Un analista o un proceso por lotes
Qué lee Unas pocas filas, por clave Millones de filas, casi todas
Qué escribe Filas sueltas, todo el tiempo Cargas grandes, cada cierto tiempo
Cuántas consultas Muchas por segundo Pocas por hora
Qué se mide Latencia de cada operación (p95, p99) Throughput; duración del reporte
Qué datos El estado de ahora La historia

La diferencia se ve en el plan de ejecución. La base de datos de la semana, arq_w09, tiene una tabla orders con 300 000 filas. Esta es una lectura transaccional, una orden por su id:

arq_w09=# EXPLAIN (ANALYZE, BUFFERS, COSTS OFF, TIMING OFF)
          SELECT id, buyer_email, total_cents, status FROM orders WHERE id = 150000;
 Index Scan using orders_pkey on orders (actual rows=1.00 loops=1)
   Index Cond: (id = 150000)
   Index Searches: 1
   Buffers: shared hit=4
 …
 Execution Time: 0.147 ms

Cuatro páginas de 8 kB: las del índice, de la raíz a la hoja, y la página donde está la fila. Y esta es una lectura analítica, los cinco compradores que más gastaron:

arq_w09=# EXPLAIN (ANALYZE, BUFFERS, COSTS OFF, TIMING OFF)
          SELECT buyer_email, count(*) AS orders, sum(total_cents) AS total_cents
            FROM orders WHERE status = 'paid'
           GROUP BY buyer_email ORDER BY sum(total_cents) DESC LIMIT 5;
 Limit (actual rows=5.00 loops=1)
   Buffers: shared hit=3478
         …
               ->  Gather (actual rows=15000.00 loops=1)
                     Workers Launched: 2
                     …
                           ->  Parallel Seq Scan on orders (actual rows=95652.33 loops=3)
                                 Filter: (status = 'paid'::text)
 …
 Execution Time: 79.445 ms

3 478 páginas en vez de 4: la tabla entera (pg_table_size dice que ocupa 27 MB), leída por tres procesos a la vez, el que atiende la consulta y dos ayudantes (Workers Launched: 2). No hay índice que evite ese recorrido, porque la pregunta es sobre todas las filas. Una sola de estas consultas ocupa tres núcleos durante todo el tiempo que dura.

El reporte compite con la venta

Si las dos clases de consulta corren en la misma base de datos, comparten todo lo que la base de datos tiene: procesador, memoria, disco y conexiones. tools/oltp-vs-olap.ts lo mide. Ocho sesiones hacen lecturas por id, una detrás de otra, durante cinco segundos. Después hacen lo mismo mientras otras cuarenta sesiones repiten el reporte de arriba. Y al final otra vez solas, para comprobar que el efecto se va cuando se van los reportes:

$ make oltp-olap
arq_w09: 300000 órdenes; 8 sesiones leen una orden por id durante 5 s.

solo lecturas por id                 19973 lecturas/s   p50    0.31 ms   p95    0.93 ms   p99    1.94 ms
con 40 sesiones de reportes           2983 lecturas/s   p50    0.82 ms   p95    9.79 ms   p99   22.37 ms   (401 reportes, mediana 473 ms)
solo lecturas por id, otra vez       13361 lecturas/s   p50    0.35 ms   p95    1.83 ms   p99    4.03 ms

Las mismas lecturas, sobre los mismos datos, con el mismo índice. Lo único que cambió es quién más estaba usando la base de datos. El throughput de las lecturas cayó a menos de la sexta parte, y el p99 se multiplicó por más de diez. Repetimos la medición tres veces: en las tres el throughput con reportes quedó entre 1 500 y 3 000 lecturas por segundo, contra 12 000 a 20 000 sin ellos, y el p99 entre 22 y 56 ms, contra 2 a 5 ms. La máquina donde se midió estaba ocupada con otras cosas, y por eso los valores absolutos se mueven tanto; la caída no desapareció en ninguna corrida.

Miren también lo que casi no cambió: el p50 pasó de 0,31 ms a 0,82 ms. La mitad de las lecturas apenas se enteró. Es el mismo fenómeno de la semana 2: cuando un recurso se satura, la mediana lo disimula y la cola de la distribución lo muestra. Quien mire solo el promedio de este servicio va a decir que el reporte no molesta.

Tres filas, una por cada tramo de la medición de make oltp-olap, con dos paneles. A la izquierda, barras con las lecturas por segundo: 19 973 con solo lecturas por id, 2 983 con 40 sesiones de reportes (401 reportes, mediana 473 ms) y 13 361 otra vez solas. A la derecha, el p50, el p95 y el p99 de una lectura sobre un eje logarítmico de 0,1 ms a 100 ms: solas, 0,31, 0,93 y 1,94 ms; con reportes, 0,82, 9,79 y 22,37 ms; otra vez solas, 0,35, 1,83 y 4,03 ms. Con reportes el punto del p50 casi no se mueve y los del p95 y el p99 se van una década a la derechaTres filas, una por cada tramo de la medición de make oltp-olap, con dos paneles. A la izquierda, barras con las lecturas por segundo: 19 973 con solo lecturas por id, 2 983 con 40 sesiones de reportes (401 reportes, mediana 473 ms) y 13 361 otra vez solas. A la derecha, el p50, el p95 y el p99 de una lectura sobre un eje logarítmico de 0,1 ms a 100 ms: solas, 0,31, 0,93 y 1,94 ms; con reportes, 0,82, 9,79 y 22,37 ms; otra vez solas, 0,35, 1,83 y 4,03 ms. Con reportes el punto del p50 casi no se mueve y los del p95 y el p99 se van una década a la derecha
La medición de arriba, dibujada. Con los reportes corriendo, el throughput cae a menos de la sexta parte y la cola de la distribución se aleja, mientras el p50 casi no se mueve.

Hay que decir bajo qué condición aparece el efecto. Cuarenta sesiones de reportes, cada una con hasta tres procesos, son más procesos que los 14 núcleos del contenedor: el procesador está saturado. Con una sola sesión de reportes (ANALYTIC=1 make oltp-olap), la diferencia queda dentro de lo que la medición varía sola de una corrida a otra. La conclusión no es “un reporte arruina la base de datos”, sino esta: las dos cargas compiten por el mismo recurso, y la analítica no tiene un tamaño fijo. El día en que el reporte del mes coincide con la apertura de una venta, quien espera es el comprador.

En Tinkuy. GET /reports/sales recorre las órdenes, las entradas y los asientos de un evento con varios JOIN, en la misma base de datos que atiende POST /orders. Y el organizador de un concierto abre su reporte justamente cuando la venta está en su pico, porque es cuando le interesa.

Separarlos: de menos a más costo

Hay tres respuestas habituales. Van en orden de costo, y la regla es no pasar a la siguiente mientras la anterior alcance.

No separar, y acotar. Si los reportes son pocos y se pueden programar, corren de madrugada, con un tope de tiempo (statement_timeout) y sin procesos ayudantes. No cuesta nada y funciona mientras el negocio acepte que el reporte no es en vivo. Deja de funcionar cuando alguien necesita el reporte durante la venta.

Una réplica para las lecturas pesadas. Una segunda copia de la base de datos, que recibe los cambios de la principal y solo atiende lecturas. Los reportes van a la réplica y dejan de competir con las ventas. Se paga una máquina más, y se acepta algo nuevo: la réplica va un poco atrasada, así que el reporte puede no incluir la venta de hace un segundo. Es el tema de la semana 10, y la primera mitad de P3.

Un data warehouse. Una base de datos distinta, pensada para consultas analíticas, a la que los datos llegan copiados: por lotes (cada noche) o por streams (a medida que ocurren). Aquí la separación es completa: otro motor, otro esquema (organizado para preguntar, no para vender), y la historia de varios sistemas en un solo lugar. Los motores analíticos guardan los datos de otra manera, por columnas en vez de por filas, porque un reporte lee tres columnas de millones de filas y no las veinte columnas de una. Se paga un sistema más que operar, un proceso de carga que puede fallar, y un retraso que ya no es de un segundo sino del tiempo entre cargas.

Trade-off. Cada paso compra aislamiento entre las dos cargas y lo paga con frescura de los datos y con operación. Una réplica atrasa el reporte segundos y agrega una máquina. Un data warehouse lo atrasa minutos u horas y agrega un sistema entero con su proceso de carga. La pregunta que decide no es técnica: ¿qué tan viejo puede ser el dato que ve quien lee el reporte?

Sistema de registro y datos derivados

En cuanto un sistema tiene más de un lugar donde guardar datos, el mismo dato empieza a estar en varios. La orden está en PostgreSQL, su resumen en una cache, su total en el reporte del mes. Para no perderse, cada dato se clasifica en uno de dos grupos.

El sistema de registro (system of record) de un dato es el lugar donde ese dato se escribe primero y donde está su versión oficial. Si dos lugares no coinciden, el sistema de registro tiene la razón por definición. Para cada dato hay uno solo.

Un dato derivado es el resultado de tomar datos de otro lugar y transformarlos: una cache, un índice de búsqueda, una vista materializada, un reporte, una tabla de totales. Su propiedad esencial es que se puede reconstruir: si se pierde, se vuelve a calcular a partir del sistema de registro. Lo que se pierde es tiempo, no información.

Dato Clase Si se pierde
La tabla de órdenes Sistema de registro No hay de dónde recuperarla, salvo un respaldo. Se pierden ventas
La cache del catálogo Derivado Las lecturas se vuelven lentas hasta que se llena otra vez
El índice de búsqueda Derivado No se puede buscar mientras se reconstruye; puede tardar horas
El reporte de ventas del mes Derivado Se vuelve a correr
Diagrama con tres columnas. A la izquierda, la aplicación, con una flecha que dice escribe, primero aquí, hacia el centro. Al centro, el sistema de registro: PostgreSQL, la tabla de órdenes, la versión oficial; debajo dice que si se pierde se pierden ventas y solo queda un respaldo. A la derecha, tres datos derivados, cada uno con una flecha punteada que sale del sistema de registro: la cache del catálogo (si se pierde, lecturas lentas hasta que se llena), el índice de búsqueda (sin búsqueda hasta reconstruirlo) y el reporte de ventas del mes (se vuelve a correr); una nota dice que se calculan a partir del registro y se pueden reconstruir. Abajo, una flecha punteada roja va de la aplicación directo a un derivado, tachada con una cruz: error común, escribir en un derivado; deja de poderse reconstruirDiagrama con tres columnas. A la izquierda, la aplicación, con una flecha que dice escribe, primero aquí, hacia el centro. Al centro, el sistema de registro: PostgreSQL, la tabla de órdenes, la versión oficial; debajo dice que si se pierde se pierden ventas y solo queda un respaldo. A la derecha, tres datos derivados, cada uno con una flecha punteada que sale del sistema de registro: la cache del catálogo (si se pierde, lecturas lentas hasta que se llena), el índice de búsqueda (sin búsqueda hasta reconstruirlo) y el reporte de ventas del mes (se vuelve a correr); una nota dice que se calculan a partir del registro y se pueden reconstruir. Abajo, una flecha punteada roja va de la aplicación directo a un derivado, tachada con una cruz: error común, escribir en un derivado; deja de poderse reconstruir
Las escrituras entran por un solo lugar y los derivados se alimentan de él. Un derivado en el que alguien escribe directamente deja de ser reconstruible.

Saber cuál es cuál decide varias cosas a la vez: qué se respalda y con qué cuidado, qué se puede guardar en un sistema que pierde datos al reiniciarse (el Redis del contenedor arranca sin persistencia: sirve para una cache, no para las órdenes), y a quién se le cree cuando dos copias no coinciden.

Error común. Tratar un dato derivado como si fuera el oficial. Pasa sin que nadie lo decida: alguien corrige un total directamente en la tabla del reporte, o un servicio empieza a leer el saldo de la cache porque es más rápido, y un día escribe ahí. Desde ese momento el dato “derivado” ya no se puede reconstruir, porque contiene información que no está en ningún otro lugar, y nadie lo respalda porque todos creen que es una cache.

Que un dato sea derivado no quiere decir que sea barato perderlo. “Se puede reconstruir” tiene un tiempo, y ese tiempo es parte del diseño. Si reconstruir el índice de búsqueda tarda seis horas y el sitio no sirve sin búsqueda, ese índice necesita casi el mismo cuidado que el sistema de registro, aunque por otra razón: disponibilidad, no durabilidad.

Un nodo o muchos

Tres razones para distribuir los datos

Hasta aquí todo cabe en una máquina. Un nodo es una máquina que participa en un sistema de datos, y la pregunta de esta sección es cuándo conviene que los datos estén en más de uno. En la semana 5 vimos las razones para distribuir el código; para los datos son tres, y cada una es un escenario.

  • Tolerar la falla de una máquina. Si los datos están en un solo nodo y ese nodo se cae, el sistema se detiene; si su disco se daña, además se pierden datos. Con una copia en otro nodo, el sistema puede seguir. Es un escenario de disponibilidad.
  • Escalar más allá de una máquina. Si la carga o el volumen no caben en el nodo más grande que se puede pagar, hay que repartir: las lecturas entre varias copias (replicación, semana 10) o los datos mismos entre varios nodos (sharding, semana 11). Es un escenario de rendimiento.
  • Acercar los datos a los usuarios. Una petición de Lima a un centro de datos en Virginia paga decenas de milisegundos de ida y vuelta antes de que la base de datos haga nada. Una copia cerca del usuario elimina ese tiempo para las lecturas. Es un escenario de latencia.

Lo que cuesta

Las falacias de la semana 5 valen aquí sin cambios, y con los datos duelen más, porque un dato mal escrito se queda mal escrito. Cuatro costos que no existen en un solo nodo:

  • Fallas parciales. En un nodo, la base de datos funciona o no funciona. Con varios, una parte funciona y otra no, y la parte que funciona muchas veces no puede saber qué le pasó a la otra: si un nodo no responde, puede estar caído, puede estar lento, o puede haber respondido y que la respuesta se haya perdido. Los apuntes de Kleppmann para Cambridge empiezan el curso por aquí: distintas computadoras solo se comunican enviándose mensajes por una red, y eso lo cambia todo.
  • Retraso de replicación. Una copia no recibe los cambios en el mismo instante en que ocurren. Quien lee de la copia puede ver el pasado: compra una entrada, recarga la página, y la compra no aparece.
  • Relojes que no coinciden. Cada máquina tiene su reloj, y dos relojes nunca marcan exactamente lo mismo. “La escritura más reciente” deja de tener una respuesta evidente cuando las dos escrituras ocurrieron en nodos distintos.
  • Lo que era una transacción pasa a ser un protocolo. En un nodo, BEGIN y COMMIT garantizan que dos escrituras ocurren juntas. Entre dos nodos no hay un COMMIT que cubra a ambos: hay mensajes, y un procedimiento para decidir qué hacer cuando uno de los mensajes no llega. La semana 12 es sobre eso.

Cuánto aguanta una sola máquina

Contra esos costos hay que poner un dato que se suele subestimar: una sola máquina aguanta mucho. En la medición de la sección anterior, un PostgreSQL sin ajustar, dentro de un contenedor en una laptop que además estaba ocupada, respondió entre 12 000 y 20 000 lecturas por clave por segundo con ocho sesiones (y más de 50 000 en un momento en que la laptop estaba más libre). No es una medición de capacidad (para eso habría que variar la concurrencia y medir escrituras), pero da el orden de magnitud. La prueba de carga de la venta en Tinkuy, make load-sale, usa 200 compradores a la vez: está muy por debajo.

Y una sola máquina es más simple de razonar: tiene un reloj, las transacciones funcionan, no hay retraso de replicación porque no hay réplica, y cuando falla, falla entera.

Trade-off. Un solo nodo da transacciones, un solo reloj y un modelo de fallas simple, y cobra un techo de capacidad y un punto único de falla. Varios nodos quitan ese techo y ese punto único, y cobran fallas parciales, datos atrasados y protocolos en lugar de transacciones. El primer nodo extra casi siempre se justifica por disponibilidad (una copia para no perder los datos), no por carga.

Servicio administrado o propio

La base de datos se puede operar o se puede alquilar. Propio quiere decir que el equipo instala PostgreSQL en sus máquinas, lo configura, lo actualiza, lo respalda, prueba que los respaldos sirven y se levanta de madrugada cuando se llena el disco. Administrado quiere decir que un proveedor hace todo eso y entrega una dirección a la cual conectarse.

Parece una decisión de compras, y es de arquitectura por dos razones.

La primera: fija qué garantías se pueden pedir. Un servicio administrado ofrece un menú. Si el menú dice que el failover tarda hasta dos minutos, ese es el piso del escenario de disponibilidad, y ningún diseño del equipo lo va a mejorar. Si no permite cierta extensión, cierta versión o cierto parámetro, el diseño tiene que funcionar sin eso. A cambio, el menú trae cosas que al equipo le costaría meses hacer bien: réplicas, respaldos continuos, recuperación a un instante dado.

La segunda: fija cuánto cuesta salir. Cuanto más propio del proveedor es lo que se usa, más cara es la mudanza. Un PostgreSQL administrado se puede llevar a otro proveedor o a máquinas propias con un dump y una ventana de mantenimiento, porque del otro lado hay otro PostgreSQL. Una base de datos que solo existe en un proveedor no tiene otro lado: salir es reescribir el acceso a datos.

Administrado Propio
Quién opera (respaldos, parches, failover) El proveedor El equipo
Qué se paga Dinero, cada mes, creciente con el uso Tiempo de personas que sepan hacerlo
Control (versión, parámetros, extensiones) El que el menú permita Todo
Garantías Las del contrato del proveedor Las que el equipo logre construir
Salir Fácil si es un motor estándar; muy caro si no No hay de dónde salir

Trade-off. Con un servicio administrado se paga para no operar, y se entrega control y portabilidad. Conviene cuando el equipo es pequeño y operar una base de datos no es lo que lo distingue, que es casi siempre. Deja de convenir cuando la cuenta crece más rápido que el negocio, cuando se necesita algo que el menú no trae, o cuando una regulación exige que los datos estén en un lugar que el proveedor no ofrece.

La pregunta de la semana 5 vuelve con otra forma. Allí era ¿el equipo puede operar esto? Aquí es ¿el equipo quiere que operar esto sea su trabajo?

La escalabilidad es una pregunta

Describir la carga

“El sistema es escalable” no dice nada, igual que “el sistema es rápido” no decía nada en la semana 2. La escalabilidad no es una propiedad que un sistema tiene o no tiene. Es la respuesta a una pregunta con esta forma: si la carga crece de esta manera, ¿qué opciones hay para seguir cumpliendo, y cuánto cuesta cada una?

Para hacer la pregunta, primero hay que describir la carga, con números. Los parámetros de carga dependen del sistema, pero casi siempre incluyen:

  • lecturas por segundo y escrituras por segundo;
  • la proporción entre unas y otras;
  • el tamaño de los datos, y cuánto crece;
  • la forma en que llega: pareja, o en picos;
  • el caso extremo: el usuario, el producto o la clave que concentra la carga.

Para Tinkuy, con lo que sabemos desde la semana 2:

Parámetro Valor De dónde sale
Lecturas por cada escritura Miles de visitas al catálogo por cada compra Mirar es gratis; comprar no
Forma de las escrituras Casi nada, y un pico el minuto en que abre una venta Todos quieren el mismo asiento a la misma hora
Tamaño Unos 13 000 asientos y 1 300 órdenes La semilla de make db
Caso extremo Un solo evento concentra casi todas las escrituras del pico El evento 1

Dos sistemas con el mismo total de peticiones por segundo pueden necesitar arquitecturas opuestas. Uno con mil lecturas por cada escritura se resuelve con copias para leer (réplicas, cache). Uno con mil escrituras por cada lectura no gana nada con eso, porque todas las copias tienen que recibir todas las escrituras. Y un sistema cuya carga se concentra en una clave no se arregla repartiendo las claves entre máquinas, porque esa clave sigue cayendo entera en una sola. Por eso el caso extremo va en la lista.

Calcular al leer o al escribir: las líneas de tiempo

El capítulo 2 del libro desarrolla un caso que se volvió clásico: la línea de tiempo de una red social. Lo vamos a reconstruir en pequeño, con nuestros propios datos y nuestras propias mediciones, porque es la forma más clara de ver una decisión que aparece en todos los sistemas de datos.

El problema: cada usuario sigue a otros, y al abrir la aplicación quiere ver las veinte publicaciones más recientes de las cuentas que sigue. Hay dos operaciones, publicar y leer la línea de tiempo, y dos maneras de repartir el trabajo entre ellas.

Calcular al leer. Publicar guarda una fila. Leer busca a quiénes sigue el usuario, trae las publicaciones de todos ellos, las ordena y se queda con veinte. Las dos versiones están en timeline/timeline.ts; esta es la consulta de la primera:

SELECT p.id AS post_id, p.created_at
  FROM tl_follows f JOIN tl_posts p ON p.author_id = f.followee_id
 WHERE f.follower_id = $1
 ORDER BY p.created_at DESC, p.id DESC
 LIMIT 20

Calcular al escribir. Cada usuario tiene su línea de tiempo ya armada, en la tabla tl_home. Publicar guarda la publicación y, además, agrega una fila a la línea de tiempo de cada seguidor. Leer es recorrer veinte entradas de un índice. A repartir una escritura entre muchos destinatarios se le dice fan-out:

-- En la misma transacción que guarda la publicación $3 del autor $1:
INSERT INTO tl_home (user_id, created_at, post_id)
SELECT follower_id, $2, $3 FROM tl_follows WHERE followee_id = $1

El costo de cada diseño se puede escribir antes de medir nada. Si un usuario sigue a ss cuentas y cada una tiene pp publicaciones recientes, calcular al leer examina del orden de s⋅ps \cdot p publicaciones en cada lectura, y publicar escribe una fila. Si el autor tiene ff seguidores, calcular al escribir escribe 1+f1 + f filas en cada publicación, y leer examina veinte entradas. El trabajo no desaparece: se mueve de una operación a la otra.

make timeline crea una red de 10 000 usuarios. Cada uno sigue a unas treinta cuentas y además a la cuenta 1, la famosa, a la que siguen todos:

$ make timeline
10000 usuarios, 50000 publicaciones, 1549845 filas en las líneas de tiempo ya calculadas.
La cuenta 4242 tiene 30 seguidores; la cuenta 1, 9999.

Leer una línea de tiempo (mediana de 500 lectores):
  calculada al leer       0.58 ms
  calculada al escribir   0.32 ms

Publicar (mediana de 20 publicaciones):
  calculada al leer,     cuenta común    0.96 ms   (1 fila)
  calculada al leer,     cuenta famosa   0.93 ms   (1 fila)
  calculada al escribir, cuenta común    1.54 ms   (31 filas)
  calculada al escribir, cuenta famosa   96.33 ms   (10000 filas)

Lo que se ve, de arriba hacia abajo:

  • La primera línea ya es un costo: 50 000 publicaciones se convirtieron en más de un millón y medio de filas derivadas. Calcular al escribir se paga también en espacio.
  • Leer es más rápido con la línea de tiempo ya calculada, pero a esta escala la diferencia es chica: con 31 cuentas seguidas y cinco publicaciones cada una, calcular al leer examina unas 155 filas, y eso es poco trabajo. La ventaja crece con s⋅ps \cdot p, es decir, con una red más activa que la del ejemplo. Los tiempos de lectura son además los que más se movieron entre corridas, por la carga de la máquina; lo estable es el orden.
  • Publicar desde una cuenta común cuesta casi lo mismo en los dos diseños: 31 filas en vez de una.
  • Publicar desde la cuenta famosa cuesta 10 000 filas. En las tres corridas que hicimos tardó entre 87 y 101 ms, contra 1 a 4 ms desde la misma cuenta sin fan-out. El conteo de filas no depende de la máquina: es 1+f1 + f.

Ese último renglón es el punto del caso. Calcular al escribir es una buena decisión para casi todos los usuarios, porque se lee mucho más de lo que se publica y cada publicación se reparte entre pocos. Y la misma decisión es mala para un puñado de cuentas: con diez mil seguidores son 10 000 filas por publicación; con diez millones, una sola publicación es una carga que no cabe en una transacción. El usuario extremo rompe la opción que servía para los demás.

La salida habitual es no elegir una de las dos para todos: las publicaciones de las cuentas comunes se reparten al escribir, y las de las pocas cuentas enormes se buscan al leer y se mezclan con la línea de tiempo ya calculada. Se paga con un sistema que tiene dos caminos, y con una regla más que decidir y mantener: desde cuántos seguidores una cuenta cambia de camino.

Dos cosas más que el ejemplo deja a la vista. La tabla tl_home es un dato derivado, en el sentido de la sección anterior: test/timeline.test.ts la borra entera y la reconstruye a partir de las otras dos. Y por ser derivada puede quedar atrasada: si algo publica sin repartir, las líneas de tiempo ya calculadas no se enteran. La misma prueba lo comprueba.

Idea clave. Casi toda decisión de rendimiento sobre datos es una variante de esta: hacer el trabajo cuando se escribe, para que leer sea barato, o cuando se lee, para que escribir lo sea. Un índice, una cache, una vista materializada y una tabla de totales son todos “calcular al escribir”. La elección depende de la proporción entre lecturas y escrituras, y del caso extremo.

La misma decisión en Tinkuy

Tinkuy toma esta decisión, en pequeño, cada vez que alguien abre el catálogo. GET /events muestra cuántos asientos le quedan a cada evento. Hoy lo calcula al leer. En src/catalog/seats.ts:

export async function countAvailableSeats(eventId: number): Promise<number> {
  const rows = await query<{ available: number }>(
    `SELECT count(*)::int AS available FROM seats WHERE event_id = $1 AND status = 'available'`,
    [eventId],
  );
  return rows[0]?.available ?? 0;
}

y listEvents llama a esa función una vez por cada evento de la lista. Es el N+1 de la semana 6, y es la razón por la que GET /events es la lectura más lenta del sistema. La alternativa es calcular al escribir: guardar en cada evento un número, los asientos que le quedan, y cambiarlo en cada venta.

Contar en cada lectura (hoy) Mantener el número al vender
Leer el catálogo Un COUNT por evento, sobre todos sus asientos Un número ya calculado
Vender Nada extra Una escritura más, en la misma transacción
Puede estar desactualizado No: siempre se cuenta lo que hay Sí, si alguna escritura olvida actualizarlo
Caso extremo Un catálogo con muchos eventos grandes Todas las ventas del pico cambian la misma fila

La última fila es la cuenta famosa de Tinkuy. Con la carga del sistema (miles de lecturas por cada compra), mantener el número parece la opción evidente. Pero el minuto en que abre una venta, todas las compras son del mismo evento, y todas tendrían que modificar la misma fila: la que guarda el contador. La decisión que conviene para la carga normal concentra el pico en un solo punto. No es una razón para descartarla; es lo que hay que medir antes de tomarla, y lo que un ADR sobre esta decisión tendría que decir en sus consecuencias.

Diseñar para una escala que no existe

Error común. Diseñar para una escala que no existe. “Pongamos sharding desde el inicio, por si crece.” “Usemos una base de datos distribuida, que escala sola.” Cada componente distribuido que se agrega “por si crece” es operación y modos de falla desde hoy: hay que desplegarlo, monitorearlo, actualizarlo y entender qué pasa cuando una parte se cae. El crecimiento es una hipótesis; el costo es un hecho, y empieza el primer día.

Lo contrario tampoco es una virtud. No pensar en la carga hasta que el sistema se cae también es un error, y es el que la semana 2 enseñó a evitar con escenarios. El punto medio tiene tres partes, y ninguna necesita construir nada por adelantado:

  1. Describir la carga de hoy y la que se espera, con sus parámetros. Si nadie puede decir cuánto va a crecer ni por qué, no hay base para diseñar para ese crecimiento.
  2. Saber dónde está el límite del diseño actual. Se mide: ¿con cuántas compras por segundo deja de cumplirse el escenario? Si el límite está a diez veces de la carga actual, hay tiempo.
  3. No cerrarse la puerta. Las decisiones baratas de hoy que hacen posible el cambio de mañana: que el acceso a los datos pase por un módulo y no esté regado por todo el código, que cada módulo sea owner de sus tablas, que las claves no dependan de estar todas en una máquina. Son las reglas de la primera mitad del curso, y esta es una de las razones por las que existen.

El modelo de datos decide qué preguntas son fáciles

Relacional y de documentos, con el mismo pedido

Un modelo de datos es la forma en que un sistema de almacenamiento deja representar la información: tablas con filas, documentos con campos anidados, nodos unidos por aristas, o claves con un valor opaco. No hay un modelo mejor. Cada uno hace baratas unas preguntas y caras otras, y se elige mirando qué preguntas hace el sistema: sus patrones de acceso.

Los dos más usados son el relacional y el de documentos, y se entienden mejor con el mismo dato guardado de las dos maneras. models/models.sql guarda mil pedidos de una librería en tres tablas (m_orders, m_items, m_books) y, además, como un documento JSON por pedido. PostgreSQL permite las dos cosas, así que se pueden comparar sin cambiar de base de datos. make models hace cuatro preguntas a cada uno.

Leer un pedido entero. El documento es una fila:

$ make models
== 1. Leer un pedido entero
Documento: una fila, sin JOIN.
                    pedido_4
------------------------------------------------
 {                                             +
     "buyer": "comprador 4",                   +
     "items": [                                +
         {                                     +
             "title": "La ciudad y los perros",+
             "quantity": 1,                    +
             "priceCents": 5200                +
         },                                    +
 …

Relacional: tres tablas.
    buyer    |         title          | price_cents | quantity
-------------+------------------------+-------------+----------
 comprador 4 | La ciudad y los perros |        5200 |        1
 comprador 4 | Trilce                 |        3000 |        1

Para esta pregunta el documento gana: lo que la aplicación usa junto está guardado junto. A la unidad que se lee y se escribe entera se le llama un agregado, y el modelo de documentos está hecho para eso. El modelo relacional lo parte en tres tablas y lo vuelve a armar con dos JOIN cada vez.

Una pregunta que cruza pedidos. ¿Cuántos ejemplares se vendieron de cada libro?

== 2. Una pregunta que cruza pedidos: cuántos ejemplares se vendieron de cada libro
Relacional:
         title          | ejemplares
------------------------+------------
 La ciudad y los perros |        584
 Los ríos profundos     |        583
 Trilce                 |        583

Documento: hay que abrir todos los documentos y desarmar sus listas.
         title          | ejemplares
------------------------+------------
 La ciudad y los perros |        584
 Los ríos profundos     |        583
 Trilce                 |        583

Las dos responden lo mismo, pero no de la misma forma. La relacional recorre una tabla angosta, m_items, que existe precisamente porque la relación entre pedidos y libros es de muchos a muchos. La de documentos abre cada pedido y desarma su lista:

SELECT item->>'title' AS title, sum((item->>'quantity')::int) AS ejemplares
FROM m_order_docs, jsonb_array_elements(doc->'items') AS item GROUP BY 1 ORDER BY 1;

Corregir un dato compartido. El título de un libro tenía un error:

== 3. Corregir el título de un libro
Relacional:
UPDATE 1
Documento: el título está copiado en cada pedido que lo incluye.
UPDATE 416

Una fila contra 416 documentos. En el modelo relacional cada dato está en un solo lugar (eso es lo que la normalización consigue) y los demás lo referencian. En el documento, el título viaja copiado dentro de cada pedido. No toda copia es un defecto: el precio debe estar copiado en el pedido, porque es el precio al que se vendió, un hecho que no cambia aunque el libro suba mañana. El título, en cambio, es una referencia a algo que vive en otro lado, y copiarlo obliga a corregirlo en todas partes.

Un dato mal formado.

== 4. Un dato mal formado
Relacional (esquema al escribir): la base de datos lo rechaza.
psql:models/models.sql:61: ERROR:  new row for relation "m_items" violates check constraint "m_items_quantity_check"
DETAIL:  Failing row contains (1, 3, 0).
Documento (esquema al leer): entra, y falla después, en quien lo lea.
psql:models/models.sql:64: ERROR:  invalid input syntax for type integer: "dos"

El segundo error no ocurrió al insertar el documento con "quantity": "dos": ocurrió en la consulta siguiente, la que suma cantidades. Volvemos a esto en Esquema al escribir y esquema al leer.

Relacional De documentos
Unidad La fila; un objeto se reparte entre tablas El documento; un objeto completo
Fácil Relaciones de muchos a muchos, JOIN, restricciones, transacciones entre varias tablas Leer y escribir un agregado entero; campos que varían de un documento a otro
Difícil Armar un objeto con muchas partes; cambiar el esquema de una tabla enorme Relaciones entre documentos; preguntas que cruzan agregados; datos compartidos
Esquema Lo hace cumplir la base de datos Está en el código que lee

Trade-off. El modelo de documentos gana cuando los datos forman agregados independientes que se leen enteros (un pedido, un perfil, un carrito). El relacional gana cuando lo que importa son las relaciones entre las cosas y las preguntas que nadie previó. La mayoría de los sistemas tienen de las dos clases de datos, y por eso las bases de datos relacionales aceptan JSON y las de documentos fueron agregando formas de JOIN. La frontera es menos nítida de lo que sugieren los nombres.

Grafos y clave-valor

Otros dos modelos ocupan los extremos.

De grafos. Cuando las relaciones no son un detalle de los datos sino los datos mismos: quién sigue a quién, qué cuenta le transfirió a cuál, qué pieza depende de qué otra. Las preguntas típicas recorren un número de pasos que no se conoce de antemano (¿hay un camino entre estas dos cuentas?, amigos de amigos de amigos). En SQL se pueden escribir, con consultas recursivas, pero cada paso es un JOIN más. Un modelo de grafos guarda nodos y aristas y tiene un lenguaje de consulta donde recorrer es la operación básica. Se paga con un motor menos común, que menos gente sabe operar.

Clave-valor. El modelo más simple posible: se guarda un valor bajo una clave y se recupera por esa clave. Nada más: ni consultas por otro campo, ni JOIN, ni restricciones entre valores. Esa pobreza es lo que se compra: como cada operación toca una sola clave, repartir las claves entre muchas máquinas es directo (semana 11), y cada operación es tan rápida como puede ser. Redis, en su uso como cache, es esto. Sirve cuando el patrón de acceso es de verdad “dame lo que hay bajo esta clave”, y se vuelve una trampa el día en que alguien necesita “dame todos los que cumplen tal condición”.

Error común. Elegir el modelo por moda o por lo que el equipo usó en el proyecto anterior. El procedimiento es el mismo que para elegir un estilo de arquitectura: se escriben las cinco o seis consultas que el sistema hace todo el tiempo y las dos o tres que no puede dejar de responder, y se mira con qué modelo cada una es una operación natural. Si casi todas lo son con el modelo relacional, la pregunta está resuelta, y es el caso más frecuente.

Esquema al escribir y esquema al leer

Las bases de datos de documentos se describen a veces como “sin esquema”. No es exacto, y el cuarto resultado de make models muestra por qué. El código que suma cantidades supone que quantity es un número. Esa suposición es un esquema. Lo que cambia es dónde vive y quién lo hace cumplir:

  • Esquema al escribir (schema-on-write): la estructura está declarada en la base de datos, y un dato que no la cumple no entra. Es lo que hizo la restricción CHECK (quantity > 0). El error le llega a quien escribe, en el momento en que escribe.
  • Esquema al leer (schema-on-read): la base de datos acepta cualquier cosa, y la estructura está implícita en el código que lee. El error le llega a quien lee, cuando lee, que puede ser meses después y en otro programa.

Idea clave. “Sin esquema” quiere decir que el esquema está en el código que lee, sin nadie que lo haga cumplir. Sigue habiendo un esquema; lo que no hay es un lugar donde esté escrito ni un guardián.

El esquema al leer tiene usos legítimos. Cuando los datos vienen de fuera y no se controla su forma, o cuando cada documento tiene de verdad campos distintos, obligar una estructura única estorba. Y un cambio de estructura no necesita migrar nada: el código nuevo empieza a escribir el campo nuevo, y al leer maneja los documentos que no lo tienen. Lo que se paga es que todo lector tiene que manejar todas las formas que el dato tuvo alguna vez, y nada le avisa cuáles son.

Persistencia políglota

Si cada modelo es bueno para algo, la conclusión tentadora es usar varios: una base de datos por necesidad. A eso se le llama persistencia políglota. Para un sistema como Tinkuy podría ser PostgreSQL para las órdenes, Redis para la cache del catálogo y un índice de búsqueda para encontrar eventos por nombre.

Lo que se gana es ajuste: cada dato está donde sus preguntas son fáciles. Lo que se paga tiene dos partes.

La primera es operación. Tres sistemas son tres cosas que instalar, actualizar, monitorear y respaldar, y tres conjuntos de modos de falla que alguien del equipo tiene que entender.

La segunda es más profunda, y es el tema de las próximas semanas: ya no hay una transacción que cubra todo. Cuando un evento cambia de nombre, hay que cambiarlo en PostgreSQL, invalidarlo en Redis y actualizarlo en el índice de búsqueda. Son tres escrituras en tres sistemas, y ninguno de ellos puede garantizar que ocurran las tres o ninguna. Si la segunda falla, el catálogo muestra el nombre anterior hasta que alguien lo note. Mantener las copias de acuerdo pasa a ser trabajo del equipo.

Aquí es donde la distinción entre sistema de registro y dato derivado deja de ser vocabulario. Una persistencia políglota que se sostiene tiene un sistema de registro por dato, y los demás almacenes son derivados que se alimentan de él y se pueden reconstruir. Una que no se sostiene tiene tres almacenes que la aplicación escribe por separado, cada uno un poco distinto de los otros, y nadie sabe cuál tiene la razón.

Trade-off. Cada almacén que se agrega mejora el ajuste para una clase de consultas y cobra operación y consistencia. Antes de agregar el segundo, vale la pena preguntar si el primero no alcanza: PostgreSQL guarda documentos (jsonb), busca texto y hace consultas recursivas. No lo hace tan bien como un sistema dedicado, y para muchos sistemas “no tan bien” es suficiente y cuesta un sistema menos.

El modelo de datos como interfaz

Queda un punto que conecta esta sesión con la primera mitad del curso. En la semana 3 una interfaz era lo que un módulo promete a los demás, y todo lo que no está en la interfaz se puede cambiar sin avisar. ¿Dónde queda el esquema de la base de datos?

Depende de quién lo lea. Si las tablas de órdenes solo las toca el módulo de órdenes, el esquema es un detalle de implementación: se puede cambiar el nombre de una columna y nadie más se entera. Pero si el módulo de reportes hace sus propias consultas sobre esas tablas, el esquema se volvió un contrato público. Cada columna que el reporte lee es una promesa que el módulo de órdenes hizo sin saberlo.

De ahí viene la regla que ya vieron dos veces, en el modular monolith (semana 4) y en los microservicios (semana 5): cada módulo o servicio es owner de sus datos, y los demás los piden por su interfaz. No es una regla de orden. Es lo que hace posible cambiar el esquema.

En Tinkuy. En el Tinkuy inicial, el módulo reports consulta directamente las tablas orders, order_items y seats, que son de otros módulos. make deps no lo ve: la dependencia está escrita en SQL, no en un import. Mientras alguien lea esas tablas por su cuenta, ninguna de sus columnas se puede cambiar sin coordinar con él.

El caso del laboratorio tiene exactamente esa forma: un servicio de órdenes, y un proceso de reportes de otro equipo que se conecta a su base de datos y lee la tabla. El resto del capítulo es sobre qué hacer cuando ya es tarde para evitarlo.

Por qué la evolución es un problema de arquitectura

Versiones que conviven

Cambiar un programa que corre en una sola computadora es simple: se detiene, se reemplaza, se inicia. Todo el código que existe es de la misma versión.

En un sistema que no se detiene, eso no pasa nunca. Hay al menos cuatro situaciones en las que código de dos versiones funciona al mismo tiempo sobre los mismos datos:

  • Un despliegue gradual. Para no detener el servicio, las instancias se reemplazan de a pocas. Durante unos minutos, unas atienden con la versión anterior y otras con la nueva, y un load balancer reparte las peticiones entre todas. Las dos versiones leen y escriben la misma base de datos.
  • Un cliente que no se actualiza. Una aplicación móvil instalada hace dos años sigue llamando a la API como se llamaba hace dos años. El equipo no puede obligar a nadie a actualizarla.
  • Un mensaje que quedó en una cola. Lo escribió la versión anterior y lo va a leer la nueva. O al revés: la nueva ya publica, y un consumidor que todavía no se actualizó lo recibe.
  • Los datos guardados. Toda fila de la base de datos la escribió alguna versión del código, casi siempre una anterior a la que hoy la lee.

Idea clave. En un sistema que no se detiene, la versión vieja y la nueva del código conviven siempre, aunque sea por unos minutos. Un cambio de formato o de contrato no se diseña para “antes” y “después”: se diseña para “durante”.

Es un problema de arquitectura, y no de programación, porque atraviesa fronteras. El formato de una fila, de un mensaje o de una respuesta HTTP es lo que conecta partes del sistema que se despliegan por separado y que a veces pertenecen a equipos distintos.

Hacia atrás y hacia adelante

La compatibilidad tiene dos direcciones, y casi todas las confusiones vienen de no decir cuál.

Compatibilidad hacia atrás (backward compatibility): el código nuevo puede leer datos escritos por el código viejo. Es la que todos tienen presente, y la fácil: quien escribe el código nuevo conoce el formato viejo y puede manejarlo explícitamente.

Compatibilidad hacia adelante (forward compatibility): el código viejo puede leer datos escritos por el código nuevo. Es la difícil, porque el código viejo ya está escrito y desplegado. No se le puede enseñar el formato nuevo: tiene que haber sido escrito, desde el principio, de modo que tolere lo que todavía no existía.

Quién escribe Quién lee Cuándo importa
Hacia atrás La versión vieja La versión nueva Siempre: los datos guardados son viejos
Hacia adelante La versión nueva La versión vieja Despliegue gradual, rollback, clientes que no se actualizan
Dos filas con el mismo esquema: quién escribe, el dato y quién lee. Hacia atrás (backward): la versión vieja escribe un dato con el formato viejo y la versión nueva lo lee; es la fácil, porque quien escribe el código nuevo conoce el formato viejo, e importa siempre, porque los datos guardados son viejos. Hacia adelante (forward): la versión nueva escribe un dato con el formato nuevo y la versión vieja, resaltada, lo lee; es la difícil, porque el código viejo ya está desplegado y debe tolerar lo que no existía, e importa en un despliegue gradual, en un rollback y con clientes que no se actualizanDos filas con el mismo esquema: quién escribe, el dato y quién lee. Hacia atrás (backward): la versión vieja escribe un dato con el formato viejo y la versión nueva lo lee; es la fácil, porque quien escribe el código nuevo conoce el formato viejo, e importa siempre, porque los datos guardados son viejos. Hacia adelante (forward): la versión nueva escribe un dato con el formato nuevo y la versión vieja, resaltada, lo lee; es la difícil, porque el código viejo ya está desplegado y debe tolerar lo que no existía, e importa en un despliegue gradual, en un rollback y con clientes que no se actualizan
El nombre de cada dirección lo pone quien lee: hacia atrás, el código nuevo lee datos viejos; hacia adelante, el código viejo lee datos nuevos.

La compatibilidad hacia adelante importa incluso cuando todos los clientes son del mismo equipo y se actualizan juntos. Durante un despliegue gradual, una instancia nueva escribe una fila, y la petición siguiente sobre esa misma fila le toca a una instancia vieja. Y si el despliegue sale mal y se hace rollback, toda la base de datos queda con filas escritas por la versión nueva y leídas por la vieja. Un sistema sin compatibilidad hacia adelante es un sistema donde el rollback no funciona.

El campo que se pierde

“Tolerar lo que no se conoce” tiene dos niveles. El primero es no fallar: el código viejo ve un campo que no conoce y lo ignora. El segundo es más exigente y es el que se olvida: no destruirlo.

El caso es este. El código nuevo guarda una orden con un campo currency. El código viejo la lee para anularla, cambia el estado y la vuelve a guardar. formats/document-roundtrip.ts tiene las dos maneras de escribir ese código viejo:

/** Como se escribe sin pensarlo: se copia el documento a un objeto con los campos conocidos. */
export function cancelDroppingUnknown(document: string): string {
  const raw = JSON.parse(document) as OrderV1;
  const order: OrderV1 = { id: raw.id, buyerName: raw.buyerName, totalCents: raw.totalCents, status: 'cancelled' };
  return JSON.stringify(order);
}

/** Lo mismo, llevando consigo todo lo que llegó: solo se toca el campo que cambia. */
export function cancelKeepingUnknown(document: string): string {
  const raw = JSON.parse(document) as Record<string, unknown>;
  return JSON.stringify({ ...raw, status: 'cancelled' });
}
$ node formats/document-roundtrip.ts
escrito por el código nuevo:  {"id":7,"buyerName":"Ana Ccori","givenName":"Ana","familyName":"Ccori","totalCents":10000,"currency":"USD","status":"paid"}
anulado por el código viejo:  {"id":7,"buyerName":"Ana Ccori","totalCents":10000,"status":"cancelled"}
anulado conservando el resto: {"id":7,"buyerName":"Ana Ccori","givenName":"Ana","familyName":"Ccori","totalCents":10000,"currency":"USD","status":"cancelled"}

La primera función no falló. Leyó el documento, hizo su trabajo y guardó un documento válido. Y una orden de 100 dólares quedó convertida en una orden de 100 de una moneda que ya nadie sabe cuál es. No hubo error, no hubo log, y el código que lo causó es el viejo, el que nadie tocó.

Dos observaciones. La primera función es la que sale naturalmente cuando el código convierte lo que lee en un objeto con tipo: los campos que el tipo no declara no tienen dónde quedarse. Y el problema depende del modelo de datos. En una tabla relacional, anular una orden es UPDATE orders SET status = 'cancelled' WHERE id = $1, que no toca las demás columnas, conozca o no el código su existencia. En el modelo de documentos, donde se lee y se escribe el agregado entero, quien reescribe es responsable de todo lo que había. make forward lo muestra con el servicio de la semana, y es el último paso del laboratorio.

Formatos

Para que un dato salga de la memoria de un proceso (hacia un archivo, una fila, un mensaje o una respuesta HTTP) hay que convertirlo en una secuencia de bytes, y del otro lado hay que hacer lo contrario. Al primer paso se le dice codificar o serializar. El formato que se elige determina qué cambios se pueden hacer después sin romper a nadie.

JSON

JSON es el formato de casi todas las API web, incluidas la de Tinkuy y la del servicio de la semana. Sus ventajas son reales: es texto, se lee a simple vista, todos los lenguajes lo entienden, y cada mensaje lleva los nombres de sus campos, así que se puede interpretar sin tener nada más.

Tiene tres debilidades que conviene conocer.

No trae esquema. Nada en un mensaje JSON dice qué campos son obligatorios ni de qué tipo. Es esquema al leer, con las consecuencias de la sección anterior. Se le puede agregar un esquema por fuera (JSON Schema, OpenAPI), pero es opcional y nada obliga a que el código y el esquema coincidan.

Es ambiguo con los números. JSON tiene “número” y nada más: no distingue enteros de decimales ni dice cuánta precisión tienen. Cada lenguaje decide. JavaScript los lee todos como punto flotante de 64 bits, que representa enteros exactos solo hasta 253−12^{53} - 1:

$ node formats/json-numbers.ts
texto recibido:   {"orderId": 9007199254740993, "totalCents": 1999, "price": 0.1}
orderId leído:    9007199254740992
vuelto a escribir: {"orderId":9007199254740992,"totalCents":1999,"price":0.1}
Number.MAX_SAFE_INTEGER = 9007199254740991
0.1 + 0.2 = 0.30000000000000004   (por eso los montos van en céntimos, como enteros)
como texto:       9007199254740993

El identificador cambió al pasar por JSON.parse, sin ningún error. Un servicio en otro lenguaje, con enteros de 64 bits, lo habría leído bien, y por eso el problema aparece solo entre ciertas parejas de sistemas. Las API que usan identificadores grandes los envían como texto.

Es grande. Los nombres de los campos viajan en cada mensaje. En una respuesta HTTP no importa. En mil millones de filas o de mensajes, sí.

Binarios con esquema: etiquetas en vez de nombres

Los formatos binarios con esquema, como Protocol Buffers y Avro, parten de otra idea: el esquema se escribe aparte, una vez, y los mensajes llevan solo los valores. Lo interesante para este capítulo no es que ocupen menos, sino que sus reglas de evolución son explícitas.

En Protocol Buffers, cada campo del esquema tiene un número, su etiqueta, y en los bytes viaja la etiqueta, no el nombre. Para ver qué consecuencias tiene, formats/tagged.ts implementa un formato mínimo con esa misma idea: unas cien líneas, con enteros y textos. El esquema de la orden tiene dos versiones; esta es la segunda:

export const orderV2: Schema = {
  1: { name: 'id', type: 'int' },
  2: { name: 'buyerName', type: 'string' },
  3: { name: 'totalCents', type: 'int' },
  4: { name: 'givenName', type: 'string' },   // las etiquetas 4, 5 y 6 no existen en orderV1
  5: { name: 'familyName', type: 'string' },
  6: { name: 'currency', type: 'string' },
};
$ node formats/tagged.ts
JSON (109 bytes): {"id":150,"buyerName":"Ana Ccori","totalCents":32000,"givenName":"Ana","familyName":"Ccori","currency":"USD"}
binario (35 bytes): 08 96 01 12 09 41 6e 61 20 43 63 6f 72 69 18 80 fa 01 22 03 41 6e 61 2a 05 43 63 6f 72 69 32 03 55 53 44

Un lector con el esquema v1 lee el mensaje escrito con el v2:
  conoce:    {"id":150,"buyerName":"Ana Ccori","totalCents":32000}
  no conoce: etiquetas 4, 5, 6

El lector v1 cambia totalCents y vuelve a escribir, conservando lo que no conoce:
  un lector v2 lee: {"id":150,"buyerName":"Ana Ccori","totalCents":30000,"givenName":"Ana","familyName":"Ccori","currency":"USD"}
Si no lo conserva:
  un lector v2 lee: {"id":150,"buyerName":"Ana Ccori","totalCents":30000}

Los tres primeros bytes, 08 96 01, son el campo 1 con el valor 150: 08 es la etiqueta 1 con el tipo “entero”, y 96 01 es 150 en una codificación de largo variable. La palabra id no aparece en ningún lado. De ahí salen las propiedades del formato:

  • Agregar un campo es compatible en las dos direcciones. El lector nuevo que recibe un mensaje viejo simplemente no encuentra las etiquetas 4, 5 y 6, y las trata como ausentes. El lector viejo que recibe un mensaje nuevo encuentra etiquetas que no conoce; como cada campo dice de qué tipo es, sabe cuántos bytes saltar.
  • El lector viejo puede conservar lo que no conoce. Guarda los bytes de los campos desconocidos y los vuelve a escribir tal cual. Es la solución al problema de El campo que se pierde, resuelta por el formato y no por la disciplina de cada programador.
  • Cambiar el nombre de un campo es gratis. El nombre solo existe en el esquema; los bytes no cambian.
  • La etiqueta es para siempre. Si se reutiliza el número 2 para otra cosa, los mensajes viejos se van a leer con el significado nuevo. test/formats.test.ts comprueba las dos últimas afirmaciones.

En la industria. La guía de Protocol Buffers lo dice sin matices: los números de campo no se deben reutilizar nunca, y un campo que se elimina debe dejar su número en una lista reserved para que el compilador rechace a quien intente usarlo de nuevo. Entre las consecuencias de reutilizarlo, la guía lista corrupción de datos y fuga de datos personales. También dice que los campos desconocidos se conservan al leer y se incluyen al volver a escribir, y que se pierden si el mensaje se convierte a JSON o se copia campo por campo a un mensaje nuevo. Fuente: Language Guide (proto 3), secciones Assigning Field Numbers, Deleting Fields y Unknown Fields.

Avro resuelve lo mismo de otra manera. Sus mensajes no llevan ni nombres ni etiquetas, solo los valores en el orden del esquema, así que para leer uno hace falta el esquema exacto con que se escribió. Quien lee tiene entonces dos esquemas, el de quien escribió y el suyo, y la biblioteca los empareja campo por campo, por nombre: a eso se le llama resolución de esquemas. Un campo que está en el esquema de quien lee y no en el de quien escribió toma su valor por omisión; uno que está solo en el de quien escribió se descarta. La consecuencia es la regla inversa a la de Protocol Buffers: en Avro el nombre es lo que identifica al campo, y por eso cambiar un nombre exige declarar un alias.

Las reglas de evolución

Con cualquiera de los dos, las reglas se pueden escribir en una tabla, y esa es la ventaja sobre JSON: con JSON las mismas reglas valen, pero nadie las comprueba.

Cambio ¿Compatible? Por qué
Agregar un campo opcional, o con valor por omisión Sí, en las dos direcciones El lector viejo lo ignora; el nuevo usa el valor por omisión cuando falta
Agregar un campo obligatorio No hacia atrás Los datos viejos no lo tienen, y el lector nuevo los rechaza
Quitar un campo opcional Sí, si su etiqueta o su nombre no se reutilizan El lector viejo lo ve ausente
Quitar un campo obligatorio No hacia adelante El lector viejo lo exige y ya no llega
Cambiar el nombre de un campo Depende del formato Gratis con etiquetas; incompatible en JSON; con alias en Avro
Cambiar el tipo de un campo En general, no Los bytes viejos se interpretan con el tipo nuevo, o al revés

La fila del campo obligatorio explica una decisión de diseño de estos formatos: empujan a que todo campo nuevo sea opcional o tenga valor por omisión. Un campo obligatorio es una promesa que no se puede retirar.

Trade-off. JSON da legibilidad y cero herramientas, y cobra con un esquema que nadie hace cumplir. Un formato binario con esquema da mensajes compactos y compatibilidad que una herramienta puede comprobar, y cobra con un paso de generación de código, con mensajes que no se leen a simple vista y con la disciplina de administrar el esquema. Para una API pública que consumen navegadores, JSON es casi siempre la respuesta. Para mensajes entre servicios propios, o datos que se guardan por años, el esquema explícito empieza a pagar.

Evolucionar una API

Cambios compatibles e incompatibles

Una API HTTP con JSON es un contrato entre el servicio y sus clientes, y evoluciona con las mismas reglas, con un detalle: tiene dos sentidos. En la petición, el cliente escribe y el servicio lee. En la respuesta es al revés. El mismo cambio puede ser inocuo en un sentido y romper en el otro.

Cambio En la respuesta En la petición
Agregar un campo opcional Compatible, si los clientes ignoran lo que no conocen Compatible: quien no lo envía sigue funcionando
Agregar un campo obligatorio Compatible (el servicio siempre lo envía) Incompatible: los clientes de hoy no lo envían
Quitar un campo Incompatible para quien lo lee Compatible, si el servicio ignora lo que ya no usa
Cambiar el nombre de un campo Incompatible Incompatible
Cambiar un tipo (número a texto) Incompatible Incompatible
Volver obligatorio un campo opcional Compatible Incompatible
Cambiar el significado de un campo Incompatible, y sin ningún error Incompatible, y sin ningún error
Agregar un endpoint Compatible

La regla que resume la tabla: es compatible exigir menos y prometer más. Un servicio puede aceptar peticiones que antes rechazaba y puede responder con más de lo que respondía. No puede exigir algo que antes no exigía, ni dejar de enviar algo que antes enviaba.

Lector tolerante

La primera fila de la tabla tiene una condición: si los clientes ignoran lo que no conocen. Esa condición no es automática. Depende de cómo se escribió cada cliente.

Un lector tolerante (tolerant reader) toma de una respuesta lo que necesita y no opina sobre el resto. Si necesita dos campos, busca esos dos; no comprueba que no haya otros, ni supone un orden, ni convierte la respuesta completa en un objeto rígido. La idea viene de la ley de Postel, que Fowler cita en su artículo: ser conservador en lo que se envía y liberal en lo que se acepta.

Lo contrario es un lector que valida la respuesta contra la lista exacta de campos que conocía cuando se escribió. errors/strict-reader.ts tiene uno de cada clase. El estricto:

export function strictRead(order: Record<string, unknown>): string {
  const extra = Object.keys(order).filter((key) => !KNOWN_FIELDS.includes(key));
  if (extra.length > 0) throw new Error(`Respuesta inesperada: campos desconocidos ${extra.join(', ')}`);
  return `Orden #${String(order.id)} de ${String(order.buyerName)}`;
}

tolerantRead es la misma función sin las dos primeras líneas.

$ node errors/strict-reader.ts
lector tolerante, respuesta de antes:   Orden #7 de Ana Ccori
lector tolerante, respuesta con campos nuevos: Orden #7 de Ana Ccori
lector estricto, respuesta de antes:    Orden #7 de Ana Ccori
lector estricto, respuesta con campos nuevos:
…
Error: Respuesta inesperada: campos desconocidos givenName, familyName, currency

El lector estricto parece el más cuidadoso de los dos, y es el que convierte el cambio más inocente que existe, agregar un campo, en una caída. Además le quita al servicio la única forma de evolucionar sin coordinarse con nadie.

Tolerante no quiere decir que acepte cualquier cosa. El cliente móvil de la semana (consumers/mobile-client.ts) es tolerante con lo que no usa y exigente con lo que usa: si buyerName no llega, o no es un texto, falla diciendo qué campo falta. Eso es lo correcto: un cliente que mostrara “A nombre de: undefined” no sería tolerante, sería un cliente con un error que nadie ve.

Ley de Hyrum

El lector tolerante es una recomendación para quien consume. Quien publica una API no puede contar con que todos la sigan, y hay una observación que dice hasta dónde llega el problema. La ley de Hyrum: con suficientes usuarios de una API, no importa lo que el contrato prometa; alguien dependerá de cada comportamiento observable del sistema.

“Comportamiento observable” incluye mucho más que los campos documentados. Algunos ejemplos de cosas de las que alguien termina dependiendo:

  • El orden de los elementos de una lista. El contrato dice “devuelve las órdenes del comprador”. La implementación, por cómo está escrita la consulta, las devuelve por id. Un cliente muestra “tu última compra” tomando el último elemento. El día en que alguien agrega un índice y PostgreSQL elige otro plan, el orden cambia y ese cliente muestra una compra de hace tres años. Nadie rompió el contrato.
  • El orden de las claves de un objeto JSON. Un cliente que busca el total con una expresión regular sobre el texto, en vez de interpretar el JSON.
  • El texto de un mensaje de error. Un cliente que decide si reintentar buscando la palabra “ocupado” en el mensaje.
  • La latencia. Un cliente con un timeout de 200 ms funciona mientras el servicio responda en 150 ms, aunque nadie lo haya prometido.

En la industria. Hyrum Wright, que fue ingeniero en Google, formuló la observación después de varios años de migraciones de infraestructura en un sistema muy grande: con suficientes consumidores, la interfaz implícita termina coincidiendo con la implementación, y cualquier cambio rompe la expectativa de alguien. El nombre “ley de Hyrum” se lo puso Titus Winters. Fuente: hyrumslaw.com.

La ley no dice que no se pueda cambiar nada. Dice que “no cambié el contrato” no es una prueba de que el cambio sea seguro. Las consecuencias prácticas son dos: lo que no se quiere prometer conviene que no sea observable (devolver la lista sin un orden estable, a propósito, es una defensa conocida), y antes de quitar algo hay que medir si alguien lo usa, que es el tema de Cuándo contraer.

Compatible en la forma, incompatible en el significado

La fila más peligrosa de la tabla es la penúltima. El servicio de la semana guarda montos en céntimos de sol, y el cambio pedido en el laboratorio agrega un campo currency. Mirado como estructura, es el cambio más seguro que hay: un campo opcional más en la respuesta. El cliente móvil, que es un lector tolerante, lo ignora y sigue funcionando.

Ese es justamente el problema. errors/currency-meaning.ts le da al código del cliente antiguo una orden en dólares:

$ node errors/currency-meaning.ts
El servicio responde: {"id":300010,"buyerEmail":"ana.ccori@correo.pe","buyerName":"Ana Ccori","givenName":"Ana","familyName":"Ccori","totalCents":10000,"currency":"USD","status":"paid","createdAt":"2026-11-16T15:00:00.000Z"}
El cliente móvil antiguo muestra:
  Orden #300010
  A nombre de: Ana Ccori
  Total: S/ 100.00
  Estado: pagada

Cien dólares mostrados como cien soles. El campo totalCents no cambió de nombre ni de tipo. Cambió de significado: antes era “céntimos de sol” y ahora es “céntimos de la moneda que diga currency”. Ninguna herramienta de compatibilidad de esquemas detecta eso, porque el esquema viejo es un subconjunto exacto del nuevo.

Error común. Creer que un cambio es compatible porque ningún cliente falla. Los cambios de significado no producen errores: producen datos equivocados que se ven correctos. Las preguntas que hay que hacerse ante un campo nuevo no son solo “¿quién falla si aparece?”, sino también “¿qué suponía quien lee los campos viejos, y sigue siendo cierto?”.

Mientras todas las órdenes sean en soles, el cliente antiguo acierta por casualidad. Las salidas posibles cuestan todas algo: no crear órdenes en otra moneda mientras ese cliente exista (se retrasa el negocio); dejar totalCents siempre en soles y poner el monto en la otra moneda en campos nuevos (el contrato queda con dos formas de decir lo mismo); o aceptar que el cliente antiguo mostrará mal las órdenes en dólares, y decidir que es tolerable porque ese cliente no puede crearlas. En el laboratorio tienen que elegir una y defenderla.

Una versión nueva para cada cambio

La respuesta que muchos equipos dan a todo lo anterior es versionar la API: lo nuevo va en /v2, y /v1 queda como estaba.

Error común. Versionar la API para cada cambio. Parece la opción segura porque nadie se rompe. Pero cada versión viva es código que hay que mantener, probar y operar: un error de seguridad se corrige en todas, y una regla de negocio nueva se implementa en todas. Y el problema original no se resolvió, solo se aplazó: los clientes de /v1 siguen ahí, y algún día alguien tiene que decidir cuándo se apaga.

La mayoría de los cambios se pueden hacer compatibles, y esa es la primera opción. De los cambios de las tablas anteriores, agregar campos y endpoints no necesita versión. Cambiar un nombre o partir un campo en dos tampoco: se agrega lo nuevo al lado de lo viejo, se espera, y se quita lo viejo cuando nadie lo usa. Eso es la sección siguiente.

Una versión nueva se justifica cuando el cambio no admite que las dos formas convivan en la misma respuesta: cambió el modelo entero, cambió el significado de casi todo, o cambió el mecanismo de autenticación.

En la industria. Stripe describe por qué evita las versiones grandes (v1, v2): los cambios entre una y otra son tan grandes que actualizarse se parece a integrarse de nuevo, y siempre queda un grupo de usuarios atrapado en la versión vieja. Su API usa en cambio versiones con fecha, cada una con un conjunto pequeño de cambios incompatibles; cada cuenta queda fijada en la versión de su primera petición, y cada cambio incompatible vive en un módulo que transforma la respuesta actual a la forma que esperaba la versión anterior. Es versionar, y el costo de mantener lo viejo queda encerrado en esos módulos en vez de regado por el código. Fuente: Brandur Leach, APIs as infrastructure: future-proofing Stripe with versioning (2017).

Expandir, migrar y contraer

Renombrar en un solo paso

El caso más simple de cambio incompatible es cambiar un nombre. Una tabla de cupones tiene una columna discount, un porcentaje, y el equipo quiere que se llame percent_off. En SQL es una línea, y es atómica: ALTER TABLE coupons RENAME COLUMN discount TO percent_off. El código cambia en un commit.

El problema es que la línea de SQL y el despliegue del código no ocurren en el mismo instante, y no hay orden que funcione:

  • Si primero se cambia la tabla, el código que está corriendo pregunta por una columna que ya no existe, hasta que termine el despliegue.
  • Si primero se despliega el código, pregunta por una columna que todavía no existe, hasta que se cambie la tabla.
  • Si el despliegue es gradual, durante varios minutos hay instancias de las dos versiones, y con cualquier esquema una de las dos falla.

Error común. Renombrar una columna o un campo en un solo despliegue. Durante los minutos que dura, la mitad del sistema lee un nombre que ya no existe. En el ambiente de desarrollo no se nota, porque ahí hay una sola instancia, se detiene y se inicia, y nadie más lee la tabla.

El ejemplo: cambiar el nombre de una columna

La salida es dejar de pensar en “el cambio” como un paso. Entre el código que solo conoce discount y el que solo conoce percent_off hace falta una tercera versión, que conozca las dos. expand-contract/versions.ts tiene las tres. La versión antigua es la que está en producción:

export const oldCode: CouponCode = {
  name: 'antigua',
  write: async (client, code, percent) =>
    void (await client.query('INSERT INTO coupons (code, discount) VALUES ($1, $2)', [code, percent])),
  read: (client, code) => one(client, 'SELECT discount AS percent FROM coupons WHERE code = $1', code),
};

La versión puente escribe en las dos columnas y lee la nueva, con la vieja de respaldo:

export const bridgeCode: CouponCode = {
  name: 'puente',
  write: async (client, code, percent) =>
    void (await client.query('INSERT INTO coupons (code, discount, percent_off) VALUES ($1, $2, $2)', [code, percent])),
  read: (client, code) =>
    one(client, 'SELECT coalesce(percent_off, discount) AS percent FROM coupons WHERE code = $1', code),
};

Y la nueva solo nombra percent_off. El esquema también pasa por estados intermedios. Son tres archivos SQL, en expand-contract/steps/:

-- 1-expand.sql
ALTER TABLE coupons
    ADD COLUMN percent_off integer CHECK (percent_off BETWEEN 1 AND 100);

-- 2-migrate.sql
UPDATE coupons SET percent_off = discount WHERE percent_off IS NULL;
ALTER TABLE coupons
    ALTER COLUMN percent_off SET NOT NULL,
    ALTER COLUMN discount DROP NOT NULL;

-- 3-contract.sql
ALTER TABLE coupons DROP COLUMN discount;

make expand-contract aplica los pasos uno por uno. Después de cada uno prueba todas las parejas de versiones: una escribe un cupón y otra lo lee. Dos versiones pueden correr a la vez sobre un esquema si todas las combinaciones entre ellas dan bien:

$ make expand-contract

== 0-initial.sql
escribe \ lee antigua     puente      nueva
antigua       bien        no lee      no lee
puente        no escribe  no escribe  no escribe
nueva         no escribe  no escribe  no escribe
  puente: column "percent_off" of relation "coupons" does not exist
  nueva: column "percent_off" of relation "coupons" does not exist
  pueden convivir: antigua

== 1-expand.sql
escribe \ lee antigua     puente      nueva
antigua       bien        bien        lee NULL
puente        bien        bien        bien
nueva         no escribe  no escribe  no escribe
  nueva: null value in column "discount" of relation "coupons" violates not-null constraint
  pueden convivir: antigua y puente

== 2-migrate.sql
escribe \ lee antigua     puente      nueva
antigua       no escribe  no escribe  no escribe
puente        bien        bien        bien
nueva         lee NULL    bien        bien
  antigua: null value in column "percent_off" of relation "coupons" violates not-null constraint
  pueden convivir: puente y nueva

== 3-contract.sql
escribe \ lee antigua     puente      nueva
antigua       no escribe  no escribe  no escribe
puente        no escribe  no escribe  no escribe
nueva         no lee      no lee      bien
  antigua: column "discount" does not exist
  puente: column "discount" does not exist
  pueden convivir: nueva

La última línea de cada bloque cuenta toda la historia:

Animación en cuatro etapas, una por cada estado del esquema de la tabla coupons. A la izquierda, las tres versiones del código: antigua (escribe y lee discount), puente (escribe las dos; lee percent_off o discount) y nueva (escribe y lee percent_off); a la derecha, las columnas discount y percent_off, con flechas desde cada versión que funciona hacia las columnas que usa. Abajo, una línea con las versiones que pueden convivir en cada estado y los pasos entre ellos. Etapa inicial, 0-initial.sql: discount es NOT NULL y percent_off no existe; funciona solo la antigua, y la puente y la nueva fallan porque percent_off no existe. Etapa 1, expandir: se agrega percent_off, que admite NULL; funcionan la antigua y la puente, y la nueva falla porque discount es NOT NULL. Etapa 2, migrar: discount pasa a admitir NULL y percent_off queda NOT NULL con los datos copiados; funcionan la puente y la nueva, y la antigua falla porque percent_off es NOT NULL. Etapa 3, contraer: discount queda eliminada; funciona solo la nueva. En la línea de abajo se lee antigua, antigua y puente, puente y nueva, nueva; expandir y migrar dicen se puede revertir, y contraer dice no se puede revertirAnimación en cuatro etapas, una por cada estado del esquema de la tabla coupons. A la izquierda, las tres versiones del código: antigua (escribe y lee discount), puente (escribe las dos; lee percent_off o discount) y nueva (escribe y lee percent_off); a la derecha, las columnas discount y percent_off, con flechas desde cada versión que funciona hacia las columnas que usa. Abajo, una línea con las versiones que pueden convivir en cada estado y los pasos entre ellos. Etapa inicial, 0-initial.sql: discount es NOT NULL y percent_off no existe; funciona solo la antigua, y la puente y la nueva fallan porque percent_off no existe. Etapa 1, expandir: se agrega percent_off, que admite NULL; funcionan la antigua y la puente, y la nueva falla porque discount es NOT NULL. Etapa 2, migrar: discount pasa a admitir NULL y percent_off queda NOT NULL con los datos copiados; funcionan la puente y la nueva, y la antigua falla porque percent_off es NOT NULL. Etapa 3, contraer: discount queda eliminada; funciona solo la nueva. En la línea de abajo se lee antigua, antigua y puente, puente y nueva, nueva; expandir y migrar dicen se puede revertir, y contraer dice no se puede revertir
En cada estado del esquema funcionan dos versiones consecutivas del código, nunca la antigua con la nueva. Contraer es el único paso que destruye algo.

En ningún estado del esquema conviven la antigua y la nueva: por eso el cambio en un paso es imposible. Y en cada estado conviven dos versiones consecutivas: por eso cada paso se puede hacer con un despliegue gradual, y se puede deshacer volviendo a la versión anterior, que sigue funcionando sobre el mismo esquema.

Vale la pena mirar dos celdas. Con la tabla solo expandida, la antigua escribe y la nueva lee NULL: lo que la versión antigua guarda no llega a la columna nueva. Por eso la versión puente lee con coalesce, y por eso la copia de datos de 2-migrate.sql se hace cuando ya no queda ninguna instancia antigua: si quedara una, seguiría creando filas con percent_off vacío después de la copia. Y en 2-migrate.sql se intercambian las obligaciones: percent_off pasa a ser obligatoria y discount deja de serlo. Sin lo segundo, la versión nueva no podría insertar mientras la columna vieja exista.

Las tres fases y sus condiciones

El patrón se llama cambio en paralelo (parallel change), o expandir y contraer. Sirve para una columna, para un campo de una API, para la firma de una función pública o para un mensaje.

Expandir. Se agrega lo nuevo junto a lo viejo, sin quitar ni cambiar nada: la columna nueva, el campo nuevo en la respuesta, el campo nuevo aceptado en la petición. Lo nuevo tiene que ser opcional (una columna que admite NULL, o con un valor por omisión), porque quienes solo conocen lo viejo siguen escribiendo. Después se despliega el código que escribe en ambos. Condición para terminar: todo lo que escribe, escribe en los dos lugares.

Migrar. Se copian los datos antiguos a la forma nueva, y se mueve a quienes leen, uno por uno, de lo viejo a lo nuevo. Es la fase más larga, porque depende de otros: de otro equipo, o de usuarios que tienen que actualizar una aplicación. Condición para terminar: nadie lee ni escribe lo viejo. Saberlo es el problema de Cuándo contraer.

Contraer. Se quita lo viejo: primero del código, después del esquema. Condición para empezar: evidencia, no esperanza, de que nadie lo usa.

Idea clave. Un cambio incompatible se convierte en una secuencia de cambios compatibles. En cada momento, el esquema admite la versión del código que está corriendo y la siguiente; por eso cada paso es un despliegue normal, que se puede revertir.

“Se puede revertir” tiene una excepción, y hay que nombrarla. Expandir se revierte quitando lo que se agregó. Migrar se revierte moviendo a los lectores de regreso. Contraer destruye la columna vieja: se puede volver a crear, pero lo que tenía hay que reconstruirlo desde lo nuevo, si es que se puede. Por eso va al final, por eso exige evidencia, y por eso muchos equipos dejan pasar un tiempo entre que el código deja de usar una columna y que la borran.

En la industria. Stripe describe una migración de este tipo sobre sus suscripciones, que pasaron de vivir dentro de la tabla de clientes a una tabla propia. La presentan como un patrón de cuatro pasos: escribir en las dos tablas para mantenerlas de acuerdo; cambiar todas las lecturas para que usen la tabla nueva; cambiar todas las escrituras para que solo escriban en la nueva; y eliminar los datos que dependían del modelo anterior. Fuente: Jacqueline Xu, Online migrations at scale (2017).

Migrar los datos sin detener a nadie

En la tabla de cupones, copiar los datos fue una línea: UPDATE coupons SET percent_off = discount. Con dos filas no importa cómo se haga. Con una tabla grande y en uso, importa mucho, por lo que el UPDATE hace mientras corre.

En PostgreSQL, una transacción que modifica una fila la deja bloqueada con un lock hasta que termina: nadie más puede modificarla ni borrarla. Leerla sí se puede, porque quien lee ve la versión anterior de la fila. Un UPDATE de toda la tabla es una transacción que modifica todas las filas, así que durante todo el tiempo que tarda, cualquier otra escritura sobre una fila que ya pasó tiene que esperar a que termine.

Un ALTER TABLE es peor. Toma un lock sobre la tabla entera que no deja ni leer, y lo mantiene hasta el final de su transacción. Si la transacción contiene solo el ALTER, y el ALTER solo cambia el catálogo, eso dura milisegundos. Si en la misma transacción va la copia de los datos, dura lo que dure la copia.

tools/lock-time.ts mide las tres formas de hacer la migración del laboratorio sobre las 300 000 órdenes. Mientras corre cada una, una sesión lee órdenes al azar y otra las modifica, como haría el servicio, y se anota la espera más larga de cada una:

$ make lock-time
300000 órdenes. Durante cada migración, una sesión lee y otra modifica órdenes al azar.

migración                                                      duró   lectura más lenta   escritura más lenta
todo en una transacción (errors/rename-in-one-step.sql)     2311 ms             2311 ms               2309 ms
un UPDATE de toda la tabla                                  2554 ms               10 ms               2500 ms
lotes de 5000 filas (tools/backfill-batches.ts)             2584 ms               26 ms                 58 ms
  • Todo en una transacción. La primera sentencia es un ALTER TABLE, y su lock dura hasta el COMMIT: lecturas y escrituras esperaron los 2,3 s completos. Para los usuarios, el servicio estuvo caído ese tiempo.
  • Un UPDATE de toda la tabla. Las lecturas no se enteraron. Una escritura esperó 2,5 s, casi todo lo que duró el UPDATE.
  • Por lotes. La migración tardó lo mismo, y la espera más larga de una escritura fue de 58 ms.

Hicimos la medición cinco veces. Las dos primeras formas hicieron esperar a alguien entre 2,3 y 6,8 s, según lo ocupada que estaba la máquina; con lotes, la escritura más lenta estuvo entre 43 y 109 ms en cuatro corridas, y fue de 612 ms en la peor. Con 300 000 filas la diferencia es de segundos contra decenas de milisegundos. Con 300 millones, el UPDATE único tardaría mil veces más, y la espera con él; la de los lotes no depende del tamaño de la tabla, sino del tamaño del lote.

test/locks.test.ts comprueba el mecanismo sin medir tiempos: con un UPDATE sin confirmar, otra sesión puede leer la fila y no modificarla, y puede modificar las filas que el UPDATE no tocó, que es la razón por la que los lotes funcionan. Con un ALTER TABLE sin confirmar, no puede ni leer.

El script por lotes, tools/backfill-batches.ts, es corto. A esta copia de datos antiguos hacia la forma nueva se le dice backfill:

for (let from = first; from <= last; from += options.batchSize) {
  const batchStart = performance.now();
  const updated = await conn.query(
    `UPDATE orders
        SET given_name = ${GIVEN_NAME_SQL}, family_name = ${FAMILY_NAME_SQL}
      WHERE id >= $1 AND id < $2 AND given_name IS NULL`,
    [from, from + options.batchSize],
  );
  …
  if (options.pauseMs > 0) await new Promise((resolve) => setTimeout(resolve, options.pauseMs));
}

Tres decisiones de diseño, todas con su razón:

  • Cada lote es su propia transacción. Ningún lock dura más que un lote.
  • Se avanza por rangos de la clave primaria, no con OFFSET: cada lote encuentra sus filas por el índice, sin recorrer las anteriores.
  • Solo toca las filas que faltan (given_name IS NULL). Por eso se puede interrumpir y volver a correr, y correr otra vez al final para recoger las filas que alguna instancia antigua escribió mientras tanto. test/backfill.test.ts lo interrumpe a la mitad y lo retoma.

Trade-off. Migrar por lotes cambia una espera larga por muchas esperas cortas, y cobra dos cosas. La migración deja de ser atómica: durante minutos u horas la tabla tiene filas migradas y filas sin migrar, y todo el código que lee tiene que funcionar con ambas. Y la migración pasa a ser un programa con estado, que hay que poder detener, retomar y vigilar. La alternativa, una ventana de mantenimiento con el sistema detenido, es más simple y es legítima cuando el negocio la acepta: un sistema interno que nadie usa de madrugada no necesita nada de esto.

Hay un problema que los lotes no resuelven, porque no es de la mecánica sino de los datos. Partir buyer_name en nombre y apellido es adivinar: el texto no dice dónde termina uno y empieza el otro. El script usa una regla (la primera palabra es el nombre) y avisa de cuántas filas son dudosas:

$ make backfill
arq_w09: 300000 filas en 60 lotes de hasta 5000, 1334 ms en total; el lote más largo tardó 28 ms
Nombres de tres o más palabras, donde la regla pudo partir mal: 51686

“Rosa Quispe Mamani” queda bien; “Luz Marina Flores” queda con el apellido “Marina Flores”. Una migración que agrega estructura a datos que no la tenían siempre tiene esta forma, y el plan tiene que decir qué se hace con los casos dudosos: aceptarlos, marcarlos, o pedirle el dato a su owner la próxima vez que entre.

La cola de locks

Expandir con un ALTER TABLE ... ADD COLUMN es rápido en PostgreSQL cuando la columna admite NULL o tiene un valor por omisión constante: solo cambia el catálogo, no reescribe la tabla. Otros cambios sí la reescriben entera, con el lock fuerte tomado todo ese tiempo: cambiar el tipo de una columna de integer a bigint es el ejemplo habitual. La documentación de ALTER TABLE dice cuál es cuál.

Pero incluso el ALTER de un milisegundo puede detener un servicio, por cómo se forman las colas. El ALTER necesita un lock que es incompatible con todos los demás, incluido el de una simple lectura. Si en ese momento hay una transacción larga que ya leyó la tabla (un reporte, por ejemplo), el ALTER espera. Y mientras espera, todas las consultas que llegan después esperan detrás de él, también las lecturas que con el reporte solo habrían pasado sin problema. Un reporte de dos minutos más un ALTER de un milisegundo son dos minutos de servicio detenido.

La tercera prueba de test/locks.test.ts arma esa cola paso por paso: un reporte con una transacción abierta, un ALTER TABLE que espera, y una lectura que antes pasaba y ahora no. La defensa es que la migración se rinda en vez de hacer cola: SET lock_timeout = '2s' antes del ALTER, y si no consigue el lock en ese tiempo, falla y se reintenta más tarde. Los niveles de lock y sus conflictos están en la sección Explicit Locking de la documentación; las transacciones y sus locks son el tema de la semana 12.

Cuándo contraer

La fase de contraer empieza con una pregunta que parece fácil: ¿alguien usa todavía lo viejo?

Para el código propio se responde buscando. Para el código ajeno hay que medir, y lo primero es admitir un límite: un servicio no puede ver qué campos de una respuesta lee un cliente. Envía el JSON completo y no sabe qué pasa después. Lo que sí puede ver son aproximaciones:

Qué se mide Qué dice Qué no ve
Quién llama (user-agent, clave de API) Si siguen llegando peticiones de clientes que se sabe que usan lo viejo Un cliente desconocido que también lo usa
Qué envía el cliente Si alguien todavía escribe con la forma vieja A quien solo lee
Quién pidió la forma nueva (una cabecera, un parámetro) A quien la pidió se le deja de enviar lo viejo; todos los demás cuentan como uso Cuenta de más: quien no pidió nada y tampoco lee el campo

La tercera es la más segura, porque se equivoca hacia el lado conservador: no puede decir “nadie lo usa” cuando alguien sí. Cuesta que los clientes nuevos tengan que declarar algo.

Con cualquiera de las tres, el número solo vale junto con un plazo. “Cero peticiones” durante una hora no dice nada si hay un cliente que corre una vez al mes. La ventana tiene que cubrir el uso más espaciado que se conozca, y el contador tiene que sobrevivir a los reinicios del servicio.

Y hay consumidores que ningún contador del servicio ve: los que no pasan por el servicio. El proceso de reportes que lee la tabla directamente no aparece en ninguna métrica de la API. Es la consecuencia práctica de El modelo de datos como interfaz: a quien entra por la interfaz se le puede contar; a quien entra por la base de datos hay que ir a buscarlo.

Cuando lo viejo no llega a cero, porque hay una aplicación instalada en celulares que nadie va a actualizar, la decisión deja de ser técnica: mantener el campo viejo para siempre, que es barato si se puede calcular a partir de lo nuevo, o anunciar una fecha y dejar de atender a esa versión. Lo que la arquitectura aporta a esa conversación es el número: cuántos son y cuánto cuesta seguir atendiéndolos.

Lo que cuesta, y las alternativas

Trade-off. Expandir, migrar y contraer compra cero tiempo de inactividad y la posibilidad de revertir cada paso. Lo paga con tiempo (tres o más despliegues, y una espera en el medio que puede durar meses), con código que durante la transición maneja las dos formas, y con una deuda: si nadie hace la contracción, el sistema se queda para siempre con las dos, y con la duda de cuál es la buena.

Las alternativas, y cuándo son razonables:

  • Una ventana de mantenimiento. Se detiene todo, se cambia y se inicia. Simple y sin estados intermedios. Exige que el negocio acepte la caída y que todos los consumidores se puedan cambiar a la vez; con un cliente móvil instalado en celulares ajenos, lo segundo es imposible.
  • Una versión nueva de la API. Lo visto en Una versión nueva para cada cambio: se justifica cuando las dos formas no pueden convivir en un mismo contrato.
  • Sincronizar en la base de datos. En vez de que el código escriba en las dos columnas, un trigger copia de una a la otra. Atrapa a todos los que escriben, incluidas las instancias antiguas y los que no pasan por el servicio. Se paga con lógica que vive fuera del código, donde es fácil olvidarla.

Una advertencia para las semanas que vienen. En el ejemplo, “escribir en ambos” fue un INSERT con dos columnas: una sola sentencia, atómica. Cuando lo viejo y lo nuevo están en dos sistemas distintos (dos bases de datos, o una base de datos y un stream de mensajes), escribir en ambos ya no es atómico: puede ocurrir una escritura y fallar la otra. Qué hacer entonces es el tema de la semana 12.

En Tinkuy. La tabla orders guarda el nombre del comprador en una sola columna, buyer_name, y el monto en total_cents, que se entiende en soles porque nada dice otra cosa. La API devuelve lo mismo como buyer.name y totalCents. Separar nombre y apellido, o agregar la moneda, son cambios de la misma clase que los de este capítulo, y con el reporte y un cliente antiguo leyendo, ninguno de los dos se puede hacer en un paso. P3 pide un cambio de contrato sobre Tinkuy; el laboratorio de esta semana es el lugar para practicar la secuencia sobre un servicio más pequeño antes de hacerla ahí.

El código de la semana

Todo está en code/week-09/ y se usa dentro del contenedor del curso. make crea la base de datos arq_w09 con 300 000 órdenes.

Carpeta Qué tiene
orders-v1/ El servicio de órdenes, versión 1. No se modifica
consumers/ El cliente móvil antiguo y el proceso de reportes, con sus pruebas. No se modifican
lab/ La copia de trabajo del laboratorio: el servicio, el reporte y las migraciones por escribir
errors/ El cambio en un solo paso, un lector estricto y el cambio de significado de totalCents
tools/ El backfill por lotes y las mediciones (lock-time, oltp-olap, forward)
expand-contract/ El ejemplo resuelto: el cambio de nombre de una columna
timeline/, models/, formats/ Los ejemplos de las líneas de tiempo, los modelos de datos y los formatos
test/ Las pruebas que comprueban lo que afirma el capítulo

Los comandos están al inicio del Makefile. make test revisa los tipos y corre las pruebas sobre otra base de datos, arq_w09_test: no toca arq_w09.

$ make test
tsc -p .
…
✔ [orders-v1] el cliente móvil antiguo muestra una orden que ya existía (21.945417ms)
✔ [orders-v1] el cliente móvil antiguo compra y ve su compra (8.907917ms)
✔ [consumers/sales-report.ts] el reporte de marzo de 2026 dice lo mismo de siempre (27.510541ms)
✔ si se interrumpe a la mitad, lo hecho queda hecho (250.487792ms)
…
✔ en cada estado del esquema conviven dos versiones consecutivas del código, nunca la primera con la última (97.924542ms)
…
✔ un UPDATE sin confirmar deja leer la fila, pero no modificarla (339.424584ms)
✔ un ALTER TABLE sin confirmar no deja ni leer (308.119709ms)
…
ℹ tests 31
ℹ suites 0
ℹ pass 31
ℹ fail 0

Cada prueba lleva en el nombre la afirmación del capítulo que comprueba. Las primeras dicen entre corchetes contra qué versión corrieron: en el laboratorio van a correr las mismas contra su copia, con make consumers S=lab.

Laboratorio: cambiar un contrato sin romper a quien lo usa

El laboratorio se hace en parejas, con el material de code/week-09/. El cambio pedido tiene dos partes: separar buyer_name en given_name y family_name, y agregar currency a los montos. Se trabaja sobre lab/; orders-v1/ y consumers/ no se tocan, porque representan código que no controlan. Al terminar deben tener el cambio hecho, las pruebas de los consumidores pasando en cada paso intermedio, y escritas las decisiones que tomaron en el camino.

Paso 1: el caso. Corran make y make test. Lean orders-v1/server.ts, consumers/mobile-client.ts y consumers/sales-report.ts, y levanten el servicio con make start para probarlo desde otra terminal (node consumers/mobile-client.ts show 1, make report). Lo que deben poder responder: ¿por dónde entra cada consumidor, y de qué nombres exactos depende cada uno?

Paso 2: clasificar. Antes de escribir nada, llenen lab/compatibility-table.md: para cada parte del cambio, en la API y en la tabla, si es compatible hacia atrás, hacia adelante, ambas o ninguna. Este paso muestra que “el cambio” son una decena de cambios, y que no todos son del mismo tipo.

Paso 3: hacerlo mal. Apliquen errors/rename-in-one-step.sql con psql y corran make consumers. Anoten qué prueba falla, con qué mensaje, y cuál de los dos consumidores da el mensaje más útil. Deshagan con errors/undo-rename-in-one-step.sql o con make db. Este paso muestra cómo se ve, desde cada consumidor, un cambio incompatible.

Paso 4: expandir. Primero la tabla: escriban lab/migrations/01-expand.sql, aplíquenlo, y comprueben con make consumers que orders-v1 y los dos consumidores no notaron nada. Después el servicio: modifiquen lab/orders/ para que acepte y devuelva los campos nuevos sin dejar los viejos, y escriba en ambos. make consumers S=lab debe pasar sin haber tocado las pruebas. Piensen qué necesita cada columna nueva para que orders-v1, que no la conoce, pueda seguir insertando.

Paso 5: migrar. Llenen las filas antiguas con make backfill, y corran make lock-time para ver cuánto hace esperar cada forma de hacerlo. Muevan lab/sales-report.ts a las columnas nuevas: su prueba no cambia, así que el reporte tiene que seguir diciendo lo mismo. Decidan qué hace el reporte con la moneda. Escriban lab/migrations/02-migrate.sql. Este paso muestra que migrar tiene dos mitades, los datos y los lectores, y que la segunda no depende de ustedes.

Paso 6: el cliente que no se actualiza. Decidan cuánto tiempo se mantiene el campo viejo y cómo sabrían que ya nadie lo usa, y agreguen al servicio un contador de las peticiones que todavía dependen de él. Escriban qué cuenta exactamente el contador y qué uso no vería.

Paso 7: contraer. Cuando el contador esté en cero (en el laboratorio, dejando de correr el cliente antiguo), quiten lo viejo: del servicio y, con lab/migrations/03-contract.sql, de la tabla. Corran todo. Algunas pruebas de consumers/ van a fallar: digan cuáles, y por qué en este punto eso es lo esperado y no un error.

Paso 8: hacia adelante. make forward le envía a orders-v1, sin modificar, órdenes con la forma que escribe el servicio nuevo. Respondan con la salida a la vista: ¿las acepta?, ¿conserva los campos que no conoce al devolverlas?, ¿qué hizo con el currency de la primera orden, y avisó? Y expliquen por qué importa durante un despliegue gradual, en el que orders-v1 y su versión nueva atienden a la vez.

Resumen

  • El código sin estado se reemplaza, se copia y se descarta; los datos no, y viven más que el código que los escribió. Por eso las decisiones sobre datos son las que más cuesta deshacer.
  • Transaccional (muchas operaciones pequeñas, por clave; importa la latencia) y analítico (pocas consultas que recorren todo; importa el throughput) compiten por los mismos recursos cuando comparten base de datos. En la medición de la semana, con el procesador saturado por reportes, el throughput de las lecturas por clave cayó a menos de la sexta parte y el p99 se multiplicó por más de diez, mientras el p50 casi no se movió.
  • Cada dato tiene un sistema de registro; lo demás son datos derivados, que se pueden reconstruir. Saber cuál es cuál decide qué se puede perder y a quién se le cree.
  • Distribuir los datos se justifica por tolerancia a fallas, por escala o por cercanía, y cobra fallas parciales, datos atrasados y protocolos en lugar de transacciones. Un servicio administrado cobra control y portabilidad a cambio de no operar.
  • La escalabilidad es una pregunta sobre una carga descrita con parámetros. Calcular al leer o al escribir mueve el trabajo de una operación a la otra; el caso extremo (la cuenta con diez mil seguidores, el evento que concentra todas las ventas) es el que rompe la opción que servía para los demás.
  • El modelo de datos se elige por los patrones de acceso. “Sin esquema” quiere decir esquema al leer. Si otros leen las tablas, el esquema es un contrato público.
  • Hacia atrás: lo nuevo lee lo que escribió lo viejo. Hacia adelante: lo viejo lee lo que escribió lo nuevo, sin fallar y sin destruir lo que no conoce. La segunda es la que hace posible un despliegue gradual y un rollback.
  • En una API es compatible exigir menos y prometer más. Un cambio puede ser compatible en la forma e incompatible en el significado, y ese no produce ningún error.
  • Expandir, migrar y contraer convierte un cambio incompatible en una secuencia de cambios compatibles: en cada estado conviven dos versiones consecutivas del código. Los datos se migran por lotes, y se contrae con evidencia de que nadie usa lo viejo.

Ejercicios

  1. Clasifiquen como transaccional o analítica cada consulta de la API de Tinkuy (la tabla de rutas de su README). Para las que consideren analíticas, digan qué tan viejo podría ser el dato que devuelven sin que su usuario lo note, y qué opción de Separarlos: de menos a más costo permitiría eso.

  2. Corran make oltp-olap con ANALYTIC=1, ANALYTIC=4, ANALYTIC=14 y ANALYTIC=40, dos veces cada uno. Hagan una tabla con el throughput y el p99 de las lecturas por id. ¿A partir de qué valor el efecto es mayor que la diferencia entre dos corridas iguales? ¿Qué relación tiene ese valor con el número de núcleos de su máquina (nproc)?

  3. Un sistema de préstamos de una biblioteca tiene: la tabla de préstamos en PostgreSQL, un contador de “libros prestados hoy” en Redis, un índice de búsqueda del catálogo, y una hoja de cálculo donde la bibliotecaria corrige a mano las multas. Clasifiquen cada uno como sistema de registro o dato derivado, digan qué pasa si se pierde, y encuentren el que está mal clasificado en la práctica aunque nadie lo haya decidido.

  4. En make timeline, cambien el número de usuarios (USERS=2000 y USERS=20000). ¿Cómo cambia el costo de publicar desde la cuenta 1 con fan-out? Escriban la relación con una fórmula. Después propongan un umbral de seguidores a partir del cual una cuenta debería dejar de repartir al escribir, y digan qué dato de carga necesitarían para defenderlo.

  5. Para la disponibilidad de un evento en Tinkuy, escriban el ADR de la decisión entre contar en cada lectura y mantener el número al vender: contexto (con los parámetros de carga), las dos opciones, y las consecuencias de cada una. No escriban código. ¿Qué medirían antes de decidir?

  6. Un taller mecánico guarda fichas de vehículos. Cada ficha tiene los datos del vehículo, una lista de órdenes de trabajo, y cada orden una lista de repuestos usados. Las consultas frecuentes son “abre la ficha de este vehículo” y “¿en qué vehículos se instaló este repuesto en el último mes?”. Digan qué modelo hace fácil cada una, qué dato quedaría copiado en el modelo de documentos, y si esa copia es un defecto o un hecho histórico.

  7. Para cada cambio, digan si es compatible hacia atrás, hacia adelante, ambas o ninguna, y quién lo notaría: (a) la respuesta de GET /orders/:id agrega paidAt; (b) POST /orders empieza a exigir phone; (c) totalCents pasa de número a texto; (d) status empieza a devolver también 'refunded'; (e) la lista de órdenes pasa a ordenarse por fecha en vez de por id. Para (d) y (e), relacionen su respuesta con el lector tolerante y con la ley de Hyrum.

  8. Modifiquen una copia de formats/tagged.ts para que el esquema v2 quite el campo buyerName. Muestren con una prueba qué lee un lector v1 de un mensaje v2, y qué pasa si, un año después, alguien define un campo nuevo con la etiqueta 2 y tipo entero. ¿Qué mecanismo de Protocol Buffers existe para impedir lo segundo?

  9. Una tabla payments recibe escrituras todo el día y su columna id es integer; se va a quedar sin números. Escriban los pasos para pasarla a bigint sin detener el servicio: qué se agrega, quién escribe en qué durante la transición, cómo se copian los datos, y cuál es el paso que no se puede deshacer. Indiquen en qué pasos usarían lock_timeout y por qué.

  10. El backfill del laboratorio parte “Luz Marina Flores” en nombre “Luz” y apellido “Marina Flores”. Propongan dos maneras de tratar las 51 686 filas dudosas, una que no requiera a ninguna persona y otra que sí, con lo que cuesta cada una. ¿Cambia su respuesta si el nombre se usa solo para saludar en un correo, o si se imprime en un comprobante?

  11. Un equipo dice: “mantenemos /v1 y /v2 de la API, así nunca rompemos a nadie”. Tienen 40 endpoints, tres clientes propios y unos 200 clientes externos. Escriban qué les preguntarían para saber si esa decisión les conviene, y describan cómo se vería el mismo cambio que motivó /v2 hecho con expandir, migrar y contraer. ¿Para qué clase de cambio le darían la razón al equipo?