约束参考

此模块中定义的类创建数据库约束。它们被添加到模型 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')。

约束验证

约束在 模型验证期间检查。

使用 JSONField 验证约束

包含 JSONField 的约束可能不会引发验证错误，因为键、索引和路径转换具有许多特定于数据库的注意事项。此 稍后可能会得到完全支持。

您应该始终检查 django.db.models 记录器中是否存在日志消息，例如 “在调用 ... 上的 check() 时收到数据库错误”，以确认其已正确验证。

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

Django 5.0 中的新增功能。
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)

验证在 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') 确保 age 字段永远不小于 18。

表达式顺序

Q 参数顺序不一定保留，但 Q 表达式本身的顺序会保留。对于出于性能原因保留检查约束表达式顺序的数据库，这可能很重要。例如，如果顺序很重要，请使用以下格式

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

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 不支持可延迟的唯一约束，因此会忽略它们。

警告

可延迟的唯一约束可能会导致 性能下降。

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"]
)

使用 varchar_pattern_ops 在 username 上创建唯一索引。

除了 PostgreSQL 之外的数据库将忽略 opclasses。

nulls_distinct

Django 5.0 中的新增功能。
UniqueConstraint.nulls_distinct

是否应将包含唯一约束所涵盖的 NULL 值的行视为彼此不同。默认值为 None，它使用数据库默认值，该默认值在大多数后端上为 True。

例如

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

创建一个唯一约束，该约束仅允许一行在 ordering 列中存储 NULL 值。

除了 PostgreSQL 15+ 之外的数据库将忽略具有 nulls_distinct 的唯一约束。

violation_error_code

Django 5.0 中的新增功能。
UniqueConstraint.violation_error_code

在 模型验证期间引发 ValidationError 时使用的错误代码。默认为 None。

此代码不适用于具有 UniqueConstraint 和 fields 且没有 condition 的 UniqueConstraint。此类 UniqueConstraint 具有与使用 Field.unique 或在 Meta.unique_together 中定义的约束相同的错误代码。

violation_error_message

UniqueConstraint.violation_error_message

在 模型验证 期间引发 ValidationError 时使用的错误消息。默认为 BaseConstraint.violation_error_message。

此消息不用于带有 UniqueConstraint 和没有 fields 以及 condition 的 UniqueConstraint。此类 UniqueConstraint 显示与使用 Field.unique 或在 Meta.unique_together 中定义的约束相同的消息。

模型索引参考
模型 _meta API
返回顶部