Migraciones con la CLI de Supabase para apps hechas con IA

Una migración es un archivo SQL que describe un cambio en tu base de datos; se guarda en supabase/migrations dentro del repositorio y se aplica en orden. Con la CLI de Supabase capturas el esquema que armó tu herramienta de IA (supabase db pull), escribes cada cambio nuevo como archivo (supabase migration new), lo pruebas en una copia local (supabase db reset) y lo aplicas en producción (supabase db push). La idea es que cada cambio quede revisado, se pueda repetir y viva en Git, en lugar de escribirse en el panel y olvidarse.

Esta guía es para apps que nacieron en Lovable, Bolt, Cursor o similares y ahora necesitan una forma más segura de cambiar la base. Cubre la configuración inicial, el ciclo de cada día y los errores que más rompen db push.

¿Para qué sirven las migraciones?

Porque los errores más caros en apps hechas con IA son cambios en la base que nadie puede rastrear: una columna renombrada en el panel que el código sigue usando, una tabla creada en producción que nunca existió en el proyecto de pruebas, una política que alguien "arregló" a mano. Las migraciones lo resuelven convirtiendo la base en archivos:

• Ves exactamente qué cambió, cuándo y por qué, en el historial de Git.
• Puedes reconstruir la misma base para un entorno de pruebas o para una persona nueva en el equipo con un solo comando.
• Los errores aparecen en una copia local antes de tocar datos reales.

Muchas herramientas de IA ya escriben archivos SQL en una carpeta supabase/migrations cuando cambian el esquema. Revisa tu repositorio: si la carpeta existe, tienes medio camino hecho.

¿Qué necesito antes de empezar?

1. La CLI de Supabase instalada en tu computadora.
2. Docker funcionando. La CLI levanta un Postgres local en Docker para db reset, db diff y db pull.
3. El código del proyecto en Git, idealmente conectado a GitHub para trabajar en una rama.
4. El project ref (el identificador que aparece en la URL del proyecto) y la contraseña de la base.

¿Cómo pongo un proyecto existente bajo migraciones?

Se hace una sola vez, en una rama.

supabase login
supabase init                               # crea la carpeta supabase/ si no existe
supabase link --project-ref abcdefghijklmnop
supabase db pull                            # guarda el esquema remoto actual como migración

supabase db pull crea un archivo de migración en supabase/migrations con lo que hay hoy en producción. Si la carpeta ya tenía migraciones de tu herramienta, ejecuta antes supabase migration list: muestra qué migraciones están aplicadas en local y en remoto, y dónde no coinciden.

Cuando el historial y la realidad no coinciden (por ejemplo, los archivos de la herramienta no reflejan lo que hay en producción), el comando supabase migration repair permite marcar una migración como aplicada o revertida. Solo edita el registro del historial y no ejecuta SQL, así que úsalo para corregir la contabilidad, nunca para "aplicar" un cambio.

Después confirma que los archivos reconstruyen la base desde cero:

supabase start      # entorno local
supabase db reset   # aplica todas las migraciones y luego supabase/seed.sql

Si el reset falla, corrige los archivos hasta que funcione. Un historial de migraciones que no reconstruye la base es justamente el problema que quieres eliminar.

¿Cómo es el ciclo de cada día?

Para cada cambio, los mismos pasos. La guía oficial de migraciones describe el mismo flujo.

1. Crea el archivo de migración

supabase migration new agregar_fecha_limite_a_tareas

Esto crea supabase/migrations/<timestamp>_agregar_fecha_limite_a_tareas.sql. Escribe el cambio ahí:

alter table public.tasks add column due_date date;

create index tasks_due_date_idx on public.tasks (due_date);

2. O captura un cambio hecho en local

Si prefieres hacer clic en el Studio local, haz el cambio en tu base local y genera el archivo después:

supabase db diff -f agregar_fecha_limite_a_tareas

Haz estos cambios solo en la base local. Los cambios hechos directamente en el proyecto remoto se saltan el historial de migraciones y son una causa común de que db push falle después.

3. Pruébalo

supabase db reset

Luego corre la app contra el entorno local y recorre las partes que usan esa tabla.

4. Haz commit y revisa

Sube la migración junto con el código que la usa, abre un pull request y lee el SQL. Es el momento de detectar un drop column que no debería estar ahí.

5. Aplícala en producción

supabase db push --dry-run   # muestra lo que se aplicaría
supabase db push

Si el cambio borra o reescribe datos, haz un respaldo antes; en respaldos de Supabase está cómo. Si trabajas en equipo, que una sola persona haga push a la vez, porque las migraciones se aplican en orden de fecha.

¿Qué más va en una migración además de tablas?

Todo lo que define cómo se comporta la base:

• RLS y políticas. alter table ... enable row level security; y cada create policy van en la misma migración que crea la tabla. Mira nuestros ejemplos de políticas RLS.

• Permisos (grants). Desde el 30 de mayo de 2026, los proyectos nuevos de Supabase no exponen automáticamente las tablas nuevas en la Data API, y Supabase indica que los existentes reciben el mismo comportamiento el 30 de octubre de 2026. Una tabla nueva necesita permisos explícitos, así que escríbelos en la migración que la crea:

  grant select, insert, update, delete on public.tasks to authenticated;

  Sin esto, la app recibe permission denied for table tasks aunque las políticas estén bien.

• Funciones, triggers e índices.
• Buckets de Storage y sus políticas, si tu app depende de ellos.

Los datos de prueba van en supabase/seed.sql, no en migraciones, para que nunca lleguen a producción por accidente.

¿Cómo evito que la herramienta de IA deshaga esto?

Si sigues usando una herramienta de IA, dale las reglas. En Cursor o Claude Code, ponlas en las reglas del proyecto: "nunca cambies la base desde el panel o por MCP; crea un archivo nuevo con supabase migration new e incluye RLS y grants". En reglas de Cursor para proyectos reales explicamos cómo. Con Lovable o Bolt, revisa el SQL que propone la herramienta antes de aprobarlo y haz que los cambios de producción pasen por la CLI.

Respuestas rápidas

¿Puedo editar una migración que ya se aplicó? No lo hagas. Escribe una migración nueva que la modifique. Si editas un archivo aplicado, producción y el historial dejan de coincidir.

¿Cómo deshago una migración? Con una migración nueva que haga lo contrario, por ejemplo borrar la columna que agregaste. No cuentes con un paso automático para volver atrás.

¿Necesito otro proyecto de Supabase para pruebas? Es muy recomendable cuando ya tienes usuarios reales. Aplicas las mismas migraciones primero en pruebas y después en producción.

¿db push mueve mis datos? No. Cambia la estructura; los datos se quedan donde están. Por eso los cambios destructivos necesitan un respaldo antes.

¿Quieres ayuda para dejarlo andando?

Ordenar el historial de un proyecto hecho con IA cuesta la primera vez. Una revisión de seguridad de Supabase revisa esquema, políticas y permisos, y una Dev Subscription te da un desarrollador para armar el flujo contigo. También puedes escribirnos con tus dudas.