database-schema-design

name	Database Schema Design
description	DISEÑAR esquema de base de datos relacional normalizado y escalable antes de escribir código backend. Hacer cumplir 3FN, claves primarias UUIDv7, claves foráneas con reglas de cascada e índices de consulta. Prevenir datos desnormalizados, restricciones faltantes y consultas sin índice. Activadores: "design (the|a) database", "create (the|a) schema", "set up (Prisma|Drizzle)", "plan (the|the) tables".
category	backend
version	3.0.0
last_updated	2026-06-28T00:00:00.000Z
stacks	["PostgreSQL 17","Prisma 7","Drizzle ORM 0.45+","MySQL","SQLite"]
triggers	[{"pattern":"design (the|a) (database|schema|tables)","action":"EJECUTAR flujo de diseño de esquema"},{"pattern":"set up (Prisma|Drizzle)","action":"EJECUTAR flujo de diseño de esquema"},{"pattern":"plan (the|the) tables","action":"EJECUTAR flujo de diseño de esquema"},{"pattern":"el proyecto requiere persistencia de datos","action":"EJECUTAR diseño de esquema antes de cualquier código de ruta API"}]
related_skills	["api-route-structure","backend-validation-layers","saas-app-structure"]
lang	es
direction	ltr
source_version	3.0.0
translated_at	2026-06-29T00:00:00.000Z

Diseño de Esquema de Base de Datos

IDENTIFICAR: Cuándo activarse

Activar cuando:

• Se planifica una nueva funcionalidad que persiste datos relacionales complejos
• El usuario dice "design the database", "create tables", "set up Prisma/Drizzle"
• Durante la fase de planificación arquitectónica (después del descubrimiento de requisitos)

DECIDIR: Ruta de Diseño de Esquema

SI proyecto greenfield →
  EJECUTAR Pasos 1-7 en orden

SI se añaden tablas a un esquema existente →
  ESCANEAR esquema existente primero (schema.prisma o esquema drizzle)
  SEGUIR convenciones existentes (UUID vs auto-incremento, estilo de nombres, marcas de tiempo)
  EJECUTAR Pasos 1-7, pero omitir decisiones ya tomadas por el esquema existente

SI se requiere NoSQL (basado en documentos, clave-valor) →
  DETENER, esta habilidad es solo para bases de datos relacionales

EJECUTAR: Instrucciones

Paso 1: Identificar Entidades

Listar cada "cosa" distinta que la aplicación rastrea. Cada una se convierte en una tabla.

REGLAS DE IDENTIFICACIÓN:
- Cada entidad es un sustantivo: User, Order, Product, Comment, Tag
- Cada entidad obtiene UNA tabla
- Si un sustantivo no puede existir independientemente → es un atributo, no una entidad

Paso 2: Definir Relaciones

Mapear conexiones entre entidades:

TIPOS DE RELACIÓN:
1:1  → Clave foránea en cualquier lado + restricción UNIQUE
1:N  → Clave foránea en el lado "muchos"
N:M  → Tabla puente (PK compuesta)

Paso 3: Elegir Claves Primarias

POR DEFECTO: UUIDv7 (ordenado por tiempo, amigable con B-tree, seguro en distribución)

Prisma 7 (TypeScript puro):

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Paso 4: Normalizar a 3FN

1FN: Sin grupos repetidos
2FN: Columnas no clave dependen de toda la PK
3FN: Sin dependencias transitivas

Paso 5: Definir Claves Foráneas

Cada relación DEBE tener una restricción de clave foránea con ON DELETE explícito:

CREATE TABLE posts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  author_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE
);