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

Классы, определенные в этом модуле, создают ограничения базы данных. Они добавляются в опцию модели 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(check=Q(age__gte=18), name='%(app_label)s_%(class)s_is_adult').

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

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

Проверка ограничений с помощью JSONField

Ограничения, содержащие JSONField, могут не вызывать ошибок валидации, поскольку преобразования ключей, индексов и путей имеют много специфических для базы данных оговорок. Это may be fully supported later.

Вы всегда должны проверять, что в журнале django.db.models нет сообщений типа «Got a database error calling check() on … « для подтверждения правильности проверки.

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

New in Django 5.0.
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(*, check, name, violation_error_code=None, violation_error_message=None)[исходный код]

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

check

CheckConstraint.check

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

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

Oracle

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

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

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, при этом получая данные только из индекса.

include поддерживается только в 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

New in Django 5.0.
UniqueConstraint.nulls_distinct

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

Например:

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

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

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

violation_error_code

New in Django 5.0.
UniqueConstraint.violation_error_code

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

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

violation_error_message

UniqueConstraint.violation_error_message

Сообщение об ошибке, используемое, когда ValidationError возникает во время model validation. По умолчанию используется BaseConstraint.violation_error_message.

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

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