Las clases definidas en este módulo crean restricciones del servidor de bases de datos. Se agregan en la opción Meta.constraints del modelo.
Referenciando restricciones integradas
Las restricciones se definen en django.db.models.constraints, pero por conveniencia están importadas en django.db.models. La convención estándar es utilizar from django.db import models y referirse a las restricciones como models.<Foo>Constraint.
Restricciones en clases base abstractas
Debes especificar siempre un nombre único para la restricción. Como tal, no puedes normalmente especificar una restricción en una clase base abstracta, ya que la opción Meta.constraints se hereda por las subclases, con exactamente los mismos valores para los atributos (incluido name) cada vez. Para evitar colisiones de nombres, parte del nombre puede contener '%(app_label)s' y '%(class)s', que se reemplazan, respectivamente, por el etiqueta de aplicación en minúsculas y el nombre de la clase del modelo concreto. Por ejemplo:
CheckConstraint(condition=Q(age__gte=18), name="%(app_label)s_%(class)s_is_adult")
Validación de restricciones
Los textos traducidos son:
Clase base para todas las restricciones. Las subclases deben implementar los métodos constraint_sql(), create_sql(), remove_sql() y validate().
Obsoleto desde la versión 5.0: Se ha deprecado el soporte para pasar argumentos posicionales.
Todas las restricciones tienen los siguientes parámetros en común:
nombre¶El nombre de la restricción. Debes especificar siempre un nombre único para la restricción.
código_de_error_violación¶El código de error utilizado cuando se levanta ValidationError durante la validación del modelo. Por defecto, es None.
mensaje_de_error_violación¶El mensaje de error utilizado cuando se levanta una ValidationError durante la validación del modelo. Por defecto es "La restricción “%(name)s” está violada.".
Verifica que la restricción, definida en model, se respeta en el instance. Esto hará una consulta en la base de datos para asegurarse de que la restricción se respeta. Si los campos en la lista exclude son necesarios para validar la restricción, la restricción es ignorada.
Levanta una ValidationError si la restricción está violada.
Este método debe ser implementado por una subclase.
CheckConstraint¶Crea una restricción de verificación en la base de datos.
condición¶Un objeto Q o una expresión booleana Expression que especifica la comprobación condicional que deseas que la restricción imponga.
Por ejemplo:
CheckConstraint(condition=Q(age__gte=18), name="age_gte_18")
asegura que el campo edad nunca sea menor a 18.
Orden de las expresiones
El orden del argumento Q no se preserva necesariamente, sin embargo, el orden de las expresiones Q en sí mismas se preservan. Esto puede ser importante para bases de datos que preserven el orden de las expresiones de la restricción de verificación por razones de rendimiento. Por ejemplo, utiliza el siguiente formato si importa el orden:
CheckConstraint(
condition=Q(age__gte=18) & Q(expensive_check=condition),
name="age_gte_18_and_others",
)
Oracle < 23c
Las comprobaciones con campos nulos en Oracle < 23c deben incluir una condición que permita valores NULL para que validate() se comporte de la misma manera que la validación de las restricciones de verificación. Por ejemplo, si el campo age es un campo nulo:
CheckConstraint(condition=Q(age__gte=18) | Q(age__isnull=True), name="age_gte_18")
Obsoleto desde la versión 5.1: La propiedad check está desaconsejada en favor de ``condition””.
UniqueConstraint¶Crea una restricción única en la base de datos.
expressiones¶El argumento posicional *expressions permite crear restricciones únicas funcionales sobre expresiones y funciones de la base de datos.
Por ejemplo:
UniqueConstraint(Lower("name").desc(), "category", name="unique_lower_name_category")
crea una restricción única sobre el valor lowercased del campo name en orden descendente y el campo category en el orden ascendente por defecto.
Las restricciones únicas funcionales tienen las mismas restricciones de la base de datos que Index.expressions.
fields¶Una lista de nombres de campos que especifica el conjunto único de columnas que deseas que la restricción aplique.
Por ejemplo:
UniqueConstraint(fields=["room", "date"], name="unique_booking")
asegura que cada habitación solo se puede reservar una vez para cada fecha.
condición¶Un objeto Q que especifica la condición que deseas que la restricción aplique.
Por ejemplo:
UniqueConstraint(fields=["user"], condition=Q(status="DRAFT"), name="unique_draft_user")
asegura que cada usuario solo tenga un borrador.
Estas condiciones tienen las mismas restricciones de la base de datos que Index.condition.
deferible¶Setea este parámetro para crear una restricción única diferible. Los valores aceptados son Deferrable.DEFERRED o Deferrable.IMMEDIATE. Por ejemplo:
from django.db.models import Deferrable, UniqueConstraint
UniqueConstraint(
name="unique_order",
fields=["order"],
deferrable=Deferrable.DEFERRED,
)
Por defecto, las restricciones no se retrasan. Una restricción diferida no se aplicará hasta el final de la transacción. Una restricción inmediata se aplicará inmediatamente después de cada comando.
MySQL, MariaDB y SQLite.
Las restricciones únicas diferibles se ignoran en MySQL, MariaDB y SQLite ya que no las soportan.
Advertencia
Las restricciones únicas diferidas pueden provocar una penalización de rendimiento <https://www.postgresql.org/docs/current/sql-createtable.html#id-1.9.3.85.9.4>_.
incluye¶Una lista o tupla con los nombres de los campos a incluir en el índice único cubriente como columnas no clave. Esto permite utilizar escaneos solo del índice para consultas que seleccionan solo los campos incluidos (include) y filtran solo por campos únicos (fields).
Por ejemplo:
UniqueConstraint(name="unique_booking", fields=["room", "date"], include=["full_name"])
Permitirá filtrar en room y date, también seleccionando full_name, mientras se obtiene la data sólo desde el índice.
Las restricciones únicas con columnas no clave se ignoran para bases de datos además de PostgreSQL.
Las columnas no clave tienen las mismas restricciones de base de datos que Index.include.
opclasses¶Los nombres de los clases de operadores de PostgreSQL a utilizar para este índice único. Si requieres una clase de operador personalizada, debes proporcionarla para cada campo en el índice.
Por ejemplo:
UniqueConstraint(
name="unique_username", fields=["username"], opclasses=["varchar_pattern_ops"]
)
crea un índice único sobre username utilizando varchar_pattern_ops.
Las opclasses se ignoran para bases de datos excepto PostgreSQL.
nulls_distinct¶Si las filas que contienen valores NULL cubiertos por la restricción única deben considerarse distintas entre sí. El valor predeterminado es None que utiliza el valor por defecto de la base de datos, que es True en la mayoría de los backends.
Por ejemplo:
UniqueConstraint(name="ordering", fields=["ordering"], nulls_distinct=False)
crea una restricción única que solo permite una fila almacenar un valor NULL en la columna ordering.
Las restricciones únicas con nulls_distinct se ignoran para bases de datos excepto PostgreSQL 15+.
código_de_error_violación¶El código de error utilizado cuando se levanta una ValidationError durante la validación del modelo.
Por defecto, utiliza el código de error de BaseConstraint.violation_error_code, cuando se establezca o no se establezca UniqueConstraint.condition o UniqueConstraint.fields.
Si se establece UniqueConstraint.fields sin una UniqueConstraint.condition, utiliza el código de error de Meta.unique_together cuando haya múltiples campos, y el código de error de Field.unique cuando haya un solo campo.
En versiones antiguas, el código de error proporcionado por UniqueConstraint.violation_error_code no se utilizaba cuando se establecía UniqueConstraint.fields sin una UniqueConstraint.condition.
mensaje_de_error_violación¶El error de mensaje utilizado cuando se levanta una ValidationError durante la validación del modelo.
Por defecto, utiliza el mensaje de error de violación de BaseConstraint.violation_error_message, cuando se establezca o no se establezca UniqueConstraint.fields.
Si se establece UniqueConstraint.fields sin una UniqueConstraint.condition, utiliza por defecto el mensaje de error de la Meta.unique_together cuando haya múltiples campos, y el mensaje de error de Field.unique cuando haya un solo campo.
En versiones anteriores, no se utilizaba el mensaje de error proporcionado por UniqueConstraint.violation_error_message cuando se establecía UniqueConstraint.fields sin una UniqueConstraint.condition.
may 31, 2026