Constraints reference¶
The classes defined in this module create database constraints. They are added
in the model Meta.constraints
option.
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 as models.<Foo>Constraint.
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
(including name) each time. To work around name collisions, part of the
name may contain '%(app_label)s' and '%(class)s', which are
replaced, respectively, by the lowercased app label and class name of the
concrete model. For example CheckConstraint(check=Q(age__gte=18),
name='%(app_label)s_%(class)s_is_adult').
Validation of Constraints
In general constraints are not checked during full_clean(), and do
not raise ValidationErrors. Rather you’ll get a database integrity
error on save(). UniqueConstraints without a
condition (i.e. non-partial unique constraints)
are different in this regard, in that they leverage the existing
validate_unique() logic, and thus enable two-stage validation. In
addition to IntegrityError on save(), ValidationError is also
raised during model validation when the UniqueConstraint is violated.
CheckConstraint¶
-
class
CheckConstraint(*, check, name)¶ Creates a check constraint in the database.
check¶
-
CheckConstraint.check¶
A Q object or boolean Expression that
specifies the check you want the constraint to enforce.
For example, CheckConstraint(check=Q(age__gte=18), name='age_gte_18')
ensures the age field is never less than 18.
Support for boolean Expression was added.
UniqueConstraint¶
-
class
UniqueConstraint(*, fields, name, condition=None, deferrable=None)¶ Creates a unique constraint in the database.
fields¶
-
UniqueConstraint.fields¶
A list of field names that specifies the unique set of columns you want the constraint to enforce.
For example, UniqueConstraint(fields=['room', 'date'],
name='unique_booking') ensures each room can only be booked once for each
date.
name¶
-
UniqueConstraint.name¶
The name of the constraint. You must always specify a unique name for the constraint.
Interpolation of '%(app_label)s' and '%(class)s' was added.
condition¶
-
UniqueConstraint.condition¶
A Q object that specifies the condition you want the constraint to
enforce.
For example:
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
Index.condition.
deferrable¶
-
UniqueConstraint.deferrable¶
Set this parameter to create a deferrable unique constraint. Accepted values
are Deferrable.DEFERRED or 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.
Warning
Deferred unique constraints may lead to a performance penalty.
