Ссылка на ограничения

Классы, определенные в этом модуле, создают ограничения базы данных. Они добавляются в опцию модели Meta.constraints.

Обращение к встроенным ограничениям

Ограничения определены в django.db.models.constraints, но для удобства они импортированы в django.db.models. Стандартным соглашением является использование from django.db import models и обращение к ограничениям как models.<Foo>Constraint.

Ограничения в абстрактных базовых классах

Вы всегда должны указывать уникальное имя для ограничения. Таким образом, вы обычно не можете указать ограничение для абстрактного базового класса, поскольку параметр Meta.constraints наследуется подклассами с точно такими же значениями атрибутов (включая name) каждый раз. Чтобы избежать коллизий в именах, часть имени может содержать '%(app_label)s' и '%(class)s', которые заменяются, соответственно, строчной меткой приложения и именем класса конкретной модели. Например, CheckConstraint(condition=Q(age__gte=18), name='%(app_label)s_%(class)s_is_adult').

Валидация ограничений

Ограничения проверяются во время model validation.

BaseConstraint

class BaseConstraint(*name, violation_error_code=None, violation_error_message=None)

Базовый класс для всех ограничений. Подклассы должны реализовывать методы constraint_sql(), create_sql(), remove_sql() и validate().

Не рекомендуется, начиная с версии 5.0: Поддержка передачи позиционных аргументов устарела.

Все ограничения имеют следующие общие параметры:

name

BaseConstraint.name

Имя ограничения. Вы всегда должны указывать уникальное имя для ограничения.

violation_error_code

BaseConstraint.violation_error_code

Код ошибки, используемый при возникновении ValidationError во время выполнения model validation. По умолчанию равен None.

violation_error_message

BaseConstraint.violation_error_message

Сообщение об ошибке, используемое, когда ValidationError возникает во время model validation. По умолчанию используется "Constraint “%(name)s” is violated.".

validate()

BaseConstraint.validate(model, instance, exclude=None, using=DEFAULT_DB_ALIAS)

Проверяет, что ограничение, определенное на model, соблюдается на instance. Выполняется запрос к базе данных, чтобы убедиться, что ограничение соблюдается. Если поля в списке exclude необходимы для проверки ограничения, ограничение игнорируется.

Вызвать ошибку ValidationError, если ограничение нарушено.

Этот метод должен быть реализован подклассом.

CheckConstraint

class CheckConstraint(*, condition, name, violation_error_code=None, violation_error_message=None)

Создает контрольное ограничение в базе данных.

condition

CheckConstraint.condition

Объект Q или логическое значение Expression, указывающее условную проверку, которую вы хотите применить к ограничению.

Например, CheckConstraint(condition=Q(age__gte=18), name='age_gte_18') гарантирует, что поле «Возраст» никогда не будет меньше 18.

Порядок выражений

порядок аргументов Q не обязательно сохраняется, однако порядок самих выражений Q сохраняется. Это может быть важно для баз данных, которые сохраняют порядок выражений с ограничением проверки по соображениям производительности. Например, если порядок имеет значение, используйте следующий формат:

CheckConstraint(
    condition=Q(age__gte=18) & Q(expensive_check=condition),
    name="age_gte_18_and_others",
)

Оракул < 23с

Проверки с полями, имеющими значение null, в Oracle < 23c должны включать условие, допускающее значения NULL, чтобы validate() вел себя так же, как проверка ограничений проверки. Например, если age является полем с возможностью обнуления:

CheckConstraint(condition=Q(age__gte=18) | Q(age__isnull=True), name="age_gte_18")

Не рекомендуется, начиная с версии 5.1: Атрибут check устарел в пользу condition.

UniqueConstraint

class UniqueConstraint(*expressions, fields=(), name=None, condition=None, deferrable=None, include=None, opclasses=(), nulls_distinct=None, violation_error_code=None, violation_error_message=None)

Создает уникальное ограничение в базе данных.

expressions

UniqueConstraint.expressions

Позиционный аргумент *expressions позволяет создавать функциональные уникальные ограничения на выражения и функции базы данных.

Например:

UniqueConstraint(Lower("name").desc(), "category", name="unique_lower_name_category")

создает уникальное ограничение на строчные значения поля name в порядке убывания и поля category в порядке возрастания по умолчанию.

Функциональные уникальные ограничения имеют те же ограничения базы данных, что и Index.expressions.

fields

UniqueConstraint.fields

Список имен полей, определяющий уникальный набор столбцов, на которые необходимо наложить ограничение.

