Migraciones versionadas

El esquema de una base de datos es código, aunque casi nadie lo trate así. Cada CREATE TABLE, cada índice, cada columna nueva es una decisión que debería vivir en el repositorio, revisarse en un pull request y desplegarse con la misma disciplina que una función. Cuando el esquema se edita a mano desde un panel, se vuelve estado oculto: nadie sabe con certeza qué versión corre en producción, cómo llegó ahí ni cómo deshacerlo. Las migraciones versionadas de D1 cierran esa grieta al convertir cada cambio en un archivo .sql numerado, ordenado e irrepetible.

El esquema como código

Una migración es una unidad de cambio de esquema con nombre, número e historia. En lugar de teclear un ALTER TABLE contra la base y olvidarlo, escribes ese ALTER TABLE en un archivo, lo numeras y lo guardas junto al código. La carpeta migrations —creada en la raíz del proyecto la primera vez que generas una— pasa a ser la definición autoritativa del esquema: la secuencia de archivos, leída en orden, reconstruye la estructura de la base desde cero.

El valor de esto no es burocrático, es epistemológico. Un esquema editado a mano no tiene respuesta a la pregunta de cómo se llegó a ese estado. Un esquema versionado sí: es la suma de sus migraciones, cada una revisable en su pull request, atribuible a un commit y reproducible en cualquier entorno. La base de desarrollo, la de staging y la de producción convergen a la misma forma porque aplican la misma lista de archivos.

Conviene subrayar qué no es una migración de D1: no es un ORM que infiere cambios comparando dos estados del esquema, ni una herramienta que revierte sola. Es más primitiva y, por eso, más honesta: un archivo de SQL que tú escribes y que se ejecuta tal cual. Esa primitividad es una virtud, porque no hay comportamiento oculto entre lo que lees en el pull request y lo que le ocurre a la base.

La contrapartida de esa transparencia es responsabilidad: como D1 no infiere ni revierte por ti, eres tú quien garantiza que el SQL de cada migración sea correcto y compatible con los datos existentes. La herramienta te da control total y, con él, la obligación de pensar cada cambio. Es el mismo trato que ofrece un buen sistema de tipos: no te ahorra decidir, te protege de olvidar lo que decidiste.

Crear la migración

wrangler d1 migrations create genera un archivo vacío con el siguiente número de la secuencia y el mensaje que le des:

npx wrangler d1 migrations create mi-base "crear tabla usuarios"
# crea migrations/0001_crear_tabla_usuarios.sql

El archivo nace vacío; tú escribes el SQL del cambio. Aquí no hay introspección ni magia: una migración es exactamente el SQL que redactas, lo que la vuelve transparente y auditable.

-- migrations/0001_crear_tabla_usuarios.sql
CREATE TABLE usuarios (
  id         INTEGER PRIMARY KEY,
  email      TEXT NOT NULL UNIQUE,
  creado_en  INTEGER NOT NULL DEFAULT (unixepoch())
);
CREATE INDEX idx_usuarios_email ON usuarios(email);

El número al frente del nombre no es decorativo: fija el orden total en que las migraciones se aplican. La 0002 va después de la 0001, siempre, en todos los entornos. Ese orden es lo que garantiza que la base llegue a la misma forma sin importar desde qué punto parta.

Una migración típica no crea tablas desde cero, sino que evoluciona lo existente. Añadir una columna es el caso más común, y la clave para que sea segura es darle un valor por defecto: así las filas que ya existen quedan bien definidas sin tocarlas una a una.

-- migrations/0002_anadir_estado_a_pedidos.sql
ALTER TABLE pedidos ADD COLUMN estado TEXT NOT NULL DEFAULT 'pendiente';
CREATE INDEX idx_pedidos_estado ON pedidos(estado);

Cada archivo hace una cosa nombrable —añadir el estado de un pedido— y su nombre lo dice. Cuando dentro de seis meses alguien lea el historial, la secuencia de nombres contará la evolución del producto tan bien como el propio código; una migración sin mensaje claro es una entrada de diario sin fecha.

Aplicar: local y remoto

Aplicar es ejecutar contra la base las migraciones que aún no se han aplicado. El comando distingue dos mundos:

# base local: un SQLite en .wrangler/state, para desarrollar
npx wrangler d1 migrations apply mi-base --local

# base real, la que usan tus Workers desplegados
npx wrangler d1 migrations apply mi-base --remote

--local toca un archivo SQLite en .wrangler/state: rápido, desechable, ideal para iterar. --remote toca la base de producción. Antes de aplicar, wrangler d1 migrations list te dice qué migraciones quedan pendientes, para que nunca despliegues a ciegas.

npx wrangler d1 migrations list mi-base --remote

El flujo maduro es una tubería: editas el .sql, aplicas en local y corres tus pruebas, abres el pull request donde el diff del esquema se revisa como cualquier código, y solo tras el merge aplicas en --remote como un paso más del despliegue.

Solo hacia adelante

D1 lleva la cuenta de lo aplicado en una tabla real dentro de tu base, d1_migrations. Cada vez que apply ejecuta un archivo, escribe su nombre ahí; en la siguiente corrida, salta lo ya anotado. De esa idempotencia sale una consecuencia dura: las migraciones no tienen down, solo up. El historial avanza, nunca retrocede.

Esto obliga a pensar cada cambio como irreversible en el sentido operativo. Un cambio destructivo —soltar una columna, renombrar una tabla— no se deshace con un rollback; se corrige con una migración nueva que lo compense, o se restaura la base entera con Time Travel. Por eso el patrón profesional para cambios peligrosos es expandir y contraer: primero añades lo nuevo en una migración, migras los datos y el código en otra, y solo cuando nada usa lo viejo lo retiras en una tercera.

# no se edita la 0007 ya aplicada; se compensa con la 0008
npx wrangler d1 migrations create mi-base "revertir columna sobrante"

El libro solo crece, y esa es precisamente la garantía: cualquiera puede reconstruir el estado actual releyéndolo entero, sin depender de qué se tecleó a mano en qué consola.

Hay un corolario operativo que vale oro en equipos: como el estado de la base es la lista de migraciones aplicadas, poner al día un entorno nuevo —la máquina de un compañero, un staging recién creado— es un solo comando, migrations apply, que reproduce la historia entera. No se copian bases; se replican historias.

Y cuando un entorno se corrompe, no se restaura desde una copia frágil: se recrea desde cero aplicando la historia, o se rebobina con Time Travel. Dos redes de seguridad que nacen de la misma idea —tratar los cambios como hechos registrados—.