Desplegar, paso a paso

Esta página es el recorrido completo, sin dar nada por sabido: qué se toca, en qué orden, desde qué carpeta y en qué plataforma.

Puesta en producción explica cómo se armó la infraestructura una vez. Esta explica cómo se despliega cada cambio.

Y Checklist de despliegue es la que se recorre cada vez: qué verificar en cada ambiente, el respaldo antes de migrar, y las cinco cosas que nunca se hacen contra producción ahora que hay clientes reales cargados.

Primero: el mapa

Tres repositorios separados, tres plataformas, una sola base de datos.

Repo	Dónde vive en tu máquina	Se despliega en	Qué es
api	~/code/aquazaku/api	Railway	El backend. Habla con Postgres
web	~/code/aquazaku/web	Vercel	El front. Habla con api, nunca con Postgres
docs	~/code/aquazaku/docs	(sitio estático)	Esta documentación

Y la base:

	Dónde	Schema
Producción	Supabase	public
Preview	la MISMA Supabase	preview
Local	Postgres de tu máquina	public de aquazaku_dev

Producción y preview comparten base, no datos

Son dos schemas dentro del mismo Postgres. preview.clientes y public.clientes son tablas distintas, con datos distintos y usuarios distintos. Cuál usa cada proceso lo decide AQUAZAKU_ENV — ver Entornos.

La regla que hay que entender antes de nada

Railway y Vercel despliegan solos al mergear a main. Las migraciones NO.

El startCommand de producción está vacío a propósito: el container solo arranca el servidor. Migrar es un acto separado, deliberado, que hacés vos desde tu máquina.

De ahí salen las dos preguntas de todo despliegue:

1. ¿Este cambio trae una migración?
2. Si la trae, ¿el código nuevo aguanta el schema viejo, o al revés?

Caso A — Sin migraciones

El caso común. No hay nada que coordinar.

gh pr merge --merge

Railway y Vercel detectan el push a main y redespliegan. Listo.

Caso B — Con migración ADITIVA que el código nuevo NO usa todavía

Aditiva quiere decir que solo agrega: una columna nullable, una tabla, un índice. Y la condición que importa es la segunda mitad: que el código que se está desplegando no la lea.

Ahí el orden documentado funciona: mergear primero, migrar después.

Si el código nuevo la NECESITA, esto no aplica

«Aditiva» describe qué le hace al schema, no si se puede mergear primero. Una migración que solo INSERTA dos filas es aditiva de manual — y si el código que va a desplegarse las lee al arrancar, mergear antes lo deja pidiendo algo que no existe.

Pasó con M15: tres INSERT en parametros habrían dejado el tablero de producción en un error boundary, no solo sin el panel nuevo.

La pregunta no es «¿agrega o renombra?». Es ¿el código que voy a desplegar funciona sin esto? Si la respuesta es no, va por el Caso C aunque la migración no toque ninguna columna existente.

El detalle está en Checklist de despliegue.

gh pr merge --merge

cd ~/code/aquazaku/api
DATABASE_MIGRATION_URL='<cadena de Supabase>' pnpm db:migrate

Caso C — Con migración que RENOMBRA, CONVIERTE o rompe el código viejo

Acá el orden se invierte, y no es una preferencia: es que el otro orden rompe la planta.

Una migración ADITIVA puede caer acá, y es la trampa

El caso obvio es un rename. El que no se ve venir es una columna NOT NULL sin valor por omisión: agrega y nada más —aditiva de manual— pero el INSERT que el código desplegado viene haciendo deja de ser válido.

Pasó el 13-oct-2026 con la 0027. Medido:

INSERT INTO bases (id_sticker) VALUES ('9999');
ERROR:  null value in column "tipo" of relation "bases" violates not-null constraint

La prueba de si estás en el Caso C no es «¿renombra?». Es «¿el código que está corriendo ahora sobrevive a este schema?». Si la respuesta es no, seguí leyendo esta sección aunque tu migración solo agregue.

