Cómo Subir las Migraciones Locales a Supabase

Cómo Subir las Migraciones Locales a Supabase

Cómo Subir las Migraciones Locales a Supabase

🚀 Aprende a sincronizar tus migraciones de base de datos desde tu entorno local hasta Supabase Cloud de manera segura y eficiente. Esta guía te mostrará el flujo completo de trabajo para mantener tu base de datos sincronizada.

¿Qué son las Migraciones?

Las migraciones son archivos SQL que describen los cambios en el esquema de tu base de datos:

  • Creación de tablas
  • Modificación de columnas
  • Índices y restricciones
  • Políticas de seguridad (RLS)
  • Funciones y triggers

Configuración Inicial

1. Instalar Scoop (Windows Package Manager)

Primero, instala Scoop, un gestor de paquetes para Windows que facilitará la instalación de herramientas de desarrollo:

# Configurar política de ejecución para PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Instalar Scoop
iwr -useb get.scoop.sh | iex

Verifica la instalación de Scoop:

scoop --version

📖 Para más detalles sobre la instalación en Windows, consulta la documentación oficial de Supabase.

2. Agregar bucket de Supabase a Scoop

Antes de instalar la CLI de Supabase, necesitas agregar su bucket a Scoop:

scoop bucket add supabase https://github.com/supabase/scoop-bucket.git

3. Instalar CLI de Supabase con Scoop

Una vez agregado el bucket, instala la CLI de Supabase:

scoop install supabase

Verifica la instalación:

supabase --version

4. Iniciar Proyecto Local

# Inicializar proyecto Supabase
npx supabase init

# Iniciar servicios locales, solo funciona con docker
npx supabase start

5. Agregar la variable de entorno SUPABASE_ACCESS_TOKEN

# Agregar la variable de entorno, desde el CMD
set SUPABASE_ACCESS_TOKEN "tu-access-token"

tu-access-token es el token que obtienes de tu cuenta de Supabase, lo puedes obtener ingresando a tu cuenta de Supabase, luego donde aparece tu imagen de perfil, en la sección de configuración de tu proyecto (preferencias de la cuenta), en la pestaña tokens de acceso.

6. Conectar con Proyecto Remoto

# Enlazar con tu proyecto en Supabase Cloud.
# Te pedirá que elijas el proyecto remoto, selecciona el que deseas.
npx supabase link

Flujo de Trabajo de Migraciones

1. Crear Nueva Migración

# Crear una nueva migración
npx supabase migration new crear_tabla_usuarios

Esto creará un archivo en supabase/migrations/ con timestamp:

-- migrations/20240101000000_crear_tabla_usuarios.sql

2. Escribir la Migración

Edita el archivo de migración:

