# Migraciones de base de datos en el deploy

Las migraciones de base de datos en el deploy corren una vez, antes de que la versión nueva reciba tráfico. Un rollback de código no deshace el schema.

Canonical URL: https://unbroker.cloud/es/blog/database-migrations-on-deploy
Published: 2026-11-03
Reviewed: 2026-11-13
Author: Timoteo Borgobello

## 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](https://unbroker.cloud/es/blog/docker-compose-to-production) y en [Postgres gestionado](https://unbroker.cloud/managed-databases/postgres). Operar el servidor está en [Postgres en producción](https://unbroker.cloud/es/blog/postgres-in-production).

## 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](https://docs.unbroker.cloud/guides/deploy-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](https://docs.unbroker.cloud/guides/deploy-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](https://unbroker.cloud/changelog/2026-08-01-jobs-terminal-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](https://unbroker.cloud/es/blog/heroku-procfile-to-services).

## 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.

```sql
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](https://docs.unbroker.cloud/cli/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](https://docs.unbroker.cloud/cli/deployments) lo muestra con un id de servicio y un id de deployment:

```bash
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](https://unbroker.cloud/changelog/2026-08-01-jobs-terminal-pre-deploy).

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](https://docs.unbroker.cloud/cli/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](https://unbroker.cloud/es/blog/postgres-in-production).

## 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](https://martinfowler.com/bliki/ParallelChange.html), 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.

1. **Expandir.** Sumá `full_name`. El código nuevo escribe las dos columnas y sigue leyendo `name`. El código viejo solo conoce `name`, así que un rollback sigue corriendo.

```sql
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.

2. **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_name` y sigue escribiendo `name`, así que un rollback al release de expand sigue viendo las escrituras nuevas en `name`.

```sql
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.

3. **Contraer.** El código nuevo lee y escribe solo `full_name`. Dejá `name` en su lugar. Tirala en un release posterior, cuando ya no vayas a volver a un release que todavía la lee o la escribe.

```sql
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](https://www.postgresql.org/docs/current/sql-altertable.html).

## 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](https://www.postgresql.org/docs/current/sql-altertable.html).

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.

```sql
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](https://www.postgresql.org/docs/current/sql-createindex.html).

`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](https://www.postgresql.org/docs/current/runtime-config-client.html).

## 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](https://unbroker.cloud/es/blog/postgres-in-production). 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](https://docs.unbroker.cloud/cli/deployments) y el [changelog del 26 de octubre](https://unbroker.cloud/changelog/2026-10-26-post-deploy-command).

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](https://docs.unbroker.cloud/guides/deploy-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](https://unbroker.cloud/es/blog/pull-request-preview-environments).

## 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](https://unbroker.cloud/changelog/2026-08-01-jobs-terminal-pre-deploy) 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](https://unbroker.cloud/es/blog/background-workers-cron-jobs).

`@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](https://docs.unbroker.cloud/cli/infrastructure-as-code) y la de [deployments](https://docs.unbroker.cloud/cli/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](https://docs.unbroker.cloud/apps/services).

La [página de planes](https://docs.unbroker.cloud/billing/plans) 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](https://unbroker.cloud/es/precios).

<aside class="plan-box">
<p><strong>En Unbroker.</strong> El comando pre-deploy es el paso de release. Los comandos de migración requieren Pro. Un rollback promueve el deployment anterior y no vuelve a correr ese comando.</p>
</aside>

## Checklist

1. Corré la migración una vez, antes de que la versión nueva reciba tráfico.
2. Dejala fuera del build de la imagen Docker. Las guías de Django y de FastAPI lo dicen.
3. Dejala fuera del comando de arranque de cada réplica.
4. Hacé que una segunda corrida no haga nada si el schema ya está al día.
5. Definí `lock_timeout` en esa sesión. No lo toques en `postgresql.conf`.
6. Poné los secretos en variables, no en el comando. No imprimas el connection string.
7. 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.
8. Poné un backfill grande en un comando de una vez o en un job programado.
9. Probalo en una copia descartable. Apuntá los previews a una base que no sea producción.
10. Tratá un rollback como un deployment anterior, no como un schema anterior. Guardá un restore que ya hayas corrido.
11. En Unbroker, los comandos de migración requieren Pro. El camino de Django es [Desplegar Django](https://unbroker.cloud/deploy/django). Qué cambia después de `runserver` está en [Django en producción](https://unbroker.cloud/es/blog/django-in-production).

## Preguntas frecuentes

### ¿Tengo que correr las migraciones en el Dockerfile?

No. La [guía de Django](https://docs.unbroker.cloud/guides/deploy-django) dice que evites poner las migraciones en el build de la imagen. La [guía de FastAPI](https://docs.unbroker.cloud/guides/deploy-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](https://docs.unbroker.cloud/billing/plans) 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](https://unbroker.cloud/es/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.

## Related reading

- [Postgres en producción](https://unbroker.cloud/es/blog/postgres-in-production)
- [Postgres gestionado](https://unbroker.cloud/managed-databases/postgres)
- [Entornos de preview por pull request](https://unbroker.cloud/es/blog/pull-request-preview-environments)
- [Docker Compose en producción](https://unbroker.cloud/es/blog/docker-compose-to-production)
- [Desplegar Django](https://unbroker.cloud/deploy/django)
- [Django en producción](https://unbroker.cloud/es/blog/django-in-production)
- [Precios](https://unbroker.cloud/es/precios)
- [Comando pre-deploy](https://unbroker.cloud/changelog/2026-08-01-jobs-terminal-pre-deploy)
- [Procfile de Heroku, línea a línea](https://unbroker.cloud/es/blog/heroku-procfile-to-services)
