Clase 05 · Módulo 07
Migraciones y entornos
Migraciones y entornos
Qué logras en esta clase
Cada cambio de tu base queda escrito en un archivo, probado en un proyecto aparte y reflejado en los tipos de tu app.
- Creas y aplicas migraciones con la CLI de Supabase
- Separas pruebas de producción con el plan gratuito
- Cambias la base sin romper versiones antiguas de la app
- Generas tipos de TypeScript desde el esquema
02
El problema: cambios que nadie recuerda
Agregas una columna desde el panel. Un mes después quieres publicar y no sabes:
- qué cambiaste exactamente
- en qué orden
- si producción tiene lo mismo que pruebas
Con el código esto no pasa, porque usas Git. La base de datos necesita el mismo trato, y Git solo guarda archivos. La solución es convertir cada cambio de la base en un archivo.
03
Qué es una migración
Una migración es un archivo SQL con fecha que describe un cambio de la base. La carpeta completa es su historia.
04
Qué gana tu proyecto
- Reproducible: aplicas la carpeta a un proyecto vacío y obtienes la misma base
- Revisable: cada cambio pasa por un diff, como el código (módulo 4)
- Parejo: pruebas y producción reciben exactamente lo mismo
- Legible para Claude Code: lee tu esquema desde archivos, sin adivinar
El último punto se nota: con las migraciones en la carpeta, Claude escribe consultas que calzan con tus tablas reales.
05
Dos entornos con el plan gratuito
| Pruebas | Producción | |
|---|---|---|
| Datos | Ficticios | Reales |
| Quién lo usa | Tú y tus builds de desarrollo | Tus usuarios |
| Si se rompe | Lo arreglas con calma | Alguien no puede usar la app |
| Cambios | Primero aquí | Solo lo ya probado |
Los 2 proyectos activos del plan Free alcanzan justo para una app. Supabase también ofrece ramas («branching») en planes de pago: comprueba su costo antes de considerarlas.
06
El camino de un cambio
Nada llega a producción sin haber pasado por pruebas. Y nada llega a pruebas sin estar escrito en un archivo.
Suena lento. En la práctica son dos comandos, y te ahorra la peor tarde posible: reparar a mano una base con datos de clientes.
07
La CLI de Supabase
La CLI es la herramienta de terminal de Supabase. Se puede ejecutar sin instalación global, anteponiendo npx:
npx supabase login
npx supabase initloginabre el navegador para autorizar tu cuentainitcrea la carpetasupabase/en tu proyecto, con su archivoconfig.toml
Hay otras formas de instalarla; la guía oficial las detalla. Esa carpeta sí se sube a Git.
08
Enlazar la carpeta con tu proyecto
npx supabase link --project-ref <ref>El ref es el identificador de la clase 2. Desde ese momento, los comandos que actúan sobre el proyecto remoto apuntan a ese.
09
Crear una migración
npx supabase migration new crear_productosAparece un archivo vacío en supabase/migrations/, con la fecha y hora delante del nombre. Ahí va el SQL: el create table, sus restricciones y la línea que activa RLS.
Ese es el archivo que le pides a Claude Code que escriba, y el que lees antes de seguir.
10
Aplicarla al proyecto enlazado
npx supabase db push --remoteLa CLI compara las migraciones de tu carpeta con las ya aplicadas en el proyecto y ejecuta solo las nuevas, en orden.
Así figura hoy en la documentación oficial. Si tu versión de la CLI se comporta distinto, ejecuta npx supabase db push --help y sigue lo que indique.
11
La regla que no se rompe
Producción solo cambia por migraciones que ya funcionaron en pruebas. Nunca a mano desde el panel.
12
Si ya cambiaste algo desde el panel
Pasa, sobre todo al inicio. Las tablas que creaste en la clase 3 están en ese caso. Hay dos comandos para traer esos cambios a archivos:
| Comando | Qué hace |
|---|---|
supabase db pull --remote | Captura en una migración lo que existe en el proyecto remoto |
supabase db diff --schema public | Genera el SQL de los cambios hechos desde el panel |
Úsalos una vez para ponerte al día. Desde ahí, todo cambio nace como migración.
13
Base local con Docker: opcional
| Proyecto de pruebas remoto | Base local | |
|---|---|---|
| Requiere | Solo internet | Docker instalado |
| Se levanta con | Nada | supabase start |
| Reiniciar de cero | Manual | supabase db reset |
| Conviene | Para partir | Cuando el proyecto o el equipo crece |
Docker es un programa que ejecuta servicios aislados en tu computador. db reset reaplica todas las migraciones y carga supabase/seed.sql. Para tu primera app, el proyecto remoto de pruebas basta.
14
Datos de prueba
- Mantén un archivo con filas ficticias: productos inventados, pedidos de ejemplo
- En la base local,
supabase/seed.sqlse carga solo con cadadb reset - En el proyecto remoto de pruebas, lo ejecutas tú cuando lo necesites
15
Tu app instalada no se actualiza sola
En una web, todos usan la última versión. En una app, la versión antigua sigue viva en muchos teléfonos durante semanas.
16
Cambios compatibles y cambios que rompen
| Cambio | Efecto en versiones antiguas |
|---|---|
| Agregar tabla | Ninguno |
Agregar columna con default | Ninguno |
Agregar columna not null sin default | Sus inserciones fallan |
| Renombrar o borrar columna | Sus consultas fallan |
Para renombrar: agrega la columna nueva, publica la app que la usa, espera a que las versiones antiguas desaparezcan y recién entonces borra la vieja. Son dos migraciones separadas por semanas.
17
Migraciones que destruyen datos
drop table, drop column y algunos cambios de tipo no tienen vuelta atrás.
- Exporta la base antes: el plan Free no tiene respaldos automáticos
- Aplica primero en pruebas y revisa la app completa
- Lee el SQL línea por línea; no lo apruebes de corrido
Y una regla más: una migración ya aplicada no se edita. Si quedó mal, se corrige con una migración nueva.
18
Generar tipos de TypeScript
npx supabase gen types typescript --remote="$PROJECT_REF" --schema public > database.types.tsEl comando lee tu esquema y escribe un archivo que describe cada tabla y cada columna con su tipo. Luego se lo entregas al cliente:
const supabase = createClient<Database>(url, clave);19
Qué ganas con los tipos
- El editor autocompleta nombres de tablas y columnas
- Una columna mal escrita se marca en rojo antes de ejecutar nada (módulo 4)
Tables<'productos'>te da el tipo de una fila, listo para tus componentes
El archivo es una foto del esquema: queda viejo con cada migración.
20
El ciclo completo con Claude Code
- Describes el cambio: «los pedidos necesitan un estado»
- Claude crea la migración y escribe el SQL
- Lees el archivo y preguntas lo que no entiendas
- Aplicas a pruebas
- Claude regenera los tipos y ajusta la app
- Pruebas en el teléfono
- Un solo commit: migración, tipos y código
Cuando publiques, enlazas producción y aplicas las mismas migraciones.
21
Errores comunes
- Cambiar producción desde el panel «solo esta vez»
- Aplicar a producción creyendo que el enlace apuntaba a pruebas
- Editar una migración ya aplicada en vez de crear otra
- Renombrar una columna con versiones antiguas de la app en uso
- Olvidar regenerar los tipos y perseguir errores que el editor habría mostrado
22
Lo que te llevas
- Una migración es un archivo SQL fechado; la carpeta es la historia de tu base
- Dos proyectos: pruebas recibe todo primero, producción solo lo probado
migration newcrea,db pushaplica,db pullydb diffrescatan cambios hechos a mano- Las versiones antiguas de la app obligan a cambiar la base de forma compatible
- Los tipos se regeneran después de cada migración
23
Hazlo ahora
Quince minutos, en tu proyecto de pruebas:
- Ejecuta
login,initylinken la carpeta de tu app - Captura con
db pulllas tablas que creaste en la clase 3 - Crea una migración que agregue una columna con
default - Aplícala y compruébala en el panel
- Genera los tipos y escribe mal esa columna en el código para ver el aviso del editor
Termina con un commit que incluya la carpeta supabase/.
Clase terminada
Sigue con la próxima.
Fuentes · revisadas el 18 de noviembre de 2026