-- Crear tabla de usuarios
CREATE TABLE usuarios (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  nombre TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Crear índice
CREATE INDEX idx_usuarios_email ON usuarios(email);

-- Crear política de seguridad
CREATE POLICY "Usuarios pueden ver su propio perfil" ON usuarios
  FOR SELECT USING (auth.uid() = id);

3. Aplicar Migración Localmente

# Aplicar migraciones en la base de datos local
npx supabase db push

4. Probar Cambios Locales

Antes de subir a producción, prueba tus cambios:

# Ver estado de la base de datos
npx supabase status

# Ver logs si hay errores
npx supabase logs db

# Conectarte a la base de datos local
npx supabase db shell

5. Subir a Supabase Cloud

# Sincronizar migraciones con el proyecto remoto
npx supabase db push --remote

Comandos Esenciales

Ver Historial de Migraciones

# Listar todas las migraciones
npx supabase migration list

# Ver detalles de una migración específica
npx supabase migration show 20240101000000_crear_tabla_usuarios

Resetear Base de Datos

# Resetear base de datos local (¡cuidado! borra todo)
npx supabase db reset

# Resetear y volver a aplicar migraciones
npx supabase db reset --linked

Backup y Restore

# Hacer backup de la base de datos
npx supabase db dump --data-only > backup.sql

# Restaurar desde backup
npx supabase db restore backup.sql

Buenas Prácticas

1. Nomenclatura de Migraciones

Usa nombres descriptivos y consistentes:

# ✅ Buenas prácticas
npx supabase migration new crear_tabla_perfiles
npx supabase migration new agregar_campo_avatar_a_perfiles
npx supabase migration new crear_indice_email_usuarios

# ❌ Evitar
npx supabase migration new fix
npx supabase migration new temp
npx supabase migration new 123

2. Migraciones Reversibles

Escribe migraciones que puedan revertirse:

-- migrations/20240101000000_crear_tabla_usuarios.sql
CREATE TABLE usuarios (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  nombre TEXT
);

-- migrations/20240101000001_crear_tabla_usuarios_down.sql
DROP TABLE IF EXISTS usuarios;

3. Validar Antes de Subir

# Verificar sintaxis SQL
npx supabase db diff --use-migra

# Comparar local con remoto
npx supabase db diff --remote

4. Manejo de Conflictos

Si hay conflictos entre local y remoto:

# Forzar sincronización (¡cuidado! puede sobreescribir datos)
npx supabase db push --remote --force

# O mejor: resolver conflictos manualmente
npx supabase db diff --remote > conflictos.sql
# Editar conflictos.sql manualmente
# Aplicar cambios uno por uno

Flujo de Trabajo Recomendado

Desarrollo Diario

# 1. Crear nueva migración
npx supabase migration new mi_cambio

# 2. Editar el archivo SQL
# (escribir los cambios)

# 3. Aplicar localmente
npx supabase db push

# 4. Probar extensamente
# (usar la app, hacer pruebas unitarias)

# 5. Subir a staging/producción
npx supabase db push --remote

Trabajo en Equipo

# 1. Pull de cambios del equipo
git pull origin main

# 2. Aplicar migraciones nuevas
npx supabase db push

# 3. Crear tus cambios
npx supabase migration new mi_feature

# 4. Aplicar y probar localmente
npx supabase db push

# 5. Commit y push
git add .
git commit -m "Add mi_feature migration"
git push origin main

# 6. Subir migraciones a producción
npx supabase db push --remote

Solución de Problemas Comunes

Error: “Migration already applied”

# Verificar estado de migraciones
npx supabase migration list

# Saltar migración ya aplicada
npx supabase db push --skip-migration 20240101000000

Error: “Connection timeout”

# Verificar conexión
npx supabase status

# Reintentar con timeout extendido
npx supabase db push --remote --timeout 60

Error: “Schema mismatch”

# Comparar esquemas
npx supabase db diff --remote

# Resetear y sincronizar desde cero
npx supabase db reset --linked
npx supabase db push --remote

Automatización con CI/CD

GitHub Actions Example

name: Deploy Migrations
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup Supabase CLI
        run: |
          curl -L https://github.com/supabase/cli/releases/latest/download/supabase_linux_amd64.tar.gz | tar xz
          sudo mv supabase /usr/local/bin/
      
      - name: Deploy migrations
        run: |
          supabase link --project-ref ${{ secrets.SUPABASE_PROJECT_REF }}
          supabase db push --remote
        env:
          SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }}

Tips Avanzados

1. Migraciones Condicionales

-- Solo ejecutar si la tabla no existe
CREATE TABLE IF NOT EXISTS usuarios (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  email TEXT UNIQUE NOT NULL
);

-- Solo agregar columna si no existe
DO $$
BEGIN
  IF NOT EXISTS (
    SELECT 1 FROM information_schema.columns 
    WHERE table_name = 'usuarios' AND column_name = 'avatar_url'
  ) THEN
    ALTER TABLE usuarios ADD COLUMN avatar_url TEXT;
  END IF;
END $$;

2. Datos de Prueba

-- Insertar datos de desarrollo
INSERT INTO usuarios (email, nombre) VALUES 
  ('test@example.com', 'Usuario Test'),
  ('dev@example.com', 'Usuario Dev')
ON CONFLICT (email) DO NOTHING;

3. Migraciones de Performance

-- Crear índices concurrentemente
CREATE INDEX CONCURRENTLY idx_usuarios_email ON usuarios(email);

-- Actualizar datos en lotes
UPDATE usuarios 
SET nombre = UPPER(nombre) 
WHERE id IN (
  SELECT id FROM usuarios LIMIT 1000
);

Conclusión

Las migraciones son fundamentales para mantener la integridad y consistencia de tu base de datos a través de diferentes entornos. Con la CLI de Supabase, tienes control total sobre el ciclo de vida de tus cambios:

✅ Desarrollo local rápido
✅ Control de versiones
✅ Despliegue seguro
✅ Colaboración en equipo
✅ Rollbacks confiables

Recuerda siempre probar tus migraciones en un entorno de desarrollo antes de aplicarlas en producción.

📖 Para más información, consulta la documentación oficial de Supabase.