Y si la ventana entre migrar y desplegar no puede ser corta, la migración se parte en dos: primero la columna nullable, se despliega el código que la llena, y una segunda la pone NOT NULL después.

Una migración que renombra nombre a nombre_libre deja al código viejo y al nuevo incompatibles en direcciones opuestas. Medido:

	Leer clientes	Registrar cliente
Código viejo + schema nuevo	✅	❌
Código nuevo + schema viejo	❌	❌

Migrar primero deja el sistema funcionando: se vende, se consulta, se cobra, y lo único que falla es dar de alta un cliente nuevo durante los dos minutos del deploy. Al revés se cae todo lo de clientes, y con eso ventas, retornables y cartera.

C.1 — Respaldo

cd ~/code/aquazaku/api
DATABASE_MIGRATION_URL='<cadena de Supabase>' pnpm db:respaldo

Sin la cadena, respalda TU MÁQUINA

db:respaldo lee DATABASE_MIGRATION_URL — la misma variable que el migrador — y el script corre con --env-file-if-exists=.env, que apunta a localhost. Sin pasarla explícitamente, el respaldo sale de aquazaku_dev y termina con un ✓ que parece éxito.

Como el migrador, anuncia el destino antes de empezar:

→ respaldando postgres.taytdxptguvrszjtsroz@aws-0-us-east-1.pooler.supabase.com/postgres

Si dice aquazaku@localhost/aquazaku_dev, ese respaldo no sirve para lo que lo pediste.

C.2 — Migrar producción, ANTES de mergear

La rama tiene que estar en tu máquina —ahí vive el archivo de la migración—.

cd ~/code/aquazaku/api
git checkout <la-rama-de-la-PR>

DATABASE_MIGRATION_URL='<cadena de Supabase>' pnpm db:migrate

C.3 — Mergear

gh pr merge --merge

api primero y web después: el front llama al backend, no al revés.

C.4 — Verificar

curl -s https://api.aquazaku.com/health

De dónde sale la cadena de Supabase

Es la parte que más se traba, y tiene dos trampas.

En el panel de Supabase: Project Settings → Database → Connection string.

La conexión directa NO sirve

db.<ref>.supabase.co tiene solo registro AAAA: es IPv6. Falla con un ENOTFOUND que jamás menciona IPv6, y se persigue como si fuera un problema de credenciales.

Va la del pooler, no la que el panel ofrece primero.

Para migrar hacen falta estas características:

	Valor
Modo	sesión (no transacción)
Puerto	5432
Usuario	postgres.<ref-del-proyecto>

El modo sesión es obligatorio porque las migraciones hacen DDL y REVOKE, y el modo transacción no los sostiene.

El pooler pide el rol con el ref pegado

El usuario del pooler no es postgres a secas, es postgres.<ref>. El panel ya te la da armada así — copiala tal cual y solo reemplazá [YOUR-PASSWORD].

Lo que el migrador imprime, y por qué hay que leerlo

Antes de tocar nada, el script anuncia a dónde va:

→ migrando postgres.taytdxptguvrszjtsroz@aws-0-us-east-1.pooler.supabase.com/postgres → schema "public"
✓ migraciones aplicadas

La contraseña nunca aparece — está sacada a propósito, porque esta línea termina en logs y en capturas de pantalla.

Si esa línea dice localhost, cortá con Ctrl+C

Es el error más caro que se puede cometer acá, y ya pasó: se dumpeó la base local creyendo que era producción, porque la variable se había puesto con export en otra terminal y el .env tomó el control en silencio.

Por eso el script lo anuncia. Leelo siempre.

pnpm db:migrate:prod lee un archivo, no tu variable

Ese atajo corre tsx --env-file-if-exists=.env.produccion.local. Si ese archivo quedó apuntando a otro lado —pasa— vas a migrar la base equivocada y el comando te va a decir «✓ migraciones aplicadas» igual.

