Référence des contraintes

Les classes définies dans ce module créent des contraintes de base de données. Elles sont ajoutées dans l’option Meta.constraints des modèles.

Référencement des contraintes intégrées

Les contraintes sont définies dans django.db.models.constraints, mais par commodité elles sont importées dans django.db.models. La convention standard est d’utiliser from django.db import models et de se référer aux contraintes avec models.<Telle>Constraint.

Contraintes dans les classes de base abstraites

Les contraintes doivent toujours être nommées de façon unique. Cela signifie qu’il n’est pas possible de définir des contraintes dans une classe de base abstraite, dans la mesure où l’option Meta.constraints est héritée par les sous-classes avec exactement les mêmes valeurs d’attributs (y compris name). Pour éviter des collisions de nom, le nom peut contenir '%(app_label)s' et '%(class)s' qui seront remplacés respectivement par l’étiquette de l’application et le nom de la classe du modèle concret (tout en minuscules). Par exemple, CheckConstraint(check=Q(age__gte=18), name='%(app_label)s_%(class)s_is_adult').

Validation des contraintes

Les contraintes sont vérifiées durant la validation des modèles.

Validation des contraintes pour JSONField

Les contraintes contenant des champs JSONField peuvent ne pas produire d’erreurs de validation car les transformations de clés, d’indices et de chemins présentent beaucoup de particularités en fonction du type de base de données. Ceci pourrait être pris en charge à l’avenir.

Vous devriez toujours vérifier qu’il n’y a pas de messages de journal dans le journaliseur django.db.models, du genre «Got a database error calling check() on …» pour être sûr que la validation s’est bien déroulée.

Changed in Django 4.1:

Dans les versions précédentes, les contraintes n’étaient pas vérifiées durant la validation des modèles.

BaseConstraint

class BaseConstraint(name, violation_error_message=None)

Classe de base pour toutes les contraintes. Les sous-classes doivent implémenter les méthodes constraint_sql(), create_sql(), remove_sql() et validate().

Toutes les contraintes partagent les paramètres suivants :

name

BaseConstraint.name

Le nom de la contrainte. La contrainte doit toujours posséder un nom unique.

violation_error_message

New in Django 4.1.
BaseConstraint.violation_error_message

Le message d’erreur utilisé lorsque ValidationError est générée pendant la phase de validation des modèles. Contient par défaut "La contrainte %(name)sn'est pas respectée".

validate()

New in Django 4.1.
BaseConstraint.validate(model, instance, exclude=None, using=DEFAULT_DB_ALIAS)

Valide que la contrainte définie sur le modèle est respectée pour l’instance. Cela produira une requête vers la base de données pour s’assurer que la contrainte est bien respectée. Si des champs de la liste exclude sont nécessaires pour valider la contrainte, celle-ci sera ignorée.

Génère ValidationError lorsque la contrainte n’est pas respectée.

Cette méthode doit être implémentée par les sous-classes.

CheckConstraint

class CheckConstraint(*, check, name, violation_error_message=None)

Crée une contrainte de vérification dans la base de données.

check

CheckConstraint.check

Un objet Q ou une Expression booléenne qui indique le contrôle que la contrainte souhaitée doit appliquer.

Par exemple, CheckConstraint(check=Q(age__gte=18), name='age_gte_18') s’assure que le champ age n’est jamais au-dessous de 18.

Oracle

Les contrôles avec des champs possiblement nuls avec Oracle doivent inclure une condition autorisant les valeurs NULL afin que validate() se comporte de la même façon que la validation des contraintes de contrôle. Par exemple, si age est un champ pouvant être nul

CheckConstraint(check=Q(age__gte=18) | Q(age__isnull=True), name="age_gte_18")
Changed in Django 4.1:

Le paramètre violation_error_message a été ajouté.

UniqueConstraint

class UniqueConstraint(*expressions, fields=(), name=None, condition=None, deferrable=None, include=None, opclasses=(), violation_error_message=None)

Crée une contrainte d’unicité dans la base de données.

expressions

UniqueConstraint.expressions

L’argument positionnel *expressions permet de créer des contraintes d’unicité fonctionnelles sur des expressions et des fonctions de base de données.

Par exemple :

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

crée une contrainte d’unicité sur la valeur en minuscules du champ name dans l’ordre alphabétique inverse et le champ category dans l’ordre alphabétique par défaut.

Les contraintes d’unicité basées sur des fonctions sont soumises aux même restrictions de base de données que Index.expressions.

fields

UniqueConstraint.fields

Une liste de noms de champs qui précise l’ensemble unique de colonnes pour lesquelles la contrainte va assurer l’unicité.

Par exemple, UniqueConstraint(fields=['chambre', 'date'], name='reservation_unique') s’assure que chaque chambre ne peut être réservée qu’une seule fois par date.

condition

UniqueConstraint.condition

Un objet Q qui indique la condition que la contrainte souhaitée doit appliquer.

Par exemple :

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

s’assure que chaque utilisateur dispose d’un seul brouillon.

Ces conditions sont soumises aux même restrictions de base de données que Index.condition.

deferrable

UniqueConstraint.deferrable

Définissez ce paramètre pour créer une contrainte d’unicité différable. Les valeurs acceptées sont Deferrable.DEFERRED ou Deferrable.IMMEDIATE. Par exemple

from django.db.models import Deferrable, UniqueConstraint

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

Par défaut, les contraintes ne sont pas différées. Une contrainte différée ne sera pas appliquée avant la fin de la transaction. Une contrainte immédiate sera appliquée immédiatement après chaque commande.

MySQL, MariaDB et SQLite.

Les contraintes d’unicité différables sont ignorées avec MySQL, MariaDB et SQLite car ces moteurs ne les prennent pas en charge.

Avertissement

Les contraintes d’unicité différées peuvent amener à des performances réduites.

include

UniqueConstraint.include

Une liste ou un tuple de noms de champs à inclure dans l’index unique couvrant, représentant des colonnes qui ne sont pas des clés. Cela permet des analyses en index pur avec des requêtes qui ne sélectionnent que les champs inclus (include) et qui ne filtrent que sur les champs indexés (fields).

Par exemple :

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

permettra le filtrage sur room et date, sélectionnant aussi full_name, tout en ne récupérant les données qu’à partir de l’index.

include n’est pris en charge que par PostgreSQL.

Les colonnes qui ne sont pas des clés sont soumises aux même restrictions de base de données que pour Index.include.

opclasses

UniqueConstraint.opclasses

Les noms des classes d’opérateurs PostgreSQL à utiliser pour cet index unique. Si vous nécessitez une classe d’opérateur personnalisée, vous devez en fournir une pour chaque champ de l’index.

Par exemple :

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

crée un index unique sur username en utilisant varchar_pattern_ops.

opclasses est ignoré pour les bases de données autres que PostgreSQL.

violation_error_message

New in Django 4.1.
UniqueConstraint.violation_error_message

Le message d’erreur utilisé lorsque ValidationError est générée pendant la phase de validation des modèles. Contient par défaut BaseConstraint.violation_error_message.

Ce message n’est pas utilisé pour les contraintes UniqueConstraint avec fields et sans condition. De telles contraintes affichent le même message que les contraintes définies avec Field.unique ou dans Meta.unique_together.

Back to Top