Communitygithub.com

Futurists2023/supabase

Úsalo para cualquier tarea que involucre Supabase. Activa: productos de Supabase (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); bibliotecas cliente e integraciones SSR (supabase-js, @supabase/ssr) en Next.js, React, SvelteKit, Astro, Remix; problemas de autenticación (inicio de sesión, cierre de sesión, sesiones, JWT, cookies, getSession, getUser, getClaims, RLS); CLI de Supabase o servidor MCP; cambios de esquema, migraciones, esquemas declarativos, auditorías de seguridad, extensiones de Postgres (pg_graphql, pg_cron, pg_vector); depuración y solución de errores o comportamiento inesperado en proyectos de Supabase (errores HTTP, errores de Postgres, sorpresas de RLS, permisos denegados, problemas de caché de esquema, tiempos de espera, fallos de Edge Function, caídas de Realtime, fallos de Storage) y lectura o consulta de registros (Logs Explorer, ClickHouse).

¿Qué es supabase?

Esta habilidad está diseñada para desarrolladores y agentes de IA que trabajan con la plataforma Supabase. Proporciona una guía completa y actualizada para abordar cualquier tarea relacionada con Supabase, desde la configuración inicial hasta la depuración avanzada y la seguridad. Incluye principios básicos como verificar los cambios en el changelog, validar las correcciones con consultas de prueba y recuperarse de errores sin entrar en bucles. También cubre aspectos críticos de seguridad, como la configuración correcta de RLS (Row Level Security), el manejo seguro de tokens JWT y `app_metadata`, y las trampas comunes con vistas, funciones `SECURITY DEFINER` y políticas de Storage. La habilidad soporta el uso de la CLI de Supabase (con comandos `--help` para descubrimiento) y el servidor MCP (con pasos de solución de problemas para la conexión y autenticación). Además, detalla los flujos de trabajo para realizar cambios en el esquema de la base de datos, ya sea mediante esquemas declarativos o migraciones imperativas, y enfatiza la importancia de consultar la documentación oficial y el changelog antes de implementar cualquier funcionalidad, dada la frecuencia con la que Supabase introduce cambios importantes.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Futurists2023/tiktok/tree/HEAD/.agents/skills/supabase

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace supabase?

Principios Fundamentales

1. Supabase cambia con frecuencia: verifica el changelog y la documentación actual antes de implementar. No confíes en los datos de entrenamiento para las funciones de Supabase. Las firmas de funciones, la configuración de config.toml y las convenciones de la API cambian entre versiones.

Primero, obtén https://supabase.com/changelog.md (un índice de resumen ligero, no una descarga pesada), busca etiquetas de breaking-change relevantes para tu tarea y sigue la página enlazada para cualquier que aplique. Luego, busca el tema relevante utilizando los métodos de acceso a la documentación que se indican a continuación.

2. Verifica tu trabajo. Después de implementar cualquier corrección, ejecuta una consulta de prueba para confirmar que el cambio funciona. Una corrección sin verificación está incompleta.

3. Recupérate de los errores, no entres en bucles. Si un enfoque falla después de 2 o 3 intentos, detente y reconsidera. Prueba un método diferente, consulta la documentación, inspecciona el error con más cuidado y revisa los registros relevantes cuando estén disponibles. Los problemas de Supabase no siempre se resuelven reintentando el mismo comando, y la respuesta no siempre está en los registros, pero a menudo vale la pena revisarlos antes de continuar.

4. Exponer tablas a la API de Datos: Dependiendo de la configuración de la API de Datos del usuario, es posible que las tablas recién creadas no se expongan automáticamente a través de la API de Datos (REST). Si este es el caso, será necesario otorgar acceso explícito a los roles anon y authenticated.

Nota: esto es independiente de RLS, que controla qué filas son visibles una vez que una tabla es accesible, no si la tabla es accesible en absoluto.

Cuando un usuario informa que una tabla creada con SQL es inesperadamente inaccesible, verifica su configuración de la API de Datos y si se ha otorgado acceso a los roles mediante GRANT SQL explícito. Al otorgar acceso público (anon/authenticated), habilita también RLS. Consulta Exponer una Tabla a la API de Datos para obtener el flujo de trabajo completo de configuración.