La forma explícita no depende de ningún archivo:

DATABASE_MIGRATION_URL='...' pnpm db:migrate

Cómo saber si quedó bien

curl -s https://api.aquazaku.com/health

Bien:

{"status":"ok","service":"aquazaku-api","base":"ok","desdeHaceMs":19608}

Mal — faltan migraciones:

{"status":"ok","service":"aquazaku-api","base":"ok","desdeHaceMs":97950,
 "esquema":"pendientes","faltan":["0016_nombre_partido"]}

Mientras aparezca faltan, el código desplegado está pidiéndole a la base algo que no tiene. status sigue diciendo ok porque el servidor está sano — lo que está mal es el schema, y por eso se reporta aparte.

faltan se corrige solo, en hasta quince minutos

Antes se calculaba una sola vez al arrancar, con este argumento: «las migraciones no se aplican solas mientras el proceso vive, y si alguien las corre, el redeploy vuelve a revisar». Es cierto para el caso normal y justamente falso durante un despliegue, que es cuando uno mira este campo.

Nos pasó el 13-oct-2026: faltan siguió apareciendo media hora después de que la migración hubiera entrado bien, y no había forma de confirmar la corrección sin reiniciar el servicio. Reiniciar producción para poder leer un indicador es exactamente lo que un indicador debería evitar.

Desde entonces se revisa en cada latido —cada quince minutos— mientras no esté al día. Y una vez al día no se vuelve a revisar nunca: para un proceso dado las migraciones esperadas son fijas (el journal viaja dentro de la imagen) y las aplicadas solo crecen, así que al-dia es un estado terminal. El costo cuando todo está bien es una consulta, la del arranque.

Cuando se resuelve, el log lo dice: el esquema quedó al día. Sin ese aviso el log muestra cuándo empezó el problema y nunca cuándo terminó.

Si no querés esperar los quince minutos, preguntale a la base:

select column_name from information_schema.columns
where table_schema = 'public' and table_name = '<la tabla que cambió>';

Reiniciar el servicio en Railway también lo refresca, pero ya no hace falta.

Y la comprobación que ninguna consola reemplaza: entrá a app.aquazaku.com y registrá un cliente de verdad.

El preview, que es otro camino

Un push a una PR despliega dos cosas más:

Plataforma	Qué
Vercel	La URL xxx-git-<rama>-aquazaku.vercel.app
Railway (staging)	La api del preview, contra el schema preview

El startCommand de staging sí migra, porque va contra un schema desechable:

pnpm db:sync-preview && pnpm db:seed && pnpm start

Los && encadenan: si uno falla, pnpm start no corre

Y entonces la api de staging no levanta, aunque Vercel muestre el front sin problemas. Desde afuera se ve como «el login no me acepta», que es un síntoma que apunta al lado equivocado.

Cuando el preview no ande, el log del deploy de staging en Railway es el primer lugar a mirar, no el último.

Cómo entrar al preview y qué usuario usar está en Entornos.

Cuando algo sale mal

Síntoma	Qué pasó	Qué hacer
/health dice faltan: [...]	Se mergeó sin migrar	Correr la migración
ENOTFOUND db.<ref>.supabase.co	Es la conexión directa, IPv6	Usar la del pooler
El migrador dice localhost	La cadena no es la de producción	Ctrl+C
500 en todas las pantallas de clientes	Casi siempre el schema atrasado	Mirar /health
El preview no acepta ningún usuario	La api de staging no arrancó	Log del deploy en Railway
CI en rojo pero GitHub deja mergear	main no tiene protección de rama	Decidirlo aparte

Rollback

Código: revert del commit. Railway y Vercel redespliegan solos.

Migración: revertir el código no la deshace. Si la migración ya corrió, hay que escribir otra que la deshaga explícitamente y correrla igual que la primera. Por eso el respaldo del paso C.1 no es ceremonia.