Справочник ограничений

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

BaseConstraint

class BaseConstraint(*name, violation_error_code=None, violation_error_message=None) [source]

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

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

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

name

BaseConstraint.name

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

violation_error_code

BaseConstraint.violation_error_code

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

violation_error_message

BaseConstraint.violation_error_message

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

validate()

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

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

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

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

CheckConstraint

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

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

condition

CheckConstraint.condition

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

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

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

CheckConstraint(condition=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) [source]

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

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,
)

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

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

Например:

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 во время валидации модели. По умолчанию None.

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

violation_error_message

UniqueConstraint.violation_error_message

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

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