Convenciones¶

Tipos de dato canónicos¶

Un concepto del dominio tiene exactamente un tipo. No se admiten dos columnas que representen lo mismo con tipos distintos.

¿Por qué acotar además con CHECK?¶

varchar(n) obliga a reescribir la tabla para ampliar el límite. Las longitudes que provienen de un requerimiento se declaran además como restricción de verificación con nombre propio, que puede agregarse NOT VALID y validarse después sin bloquear escrituras. El nombre aparece en el error y permite identificar cuál de las reglas de la tabla se violó. Ver tipos de carácter.

¿Por qué numeric y no float?¶

Los reportes de RF-A-51 suman miles de montos. double precision acumula error de representación en binario y produce totales que no cuadran contra la suma manual del comercio. numeric es exacto en base decimal. Ver tipos numéricos.

Columnas estándar¶

Toda tabla de dominio incluye estas columnas. No se repiten en las tablas de campos de cada ficha.

Las tablas append-only no llevan updated_at: una fila que nunca cambia no puede tener fecha de última modificación, y tenerla sería afirmar algo falso sobre la tabla.

Toda tabla lleva además dos protecciones heredadas de su clase base, no declaradas fila por fila: trg_protect_truncate, que bloquea TRUNCATE a nivel de sentencia, y trg_readonly_primarykey, que rechaza cualquier cambio de la llave primaria. Los tres triggers de esta sección son la única excepción al patrón trg_<tabla>_<regla> de Nomenclatura: al vivir en la clase base de la que heredan todas las tablas, se declaran una sola vez con un nombre fijo en vez de uno por tabla.

trg_touch_updatedat se dispara con una condición AnyChange que excluye la propia updated_at. En las seis tablas que llevan columnas generadas almacenadas (invitacion, comercio_horario, ventana_recogida, publicacion, reserva y validacion_reserva) la condición excluye además esas columnas: una columna generada cambia porque cambió su expresión, no porque alguien la escribiera, e incluirla en la condición haría que el trigger se considerara disparado por su propio efecto.

id se genera con uuidv7(), que es ordenable en el tiempo. Eso lo convierte en el desempate natural de toda consulta paginada: una página sin ORDER BY determinista puede repetir u omitir filas entre peticiones, y ordenar por id descendente da orden cronológico inverso sin costo adicional porque recorre la llave primaria. Toda consulta paginada del sistema termina su cláusula de orden con id.

Política de nulabilidad¶

La regla depende del tipo, porque el nulo no significa lo mismo en todos.

Nomenclatura¶

Prefijo por tipo de objeto, seguido del nombre de la tabla y de los segmentos que lo identifican. Los segmentos colapsan los guiones bajos internos del nombre de columna (created_at => createdat) y omiten el sufijo _id de las llaves foráneas, para respetar el límite de 63 bytes de los identificadores de PostgreSQL.

Las restricciones se nombran siempre de forma explícita. Un nombre generado por PostgreSQL (reserva_cantidad_check1) aparece en el mensaje de error que ve el usuario final a través de la API y no dice nada sobre la regla violada.

Los triggers de solo lectura son la segunda excepción al patrón, además de los cinco de la clase base: se llaman trg_readonly_snapshot en las seis tablas que congelan un snapshot (documento_legal, publicacion, reserva, valoracion, incidencia_descargo, validacion_reserva) sin el nombre de la tabla. Es deliberado: un trigger de esta clase no impone una regla propia, aplica el mismo régimen genérico con otra lista de columnas, y el nombre uniforme hace evidente que son el mismo mecanismo. Los nombres de trigger son únicos por tabla en PostgreSQL, así que repetirlos no colisiona.

Convención de nombres de tabla¶

Singular, snake_case, en español. Las tablas puente llevan los nombres de ambos extremos en orden de dependencia (e.g. usuario_comercio). Las tablas de catálogo de estado llevan el prefijo estado_ seguido de la entidad que gobiernan (estado_reserva), descrito en Estados.

Llaves primarias¶

Toda tabla de dominio usa una llave primaria uuid sustituta, por decisión transversal.

Las relaciones donde la llave natural sería la única candidata se expresan con un índice único sobre la columna correspondiente, que da exactamente la misma garantía sin propagar columnas a las tablas que la referencian.

Llaves foráneas¶

La acción referencial se elige por la naturaleza de la relación, no por uniformidad.

ON UPDATE no se declara en ninguna llave foránea: las llaves primarias son inmutables por trg_readonly_primarykey, de modo que no hay actualización que propagar.

Las llaves foráneas se declaran DEFERRABLE INITIALLY DEFERRED. La verificación ocurre al cerrar la transacción y no al ejecutar cada sentencia, lo que permite escribir padre e hijo en el orden que imponga la lógica sin reordenar las sentencias ni calcular dependencias.