Например, UniqueConstraint(fields=['room', 'date'], name='unique_booking') гарантирует, что каждый номер может быть забронирован только один раз на каждую дату.

condition

UniqueConstraint.condition

Объект Q, который определяет условие, которое вы хотите, чтобы ограничение выполнялось.

Например:

UniqueConstraint(fields=["user"], condition=Q(status="DRAFT"), name="unique_draft_user")

гарантирует, что у каждого пользователя будет только один черновик.

Эти условия имеют те же ограничения базы данных, что и Index.condition.

deferrable

UniqueConstraint.deferrable

Установите этот параметр для создания откладываемого уникального ограничения. Принимаются значения Deferrable.DEFERRED или Deferrable.IMMEDIATE. Например:

from django.db.models import Deferrable, UniqueConstraint

UniqueConstraint(
    name="unique_order",
    fields=["order"],
    deferrable=Deferrable.DEFERRED,
)

По умолчанию ограничения не откладываются. Отложенное ограничение не будет выполняться до конца транзакции. Немедленное ограничение будет выполняться сразу после каждой команды.

MySQL, MariaDB и SQLite.

Отсроченные уникальные ограничения игнорируются в MySQL, MariaDB и SQLite, поскольку они их не поддерживают.

Предупреждение

Отложенные уникальные ограничения могут привести к ошибке performance penalty.

include

UniqueConstraint.include

Список или кортеж имен полей, которые должны быть включены в охватывающий уникальный индекс в качестве неключевых столбцов. Это позволяет использовать сканирование только по индексу для запросов, которые выбирают только включенные поля (include) и фильтруют только по уникальным полям (fields).

Например:

UniqueConstraint(name="unique_booking", fields=["room", "date"], include=["full_name"])

позволит фильтровать по room и date, также выбирая full_name, при этом получая данные только из индекса.

Уникальные ограничения с неключевыми столбцами игнорируются для баз данных, отличных от PostgreSQL.

Столбцы без ключей имеют те же ограничения базы данных, что и Index.include.

opclasses

UniqueConstraint.opclasses

Имена операторов PostgreSQL operator classes для использования для этого уникального индекса. Если вам требуется пользовательский класс оператора, вы должны предоставить его для каждого поля в индексе.

Например:

UniqueConstraint(
    name="unique_username", fields=["username"], opclasses=["varchar_pattern_ops"]
)

создает уникальный индекс на username, используя varchar_pattern_ops.

opclasses игнорируются для всех баз данных, кроме PostgreSQL.

nulls_distinct

UniqueConstraint.nulls_distinct

Следует ли считать строки, содержащие значения NULL, на которые распространяется ограничение уникальности, отличными друг от друга. Значение по умолчанию None, которое использует значение по умолчанию базы данных, которое в большинстве бэкендов равно True.

Например:

UniqueConstraint(name="ordering", fields=["ordering"], nulls_distinct=False)

создает уникальное ограничение, которое позволяет только одной строке хранить значение NULL в столбце ordering.

Уникальные ограничения с nulls_distinct игнорируются для баз данных, отличных от PostgreSQL 15+.

violation_error_code

UniqueConstraint.violation_error_code

Код ошибки, используемый при возникновении ValidationError во время model validation.

По умолчанию используется значение BaseConstraint.violation_error_code, если задано значение UniqueConstraint.condition или UniqueConstraint.fields не задано.

Если UniqueConstraint.fields задано без UniqueConstraint.condition, по умолчанию используется код ошибки Meta.unique_together при наличии нескольких полей и код ошибки Field.unique при наличии одного поля.

Changed in Django 5.2:

В более старых версиях предоставленный UniqueConstraint.violation_error_code не использовался, когда UniqueConstraint.fields был установлен без UniqueConstraint.condition.

violation_error_message

UniqueConstraint.violation_error_message

Сообщение об ошибке, используемое при появлении ValidationError во время model validation.

По умолчанию используется значение BaseConstraint.violation_error_message, если задано значение UniqueConstraint.condition или UniqueConstraint.fields не задано.

Если UniqueConstraint.fields задано без UniqueConstraint.condition, по умолчанию выводится сообщение об ошибке Meta.unique_together при наличии нескольких полей и сообщение об ошибке Field.unique при наличии одного поля.

Changed in Django 5.2:

В более старых версиях предоставленный UniqueConstraint.violation_error_message не использовался, когда UniqueConstraint.fields был установлен без UniqueConstraint.condition.

Справочник по индексам модели
API _meta модели
Вернуться на верх