Configurar la base de datos

Qué es una migración

Una base de datos nueva está vacía — no tiene tablas para usuarios, espacios de trabajo ni registros. Una migración es un cambio de base de datos guardado y ordenado: un archivo que dice crea esta tabla, añade aquella columna. El kit incluye sus migraciones ya hechas; el comando db:migrate aplica todas las pendientes a la base de datos nombrada por DATABASE_URL.

Ejecutarlo no es una configuración opcional — es lo que convierte un Postgres vacío en la base de datos de tu app. El inicio de sesión, los espacios de trabajo, los registros de facturación y los datos guardados viven en esas tablas.

Por eso las cuentas se rompen si el inicio de sesión ocurre antes de las migraciones: la app escribe el nuevo usuario en una tabla que todavía no existe y deja una cuenta a medio crear. Migra siempre primero — los pasos de configuración de abajo hacen exactamente eso antes del primer inicio de sesión real.

Configuración y ajustes

Antes de cualquier paso, lea Antes de comenzar y Conceptos básicos del terminal. Estas instrucciones suponen que abrió el monorepo supastack completo en VS Code; su paquete raíz.json marca la raíz del repositorio. En los comandos pnpm, un paquete de espacio de trabajo es una aplicación o una carpeta de código compartido; En el producto, un espacio de trabajo es el contenedor de datos y el límite de seguridad de un equipo. corepack pnpm --filter ... selecciona un paquete del monorepo mientras los comandos se ejecutan desde su raíz. Si abrió solo una carpeta sincronizada para dispositivos móviles o de escritorio, no contiene el backend web, la configuración de Docker ni los scripts raíz: ejecute el backend desde este monorepo o un servidor alojado accesible y use los propios scripts de la carpeta de la plataforma. Una variable de entorno es una configuración con nombre almacenada en un archivo .env local o en su panel de hosting; reinicie la aplicación correspondiente después de cambiarla y mantenga los secretos del servidor fuera de los valores NEXT_PUBLIC_ y EXPO_PUBLIC_.

1. Instale e inicie Docker Desktop.

2. Copie .env.example a .env en la raíz para herramientas de migración y a apps/web/.env.local para Next.js (PowerShell: Copy-Item .env.example .env; Copy-Item .env.example apps/web/.env.local. macOS/Linux/Git Bash: cp .env.example .env; cp .env.ejemplo apps/web/.env.local). Mantenga DATABASE_URL igual en ambos archivos; el ejemplo ya coincide con la base de datos local de Docker.

3. Desde la raíz del repositorio, ejecute docker compose up -d postgres y docker compose ps; Espere hasta que Postgres informe que está en buen estado.

4. Ejecute corepack pnpm --filter @supastack/db db:migrate desde la raíz para aplicar las migraciones que ya se incluyen con el kit. Solo después de editar packages/db/src/schema.ts, ejecute db:generate, inspeccione el SQL generado y luego ejecute db:migrate. Se esperaba: el contenedor Postgres local está en buen estado y la aplicación web utiliza su base de datos migrada. Nunca apunte esta primera ejecución a producción.

Configura DATABASE_URL para la base de datos Postgres prevista en el entorno del servidor. Usa una base de datos desechable independiente para la aceptación de integración. Nunca apuntes las migraciones de prueba a una base de datos de producción.

El espacio de trabajo de la base de datos exporta definiciones del esquema y helpers de persistencia. Revisa packages/db/src/schema.ts y el directorio de migraciones antes de añadir una tabla o columna.

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

# Only after changing packages/db/src/schema.ts:
corepack pnpm --filter @supastack/db db:generate
corepack pnpm --filter @supastack/db db:migrate

# Optional Compose / Supabase settings in .env:
# POSTGRES_PASSWORD=supastack
# SUPABASE_ACCESS_TOKEN=
# DATABASE_POOLER=transaction

Comandos para copiar

Siga los comentarios para ver en qué carpeta se ejecuta un comando. Si dos terminales están etiquetados, abra dos ventanas de terminal y mantenga el primer comando ejecutándose mientras usa el segundo.

# Choose one copy method for your terminal:
# PowerShell:
Copy-Item .env.example .env
Copy-Item .env.example apps/web/.env.local

# macOS/Linux/Git Bash alternative:
# cp .env.example .env
# cp .env.example apps/web/.env.local

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

Flujo de implementación

Genera una migración después de editar el esquema, inspecciona el SQL generado y confírmala con el cambio de esquema. Planifica cómo recibirán valores los registros existentes antes de añadir una columna obligatoria.

Incluye workspaceId en cada registro propiedad de usuarios y aplica ese ámbito a las lecturas y escrituras. Usa un historial inmutable de precios de modelos para la contabilidad de IA, en lugar de reescribir precios usados por registros de uso existentes.

Verificación y solución de problemas

Si Docker dice que no puede conectarse a su motor, inicie Docker Desktop y espere a que termine de cargarse. Si postgres no está en buen estado, ejecute docker compose logs postgres desde la raíz y corrija ese error antes de migrar. Si la Web dice que falta DATABASE_URL, verifique apps/web/.env.local; Si db:migrate no puede conectarse, verifique el .env raíz. Si cambia las bases de datos, actualice ambos archivos. Lea la primera declaración de migración fallida antes de volver a intentarlo; nunca lo repita contra la producción.

Aplica las migraciones a una base aislada y ejecuta allí las pruebas que requieren base de datos. Si faltan credenciales, la comprobación debe omitirse explícitamente, no afirmar que la persistencia se verificó. Si falla una migración, antes de reintentar inspecciona qué instrucción falló y el esquema actual.