logo

Precios

Migrar de Supabase a Insforge: Guía Paso a Paso

Un toolkit de código abierto para migrar tu proyecto de Supabase—usuarios, base de datos y archivos—sin pérdida de datos.

Kyle ChungKyle Chung

Migra de Supabase a Insforge en minutos: una guía completa y probada en producción

Hola. Si has decidido mover tu proyecto de Supabase a Insforge, esta guía es para ti. Las migraciones pueden ser intimidantes. Quizás te preguntes: ¿cómo muevo a todos mis usuarios sin forzar un restablecimiento de contraseña? ¿Cómo transfiero cada archivo y actualizo todos los enlaces? ¿Qué pasa con el esquema de mi base de datos y todos esos datos valiosos?

No te preocupes. Te ayudamos.

Esta guía presenta un kit de herramientas de migración completo y probado en producción, diseñado para trasladar sin problemas todo tu proyecto de Supabase a una instancia autoalojada de Insforge. No hablamos solo de un volcado de datos parcial, sino de una migración completa que preserva:

  • ✅ Autenticación de usuarios (¡contraseñas incluidas!)
  • ✅ Base de datos completa (esquema y datos)
  • ✅ Todos los archivos de almacenamiento (con sus rutas exactas)
  • ✅ Relaciones de clave externa (al preservar los ID de usuario)

Este kit de herramientas ha sido probado en un entorno de producción real, migrando con éxito 39 usuarios, 985 filas de la base de datos y más de 1.500 archivos de almacenamiento sin pérdida de datos. Para más información sobre el autoalojamiento, consulta el repositorio de Insforge en GitHub.

Empecemos.

Primeros pasos: tu lista de comprobación previa

Antes de empezar, configuremos tu entorno para una migración fluida.

1. Prerrequisitos

Primero, asegúrate de tener las herramientas y los accesos necesarios:

  • Software:
    • Node.js (v20+)
    • Cliente de PostgreSQL (psql)
  • Accesos:
    • Credenciales de tu proyecto de Supabase (claves de API, URL de la base de datos).
    • Una instancia activa de Insforge con una clave de API de administrador.

2. Configuración del entorno

Ahora, configuremos la herramienta de migración.

Primero, clona el repositorio del kit de herramientas (o descarga el código fuente) e instala las dependencias.

# Clona el repositorio (si aplica)
# git clone <https://github.com/InsForge/supabase-to-insforge>

# Instala las dependencias
npm install

A continuación, crea tu archivo de configuración de entorno. Copia el archivo de ejemplo para crear tu propio archivo .env.

cp .env.example .env

Ahora, abre el archivo .env recién creado y rellena las credenciales tanto para el proyecto de Supabase que has decidido migrar como para el nuevo proyecto de Insforge.

Cómo encontrar tus credenciales de Supabase

Para rellenar el archivo .env, necesitarás tres datos clave del panel de tu proyecto de Supabase.

  1. SUPABASE_URL y SUPABASE_SERVICE_ROLE_KEY:
    • Navega a tu proyecto de Supabase.
    • Ve a Project Settings (el icono del engranaje).
    • Haz clic en API.
    • Aquí encontrarás la URL de tu proyecto y tu clave secreta service_role.
  2. SUPABASE_DB_URL (tu cadena de conexión):
    • En el panel de tu proyecto de Supabase, haz clic en el botón Connect en la parte superior de la página.
    • Se abrirá un panel con los detalles de conexión de tu base de datos.
    • Copia la URI de la sección Direct connection.
    • Importante: Debes reemplazar el marcador [YOUR-PASSWORD] en la cadena con tu contraseña real de la base de datos. Si la has olvidado, puedes restablecerla en Project Settings > Database.

PSQL String

# ============================================
# Configuración de Supabase
# ============================================
# Encuentra estas credenciales en los ajustes de Supabase
SUPABASE_URL=https://TU_PROYECTO.supabase.co
SUPABASE_SERVICE_ROLE_KEY=tu_clave_service_role_de_supabase
SUPABASE_DB_URL=postgresql://postgres.xxx:[TU-CONTRASEÑA]@...