5. RLS en esquemas expuestos. Habilita RLS en cada tabla de cualquier esquema expuesto, lo que incluye public por defecto. Esto es crítico en Supabase porque las tablas en esquemas expuestos pueden ser accesibles a través de la API de Datos cuando los roles anon/authenticated tienen acceso (consulta Exponer una Tabla a la API de Datos). Para esquemas privados, prefiere RLS como defensa en profundidad. Después de habilitar RLS, crea políticas que coincidan con el modelo de acceso real en lugar de usar el mismo patrón auth.uid() por defecto en cada tabla.

6. Lista de verificación de seguridad. Al trabajar en cualquier tarea de Supabase que involucre autenticación, RLS, vistas, almacenamiento o datos de usuario, revisa esta lista. Estas son trampas de seguridad específicas de Supabase que crean vulnerabilidades silenciosamente:

  • Seguridad de autenticación y sesiones

    • Nunca uses las claims de user_metadata en decisiones de autorización basadas en JWT. En Supabase, raw_user_meta_data es editable por el usuario y puede aparecer en auth.jwt(), por lo que no es seguro para políticas RLS ni para ninguna otra lógica de autorización. Almacena los datos de autorización en raw_app_meta_data / app_metadata en su lugar.
    • Eliminar un usuario no invalida los tokens de acceso existentes. Primero cierra la sesión o revoca las sesiones, mantén la caducidad de JWT corta para aplicaciones sensibles, y para garantías estrictas valida session_id contra auth.sessions en operaciones sensibles.
    • Si usas app_metadata o auth.jwt() para la autorización, recuerda que las claims de JWT no siempre están actualizadas hasta que se refresca el token del usuario.
  • Exposición de claves de API y cliente

    • Nunca expongas la clave service_role o la clave secreta en clientes públicos. Prefiere claves publicables para el código del frontend. Las claves anon heredadas son solo para compatibilidad. En Next.js, cualquier variable de entorno NEXT_PUBLIC_ se envía al navegador.
    • Usa tokens de acceso personal con ámbito para la API de Gestión, la CLI y el servidor MCP. Un token de acceso personal clásico conlleva el acceso completo a la cuenta del usuario, en cada organización y proyecto. Para scripts, CI y agentes, haz que el usuario cree un token con ámbito limitado a las organizaciones, proyectos y permisos que la tarea necesite. La guía de tokens de acceso personal enumera el permiso que requiere cada endpoint de la API de Gestión y cada herramienta MCP. Busca los permisos allí en lugar de adivinarlos.
  • RLS, vistas y código de base de datos privilegiado

    • Las vistas omiten RLS por defecto. En Postgres 15 y versiones posteriores, usa CREATE VIEW ... WITH (security_invoker = true). En versiones anteriores de Postgres, protege tus vistas revocando el acceso a los roles anon y authenticated, o colocándolas en un esquema no expuesto.
    • UPDATE requiere una política SELECT. En RLS de Postgres, un UPDATE necesita primero seleccionar la fila. Sin una política SELECT, las actualizaciones devuelven silenciosamente 0 filas, sin error, solo sin cambios.
    • auth.role() está obsoleto: usa la cláusula TO en su lugar. Supabase ha obsoletado auth.role() en favor de especificar el rol de destino directamente en la política con TO authenticated o TO anon. Más allá de la obsolescencia, auth.role() = 'authenticated' se rompe silenciosamente cuando los inicios de sesión anónimos están habilitados, porque los usuarios anónimos llevan el rol de Postgres authenticated y pasan la verificación independientemente de si el usuario está realmente conectado.
      -- Obsoleto (no usar)
      create policy "example" on table_name for select
      using ( auth.role() = 'authenticated' );
      
    • TO authenticated por sí solo es autenticación sin autorización (BOLA / IDOR). Usar TO authenticated solo verifica el rol: no restringe qué filas puede acceder un usuario. El patrón correcto combina TO authenticated con un predicado de propiedad en USING:
      create policy "example" on table_name for select
      to authenticated
      using ( (select auth.uid()) = user_id );
      
    • Las políticas UPDATE requieren tanto USING como WITH CHECK. Sin WITH CHECK, un usuario puede reasignar el user_id de una fila a otro usuario:
      create policy "example" on table_name for update
      to authenticated
      using ( (select auth.uid()) = user_id )
      with check ( (select auth.uid()) = user_id );
      
    • Las funciones SECURITY DEFINER omiten RLS. Una función SECURITY DEFINER se ejecuta con los privilegios de su creador (normalmente un rol con bypassrls, como postgres). Nunca agregues SECURITY DEFINER para resolver un error de permiso; elimina silenciosamente el control de acceso sin solucionar la causa subyacente. Prefiere SECURITY INVOKER.
    • Las funciones SECURITY DEFINER en public son invocables por todos los roles. Postgres otorga EXECUTE a PUBLIC por defecto para cada nueva función, por lo que cualquier función SECURITY DEFINER en public es un endpoint de API pública invocable por anon y authenticated (que heredan de PUBLIC) sin necesidad de una concesión adicional. Cuando SECURITY DEFINER sea realmente necesario (por ejemplo, para omitir RLS en una tabla de búsqueda interna), mantén la función en un esquema no expuesto, incluye siempre una verificación auth.uid() en el cuerpo de la función y ejecuta supabase db advisors después de hacer cambios.
  • Control de acceso a Storage

    • Upsert en Storage requiere INSERT + SELECT + UPDATE. Conceder solo INSERT permite nuevas subidas, pero el reemplazo de archivos (upsert) falla silenciosamente. Necesitas los tres permisos.
  • Seguridad de dependencias y cadena de suministro

    • Fija siempre las versiones de los paquetes y confirma los archivos de bloqueo al instalar paquetes de Supabase (supabase-js, @supabase/ssr, supabase-py, etc.). Consulta la guía de seguridad de npm para obtener la lista de verificación completa.

