此模块中定义的类创建数据库约束。它们被添加到模型中 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'
,分别替换为具体模型的小写app标签和类名。例如 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
¶所有约束的基类。子类必须实现 constraint_sql()
, create_sql()
, remove_sql()
和 validate()
方法:研究方法。
自 5.0 版本弃用: 不建议使用对传递位置参数的支持。
所有约束都有以下共同参数:
name
¶约束的名称。必须始终为约束指定唯一的名称。
violation_error_code
¶出现以下情况时使用的错误代码 ValidationError
是在过程中引发的 model validation 。默认为 None
。
violation_error_message
¶在以下情况下使用的错误消息 ValidationError
是在过程中引发的 model validation 。默认为 "Constraint “%(name)s” is violated."
。
validate()
¶验证在上定义的约束 model
,是受到尊重的 instance
。这将在数据库上执行查询,以确保遵守约束。如果 exclude
列表来验证约束,则忽略该约束。
提高一名 ValidationError
如果违反了约束。
此方法必须由子类实现。
CheckConstraint
¶在数据库中创建检查约束。
check
¶A Q
对象或布尔值 Expression
指定希望约束强制执行的检查。
例如, CheckConstraint(check=Q(age__gte=18), name='age_gte_18')
确保年龄字段不低于18岁。
甲骨文
Oracle上具有可为空的字段的检查必须包括允许 NULL
值的顺序 validate()
与检查约束验证的行为相同。例如,如果 age
是一个可以为空的字段::
CheckConstraint(check=Q(age__gte=18) | Q(age__isnull=True), name="age_gte_18")
UniqueConstraint
¶在数据库中创建唯一约束。
expressions
¶位置论元 *expressions
允许在表达式和数据库函数上创建函数唯一约束。
例如::
UniqueConstraint(Lower("name").desc(), "category", name="unique_lower_name_category")
属性的小写值创建唯一约束。 name
字段按降序排列,而 category
字段以默认升序排列。
函数唯一约束具有与相同的数据库限制 Index.expressions
。
fields
¶指定要强制约束的唯一列集的字段名称列表。
例如, UniqueConstraint(fields=['room', 'date'], name='unique_booking')
确保每个房间每个日期只能预订一次。
condition
¶A Q
对象,指定要强制约束的条件。
例如::
UniqueConstraint(fields=["user"], condition=Q(status="DRAFT"), name="unique_draft_user")
确保每个用户只有一个草稿。
这些条件的数据库限制与 Index.condition
.
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
¶要作为非键列包含在覆盖唯一索引中的字段名称的列表或元组。这允许仅索引扫描用于只选择包含字段的查询 (include
)并且只按唯一字段筛选 (fields
)
例如::
UniqueConstraint(name="unique_booking", fields=["room", "date"], include=["full_name"])
将允许筛选 room
和 date
,同时选择 full_name
,而只从索引获取数据。
include
仅在PostgreSQL上支持。
非键列的数据库限制与 Index.include
.
opclasses
¶的名称 PostgreSQL operator classes 用于此唯一索引。如果需要自定义运算符类,则必须为索引中的每个字段提供一个。
例如::
UniqueConstraint(
name="unique_username", fields=["username"], opclasses=["varchar_pattern_ops"]
)
在上创建唯一索引 username
使用 varchar_pattern_ops
.
opclasses
除了postgresql之外的数据库都被忽略。
nulls_distinct
¶行是否包含 NULL
唯一约束所涵盖的值应该被认为是彼此不同的。缺省值为 None
它使用的数据库缺省值是 True
在大多数后端上。
例如::
UniqueConstraint(name="ordering", fields=["ordering"], nulls_distinct=False)
创建唯一约束,该约束仅允许一行存储 NULL
中的值 ordering
纵队。
nulls_distinct
对于除PostgreSQL 15+以外的数据库被忽略。
violation_error_code
¶出现以下情况时使用的错误代码 ValidationError
是在过程中引发的 model validation 。默认为 None
。
此代码为 not used 为 UniqueConstraint
S与 fields
如果没有一个 condition
。是这样的 UniqueConstraint
S的错误代码与使用 Field.unique
或在 Meta.unique_together
。
violation_error_message
¶在以下情况下使用的错误消息 ValidationError
是在过程中引发的 model validation 。默认为 BaseConstraint.violation_error_message
。
这条消息是 not used 为 UniqueConstraint
S与 fields
如果没有一个 condition
。是这样的 UniqueConstraint
S显示的消息与使用 Field.unique
或在 Meta.unique_together
。
12月 18, 2023