Supabase CLI: Desarrollo Local

El Supabase CLI te permite correr una instancia completa de Supabase en tu máquina. Base de datos, auth, storage, edge functions -- todo local, sin depender de internet ni de los servidores de Supabase. Esto te da un entorno de desarrollo rápido, reproducible y gratuito.

Instalar el CLI

npm install -g supabase

Verifica la instalación:

supabase --version

Alternativas de instalación

# Con Homebrew (macOS)
brew install supabase/tap/supabase
 
# Con Scoop (Windows)
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Inicializar un proyecto

Dentro de tu proyecto (dónde está tu package.json), ejecuta:

supabase init

Esto crea una carpeta supabase/ con la siguiente estructura:

supabase/
  config.toml         # Configuración del proyecto local
  migrations/         # Archivos de migración SQL
  functions/          # Edge Functions
  seed.sql            # Datos iniciales (opcional)

El archivo config.toml contiene la configuración de todos los servicios locales: puerto de la base de datos, configuración de auth, límites de storage, etc.

Levantar Supabase local

supabase start

La primera vez tarda unos minutos porque descarga las imágenes de Docker. Las siguientes veces arranca en segundos.

Cuando termina, te muestra todas las URLs y keys locales:

Started supabase local development setup.
 
         API URL: http://localhost:54321
     GraphQL URL: http://localhost:54321/graphql/v1
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
      JWT secret: super-secret-jwt-token-for-local-dev
        anon key: eyJ...
service_role key: eyJ...

Qué incluye el entorno local

Detener los servicios

supabase stop

Para detener y borrar todos los datos locales (reset completo):

supabase stop --no-backup

Conectar con un proyecto remoto

El CLI puede conectarse a tu proyecto de Supabase en la nube para sincronizar esquemas, migraciones y configuración.

Login

supabase login

Esto abre el browser para autenticarte con tu cuenta de Supabase y guarda un token de acceso local.

Link

supabase link --project-ref tu-project-ref

El project-ref es el ID de tu proyecto. Lo encuentras en el dashboard en Settings > General > Reference ID. También es la primera parte de tu URL de Supabase (el abcdef en abcdef.supabase.co).

Cuando linkeas, el CLI sabe a qué proyecto remoto apuntar para operaciones como db push, db pull y functions deploy.

Generar migraciones con db diff

supabase db diff compara el estado actual de tu base de datos local con el último estado conocido y genera un archivo de migración SQL con los cambios.

Flujo de trabajo

1. Abre Studio local (localhost:54323)
2. Haz los cambios que necesites: crear tablas, agregar columnas, definir políticas RLS
3. Genera la migración:

supabase db diff --use-migra -f nombre_descriptivo

Esto crea un archivo en supabase/migrations/ con el SQL necesario para reproducir tus cambios:

supabase/migrations/20250312120000_nombre_descriptivo.sql

El nombre del archivo incluye un timestamp para que las migraciones se ejecuten en orden.

Generar tipos de TypeScript

Una de las mejores funciones del CLI: generar tipos de TypeScript basados en tu esquema de base de datos.

supabase gen types typescript --local > lib/database.types.ts

Esto lee tu esquema local y genera un archivo con todos los tipos:

// lib/database.types.ts (auto-generado)
export interface Database {
  public: {
    Tables: {
      productos: {
        Row: {
          id: number
          nombre: string
          precio: number
          activo: boolean
          created_at: string
        }
        Insert: {
          id?: number
          nombre: string
          precio: number
          activo?: boolean
          created_at?: string
        }
        Update: {
          id?: number
          nombre?: string
          precio?: number
          activo?: boolean
          created_at?: string
        }
      }
      // ... mas tablas
    }
  }
}

Usar los tipos generados

// lib/supabase.ts
import { createClient } from '@supabase/supabase-js'
import type { Database } from './database.types'
 
export const supabase = createClient<Database>(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

Ahora tienes autocompletado completo:

// TypeScript sabe que "productos" es una tabla válida
// y que tiene columnas "id", "nombre", "precio", etc.
const { data } = await supabase
  .from('productos')  // autocomplete de tablas
  .select('nombre, precio')  // autocomplete de columnas
  .eq('activo', true)  // TypeScript valida el tipo del valor

Generar desde el proyecto remoto

supabase gen types typescript --project-id tu-project-ref > lib/database.types.ts

{
  "scripts": {
    "types": "supabase gen types typescript --local > lib/database.types.ts"
  }
}

Flujo de trabajo local vs remoto

El CLI te permite trabajar con dos modelos:

Modelo 1: Local primero (recomendado)

1. Hacer cambios en la base de datos local (Studio o SQL)
2. Generar migración con supabase db diff
3. Verificar que la migración es correcta
4. Pushear la migración al proyecto remoto con supabase db push
5. Regenerar tipos con supabase gen types
6. Commitear migración y tipos al repositorio

# Despues de hacer cambios en Studio local
supabase db diff --use-migra -f crear_tabla_pedidos
supabase db push
supabase gen types typescript --local > lib/database.types.ts
git add supabase/migrations/ lib/database.types.ts
git commit -m "feat: crear tabla pedidos"

Modelo 2: Remoto primero

1. Hacer cambios directamente en el dashboard de producción
2. Bajar los cambios con supabase db pull
3. Esto genera una migración basada en el diff entre local y remoto

supabase db pull
# Genera migracion en supabase/migrations/

Comandos útiles

Resumen