The classes defined in this module create database constraints. They are added
in the model
Referencing built-in constraints
Constraints are defined in
django.db.models.constraints, but for
convenience they’re imported into
django.db.models. The standard
convention is to use
from django.db import models and refer to the
Constraints in abstract base classes
You must always specify a unique name for the constraint. As such, you
cannot normally specify a constraint on an abstract base class, since the
Meta.constraints option is
inherited by subclasses, with exactly the same values for the attributes
name) each time. To work around name collisions, part of the
name may contain
'%(class)s', which are
replaced, respectively, by the lowercased app label and class name of the
concrete model. For example
Validation of Constraints
Constraints are checked during the model validation.
Validation of Constraints with
You should always check that there are no log messages, in the
django.db.models logger, like “Got a database error calling check() on
…” to confirm it’s validated properly.
In older versions, constraints were not checked during model validation.
Base class for all constraints. Subclasses must implement
All constraints have the following parameters in common:
The name of the constraint. You must always specify a unique name for the constraint.
The error message used when
ValidationError is raised during
model validation. Defaults to
"Constraint “%(name)s” is violated.".
validate(model, instance, exclude=None, using=DEFAULT_DB_ALIAS)¶
Validates that the constraint, defined on
model, is respected on the
instance. This will do a query on the database to ensure that the
constraint is respected. If fields in the
exclude list are needed to
validate the constraint, the constraint is ignored.
ValidationError if the constraint is violated.
This method must be implemented by a subclass.
CheckConstraint(*, check, name, violation_error_message=None)¶
Creates a check constraint in the database.
ensures the age field is never less than 18.
Checks with nullable fields on Oracle must include a condition allowing for
NULL values in order for
to behave the same as check constraints validation. For example, if
is a nullable field:
CheckConstraint(check=Q(age__gte=18) | Q(age__isnull=True), name="age_gte_18")
violation_error_message argument was added.
UniqueConstraint(*expressions, fields=(), name=None, condition=None, deferrable=None, include=None, opclasses=(), violation_error_message=None)¶
Creates a unique constraint in the database.
*expressions allows creating functional unique
constraints on expressions and database functions.
UniqueConstraint(Lower("name").desc(), "category", name="unique_lower_name_category")
creates a unique constraint on the lowercased value of the
name field in
descending order and the
category field in the default ascending order.
Functional unique constraints have the same database restrictions as
A list of field names that specifies the unique set of columns you want the constraint to enforce.
name='unique_booking') ensures each room can only be booked once for each
Q object that specifies the condition you want the constraint to
UniqueConstraint(fields=["user"], condition=Q(status="DRAFT"), name="unique_draft_user")
ensures that each user only has one draft.
These conditions have the same database restrictions as
Set this parameter to create a deferrable unique constraint. Accepted values
Deferrable.IMMEDIATE. For example:
from django.db.models import Deferrable, UniqueConstraint UniqueConstraint( name="unique_order", fields=["order"], deferrable=Deferrable.DEFERRED, )
By default constraints are not deferred. A deferred constraint will not be enforced until the end of the transaction. An immediate constraint will be enforced immediately after every command.
MySQL, MariaDB, and SQLite.
Deferrable unique constraints are ignored on MySQL, MariaDB, and SQLite as neither supports them.
Deferred unique constraints may lead to a performance penalty.
A list or tuple of the names of the fields to be included in the covering
unique index as non-key columns. This allows index-only scans to be used for
queries that select only included fields (
and filter only by unique fields (
UniqueConstraint(name="unique_booking", fields=["room", "date"], include=["full_name"])
will allow filtering on
date, also selecting
while fetching data only from the index.
include is supported only on PostgreSQL.
Non-key columns have the same database restrictions as
The names of the PostgreSQL operator classes to use for this unique index. If you require a custom operator class, you must provide one for each field in the index.
UniqueConstraint( name="unique_username", fields=["username"], opclasses=["varchar_pattern_ops"] )
creates a unique index on
opclasses are ignored for databases besides PostgreSQL.