Base de datos

---
name: base-de-datos
description: dónde vive la información y cómo la cambias sin perderla.
---

# Base de datos

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
elijas motor, modeles tablas o escribas migraciones.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- La app tiene que recordar algo después de recargar la página.
- Hay varios usuarios, varios dispositivos, o cualquier historial que conservar.
- Vas a consultar, filtrar u ordenar sobre más de unos cientos de registros.
- Necesitas exportar, respaldar o migrar lo que la gente guardó.

Esta es casi siempre la primera skill que activas en un rebuild: casi todo lo demás
cuelga de aquí.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: **Postgres** administrado
(**Neon** o **Supabase**) con **Drizzle** o **Prisma** para el esquema y las migraciones
versionadas en el repo. **SQLite** local (`better-sqlite3`) si la app es de un solo
usuario.

1. Postgres por defecto. SQLite solo si la app corre en una máquina y una persona.
2. Modela primero las entidades que el usuario nombraría en voz alta, no las pantallas
   que vas a construir.
3. Cada cambio de esquema es un archivo de migración generado por tu ORM
   (`drizzle-kit generate`, `prisma migrate`), en orden y aplicado en despliegue. Nada de
   `ALTER TABLE` a mano en producción.
4. Pon llaves foráneas e índices desde el inicio: id de organización, id de usuario y las
   columnas por las que ordenas.
5. Define borrado suave (`deletedAt`) donde el usuario pueda arrepentirse.
6. Verifica que el respaldo restaura de verdad. Un respaldo que nunca probaste no es un
   respaldo.

## En qué te vas a trabar

- **Guardar todo como JSON en una columna se siente rápido el primer día** y bloquea
  cualquier consulta el mes tres. Modela columnas reales para lo que vas a filtrar u
  ordenar.
- **Las funciones sin servidor abren muchas conexiones**: usa pooling (el que trae Neon
  o Supabase) o vas a tumbar la base sin tráfico real.
- **Las migraciones destructivas necesitan dos pasos** (escribir en ambos lados, después
  borrar), no valentía. No borres una columna en el mismo despliegue en que dejas de
  usarla.

## Criterio de terminado

No declares el esquema listo hasta que puedas correr las migraciones desde cero contra
una base vacía, restaurar un respaldo de prueba y confirmar que las consultas más
frecuentes usan un índice y no un escaneo completo.