# ============================================
# Configuración de Insforge
# ============================================
# Detalles de tu instancia de Insforge
INSFORGE_API_URL=http://localhost:7130 # O tu URL remota
INSFORGE_API_KEY=tu_clave_api_de_insforge

3. Verifica tu conexión

Antes de ejecutar la migración, asegurémonos de que la herramienta puede conectarse a ambas bases de datos. Ejecuta estos comandos para probar tus conexiones:

# Prueba la conexión con Supabase
psql "$SUPABASE_DB_URL" -c "SELECT version();"

# Prueba la conexión con Insforge (ajústalo a tu configuración local/remota)
psql postgresql://postgres:postgres@localhost:5432/insforge -c "SELECT version();"

# Salir
\\q

Si ambos comandos se ejecutan sin errores, ¡estás listo para el evento principal!

La gran migración: una guía paso a paso

La migración se divide en tres fases lógicas. Síguelas en orden para obtener los mejores resultados.

Fase 1: Migración de tus usuarios (¡sin restablecer contraseñas!)

Esta suele ser la parte más complicada de cualquier migración, pero este kit de herramientas la simplifica. Migraremos todas las cuentas de usuario conservando sus contraseñas originales.

Paso 1.1: Exportar usuarios de Supabase

Este comando se conecta a tu proyecto de Supabase y exporta todos los usuarios de la tabla auth.users a un archivo JSON local.

npm run export:auth

Salida esperada:

✅ Conectado a Supabase PostgreSQL
✅ Exportados 39 usuarios a auth-export.json

Esto crea un archivo llamado auth-export.json que contiene los detalles de los usuarios, incluidos sus ID y contraseñas cifradas.

Paso 1.2: Importar usuarios a Insforge

Ahora, importaremos los usuarios del archivo auth-export.json a tu instancia de Insforge. El script conserva los ID de usuario originales (críticos para las claves externas) y sus contraseñas con hash bcrypt.

npm run import:auth

Salida esperada:

✅ Conectado a la API de Insforge
   URL: <https://tu-instancia-de-insforge.insforge.app>

📦 Cargando datos de exportación...
⬆️  Importando usuarios...
   ✅ Importadas 41/41 cuentas
✅ ¡Importación completa!

Consejo profesional: Este script es idempotente, lo que significa que puedes ejecutarlo varias veces sin crear usuarios duplicados. Simplemente actualizará los registros existentes si los encuentra.

Fase 2: Migración de tu base de datos

A continuación, moveremos toda tu base de datos PostgreSQL, incluido el esquema, los datos e incluso tus políticas de seguridad a nivel de fila (RLS).

Paso 2.1: Exportar el esquema y los datos de la base de datos

Este comando utiliza pg_dump para crear una copia de seguridad SQL completa de tus esquemas públicos desde Supabase.

npm run export:db

Salida esperada:

✅ Base de datos exportada con éxito
   Archivo: database-export.sql (245 KB)

Esto generará un archivo database-export.sql.

Paso 2.2: Transformar el SQL para Insforge

Supabase utiliza algunas funciones y extensiones específicas. Este script limpia el archivo SQL exportado, elimina el código específico de Supabase, actualiza las políticas RLS (p. ej., auth.uid() se convierte en uid()) y lo hace compatible con Insforge.

npm run transform:db

Salida esperada:

✅ SQL transformado para Insforge
   Salida: database-export.insforge.sql

Esto crea un nuevo archivo listo para Insforge: database-export.insforge.sql.

Paso 2.3: Importar la base de datos a Insforge

Finalmente, importemos el archivo SQL transformado a tu proyecto de Insforge.

npm run import:db

Salida esperada:

🗄️  Importando base de datos a Insforge...
✅ ¡Importación de base de datos completa!
Tablas afectadas: 12
Filas importadas: 985

¡Tu esquema y datos de la base de datos han sido migrados con éxito!

Fase 3: Migración de tu almacenamiento de archivos

La fase final es mover todos tus archivos de Supabase Storage a Insforge Storage. Este proceso preserva las rutas exactas de los archivos, lo cual es crucial para evitar enlaces rotos.

Paso 3.1: Recrear los buckets de almacenamiento

