El skill de migración de base de datos: generar el forward + rollback con los chequeos de seguridad por delante

Los cambios de esquema son donde hasta el ingeniero más tranquilo entra en pánico. El ALTER que se veía inofensivo en una base de prueba toma un lock exclusivo sobre una tabla de 40 millones de filas en producción, la app empieza a dar timeout, y de repente estás leyendo la documentación de locks de Postgres mientras el celular no para de vibrar. Un skill de migración existe para llevar ese análisis a antes de que escribas el comando, no después. Al terminar esto vas a tener un skill de Claude Code empaquetado que inspecciona el esquema en vivo, escribe una migración forward y su rollback, y te entrega un informe de riesgo que dice exactamente cuáles sentencias bloquean la tabla o borran datos, para que la parte fea sea una revisión y no una sorpresa.

Esto no es magia. Es un checklist con dientes, conectado a las herramientas para que el modelo lea tu esquema real en vez de adivinarlo. Todo el valor está en que lo peligroso se clasifica al principio, en lenguaje claro, donde tú puedes vetarlo.

01 · Qué hace el skill en realidad

Un skill de migración toma un cambio de esquema descrito, "agrega una columna bio nullable a profiles", "cambia amount de integer a numeric", "pon email NOT NULL", y produce tres artefactos:

1. La migración forward: el SQL que aplica el cambio.
2. El rollback: la migración de bajada que lo revierte, escrita en el momento, no prometida para después.
3. El informe de riesgo: cada sentencia clasificada por radio de impacto, con su comportamiento de lock y cualquier pérdida de datos resumidos en una línea cada uno.

Lo que importa es el tercer artefacto. Un ALTER TABLE … ADD COLUMN lo escribe cualquiera. El skill se gana el sueldo cuando te avisa, antes de que corras nada, que esta sentencia en particular reescribe la tabla entera y mantiene un lock todo ese rato. Es la diferencia entre una migración que puedes leer y una puerta de un solo sentido que cruzas a ciegas.

02 · Cuándo debe dispararse

El skill se dispara por la intención de cambiar una tabla, no por la palabra "migración". Su descripción debe hacer que Claude lo agarre cada vez que la conversación se mete a alterar esquema. Una buena redacción de disparo, puesta en la descripción del skill para que se active sin que tú lo nombres:

---
name: db-migration
description: >-
  Úsalo cuando el usuario quiera cambiar un esquema de Postgres/Supabase:
  agregar o eliminar una columna, cambiar el tipo de una columna, agregar
  una constraint o NOT NULL, renombrar, agregar un índice o alterar una
  tabla. Genera una migración forward revisada, un rollback y un informe
  de riesgo de locks y pérdida de datos. Se dispara con "agrega una
  columna", "cambia este tipo", "pon esto NOT NULL", "agrega un índice",
  "elimina", "renombra columna".
---

Las frases de la descripción pesan más que la prosa que las rodea. "Cambia este tipo", "pon esto NOT NULL", "elimina una columna" son justo lo que dice un dev segundos antes de provocar un incidente, así que esas son las frases que deben activar el skill.

No debe dispararse con un SELECT puro, una query de solo lectura ni una pregunta sobre los datos. Eso son tareas de reporte, no cambios de esquema, y un skill de migración activándose ahí solo agrega fricción. Acótalo bien a DDL.

03 · Cómo funciona por dentro

El skill corre una secuencia fija. El orden es el mecanismo de seguridad: inspecciona, luego escribe, luego clasifica, y al final se niega a saltarse el rollback.

1. Inspecciona el esquema en vivo primero

Antes de escribir una sola línea, el skill lee el estado actual. Con Supabase eso significa «list_tables» (y «list_migrations» para ver qué ya está aplicado), así escribe contra la realidad y no contra un esquema imaginado. Una migración generada contra un tipo de columna adivinado es peor que no tener migración.

2. Escribe la migración forward

Produce el SQL de subida, acotado exactamente al cambio descrito. Nada de ediciones de paso, nada de "ya que estoy aquí" limpiando otra cosa: un solo cambio lógico, para que el rollback quede simple y la revisión quede honesta.

3. Clasifica cada sentencia

Este es el núcleo. Cada sentencia recibe una etiqueta:

• Segura en línea, agregar una columna nullable, crear un índice con CONCURRENTLY, eliminar un índice con concurrently. No toman un lock pesado ni reescriben filas.
• Riesgosa, cambiar el tipo de una columna, agregar NOT NULL sin default, agregar una foreign key sin NOT VALID primero. Pueden reescribir la tabla y bloquear escrituras.
• Destructiva, eliminar una columna, eliminar una tabla, truncar. Pierden datos, y el rollback puede restaurar la estructura pero no las filas.

4. Escribe el rollback al mismo tiempo

La migración de bajada se escribe en la misma pasada, no se deja para después. Si el cambio es destructivo y un rollback de verdad es imposible (no puedes "des-eliminar" los datos), el skill lo dice de frente en vez de fingir que un CREATE TABLE trae las filas de vuelta.

Para los cambios riesgosos propone el patrón de dos pasos en vez de un ALTER de un solo golpe:

-- Subida (paso 1 de 2): agregar nullable, backfill por lotes, luego restringir.
-- Agregar NOT NULL directo escanea + bloquea la tabla entera de una vez.
alter table profiles add column status text;

update profiles set status = 'active' where status is null;  -- por lotes en la app

alter table profiles
  add constraint profiles_status_not_null
  check (status is not null) not valid;     -- NOT VALID se salta el scan completo
alter table profiles validate constraint profiles_status_not_null;

Todo el truco está en separar NOT VALID del VALIDATE: la constraint empieza a aplicar a las filas nuevas de inmediato bajo un lock liviano, y el costoso scan de toda la tabla queda para el VALIDATE, que toma un lock mucho más débil y no bloquea las escrituras.

04 · Una invocación concreta

Así se ve usarlo de punta a punta. Tú describes el cambio en lenguaje natural; el skill hace la inspección y produce los tres artefactos.

Tú: "Pon profiles.email único y obligatorio."

El skill, después de correr «list_tables»:

INFORME DE RIESGO: profiles.email → UNIQUE + NOT NULL

1. CREATE UNIQUE INDEX CONCURRENTLY ... (email)   [SEGURO EN LINEA]
   No reescribe la tabla. Se construye sin bloquear escrituras.
   AVISO: falla si ya existen emails duplicados; revisa primero.

2. ADD NOT NULL                                    [RIESGOSO]
   El NOT NULL directo escanea + bloquea la tabla. En su lugar uso
   el patron de dos pasos check NOT VALID + VALIDATE (ver migracion).

PRECONDICION: se encontraron 3 emails duplicados. La migracion va a
fallar en el paso 1 hasta que se resuelvan. Query de de-dupe abajo.

Después emite la migración de subida, la de bajada y la query de de-dupe, y se detiene. No las corre. Tú lees el informe, arreglas los duplicados, corres el SQL en una rama de Supabase, confirmas que ambas direcciones funcionan, y solo entonces haces merge al proyecto que toca producción.

05 · Configuración y ajuste

Un par de settings cambian qué tan cauteloso es el skill. Mételos en sus instrucciones para que el comportamiento sea consistente de una corrida a otra:

• Entorno destino, stack local vs. una rama de Supabase vs. (nunca) remoto. Por defecto déjalo en "solo generar", y que aplicar en remoto sea un paso aparte y deliberado que toma un humano.
• Umbral de lote, para los backfills, el número de filas a partir del cual cambia de un solo UPDATE a un loop por lotes. En una tabla grande, un solo update es por sí mismo un problema de lock.
• Tolerancia a locks, si un lock breve ACCESS EXCLUSIVE es aceptable (una tabla pequeña con poco tráfico) o hay que evitarlo del todo (una tabla con mucho tráfico). Esto decide si recurre al patrón de dos pasos o acepta el de un solo golpe, más simple.
• Operaciones prohibidas, operaciones que el skill debe negarse a generar sin una autorización explícita, por ejemplo DROP TABLE o TRUNCATE en una migración pensada para producción.

La configuración existe para que el skill calce con tu tolerancia al riesgo. Una tabla de un proyecto personal con 200 filas y una tabla multi-tenant con 40 millones no merecen la misma cautela, y forzar el patrón de dos pasos en la pequeña es puro trámite.

06 · Trampas

Los modos de falla aquí son específicos, y casi todos vienen de confiar de más.

• Nunca dejes que lo aplique directo a un proyecto remoto. Esta es la regla de oro. Genera el SQL, léelo, córrelo primero en una rama o en local. Un skill con «apply_migration» conectado a producción está a un solo error de confianza de provocar un outage.
• Exige el plan de backfill en el mismo PR. Cualquier cambio que toque filas existentes necesita su plan de migración de datos revisado junto al cambio de esquema, no agregado después, cuando la columna ya quedó a medio llenar.
• Un rollback que no restaura datos no es un rollback. Para los cambios destructivos, el skill debe decir con claridad que la migración de bajada restaura la estructura, no las filas. No dejes que insinúe que puedes deshacer un DROP COLUMN sin perder nada, no puedes.
• «CREATE INDEX CONCURRENTLY» no corre dentro de una transacción. Si tu runner de migraciones envuelve todo en una transacción por defecto, la construcción del índice concurrente va a fallar. El skill debe avisar cuándo una sentencia tiene que correr fuera del bloque de transacción.
• Va a estar seguro de sí mismo y equivocado sobre tu esquema si se salta la inspección. Obliga el paso de «list_tables» primero. Una migración escrita contra un tipo de columna adivinado es la salida más peligrosa que puede producir, justamente porque se ve correcta.

Un skill de migración no va a volver los cambios de esquema libres de riesgo, nada lo logra. Lo que te da es que el riesgo quede visible antes de actuar: clasificado, con el comportamiento de lock nombrado, el rollback escrito y las precondiciones revisadas. Genera, lee, prueba en una rama, promueve. Hazlo así y el ALTER de las 11 de la noche en producción deja de ser algo que te pasa a ti.