El precio es que una violación referencial aparece en el COMMIT y no en la sentencia que la causó, de modo que el error no señala qué escritura estuvo mal. Cuando eso importa (p. ej., al construir la respuesta de un error de escritura compuesta) la transacción adelanta la verificación con SET CONSTRAINTS ALL IMMEDIATE, que aplica hasta el final de la transacción y se revierte con ella.

Nombres por papel¶

Una llave foránea se nombra por el papel que cumple la fila referenciada, no por la tabla a la que apunta. comercio.logo_id y usuario.foto_id apuntan ambas a media, y llamarlas logo_media_id y foto_media_id repetiría en el nombre lo que la restricción ya declara.

La excepción es cuando el papel no distingue: motivo_id se llama así porque el papel es ser el motivo. Cuando una tabla referencia dos veces el mismo catálogo, ambos nombres llevan el papel completo: valoracion.motivo_moderacion_id frente a solicitud_afiliacion.motivo_rechazo_id.

Cascadas del modelo¶

Solo cinco relaciones son CASCADE, y todas comparten la misma forma: la fila hija es un fragmento de la madre, carece de identidad de negocio propia y nadie más la referencia.

• comercio_foto cuelga de comercio
• plantilla_oferta_item cuelga de plantilla_oferta
• plantilla_programacion cuelga de plantilla_oferta
• excepcion_calendario cuelga de plantilla_oferta
• publicacion_item cuelga de publicacion

En todos los demás casos la relación es entre entidades con vida propia, y el borrado del padre debe fallar en lugar de arrastrar historia.

Indexación¶

Toda llave foránea lleva un índice B-tree sobre su columna. PostgreSQL indexa automáticamente el lado referenciado, nunca el referenciante, y sin ese índice cada verificación de la restricción recorre la tabla hija completa. Las fichas solo listan índices de llave foránea cuando tienen columnas adicionales o una condición parcial.

Criterios de invariantes¶

Criterio único aplicado en todo el modelo. Ante la duda, gana la fila más alta de la tabla: el mecanismo más barato y más difícil de evadir.

Las dos filas de trigger que preceden a la última son la razón por la que el modelo tiene una página propia para ellos. El contrato común, las familias de las que se derivan y el catálogo completo están en Triggers.

Predicados de índice parcial¶

El predicado de un índice solo admite expresiones inmutables sobre columnas de la propia fila. No puede consultar otra tabla ni llamar a now().

En consecuencia, los índices parciales del modelo se apoyan en marcas temporales nulables, nunca en el estado. Cada entidad con ciclo de vida lleva las marcas que registran sus transiciones, y el subconjunto vivo se identifica con IS NULL sobre la marca de cierre.

CREATE UNIQUE INDEX unq_reserva_usuario_comercio_activa
ON reserva (usuario_id, comercio_id)
WHERE finalizada_at IS NULL;

Triggers que dereferencian llaves foráneas¶

Un trigger BEFORE se ejecuta antes de que se verifique la llave foránea de la fila que lo dispara, porque esa verificación está diferida al cierre de la transacción. Un trigger que lee la fila referenciada para copiar datos o validar coherencia no puede asumir que esa fila existe.

Todos ellos comprueban la existencia como primer paso y lanzan una violación referencial con la columna explícita. Sin esa comprobación, un identificador inexistente produce el error que devuelva la consulta interna del trigger, que no nombra la columna y llega al cliente como un conflicto genérico.

Formato de las fichas de trigger¶

Cada trigger se documenta con seis campos, en este orden: nombre, evento, momento, nivel, regla que impone y requerimiento que la origina. Un trigger sin requerimiento asociado es un trigger que hay que justificar o borrar.

La ficha de cada trigger vive en la página del módulo al que pertenece su tabla. Triggers define el contrato que todas respetan y clasifica el catálogo completo, distinguiendo lo que ya está implementado de lo que está diseñado y pendiente.

Nombres generados por Django¶

Las restricciones se declaran con %(class)s, que Django expande al nombre de la clase del modelo en minúsculas y sin separadores, no al nombre de la tabla.

Columnas generadas¶

PostgreSQL 18 admite las dos formas y el modelo usa cada una donde corresponde.

En ambos casos la expresión debe ser inmutable y solo puede referirse a columnas de la propia fila, nunca a otra columna generada. Una derivación que necesite datos de otra tabla no es columna generada: es una columna normal que escribe el trigger de inserción y protege un trigger de solo lectura. Lo mismo aplica cuando la expresión, aunque solo lea la propia fila, no es inmutable en el sentido que PostgreSQL exige: to_char sobre un timestamptz depende del TimeZone de la sesión y PostgreSQL la clasifica STABLE, no IMMUTABLE, así que semana_iso de campana tampoco es columna generada, sino una columna normal que deriva trg_campana_semana_iso. Ver columnas generadas.

Auditoría por tabla¶

La tabla de eventos del tercer régimen es append-only, replica las columnas de la tabla rastreada y agrega el instante del evento, su etiqueta y el contexto de la petición en jsonb. Va indexada por el identificador de la fila original, por el instante y por el actor extraído del contexto.