Primero, el script leerá la lista de buckets de tu proyecto de Supabase y creará otros idénticos en Insforge, conservando su configuración pública o privada.

npm run create:buckets

Salida esperada:

✅ Conectado a Supabase PostgreSQL
📦 Se encontraron 4 buckets en Supabase:
📋 Creando bucket: generated-images (público)... ✅ Creado con éxito
📋 Creando bucket: raw-product-images (público)... ✅ Creado con éxito
...
✅ ¡Creación de buckets completa!

Paso 3.2: Descargar todos los archivos de Supabase

Este comando descarga cada archivo de todos tus buckets de Supabase, preservando la estructura de directorios original.

npm run export:storage

Salida esperada:

📦 Iniciando exportación de almacenamiento desde Supabase...
⬇️  Descargando archivos...
   [1/1572] generated-images/user123/image.jpg ✅
   ...
   [1572/1572] reference-images/ref5.jpg ✅

✅ ¡Exportación completa! Descargados: 1.572 archivos

Todos los archivos se guardarán localmente en un directorio storage-downloads/.

Paso 3.3: Subir todos los archivos a Insforge

Ahora, subiremos todos los archivos descargados a sus buckets correspondientes en Insforge.

npm run import:storage

Salida esperada:

📦 Se encontraron 1572 archivos para importar
⬆️  [1/1572] generated-images/user123/scene/image.jpg... ✅ Subido
...
✅ ¡Importación completa! Éxito: 1569/1572

Paso 3.4: El toque final - Actualizar todas las URL de almacenamiento

Esta es la varita mágica. Es probable que tu base de datos contenga miles de URL que apuntan a Supabase Storage. Este script se conecta a tu base de datos de Insforge y realiza una búsqueda y reemplazo universal en todas las tablas. Actualiza de forma inteligente cada URL de almacenamiento de Supabase a la nueva URL de Insforge, incluso dentro de campos JSONB complejos.

npm run update:storage-urls

Salida esperada:

✅ Conectado a la API de Insforge
🔄 Reemplazo universal de URL...
📊 Encontrado:
   - 997 generaciones con URL de Supabase en la entrada
   - 1023 generaciones con URL de Supabase en la salida
⏳ Actualizando universalmente TODAS las URL...
✅ ¡Todas las URL de almacenamiento de Supabase han sido actualizadas!

¡Y eso es todo! Tu proyecto completo ha sido migrado.

¿Qué sigue? Pasos posteriores a la migración

Tus datos están migrados, pero aún no has terminado. Aquí están los pasos finales para que tu aplicación funcione en Insforge.

  1. Actualizar el código de la aplicación: Cambia la configuración del cliente de tu aplicación para que apunte a tu instancia de Insforge en lugar de a Supabase. Para una guía detallada sobre cómo reconfigurar el SDK usando MCP, consulta nuestra publicación de blog complementaria.

    // Antes (Supabase)
const supabase = createClient('URL_SUPABASE', 'CLAVE_ANON_SUPABASE');

// Después (Insforge)
const insforge = createClient('URL_API_INSFORGE', 'CLAVE_API_INSFORGE');

  2. Pruebas de extremo a extremo: Prueba tu aplicación a fondo.

    • ¿Pueden los usuarios iniciar sesión con sus contraseñas antiguas?
    • ¿Se cargan correctamente las imágenes y los archivos?
    • ¿Funcionan como se esperaba todas las funciones relacionadas con los datos?

  3. Limpieza: Una vez que hayas confirmado que todo funciona, puedes eliminar los archivos de migración temporales (storage-downloads/, .sql, .json).

Solución de problemas comunes

  • Error File too large durante la importación del almacenamiento: Tu archivo excede el límite de subida de la instancia de Insforge. Puede que necesites aumentar el límite o migrar el archivo manualmente.
  • Fallo al iniciar sesión con contraseña: Vuelve a comprobar que el script import:auth se ejecutó correctamente. Los hashes de contraseña bcrypt deberían haberse conservado tal cual.
  • Tiempo de espera de conexión agotado: Verifica que tu IP esté en la lista blanca de las restricciones de red de Supabase y que tus cadenas de conexión en .env sean correctas.

¡Feliz migración! 🚀

return Blogs