schema-design

name	schema-design
description	Diseñar esquemas de base de datos normalizados con índices y documentación. Activar cuando el usuario quiera diseñar base de datos, crear tablas, definir relaciones, aplicar normalizacion, configurar indices, crear un modelo de datos o generar un ERD.

Diseño de esquemas de base de datos

Resumen

Este skill guía el proceso de diseñar un esquema de base de datos relacional a partir de requisitos funcionales. El diseño no es solo crear tablas que almacenen datos, sino modelar el dominio del negocio de forma que garantice integridad, rendimiento y evolución sostenible.

El esquema resultante debe estar normalizado hasta la tercera forma normal (3NF) como mínimo, con índices justificados, constraints que protejan la integridad y documentación que permita a cualquier miembro del equipo entender cada tabla y columna sin necesidad de leer el código de la aplicación.

Proceso

1. Analizar los requisitos y extraer entidades. A partir de los requisitos funcionales, identificar las entidades del dominio. Cada sustantivo relevante es un candidato a entidad: usuario, pedido, producto, factura. Documentar qué atributos tiene cada entidad y cuáles son obligatorios.

2. Definir las relaciones entre entidades. Para cada par de entidades relacionadas, determinar la cardinalidad:

   • Uno a uno (1:1): poco frecuente, evaluar si realmente son dos entidades o una sola.
   • Uno a muchos (1:N): la más habitual. La clave foránea va en el lado "muchos".
   • Muchos a muchos (N:M): requiere tabla intermedia con claves foráneas compuestas.

   Documentar la dirección de la relación y si es obligatoria u opcional en cada extremo.

3. Normalizar hasta 3NF. Aplicar las formas normales secuencialmente:

   • 1NF: cada columna contiene valores atómicos, sin listas ni objetos anidados.
   • 2NF: todos los atributos no clave dependen de la clave primaria completa, no de una parte.
   • 3NF: ningún atributo no clave depende de otro atributo no clave (eliminar dependencias transitivas).

   Si hay motivos de rendimiento para desnormalizar, documentar la justificación explícitamente.

4. Aplicar convenciones de naming. Mantener coherencia en todo el esquema:

   • Tablas en plural y snake_case: users, order_items, payment_methods.
   • Columnas en singular y snake_case: email, created_at, total_amount.
   • Claves primarias: id o <tabla_singular>_id.
   • Claves foráneas: <tabla_referenciada_singular>_id.
   • Índices: idx_<tabla>_<columnas>.
   • Timestamps de auditoría: created_at y updated_at en todas las tablas.

5. Definir constraints e integridad referencial. Para cada tabla:

   • PRIMARY KEY en todas las tablas, sin excepción.
   • FOREIGN KEY con la acción ON DELETE adecuada (CASCADE, SET NULL, RESTRICT).
   • NOT NULL en columnas obligatorias.
   • UNIQUE donde corresponda (email, slug, códigos).
   • CHECK para validaciones a nivel de base de datos (rangos, enumerados, formatos).

6. Diseñar los índices. Los índices se crean para consultas concretas, no de forma preventiva:

   • Índice en todas las claves foráneas (muchos motores no lo hacen automáticamente).
   • Índice en columnas usadas frecuentemente en WHERE, ORDER BY y JOIN.
   • Índices compuestos cuando las consultas filtran por varias columnas (respetar el orden).
   • Evaluar índices parciales o funcionales si el motor lo permite.

7. Adaptar al ORM del proyecto. Traducir el diseño a la sintaxis del ORM utilizado (Prisma, Drizzle, SQLAlchemy, Django ORM, TypeORM). Asegurarse de que las relaciones, índices y constraints se expresan correctamente en el modelo del ORM, ya que no todos soportan las mismas funcionalidades.

8. Registrar las decisiones de modelado. Registrar las decisiones de modelado en la memoria del proyecto con memory_log_decision. Esto incluye el motivo de cada desnormalización, la elección de tipos de datos especiales y las concesiones de rendimiento vs. integridad.

9. Documentar el esquema. Cada tabla debe tener un comentario que explique su propósito. Las columnas no obvias deben documentar qué representan, sus valores posibles y sus restricciones. Si el motor lo permite, usar comentarios nativos (COMMENT ON); si no, documentar en un fichero adjunto o en el propio código del ORM.

Que NO hacer

• No crear campos JSON "para todo". Los campos JSON son útiles para datos semiestructurados, pero no sustituyen a columnas y relaciones bien diseñadas.
• No usar soft delete (columna deleted_at) sin evaluar las consecuencias en queries, índices y unicidad.
• No omitir las migraciones. Todo cambio en el esquema debe pasar por el sistema de migraciones del proyecto.
• No crear índices en todas las columnas "por si acaso". Cada índice ocupa espacio y ralentiza las escrituras.
• No ignorar los tipos de datos. Usar el tipo más específico posible: TIMESTAMP para fechas, DECIMAL para dinero, UUID para identificadores distribuidos.
• No normalizar en exceso para escenarios de alta lectura. A veces una desnormalización controlada y documentada es la decisión correcta cuando el patrón de acceso lo justifica.
• No diseñar sin conocer los patrones de consulta. El esquema debe servir a las queries que la aplicación ejecutará, no al revés.
• No olvidar los índices para las queries más frecuentes. Diseñar los índices junto con el esquema, no como una corrección posterior.