La respuesta corta
Las migraciones de base de datos en el deploy son un solo paso de release. Corren una vez, antes de que la versión nueva reciba tráfico. No son parte del build de la imagen, y no son parte del arranque de cada réplica.
Un rollback de ese código no deshace el schema. No hay un comando que devuelva la base. El cambio se diseña para que el release anterior siga funcionando: expandir, copiar los datos y después contraer. En Unbroker ese paso es el comando pre-deploy, y los comandos de migración requieren Pro.
Dónde corre la base es otra decisión: un contenedor que operás vos, o un clúster gestionado. Ese mapa está en Docker Compose en producción y en Postgres gestionado. Operar el servidor está en Postgres en producción.
Tres lugares para las migraciones de base de datos en el deploy
La migración se corre en uno de tres lugares. Dos se rompen cuando hay más de un build, o más de una copia de la app.
Migraciones en el build de Docker
El Dockerfile corre la migración mientras se construye la imagen. Eso pasa en cada build, no una vez para el release que está por salir.
La guía de Django dice que corras las migraciones una vez, como paso de release controlado, con las credenciales de runtime. Dice que evites ponerlas en el build de la imagen. La guía de FastAPI dice que no corras migraciones durante el build de la imagen.
En el arranque de cada réplica
El proceso migra y después sirve. Cada copia hace lo mismo. Esas copias pueden correr al mismo tiempo y compiten por el mismo cambio de schema. La guía de Django dice que evites correr migraciones en competencia en cada proceso web.
Una vez, antes de que la versión nueva reciba tráfico
Un comando, desde la imagen nueva, antes de que llegue el tráfico. Ese es el paso de release. Hay que correr las migraciones antes del deploy, no después de que el código nuevo ya está sirviendo. En Unbroker ese comando es el pre-deploy. En Heroku ese paso es la línea release del Procfile. El mapa de cada línea está en Procfile de Heroku, línea a línea.
Qué tiene que hacer el comando pre-deploy
El comando aplica el schema una vez y termina. Escribilo para que una segunda corrida no haga nada si el schema ya está en esa versión. Un release posterior puede llamarlo cuando no hay nada nuevo para aplicar.
Definí lock_timeout en la sesión que corre la migración, para que una espera de lock termine en vez de quedarse sobre la tabla. No lo pongas en postgresql.conf. PostgreSQL dice que eso afectaría a todas las sesiones. El default es 0, que apaga el timeout. Si omitís la unidad, el número es en milisegundos. El '1s' de abajo ilustra la sintaxis. No es un default de PostgreSQL ni un valor de Unbroker.
SET lock_timeout = '1s';
Si la migración falla, el comando tiene que salir con un código distinto de cero. Imprimí qué migración corrió y el error. No imprimas el connection string. Después leé el log de ese deployment. La documentación y el changelog no dicen qué le hace un pre-deploy fallido a la versión que ya está live.
Los secretos van en variables de entorno, no en el texto del comando. La sección de post-deploy en la documentación de deployments dice esa regla para el comando post-deploy, y dice que el comando no se imprime en el log. Usá el mismo criterio para el pre-deploy. El ejemplo del changelog es npm run db:migrate.
Un rollback no deshace la migración
ubctl apps rollback promueve un deployment conocido. No reconstruye el commit de origen. La documentación de deployments lo muestra con un id de servicio y un id de deployment:
ubctl apps rollback svc_123 dep_previous
Esos dos argumentos son el servicio y el deployment que estás promoviendo. Los rollbacks no vuelven a correr el comando pre-deploy, así que la migración tiene que seguir siendo compatible con el código anterior. Eso está en el changelog del 1 de agosto.
Volver a una imagen anterior no deshace cambios de configuración, escrituras en la base, datos de un volumen ni efectos externos. La documentación de infrastructure as code dice que mantengas el rollback separado de las migraciones. Un restore que ya corriste sigue siendo el camino de vuelta a las filas viejas. Ese control está en Postgres en producción.
Expand and contract, un release por vez
El caso típico es un rename. Querés que name pase a ser full_name. Si el cambio de código y el drop van en el mismo release, un rollback levanta el código viejo contra una columna que ya no está.
Es el patrón de parallel change, también llamado expand and contract. Una migración expand and contract parte el cambio en tres fases: expandir, migrar y contraer. Cada release tiene que funcionar con el anterior.
- Expandir. Sumá
full_name. El código nuevo escribe las dos columnas y sigue leyendoname. El código viejo solo conocename, así que un rollback sigue corriendo.
ALTER TABLE users ADD COLUMN full_name text;
Agregar una columna con un default no volátil guarda ese valor en los metadatos de la tabla y no la reescribe. Sin default, PostgreSQL usa NULL y también se saltea la reescritura. Un default volátil, como clock_timestamp(), reescribe la tabla y sus índices. La mayoría de las formas de ALTER TABLE toman un lock ACCESS EXCLUSIVE, salvo que la documentación anote uno más débil. El lock está en la sección de abajo.
- Migrar. Copiá las filas existentes en lotes, con un comando de una vez o un job programado, no adentro de cada request. El código nuevo lee
full_namey sigue escribiendoname, así que un rollback al release de expand sigue viendo las escrituras nuevas enname.
UPDATE users
SET full_name = name
WHERE id IN (
SELECT id FROM users
WHERE full_name IS NULL
LIMIT 1000
);
El 1000 es el tamaño del lote en el ejemplo. No es un setting de PostgreSQL. Repetilo hasta que no quede una fila con full_name nulo.
- Contraer. El código nuevo lee y escribe solo
full_name. Dejánameen su lugar. Tirala en un release posterior, cuando ya no vayas a volver a un release que todavía la lee o la escribe.
ALTER TABLE users DROP COLUMN name;
DROP COLUMN vuelve la columna invisible para SQL. No achica la tabla en disco en el momento. Las actualizaciones posteriores recuperan ese espacio cuando reescriben las filas. La fuente del comportamiento de la columna y del drop es ALTER TABLE.
Operaciones de Postgres que toman lock
Un ALTER TABLE toma un lock ACCESS EXCLUSIVE, salvo que la forma que uses diga otra cosa. Varios subcomandos en la misma sentencia toman el lock más estricto que pida cualquiera de ellos.
ADD FOREIGN KEY es una excepción: toma SHARE ROW EXCLUSIVE en la tabla que alterás y en la tabla referenciada. Agregar un check o un not-null escanea la tabla, y las otras actualizaciones esperan hasta que esa sentencia hace commit. NOT VALID se saltea ese escaneo. Un VALIDATE CONSTRAINT posterior toma SHARE UPDATE EXCLUSIVE y no bloquea las actualizaciones concurrentes. La fuente es ALTER TABLE.
Un CREATE INDEX normal bloquea las escrituras, y no las lecturas, hasta que termina el build. CREATE INDEX CONCURRENTLY no toma locks que bloqueen inserts, updates o deletes. Tarda más, porque PostgreSQL escanea la tabla dos veces y espera a las transacciones que todavía podrían usar el índice. No puede correr adentro de un bloque de transacción. Un CREATE INDEX común sí puede. Un runner de migraciones que envuelve el archivo en una transacción no puede poner CREATE INDEX CONCURRENTLY adentro de esa transacción.
CREATE INDEX CONCURRENTLY users_full_name_idx ON users (full_name);
Si el build concurrente falla, PostgreSQL puede dejar un índice inválido. Ese índice se ignora en las queries y sigue sumando trabajo en cada update. La recuperación que documentan es borrarlo y volver a correr CREATE INDEX CONCURRENTLY, o reconstruirlo con REINDEX INDEX CONCURRENTLY. Solo puede haber un build concurrente de índice por tabla a la vez. Los builds concurrentes en una tabla particionada no están soportados. Podés crear el índice con CONCURRENTLY en cada partición, y después crear el índice padre sin CONCURRENTLY. Ese paso del padre es solo metadata. La fuente es CREATE INDEX.
lock_timeout aborta una sentencia que espera más que el límite mientras intenta tomar un lock. El límite se aplica por separado a cada intento. Vale para locks explícitos y para los que la sentencia toma sola. A diferencia de statement_timeout, solo dispara mientras espera un lock. Si statement_timeout está definido y es menor o igual, dispara primero, así que un lock_timeout más largo no sirve. No definas lock_timeout en postgresql.conf. La fuente es client connection defaults.
El backfill de datos va aparte
Agregar una columna y copiar todas las filas existentes son trabajos distintos. La columna va en el paso de release. La copia va en un comando de una vez o en un job programado, en lotes, para que una sentencia no sea una transacción larga.
Una transacción que queda abierta mantiene visibles las versiones viejas de las filas, y vacuum todavía no puede tratarlas como basura. Ese es el control de transacciones largas en Postgres en producción. Una migración también es otro cliente contra max_connections. Contala con el resto de los clientes en esa nota.
Pre-deploy y post-deploy
Usá el comando pre-deploy para la migración. Corre una vez desde la imagen nueva, antes de que esa versión quede live. Los rollbacks no lo vuelven a correr.
Usá el comando post-deploy para un trabajo que puede esperar a que la versión nueva ya esté sirviendo, como purgar una caché o mandar una notificación. Corre en una copia one-off de la imagen nueva, con las variables de entorno de ese servicio, como máximo 10 minutos. La salida se agrega al log del deployment.
Si el comando post-deploy falla, el deployment queda live y no se revierte nada. El fallo queda en el log del deployment. El comando no corre si el deploy mismo falla. No monta un volumen persistente. Requiere un plan pago, y no está disponible para servicios de imagen. Los secretos van en variables, no en el texto del comando. Las fuentes son la documentación de deployments y el changelog del 26 de octubre.
Una migración no va ahí. El código nuevo ya estaría recibiendo tráfico, y un comando fallido dejaría ese release live.
Probar la migración antes de producción
Probá la migración en una copia descartable antes de aplicarla a producción. La guía de Django lo dice.
Un preview de pull request sirve para eso, apuntado a una base que podés tirar. Unbroker no documenta una base creada para cada preview. La base la elegís con una variable de alcance Preview. Una migración contra una base de staging compartida cambia ese schema para todos los otros previews. Una migración contra producción cambia producción. La nota larga es entornos de preview por pull request.
Cómo funciona en Unbroker
En Settings, un servicio puede definir un comando pre-deploy como npm run db:migrate. Corre una vez desde la imagen nueva, antes de que esa versión quede live. Los rollbacks no lo vuelven a correr, así que la migración tiene que seguir siendo compatible con el código anterior. El changelog del 1 de agosto es ese release. El 8 de octubre se eliminó la terminal interactiva. Quedaron los comandos de una vez y los jobs programados. Un comando de una vez corre una vez, con la imagen y las variables del servicio. Un job programado tiene un nombre, un cron, un comando y una timezone. La salida de cada corrida está en Executions. Cómo elegir entre un worker, ese job y un comando de una vez está en Workers y cron.
@unbroker/iac v0.2.0 mapea preDeploy. Cambiar el comando pre-deploy es un rebuild del commit que está live, así que un apply que solo toca config no publica un HEAD más nuevo de la rama. El post-deploy no está en ese schema. Definí postDeployCommand en el dashboard, o con PATCH /apps/services/:id. Cambiar el comando post-deploy marca el servicio para redeploy. La fuente es la documentación de infrastructure as code y la de deployments.
Los comandos pre-deploy y post-deploy comparten el aislamiento de entorno del servicio y pueden llegar a sus bases privadas. Esa frase está en tipos de servicio.
La página de planes lista los comandos de migración, los comandos de una vez y los jobs programados como no disponibles en Free y disponibles en Pro. Pro sale $25 por mes, con $25 de crédito de uso. El crédito se reinicia en cada ciclo y no se acumula. Si el uso elegible queda por debajo del crédito, el cargo del mes sigue siendo el precio del plan. Los precios están en precios.
Checklist
- Corré la migración una vez, antes de que la versión nueva reciba tráfico.
- Dejala fuera del build de la imagen Docker. Las guías de Django y de FastAPI lo dicen.
- Dejala fuera del comando de arranque de cada réplica.
- Hacé que una segunda corrida no haga nada si el schema ya está al día.
- Definí
lock_timeouten esa sesión. No lo toques enpostgresql.conf. - Poné los secretos en variables, no en el comando. No imprimas el connection string.
- Expandí, copiá filas en lotes y después contraé. Tirá la columna vieja solo cuando ya no vayas a volver a un código que la necesita.
- Poné un backfill grande en un comando de una vez o en un job programado.
- Probalo en una copia descartable. Apuntá los previews a una base que no sea producción.
- Tratá un rollback como un deployment anterior, no como un schema anterior. Guardá un restore que ya hayas corrido.
- En Unbroker, los comandos de migración requieren Pro. El camino de Django es Desplegar Django. Qué cambia después de
runserverestá en Django en producción.
Preguntas frecuentes
¿Tengo que correr las migraciones en el Dockerfile?
No. La guía de Django dice que evites poner las migraciones en el build de la imagen. La guía de FastAPI dice que no corras migraciones mientras se construye la imagen. Corré las migraciones una vez, como paso de release, con las credenciales de runtime, antes de que la versión nueva reciba tráfico.
¿Un rollback revierte la migración de la base?
No. `ubctl apps rollback` promueve un deployment conocido y no reconstruye el commit. Los rollbacks no vuelven a correr el comando pre-deploy. Volver a una imagen anterior no deshace cambios de configuración, escrituras en la base, datos de un volumen ni efectos externos.
¿Qué pasa si falla la migración del pre-deploy?
Leé el log de ese deployment. La documentación y el changelog no dicen qué le hace un pre-deploy fallido a la versión que ya está live. Escribí el comando para que una migración fallida salga con código distinto de cero, así el fallo se ve en ese log.
¿Puedo correr migraciones en el plan Free?
No. La página de planes lista los comandos de migración como no disponibles en Free y disponibles en Pro. Los comandos de una vez y los jobs programados son iguales. Pro sale $25 por mes, con $25 de crédito de uso. Mirá precios.
¿Las migraciones van en el pre-deploy o en el post-deploy?
En el pre-deploy. Corre una vez desde la imagen nueva, antes de que esa versión quede live. El post-deploy corre después de que la versión ya está sirviendo tráfico. Si el comando post-deploy falla, el deployment queda live y no se revierte nada.