Evolución de esquemas, migraciones y compatibilidad

Por qué los esquemas deben evolucionar sin detener el mundo

Todo dato almacenado o transmitido tiene un esquema: las tablas y los tipos de columna de una base de datos, los campos de una respuesta JSON de una API, la definición del registro de un evento en un flujo. Los esquemas cambian constantemente porque el negocio cambia: el banco añade un segundo titular de cuenta, la plataforma de reparto de comida empieza a registrar las propinas, un regulador exige un campo nuevo. La pregunta arquitectónica es cómo cambiar un esquema mientras el sistema sigue funcionando, cuando la forma antigua la siguen usando el código, los datos almacenados y otros equipos.

Tres hechos lo hacen difícil. Primero, en cualquier sistema que se despliega sin tiempo de inactividad, las versiones antigua y nueva del código se ejecutan en paralelo: un despliegue gradual (rolling deployment) sustituye las instancias una a una, un canary release (lanzamiento canario) envía una pequeña parte del tráfico a la nueva versión y un rollback trae de vuelta la versión antigua. Por tanto, cada estado del esquema debe funcionar con al menos dos versiones del código. Segundo, los datos sobreviven al código. Las filas escritas hace cinco años, los eventos de un log que se conservan para siempre, los mensajes que esperan en una cola y las copias de seguridad conservan todos la forma antigua. Tercero, los esquemas se comparten: una columna la leen informes, trabajos de extracción y a veces otros servicios, y un esquema de eventos lo leen consumidores que el productor quizá ni siquiera conozca. La Sección 7.1 defendía que los datos tengan un propietario y estén detrás de una interfaz; la evolución de esquemas es donde esa disciplina da sus frutos, porque un esquema privado puede cambiarse con el acuerdo de un solo equipo.

Compatibilidad hacia atrás, hacia adelante y completa

La compatibilidad se define en términos de lectores y escritores. Un cambio es compatible hacia atrás cuando el código que usa el esquema nuevo puede leer datos escritos con el antiguo. Añadir un campo opcional con un valor por defecto es compatible hacia atrás: el lector nuevo aporta el valor por defecto cuando a los datos antiguos les falta el campo. Un cambio es compatible hacia adelante cuando el código que usa el esquema antiguo puede leer datos escritos con el nuevo. Eso exige que los lectores antiguos ignoren los campos que no conocen, que es la disciplina del lector tolerante (tolerant reader). Un cambio es totalmente compatible cuando es ambas cosas, lo que significa que lectores y escritores pueden actualizarse en cualquier orden.

La dirección que necesitas depende de quién se actualiza primero. Si los consumidores se actualizan antes que los productores (algo habitual cuando un flujo tiene pocos consumidores y los controlas tú), necesitas compatibilidad hacia atrás. Si los productores se actualizan primero, que es el caso habitual en una base de datos (el código nuevo empieza a escribir antes de que se hayan vuelto a desplegar todos los lectores) y en las API públicas, necesitas compatibilidad hacia adelante. Cuando no puedes controlar el orden, o necesitas revertir cualquiera de los dos lados, apunta a la compatibilidad completa. Confluent Schema Registry, por ejemplo, usa por defecto la compatibilidad hacia atrás comprobada contra la versión anterior y ofrece variantes transitivas que comprueban contra todas las versiones anteriores, lo que importa cuando los consumidores pueden reproducir datos antiguos desde el principio de un log.

Una advertencia sobre el vocabulario. En el diseño de API, compatible hacia atrás se usa a menudo de forma laxa con el sentido de los clientes existentes siguen funcionando, lo que, en términos de lectores y escritores, es compatibilidad hacia adelante para los clientes que leen tus respuestas y compatibilidad hacia atrás para las solicitudes que tú lees de ellos. Cuando una discusión depende del término, pregunta qué lado cambia y qué lado debe seguir funcionando.

Expandir y contraer: la técnica central

La mayoría de los cambios incompatibles pueden dividirse en una secuencia de cambios compatibles. El patrón se llama expandir y contraer (expand and contract), o cambio en paralelo (parallel change; la descripción de Danilo Sato de 2014 en martinfowler.com llama a las fases expandir, migrar y contraer). Primero, expandir: añadir la nueva estructura junto a la antigua, de modo que funcionen tanto el código antiguo como el nuevo. Después, migrar: cambiar los escritores para que mantengan ambas, copiar los datos existentes y pasar los lectores a la nueva estructura uno a uno. Por último, contraer: cuando ya nada usa la estructura antigua, eliminarla. Cada paso se despliega por separado, cada uno es compatible con la versión anterior y cada uno puede revertirse sin perder datos.

