UUIDv7 en Python, PostgreSQL y Django

Introducción

Python 3.14 y PostgreSQL 18, ambos lanzados de forma estable en los últimos meses del 2025, introdujeron soporte nativo para UUIDv7, que proporciona ordenación por tiempo y una mejor localidad de índices (index locality).

En este artículo te guío con un ejemplo práctico que muestra cómo funciona UUIDv7 en PostgreSQL usando el ORM de Django y solo migraciones. No se necesita SQL manual y cada paso muestra código real y el resultado de las migraciones.

Este artículo asume que tienes PostgreSQL 18 disponible, ya que versiones anteriores no proporcionan funciones para generar UUIDv7 o extraer sus marcas de tiempo.

¿Qué es un UUID?

Un UUID es un identificador de 128 bits que busca ser único globalmente sin necesidad de coordinación. Funciona bien en sistemas distribuidos, por ejemplo, microservicios, porque elimina la necesidad de un generador de secuencias centralizado. Esto hace que los UUIDs sean ideales para muchas arquitecturas modernas.

UUIDv4 vs UUIDv7

La versión más común es UUIDv4, que es completamente aleatoria. UUIDv7 mejora esto al añadir un prefijo de marca de tiempo que hace que los identificadores se ordenen por fecha de creación. Esto reduce la fragmentación de los índices y hace las inserciones más eficientes.

UUIDv4

• Completamente aleatorio.
• Muy buena unicidad.
• Alta fragmentación de índices en tablas grandes.
• Las inserciones se convierten en escrituras aleatorias.

UUIDv7

• Basado en marca de tiempo y ordenado por tiempo.
• Menor fragmentación de índices y escrituras más predecibles.
• La hora de creación puede extraerse directamente.
• Adecuado como clave principal en entornos con muchas escrituras.

¿Por qué importa el orden?

UUIDv7 codifica una marca de tiempo en sus bits más significativos, lo que significa que los nuevos identificadores siguen un orden cronológico natural. Esto reduce la fragmentación de índices y evita los patrones de escritura aleatoria típicos de UUIDv4.

Como las inserciones se ubican en regiones predecibles del índice en lugar de ubicaciones dispersas, el rendimiento de escritura mejora significativamente en tablas grandes y sistemas con mucho tráfico.

¿Cómo usarlo en Django?

Este post asume que ya tienes creado y listo un proyecto de Django con las configuraciones mínimas para que se ejecute al menos en un entorno de pruebas local. Es obligatorio que uses Postgres >= 18.

Para comenzar, instala psycopg:

pip install psycopg[binary]

Configura el soporte para postgres en la sección DATABASES en el archivo settings.py de tu proyecto en django:

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "HOST": "DATABASE_HOST",
        "NAME": "DATABASE_NAME",
        "PASSWORD": "DATABASE_PASSWORD",
        "PORT": "DATABASE_PORT",
        "USER": "DATABASE_USER",
    }
}

Creamos un helper:

from django.db import models

class UUIDv7(models.Func):
    function = "uuidv7"
    output_field = models.UUIDField()

Este helper:

1. Usa la función uuidv7 de PostgreSQL: En lugar de generar el UUID en Python, delega la tarea a la base de datos. Por supuesto que puedes generar uuid7 en python, de hecho es algo soportado de forma nativa desde Python 3.14, pero como siempre digo, si está soportada, traslada a la base de datos la mayor parte del trabajo.
2. Generación automática: Cuando insertes un nuevo registro sin especificar un UUID, PostgreSQL ejecutará uuidv7() y creará el identificador por ti.
3. Mejor consistencia: Garantiza que los UUIDs se generen con el reloj de la base de datos, evitando problemas de sincronización entre servidores de aplicaciones.

Ahora ya podrás incluir esta función en cualquier modelo y hacer que su llave primaria sea un uuid7:

class Item(models.Model):
    id = models.UUIDField(
        db_default=UUIDv7(), primary_key=True
    )