Para cualquier problema de seguridad no cubierto anteriormente, obtén el índice de seguridad del producto Supabase: https://supabase.com/docs/guides/security/product-security.md

CLI de Supabase

Descubre siempre los comandos mediante --help, nunca adivines. La estructura de la CLI cambia entre versiones.

supabase --help                    # Todos los comandos de nivel superior
supabase <group> --help            # Subcomandos (ej., supabase db --help)
supabase <group> <command> --help  # Banderas para un comando específico

Trampas conocidas de la CLI de Supabase:

  • supabase db query requiere CLI v2.79.0+ → usa MCP execute_sql o psql como alternativa
  • supabase db advisors requiere CLI v2.81.3+ → usa MCP get_advisors como alternativa
  • El flujo del navegador de supabase login crea un token clásico con acceso completo a la cuenta. En CI, establece SUPABASE_ACCESS_TOKEN con un token de acceso personal con ámbito en su lugar. Tiene prioridad sobre cualquier inicio de sesión guardado. Los comandos que se conectan con la contraseña de la base de datos (--password o SUPABASE_DB_PASSWORD, por ejemplo supabase db push) no están limitados por los permisos del token.
  • En proyectos de migración imperativa, crea nuevos archivos de migración escritos a mano con supabase migration new <name> primero. Nunca inventes un nombre de archivo de migración ni confíes en la memoria para el formato esperado. Los proyectos de esquema declarativo generan migraciones desde supabase/schemas/; consulta "Realizar y Confirmar Cambios de Esquema" a continuación.

Verificación y actualización de versión: Ejecuta supabase --version para comprobarlo. Para los changelogs de la CLI y las funciones específicas de la versión, consulta la documentación de la CLI o los lanzamientos de GitHub.

Servidor MCP de Supabase

Para instrucciones de configuración, URL del servidor y configuración, consulta la guía de configuración de MCP.

