Referens för begränsningar

Klasserna som definieras i den här modulen skapar databasbegränsningar. De läggs till i modellens Meta.constraints alternativ.

Hänvisning till inbyggda begränsningar

Begränsningar definieras i django.db.models.constraints, men för enkelhetens skull importeras de till django.db.models. Standardkonventionen är att använda from django.db import models och hänvisa till begränsningarna som models.<Foo>Constraint.

Begränsningar i abstrakta basklasser

Du måste alltid ange ett unikt namn för begränsningen. Som sådan kan du normalt inte ange en begränsning på en abstrakt basklass, eftersom alternativet Meta.constraints ärvs av underklasser, med exakt samma värden för attributen (inklusive name) varje gång. För att komma runt namnkollisioner kan en del av namnet innehålla '%(app_label)s' och '%(class)s', som ersätts av den gemena appetiketten respektive klassnamnet för den konkreta modellen. Till exempel: CheckConstraint(condition=Q(age__gte=18), name='%(app_label)s_%(class)s_is_adult').

Validering av begränsningar

Begränsningar kontrolleras under modellvalidering.

BaseConstraint

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

Basklass för alla begränsningar. Underklasser måste implementera metoderna constraint_sql(), create_sql(), remove_sql() och validate().

Ersatt sedan version 5.0: Stöd för att skicka positionella argument är borttaget.

Alla begränsningar har följande parametrar gemensamt:

namn

BaseConstraint.name

Namnet på begränsningen. Du måste alltid ange ett unikt namn för begränsningen.

Felkod för överträdelse

BaseConstraint.violation_error_code

Den felkod som används när ValidationError uppstår under modellvalidering. Standardvärdet är None.

avvikelse_felmeddelande

BaseConstraint.violation_error_message

Det felmeddelande som används när ValidationError uppstår under modellvalidering. Standard är "Begränsningen "%(name)s" har brutits.".

validera()`

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

Validerar att begränsningen, som definierats i model, respekteras i instance. Detta innebär att en databasfråga görs för att säkerställa att begränsningen respekteras. Om fält i listan exclude behövs för att validera begränsningen ignoreras begränsningen.

Ger upphov till ett ValidationError om begränsningen inte uppfylls.

Denna metod måste implementeras av en subklass.

CheckConstraint

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

Skapar en kontrollbegränsning i databasen.

villkor

CheckConstraint.condition

Ett Q-objekt eller boolean Expression som anger den villkorliga kontroll som du vill att begränsningen ska genomdriva.

Exempelvis säkerställer CheckConstraint(condition=Q(age__gte=18), name='age_gte_18') att åldersfältet aldrig är mindre än 18 år.

Uttrycksordning

ordningen på Q-argument bevaras inte nödvändigtvis, men ordningen på själva Q-uttrycken bevaras. Detta kan vara viktigt för databaser som av prestandaskäl bevarar ordningsföljden på uttryck för kontrollbegränsningar. Använd t.ex. följande format om ordningen är viktig:

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

Oracle < 23c

Kontroller med nollställbara fält på Oracle < 23c måste innehålla ett villkor som tillåter NULL-värden för att validate() ska fungera på samma sätt som validering av kontrollbegränsningar. Till exempel:, om age är ett nollställbart fält:

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

Ersatt sedan version 5.1: Attributet check är föråldrat till förmån för condition.

Unik begränsning

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]

Skapar en unik begränsning i databasen.

uttryck

UniqueConstraint.expressions

Det positionella argumentet *expressions gör det möjligt att skapa funktionella unika begränsningar för uttryck och databasfunktioner.

Till exempel:

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

skapar en unik begränsning på det gemena värdet i fältet name i fallande ordning och fältet category i stigande ordning som standard.

Funktionella unika begränsningar har samma databasrestriktioner som Index.expressions.

fält

UniqueConstraint.fields

En lista med fältnamn som anger den unika uppsättning kolumner som du vill att begränsningen ska genomdriva.

Exempelvis säkerställer UniqueConstraint(fields=['room', 'date'], name='unique_booking') att varje rum bara kan bokas en gång för varje datum.

villkor

UniqueConstraint.condition

Ett Q-objekt som anger det villkor du vill att begränsningen ska genomdriva.

Till exempel:

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

säkerställer att varje användare endast har ett utkast.

Dessa villkor har samma databasrestriktioner som Index.condition.

deferrable

UniqueConstraint.deferrable

Ange denna parameter för att skapa en uppskjutbar unik begränsning. Accepterade värden är Deferrable.DEFERRED eller Deferrable.IMMEDIATE. Till exempel:

from django.db.models import Deferrable, UniqueConstraint

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

Som standard är begränsningar inte uppskjutna. En uppskjuten begränsning kommer inte att verkställas förrän i slutet av transaktionen. En omedelbar begränsning kommer att verkställas omedelbart efter varje kommando.

MySQL, MariaDB och SQLite.

Deferrable unique constraints ignoreras i MySQL, MariaDB och SQLite eftersom de inte har stöd för dem.

Varning

Uppskjutna unika begränsningar kan leda till en ”prestandaförlust” <https://www.postgresql.org/docs/current/sql-createtable.html#id-1.9.3.85.9.4>`_.

