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 elserver_defaultde 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 eljtide 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_defaultcambia en el esquema, una base ya migrada conserva el default viejo hasta que se recrea el esquema o se corre unALTER TABLE ... ALTER COLUMN id SET DEFAULT uuidv7().
Reglas no negociables¶
- PK = UUID v7 en toda tabla (la única excepción de tipo sigue siendo
mae_empresas→ BIGINT identity, ADR 0011). - En la base:
uuidv7(), nuncagen_random_uuid(). - En Python:
uuid.uuid7(), nuncauuid.uuid4(). - 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
ALTERde 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.