Solución de problemas de conexión: sigue estos pasos en orden:

  1. Verifica si el servidor es accesible: curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp Un 401 es esperado (sin token) y significa que el servidor está funcionando. Un tiempo de espera o "conexión rechazada" significa que puede estar caído.

  2. Verifica la configuración de .mcp.json: Verifica que la raíz del proyecto tenga un .mcp.json válido con la URL correcta del servidor. Si falta, crea uno que apunte a https://mcp.supabase.com/mcp.

  3. Autentica el servidor MCP: Si el servidor es accesible y .mcp.json es correcto pero las herramientas no son visibles, el usuario necesita autenticarse. El servidor MCP de Supabase usa OAuth 2.1: dile al usuario que active el flujo de autenticación en su agente, lo complete en el navegador y recargue la sesión. En CI u otros entornos donde el flujo del navegador no se puede ejecutar, pasa un token de acceso personal con ámbito en el encabezado Authorization: Bearer en su lugar.

  4. Verifica los permisos del token con ámbito: Si una herramienta falla con "No tienes permiso para realizar esta acción" mientras se usa un token de acceso personal con ámbito, el token carece del permiso de esa herramienta o el proyecto está fuera del ámbito del token. Verifica el permiso requerido de la herramienta en la guía de tokens de acceso personal.

Documentación de Supabase

Antes de implementar cualquier función de Supabase, encuentra la documentación relevante. Usa estos métodos en orden de prioridad:

  1. Herramienta MCP search_docs (preferida: devuelve fragmentos relevantes directamente)
  2. Obtener páginas de documentación como markdown: cualquier página de documentación se puede obtener añadiendo .md a la ruta de la URL.
  3. Búsqueda web para temas específicos de Supabase cuando no sepas qué página consultar.

Realizar y Confirmar Cambios de Esquema

Primero, decide qué flujo de trabajo de esquema usa el proyecto.

Opción A: Esquemas declarativos

Usa esta opción cuando exista supabase/schemas/ o config.toml establezca schema_paths. Edita el estado del esquema deseado en esos archivos, luego genera y revisa la migración. No empieces escribiendo una migración a mano. Consulta la Guía de esquemas de base de datos declarativos.

Opción B: Migraciones imperativas

Usa esta opción cuando el proyecto no use esquemas declarativos.

Para realizar cambios de esquema, usa execute_sql (MCP) o supabase db query (CLI). Estos ejecutan SQL directamente en la base de datos sin crear entradas en el historial de migraciones, por lo que puedes iterar libremente y generar una migración limpia cuando estés listo.

NO uses apply_migration para cambiar un esquema de base de datos local: escribe una entrada en el historial de migraciones en cada llamada, lo que significa que no puedes iterar, y supabase db diff / supabase db pull producirán diferencias vacías o conflictivas. Si lo usas, te quedarás atascado con el SQL que hayas pasado en el primer intento.

Cuando estés listo para confirmar tus cambios en un archivo de migración:

  1. Ejecuta advisors: supabase db advisors (CLI v2.81.3+) o MCP get_advisors. Corrige cualquier problema.
  2. Revisa la Lista de Verificación de Seguridad anterior si tus cambios involucran vistas, funciones, disparadores o almacenamiento.
  3. Genera la migración: supabase db pull <nombre-descriptivo> --local --yes
  4. Verifica: supabase migration list --local

Depuración

Cuando recibas un error en una solicitud relacionada con Supabase, por ejemplo, un código de error de la API REST de Supabase, la base de datos Postgres o PostgREST, un resultado vacío, un bloqueo inesperado por RLS, o un error de un servicio de Supabase como Auth, Realtime, Edge Functions o Storage, debes obtener la documentación de Monitorización y Depuración de Supabase antes de diagnosticar o proponer una corrección, en lugar de trabajar de memoria. Los mismos documentos también cubren optimizaciones de rendimiento, como consultas lentas e índices faltantes.

Guías de Referencia

  • Comentarios sobre la habilidad: → references/skill-feedback.md DEBE leer cuando el usuario informe que esta habilidad ha dado orientación incorrecta o carece de información.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills relacionados