backend-data-modeling

Backend data modeling

Cuándo usar

• Crear o modificar tablas, columnas, índices, constraints.
• Diseñar una migración que se va a correr en producción.
• Resolver un problema de performance que apunta a la base.

Reglas de esquema

• Una clave primaria por tabla. UUID v7 / ULID si necesitás generarla del lado app; bigserial si la base la genera.
• NOT NULL por defecto. Permitir NULL es una decisión, no el descuido.
• DEFAULT explícito en columnas booleanas y de estado.
• Tipos correctos: text (no varchar(N) salvo restricción real), timestamptz (no timestamp), numeric(p,s) para dinero (nunca float/double).
• CHECK constraints para invariantes simples (status IN (...), monto >= 0).
• FK con ON DELETE explícito: CASCADE / SET NULL / RESTRICT. Sin pensar = bomba de tiempo.

Convenciones

• Nombres en snake_case, plural para tablas (usuarios, sesiones).
• PK: id. FK: <tabla_singular>_id (usuario_id).
• Timestamps en toda tabla: created_at, updated_at (timestamptz NOT NULL DEFAULT now()).
• Soft delete solo si hay requisito real de recuperación; preferí archivado a deleted_at.

Índices

• Toda FK lleva índice (no se crea solo en Postgres).
• Índice compuesto en el orden de la query (WHERE a=? AND b=? → (a,b), no (b,a)).
• Índices parciales para flags raros: CREATE INDEX ... WHERE status='active'.
• No indexar por reflejo. Cada índice cuesta en escritura; medí con EXPLAIN ANALYZE antes.

Migraciones seguras (zero-downtime)

Para tablas grandes, dividí en pasos:

1. Agregar columna NULL (instantáneo en Postgres ≥11).
2. Backfill por lotes con cursor o batch.
3. Agregar NOT NULL y DEFAULT cuando esté lleno.
4. Cambio de aplicación que la use.
5. Drop de la vieja en migración separada y posterior.

Nunca en una sola migración: ALTER ... ADD COLUMN NOT NULL DEFAULT ... en tabla grande sin pensar; bloquea por minutos en algunos motores.