El costo es tiempo y un desorden temporal: el cambio abarca varios lanzamientos y, durante días o semanas, el esquema lleva las dos formas. La ventaja es que ningún lanzamiento necesita tiempo de inactividad, ningún despliegue necesita coordinarse entre equipos y cualquier paso puede pausarse. Refactoring Databases (2006), de Scott Ambler y Pramod Sadalage, cataloga decenas de refactorizaciones de bases de datos basadas en la misma idea, con un periodo de transición durante el cual coexisten los esquemas antiguo y nuevo, sincronizados por la aplicación o mediante triggers.

-- Migration V41 (expand): metadata-only change, no table rewrite in PostgreSQL 11+
SET lock_timeout = '3s';            -- fail fast rather than queue behind long queries
ALTER TABLE restaurants ADD COLUMN postal_code text;

-- Backfill job (run repeatedly by a script, not inside one big migration)
UPDATE restaurants
SET    postal_code = postcode
WHERE  id >= :from_id AND id < :from_id + 5000   -- one small batch per transaction
AND    postal_code IS DISTINCT FROM postcode;

-- Verify before switching reads
SELECT count(*) FROM restaurants WHERE postal_code IS DISTINCT FROM postcode;  -- expect 0

-- Migration V44: enforce NOT NULL without a long blocking scan
ALTER TABLE restaurants ADD CONSTRAINT postal_code_nn CHECK (postal_code IS NOT NULL) NOT VALID;
ALTER TABLE restaurants VALIDATE CONSTRAINT postal_code_nn;  -- scans, but allows writes
ALTER TABLE restaurants ALTER COLUMN postal_code SET NOT NULL;  -- PostgreSQL 12+: uses the check, skips scan
ALTER TABLE restaurants DROP CONSTRAINT postal_code_nn;

-- Migration V45 (contract), weeks later, once nothing reads postcode
ALTER TABLE restaurants DROP COLUMN postcode;

Las migraciones como código en el pipeline de entrega

Los cambios en la base de datos deben estar en el control de versiones junto al código de la aplicación, como una serie ordenada de migraciones, cada una un pequeño script que lleva el esquema de una versión a la siguiente. Evolutionary Database Design, de Pramod Sadalage y Martin Fowler (publicado por primera vez en 2003 y reescrito en 2016), estableció la práctica, y las herramientas están maduras. Flyway ejecuta en orden archivos SQL versionados como V41__add_postal_code.sql y registra cada uno en una tabla flyway_schema_history. Liquibase describe los cambios como changesets en SQL, XML, YAML o JSON, de los que lleva registro en una tabla DATABASECHANGELOG. Alembic, para Python y SQLAlchemy, genera scripts de revisión con funciones upgrade() y downgrade() y registra la revisión actual en alembic_version. Flyway y Liquibase también guardan una suma de comprobación (checksum) de cada migración aplicada y se detienen con un error si alguna se ha editado después, lo que evita que los entornos diverjan sin que nadie lo note.

En un pipeline de entrega continua, las mismas migraciones se ejecutan contra una base de datos nueva en las pruebas, después contra staging y después contra producción, de modo que producción nunca recibe un cambio que no se haya ensayado. Las buenas prácticas añaden algunas reglas. Nunca edites una migración que se haya aplicado en algún sitio; escribe una nueva. Mantén los cambios de esquema y el código que depende de ellos en despliegues separados, con el cambio de esquema primero en las expansiones y al final en las contracciones. Prueba las migraciones con una copia de datos de tamaño de producción, porque una sentencia que tarda 50 ms en una base de datos de pruebas puede bloquear una tabla grande durante una hora. Prefiere avanzar con una migración nueva antes que usar migraciones descendentes que eliminan columnas y, con ellas, datos. Y deja que la base de datos te avise de los bloqueos: en PostgreSQL, un ALTER TABLE que espera su bloqueo bloquea todas las consultas que llegan después, así que establece un lock_timeout corto y reintenta en lugar de quedarte en cola detrás de un informe de larga duración.

Backfills grandes y cambios de esquema en línea

Un backfill (relleno de datos) rellena una columna o tabla nueva para las filas existentes. Hecho como un único UPDATE sobre 400 millones de transacciones, mantiene bloqueos durante horas, genera un enorme volumen de registro de escritura anticipada (write-ahead log, WAL) que las réplicas deben reproducir (lo que provoca retardo de replicación) y, en PostgreSQL, deja versiones de fila muertas que el vacuum debe limpiar. El enfoque profesional es un trabajo separado y reiniciable que procesa lotes pequeños por rango de clave primaria, confirma cada lote, registra su progreso, reduce su ritmo cuando aumentan el retardo de replicación o la carga de la base de datos, y es idempotente, de modo que volver a ejecutar un lote no causa ningún daño. Ejecútalo fuera de la herramienta de migraciones, para que un despliegue nunca tenga que esperarlo.

