Constraints reference

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 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(). s 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.

class CheckConstraint(**, check, name*)

Creates a check constraint in the database.

CheckConstraint.``check

A 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.

Changed in Django 3.1:

Support for boolean was added.

name

CheckConstraint.``name

The name of the constraint. You must always specify a unique name for the constraint.

UniqueConstraint

Creates a unique constraint in the database.

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

The name of the constraint. You must always specify a unique name for the constraint.

UniqueConstraint.``condition

A object that specifies the condition you want the constraint to enforce.

For example:

ensures that each user only has one draft.

These conditions have the same database restrictions as Index.condition.

deferrable

UniqueConstraint.``deferrable

New in Django 3.1.

Set this parameter to create a deferrable unique constraint. Accepted values are Deferrable.DEFERRED or Deferrable.IMMEDIATE. For example:

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.

Deferrable unique constraints are ignored on MySQL, MariaDB, and SQLite as neither supports them.

Warning

Deferred unique constraints may lead to a performance penalty.

UniqueConstraint.``include

New in Django Development version.

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 (fields).

For example:

will allow filtering on room and date, also selecting full_name, while fetching data only from the index.

include is supported only on PostgreSQL.

Non-key columns have the same database restrictions as .

opclasses

UniqueConstraint.``opclasses

New in Django Development version.

The names of the to use for this unique index. If you require a custom operator class, you must provide one for each field in the index.

For example:

creates a unique index on username using varchar_pattern_ops.