Saltar a contenido

0019. UUID v7: identificadores ordenables por tiempo

Estado: Aceptado Fecha: 2026-10-01 Autor: Duval Alcivar

Contexto

El ADR 0011 fija cuándo usar UUID y cuándo BIGINT, pero no la versión del UUID. Hasta ahora los identificadores se generaban con gen_random_uuid(), que produce UUID v4: un valor totalmente aleatorio. Un v4 no guarda ningún orden: dos id consecutivos no dicen nada sobre cuál se creó antes, y las inserciones nuevas caen en cualquier punto del índice de la PK.

En tablas grandes (entidades de negocio, transaccionales) eso se paga: fragmentación del índice, escrituras más lentas y consultas por rango de creación que no existen.

Decisión

Todos los UUID del ecosistema son v7. Un UUID v7 lleva un timestamp en los primeros bits y el resto aleatorio: dos id se ordenan por su momento de creación y la clave nueva se mantiene "al final" del índice.

  • En la base de datos: uuidv7(), que es nativo de PostgreSQL 18. Se usa en el server_default de las PK.
  • En código Python: uuid.uuid7(), que es nativo de Python 3.14; lo usan los identificadores generados fuera de la base (por ejemplo el jti de los tokens).

Este ADR no cambia el ADR 0011: sigue valiendo la regla UUID vs BIGINT. Solo fija la versión: donde el 0011 dice UUID, ahora es UUID v7.

El aislamiento por empresa (RLS) sigue en el ADR 0012.

Por qué v7 y no v4

Criterio UUID v4 (antes) UUID v7 (ahora)
Orden Ninguno (aleatorio) Ordena por tiempo de creación
Índice de la PK Inserta al azar → fragmenta Inserta "al final" → fragmenta menos
Antigüedad No se puede inferir Se infiere del propio id
Rango por creación No disponible ORDER BY id ≈ orden de creación

Versiones que exige

Componente Versión Por qué
PostgreSQL 18+ uuidv7() es nativo; en versiones previas hace falta una función/extensión propia
Python 3.14+ uuid.uuid7() es nativo; en 3.12/3.13 no existe

Transición: lo viejo y lo nuevo

  • Lo viejo: las filas existentes con id v4 siguen siendo válidas; un UUID es un UUID. No hay que convertirlas.
  • Lo nuevo: toda fila que se inserte a partir de ahora en una base recreada/actualizada nace v7.
  • Base existente: como el server_default cambia en el esquema, una base ya migrada conserva el default viejo hasta que se recrea el esquema o se corre un ALTER TABLE ... ALTER COLUMN id SET DEFAULT uuidv7().

Reglas no negociables

  1. PK = UUID v7 en toda tabla (la única excepción de tipo sigue siendo mae_empresas → BIGINT identity, ADR 0011).
  2. En la base: uuidv7(), nunca gen_random_uuid().
  3. En Python: uuid.uuid7(), nunca uuid.uuid4().
  4. PostgreSQL 18+ y Python 3.14+ son requisitos del stack.

Consecuencias

  • El stack mínimo sube a PostgreSQL 18 y Python 3.14.
  • Las bases existentes necesitan recrearse (o un ALTER de los defaults) para que las filas nuevas salgan v7.
  • El ADR 0011 (UUID vs BIGINT) sigue vigente; la referencia de "cómo se genera el UUID" pasa a ser este ADR.