Algunos cambios no pueden hacerse en el sitio sin bloquear. PostgreSQL ofrece CREATE INDEX CONCURRENTLY (que no puede ejecutarse dentro de un bloque de transacción, así que hay que indicárselo a las herramientas de migración) y la secuencia NOT VALID seguida de VALIDATE CONSTRAINT mostrada arriba. Para MySQL, herramientas como gh-ost y pt-online-schema-change construyen una copia en la sombra de la tabla con el esquema nuevo, la mantienen sincronizada con las escrituras en curso y la ponen en su lugar con un breve cambio de nombre. Cambiar el tipo de una columna suele hacerse mejor con expandir y contraer hacia una columna nueva que con un ALTER en el sitio, que en la mayoría de las bases de datos reescribe toda la tabla.

Registros de esquemas, Avro y Protocol Buffers

Para los eventos y los mensajes, el equivalente de una herramienta de migraciones es un registro de esquemas. Los productores registran cada versión del esquema; el registro la comprueba contra la regla de compatibilidad configurada y rechaza un cambio incompatible en el momento de la compilación o del despliegue, en lugar de en producción. Cada mensaje lleva un identificador de esquema corto, de modo que los consumidores pueden obtener el esquema exacto con el que se escribió.

Apache Avro hace explícito el esquema del escritor: para decodificar se necesitan tanto el esquema del escritor como el del lector, y las reglas de resolución de Avro emparejan los campos por nombre, ignoran los campos del escritor que el lector no conoce y rellenan los campos del lector que faltan en los datos con sus valores por defecto declarados. De ahí la regla práctica: da un valor por defecto a todo campo que puedas añadir o eliminar. En el ejemplo de abajo, currency y tip_pence se añadieron en versiones posteriores con valores por defecto, así que los eventos antiguos se siguen decodificando con los consumidores nuevos.

Protocol Buffers identifica los campos por número, no por nombre, en la transmisión. Añadir campos es seguro, y los lectores antiguos conservan los campos desconocidos al volver a serializar. Renombrar un campo no afecta a la codificación binaria (aunque sí cambia la forma JSON). Las reglas fundamentales son no cambiar ni reutilizar nunca un número de campo, y marcar los números y nombres de los campos eliminados como reserved para que nadie los reutilice por accidente. Confluent recomienda la compatibilidad hacia atrás transitiva para Protobuf, porque añadir un tipo de mensaje nuevo no es compatible hacia adelante. También se puede registrar y comprobar JSON Schema, pero la apertura de JSON (¿se permite o no una propiedad desconocida?) hace que las reglas de compatibilidad sean más sutiles.

{
  "type": "record",
  "name": "OrderPlaced",
  "namespace": "food.orders.v1",
  "fields": [
    {"name": "order_id",       "type": "string"},
    {"name": "restaurant_id",  "type": "string"},
    {"name": "total_pence",    "type": "long"},
    {"name": "currency",       "type": "string", "default": "GBP"},
    {"name": "tip_pence",      "type": ["null", "long"], "default": null}
  ]
}

Evolución de los esquemas de API y de eventos

Las API y los eventos siguen los mismos principios con herramientas distintas. En las API, prefiere los cambios aditivos, exige que los clientes sean lectores tolerantes y reserva los cambios incompatibles para una versión nueva que se ejecute junto a la antigua, con monitorización del uso para ver cuándo puede retirarse la versión antigua (la Sección 6.5 trata los enfoques de versionado). Las pruebas de contratos dirigidos por el consumidor permiten que cada consumidor publique los campos de los que realmente depende, de modo que el proveedor sabe qué cambios son seguros.

Los eventos son más difíciles que las API porque se almacenan: un consumidor puede reproducir un topic desde el principio, y un sistema basado en event sourcing (Sección 7.5) reconstruye el estado a partir de eventos escritos hace años. Trata un esquema de eventos publicado como un contrato público, versiónalo en el registro y, cuando un cambio sea realmente incompatible, publica un tipo de evento o un topic nuevo (OrderPlaced.v2) durante un tiempo junto al antiguo, en lugar de modificar el existente. La Sección 6.4 trata el diseño de eventos de forma más general.