inkludera

UniqueConstraint.include

En lista eller tupel med namnen på de fält som ska ingå i det täckande unika indexet som icke-nyckelkolumner. På så sätt kan skanningar med enbart index användas för frågor som endast väljer inkluderade fält (include) och endast filtrerar efter unika fält (fields).

Till exempel:

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

tillåter filtrering på rum och datum, även val av full_name, samtidigt som data endast hämtas från indexet.

Unika begränsningar med kolumner som inte är nycklar ignoreras för databaser förutom PostgreSQL.

Icke-nyckelkolumner har samma databasrestriktioner som Index.include.

opklasser

UniqueConstraint.opclasses

Namnen på PostgreSQL-operatörsklasserna som ska användas för detta unika index. Om du behöver en anpassad operatörsklass måste du tillhandahålla en för varje fält i indexet.

Till exempel:

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

skapar ett unikt index på username med hjälp av varchar_pattern_ops.

`` Opclasses`` ignoreras för databaser förutom PostgreSQL.

nulls_distinct

UniqueConstraint.nulls_distinct

Om rader som innehåller NULL-värden som omfattas av det unika villkoret ska anses vara skilda från varandra. Standardvärdet är None som använder databasens standardvärde som är True på de flesta backends.

Till exempel:

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

skapar en unik begränsning som endast tillåter en rad att lagra ett NULL-värde i kolumnen ordering.

Unika begränsningar med nulls_distinct ignoreras för databaser förutom PostgreSQL 15+.

Felkod för överträdelse

UniqueConstraint.violation_error_code

Den felkod som används när ett ValidationError uppstår under modellvalidering.

Standardvärdet är BaseConstraint.violation_error_code, när antingen UniqueConstraint.condition har angetts eller UniqueConstraint.fields inte har angetts.

Om UniqueConstraint.fields anges utan UniqueConstraint.condition, används som standard felkoden Meta.unique_together när det finns flera fält, och felkoden Field.unique när det finns ett enda fält.

Changed in Django 5.2:

I äldre versioner användes inte den medföljande UniqueConstraint.violation_error_code när UniqueConstraint.fields angavs utan UniqueConstraint.condition.

avvikelse_felmeddelande

UniqueConstraint.violation_error_message

Det felmeddelande som används när ett ValidationError uppstår under modellvalidering.

Standardvärdet är BaseConstraint.violation_error_message, när antingen UniqueConstraint.condition har angetts eller UniqueConstraint.fields inte har angetts.

Om UniqueConstraint.fields anges utan UniqueConstraint.condition, används som standard felmeddelandet Meta.unique_together när det finns flera fält, och felmeddelandet Field.unique när det finns ett enda fält.

Changed in Django 5.2:

I äldre versioner användes inte det medföljande UniqueConstraint.violation_error_message när UniqueConstraint.fields angavs utan UniqueConstraint.condition.