Getting Help

en
Language: fr

1.10
1.11
2.0
2.1
2.2
3.0
3.1
3.2
4.0
4.1
4.2
5.0
5.1
dev
Documentation version: 1.8

Bases de données¶

Django tente d’activer autant de fonctionnalités que possible sur tous les types de base de données. Cependant, tous les types de base de données ne sont pas semblables, et nous avons dû prendre des décisions de conception sur les fonctionnalités à activer et les hypothèses sur lesquelles nous pouvions nous baser en toute sécurité.

Ce fichier décrit quelques-unes des caractéristiques qui pourraient être pertinentes pour l’utilisation de Django. Bien sûr, il ne remplace pas la documentation ou les manuels de référence spécifiques aux différents serveurs de base de données.

Remarques générales¶

Connexions persistantes¶

Les connexions persistantes évitent de devoir rétablir une connexion à la base de données pour chaque requête. Elles sont contrôlées par le réglage CONN_MAX_AGE qui définit la durée de vie maximale d’une connexion. Ce réglage peut être défini indépendamment pour chaque base de données.

La valeur par défaut est 0, pour préserver le comportement historique de la fermeture de la connexion de base de données à la fin de chaque requête. Pour activer les connexions persistantes, définissez CONN_MAX_AGE à un nombre positif de secondes. Pour que les connexions persistantes soient illimitées dans le temps, définissez-le à None.

Gestion des connexions¶

Django ouvre une connexion à la base de données lors de la première requête de base de données. Il garde cette connexion ouverte et la réutilise pour les requêtes suivantes. Django ferme la connexion dès que la limite de durée définie par CONN_MAX_AGE est dépassée ou que la connexion n’est plus utilisable.

Dans le détail, Django ouvre automatiquement une connexion à la base de données chaque fois qu’il en a besoin et qu’il n’en a pas déjà une – soit parce que c’est la première connexion, soit parce que la connexion précédente a été fermée.

Avant chaque requête à la base de données, Django clôture la connexion si celle-ci a atteint la limite de durée. Si votre base de données termine les connexions inactives après une certaine durée, vous devez définir CONN_MAX_AGE à une valeur inférieure, de sorte que Django ne cherche pas à utiliser une connexion qui a été interrompue par le serveur de base de données (ce problème ne peut affecter que les sites à très faible trafic).

À la fin de chaque requête à la base de données, Django clôture la connexion si celle-ci a atteint la limite de durée ou si elle est dans un état d’erreur irrécupérable. Si des erreurs de base de données ont eu lieu lors du traitement des requêtes, Django vérifie si la connexion fonctionne encore, et la ferme si ce n’est pas le cas. De cette manière, les erreurs de base de données affectent au plus une requête ; si la connexion devient inutilisable, la prochaine requête obtient une nouvelle connexion.

Mises en garde¶

Comme chaque fil d’exécution gère sa propre connexion, la base de données doit prendre en charge au moins autant de connexions simultanées qu’il n’y a de fils d’exécution (threads) de travail pour Django.

Parfois, la majorité des vues n’accèdent pas à une certaine base de données, par exemple parce que c’est la base de données d’un système externe, ou grâce à la mise en cache. Dans ce cas, vous devez définir CONN_MAX_AGE à une valeur faible, voire à 0, car cela n’a aucun sens de maintenir une connexion qui est peu susceptible d’être réutilisée. Cela contribuera à garder un petit nombre de connexions simultanées à cette base de données.

Le serveur de développement crée un nouveau fil d’exécution pour chaque requête qu’il gère, annulant l’effet des connexions persistantes. Ne les activez pas pendant le développement.

Lorsque Django établit une connexion à la base de données, il met en place les paramètres appropriés en fonction du type de base de données utilisé. Si vous activez les connexions persistantes, cette phase de configuration n’est pas répétée pour chaque requête. Si vous modifiez des paramètres tels que le niveau d’isolement de la connexion ou le fuseau horaire, vous devez soit restaurer les paramètres par défaut de Django à la fin de chaque requête, soit forcer une valeur appropriée avant chaque requête, soit désactiver les connexions persistantes.

Codage de caractères¶

Django suppose que toutes les bases de données utilisent le codage UTF-8. L’utilisation d’autres codages peut entraîner un comportement inattendu comme des erreurs de base de données « valeur trop longue » pour des données qui sont valides dans Django. Consultez les notes ci-dessous spécifiques à chaque base de données pour obtenir des informations sur la façon de configurer correctement votre base de données.

Notes sur PostgreSQL¶

Django prend en charge PostgreSQL 9.0 et plus récent. Il exige la version 2.4.5 ou plus récente de psycopg2 (ou 2.5+ si vous voulez profiter de django.contrib.postgres).

Paramètres de connexion PostgreSQL¶

Voir HOST pour plus de détails.

Optimisation de la configuration de PostgreSQL¶

Django a besoin des paramètres suivants pour se connecter aux bases de données :

client_encoding: 'UTF8',
default_transaction_isolation: 'read committed' par défaut, ou la valeur définie dans les options de connexion (voir ci-dessous),
timezone: 'UTC' quand USE_TZ vaut True, sinon indiquez la valeur de TIME_ZONE.

Si ces paramètres ont déjà les valeurs correctes, Django n’aura pas à les indiquer pour chaque nouvelle connexion, ce qui améliore légèrement les performances. Vous pouvez les configurer directement dans postgresql.conf ou plus commodément pour chaque utilisateur de base de données avec ALTER ROLE.

Django fonctionne très bien sans cette optimisation, mais chaque nouvelle connexion va faire quelques requêtes supplémentaires pour définir ces paramètres.

Niveau d’isolement¶

Comme pour PostgreSQL lui-même, le niveau d’isolement de Django vaut par défaut READ COMMITTED. Si vous avez besoin d’un plus haut niveau d’isolement tel que REPEATABLE READ ou SERIALIZABLE, définissez-le dans la partie OPTIONS de la configuration de base de données DATABASES:

import psycopg2.extensions

DATABASES = {
    # ...
    'OPTIONS': {
        'isolation_level': psycopg2.extensions.ISOLATION_LEVEL_SERIALIZABLE,
    },
}

Note

Sous des niveaux d’isolement plus élevés, votre application doit être préparée à gérer des exceptions générées lors d’échecs de sérialisation. Cette option est prévue pour des utilisateurs avancés.

Index pour les colonnes `varchar` et `text`¶

Lorsque vous indiquez db_index=True sur vos champs de modèle, Django génère généralement un seul CREATE INDEX. Toutefois, si le type de champ de base de données est varchar ou text (par exemple, pour les champs de type CharField, FileField ou TextField), Django crée alors un index supplémentaire qui utilise une classe opérateur de PostgreSQL appropriée pour la colonne. Cet index supplémentaire est nécessaire pour le bon fonctionnement des recherches qui utilisent l’opérateur SQL LIKE, comme le font les recherches avec contains et startswith.

Notes sur MySQL¶

Versions prises en charge¶

Django prend en charge les versions 5.5 et plus récentes de MySQL.

La fonctionnalité inspectdb de Django utilise la base de données information_schema, qui contient des données détaillées sur tous les schémas de la base de données.

Django s’attend à ce que la base de données accepte l’Unicode (codage UTF-8) et lui délègue la charge de faire respecter les transactions et l’intégrité référentielle. Il est important d’être conscient du fait que ces deux derniers aspects ne sont pas réellement appliqués par MySQL lorsque le moteur de stockage MyISAM est utilisé, voir la section suivante.

Les moteurs de stockage¶

MySQL possède plusieurs moteurs de stockage. Vous pouvez changer le moteur de stockage par défaut dans la configuration du serveur.

Jusqu’à MySQL 5.5.4, le moteur par défaut était MyISAM [1]. Le principal défaut de MyISAM est qu’il ne prend pas en charge les transactions ni le contrôle des contraintes de clé étrangère. Son aspect positif est qu’il était le seul moteur prenant en charge l’indexation et la recherche plein texte jusqu’à MySQL 5.6.4.

Depuis MySQL 5.5.5, le moteur de stockage par défaut est InnoDB. Ce moteur est pleinement transactionnel et prend en charge les références de clé étrangère. Il s’agit probablement du meilleur choix en ce moment. Notez cependant que le compteur d’incrémentation automatique de InnoDB est perdu au redémarrage de MySQL car il ne conserve pas la valeur AUTO_INCREMENT mais la recalcule comme « max(id)+1 ». Cela peut aboutir à une réutilisation inappropriée de valeurs AutoField.

Si vous mettez à jour un projet existant à MySQL 5.5.5 et que vous y ajoutez de nouvelles tables, vérifiez que toutes les tables utilisent le même moteur de stockage (MyISAM ou InnoDB). En particulier, si des tables impliquées dans une relation de clé étrangère utilisent des moteurs différents, il peut se produire des erreurs comme celle-ci lors de l’exécution de migrate:

_mysql_exceptions.OperationalError: (
    1005, "Can't create table '\\db_name\\.#sql-4a8_ab' (errno: 150)"
)

[1]	À moins que cela n’ait été modifié par le gestionnaire de votre paquet MySQL. Il nous a été rapporté que le programme d’installation de Windows Community Server définit InnoDB comme moteur de stockage par défaut, par exemple.

Pilotes DB API MySQL¶

L’API de base de données Python est décrite dans la PEP 249. Il y a trois principaux pilotes MySQL implémentant cette API :

MySQLdb est un pilote natif qui a été développé et maintenu depuis plus de 10 ans par Andy Dustman.
mysqlclient est un dérivé de MySQLdb qui ajoute la prise en charge de Python 3 et qui peut être utilisé comme remplacement à l’identique de MySQLdb. Au moment d’écrire ces lignes, il s’agit du choix recommandé pour utiliser MySQL avec Django.
MySQL Connector/Python est un pilote en Python pur écrit par Oracle qui n’a pas besoin de la bibliothèque client MySQL ni d’autres modules Python en dehors de la bibliothèque standard.

Tous ces pilotes respectent la concurrence entre fils d’exécution (thread-safe) et gèrent le regroupement de connexions. MySQLdb est le seul qui ne prend pas encore en charge Python 3.

En plus d’un pilote DB API, Django a besoin d’un adaptateur pour accéder aux pilotes de bases de données à partir de son ORM. Django fournit un adaptateur pour MySQLdb/mysqlclient alors que MySQL Connector/Python inclut le sien.

MySQLdb¶

Django a besoin de la version 1.2.1p2 ou ultérieure de MySQLdb.

Au moment d’écrire ces lignes, la version la plus récente de MySQLdb (1.2.5) ne prend pas en charge Python 3. Afin de pouvoir utiliser MySQLdb avec Python 3, il est nécessaire de le remplacer par l’installation de mysqlclient.

Note

Il existe des problèmes connus avec la façon dont MySQLdb convertit les chaînes de date en objets datetime. Plus particulièrement, les chaînes de date contenant la valeur 0000-00-00 sont valables pour MySQL mais sont converties en valeur None par MySQLdb.

Cela signifie que vous devez être prudent lors de l’utilisation de loaddata et dumpdata avec des lignes qui pourraient contenir des valeurs 0000-00-00, car elles seront converties en None.

mysqlclient¶

Django nécessite la version 1.3.3 ou ultérieure de mysqlclient. Notez que Python 3.2 n’est pas pris en charge. En dehors de la prise en charge de Python 3.3+, mysqlclient devrait se comporter de la même façon que MySQLDB.

MySQL Connector/Python¶

MySQL Connector/Python est disponible sur cette page de téléchargement. L’adaptateur Django est disponible dans les versions 1.1.X et ultérieures. Il est possible qu’il ne prenne pas en charge la toute dernière version de Django.

Définitions de fuseaux horaires¶

Si vous prévoyez d’utiliser la prise en charge des fuseaux horaires de Django, utilisez mysql_tzinfo_to_sql pour charger les tableaux de fuseaux horaires dans la base de données MySQL. Cela doit être fait une seule fois par serveur MySQL, pas pour chaque base de données.

Création d’une base de données¶

Vous pouvez créer une base de données à l’aide des outils de ligne de commande et de cette commande SQL :

CREATE DATABASE <dbname> CHARACTER SET utf8;

Cela garantit que toutes les tables et colonnes utilisent le codage UTF-8 par défaut.

Paramètres de tri¶

La méthode de tri (« collation ») d’une colonne détermine l’ordre dans lequel les données sont triées ainsi que les comparaisons d’égalité entre les chaînes. Ce paramètre peut être défini à l’échelle de la base de données mais aussi par table et par colonne. Ceci est documenté complètement dans la documentation MySQL. Dans tous les cas, la méthode de tri est définie en modifiant directement les tables de la base de données ; Django ne fournit aucun moyen de faire cela au niveau de la définition du modèle.

Par défaut, avec une base de données UTF-8, MySQL utilise la collation utf8_general_ci. En conséquence, toutes les comparaisons d’égalité de chaînes se fait de manière insensible à la casse. C’est-à-dire que « Fred » et « freD » sont jugés équivalents pour la base de données. Si vous avez placé une contrainte unique sur un champ, il ne serait pas permis d’insérer à la fois « aa » et « AA » dans cette même colonne, dans la mesure où leur comparaison dit qu’elles sont identiques (et donc pas uniques) avec la collation par défaut.

Dans de nombreux cas, ce comportement par défaut ne sera pas un problème. Toutefois, si vous voulez vraiment que les comparaisons sur une colonne ou une table particulière soient sensibles à la casse, vous devez modifier la colonne ou la table pour qu’elle utilise le tri utf8_bin. Dans ce cas, la chose importante à savoir est que si vous utilisez MySQLdb 1.2.2, la base de données dans Django renvoie alors des chaînes d’octets (au lieu de chaînes Unicode) pour tous les champs de type caractère. Il s’agit d’une grosse modification par rapport à la pratique normale dans Django de toujours renvoyer des chaînes Unicode. C’est donc à vous, le développeur, de gérer le fait que vous recevrez des chaînes d’octets si vous configurez des tables pour utiliser la méthode de tri utf8_bin. Django lui-même devrait généralement fonctionner correctement avec ces colonnes (sauf pour les tables contrib.sessions Session et contrib.admin LogEntry décrites ci-dessous), mais votre code doit parfois ajouter un appel à django.utils.encoding.smart_text() si vous voulez vraiment travailler avec des données cohérentes – Django ne le fera pas pour vous (la couche principale de base de données et la couche des modèles sont séparées en interne de sorte que la couche de la base de données ne sait pas qu’il est nécessaire de faire cette conversion dans ce seul cas particulier).

Si vous utilisez MySQLdb 1.2.1p2, la classe standard CharField de Django renvoie des chaînes Unicode même avec un tri utf8_bin. Toutefois, les champs TextField sont renvoyés comme une instance d’un tableau de type array.array (du module Python array standard). Django ne peut pas faire grand chose à ce sujet, puisque, encore une fois, les informations pour savoir quelles sont les conversions nécessaires ne sont pas disponibles au moment où les données sont lues dans la base de données. Ce problème a été résolu dans MySQLdb 1.2.2, donc si vous souhaitez utiliser TextField avec utf8_bin, la solution recommandée est de mettre à jour vers la version 1.2.2, puis de traiter les chaînes d’octets comme décrit ci-dessus (ce qui ne devrait pas être trop difficile).

Si vous vous décidiez à utiliser la collation utf8_bin pour certaines de vos tables avec MySQLdb 1.2.1p2 ou 1.2.2, il faut tout de même conserver la collation utf8_general_ci (par défaut) pour la table django.contrib.sessions.models.Session (nommée habituellement django_session) ainsi que pour la table django.contrib.admin.models.LogEntry (nommée habituellement django_admin_log). Ce sont les deux tables standards utilisant en interne un champ TextField.

Notez que selon les Jeux de caractères Unicode MySQL, les comparaisons avec la collation utf8_general_ci sont plus rapides, mais légèrement moins correctes que les comparaisons avec utf8_unicode_ci. Si cela est acceptable pour votre application, il est préférable d’utiliser utf8_general_ci car elle est plus rapide. Dans le cas contraire (par exemple si vous avez besoin de l’ordre du dictionnaire allemand), utilisez utf8_unicode_ci car cette collation est plus juste.

Avertissement

Les sous-formulaires de modèles valident les champs uniques de manière sensible à la casse. Ainsi, lors de l’utilisation d’une collation de base de données insensible à la casse, des sous-formulaires contenant des valeurs de champs uniques qui ne diffèrent que par leur casse vont passer la validation avec succès, mais au moment de l’enregistrement par save(), une exception IntegrityError va se produire.

Connexion à la base de données¶

Reportez-vous à la documentation des réglages.

Les paramètres de connexion sont utilisés dans cet ordre :

OPTIONS.
NAME, USER, PASSWORD, HOST, PORT
Fichiers d’options de MySQL.

En d’autres termes, si vous définissez le nom de la base de données dans OPTIONS, cette définition a la priorité sur NAME, qui aurait lui-même la priorité sur n’importe quelle valeur d’un fichier d’options MySQL.

Voici un exemple de configuration qui utilise un fichier d’options MySQL :

# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'OPTIONS': {
            'read_default_file': '/path/to/my.cnf',
        },
    }
}


# my.cnf
[client]
database = NAME
user = USER
password = PASSWORD
default-character-set = utf8

Quelques autres options de connexion MySQLdb peuvent se révéler utiles, telles que ssl, init_command ou sql_mode. Consultez la documentation MySQLdb pour plus de détails.

Création des tables¶

Lorsque Django génère le schéma, il ne précise pas de moteur de stockage, donc les tables seront créées avec le moteur de stockage par défaut de votre serveur de base de données. La solution la plus simple est de définir le moteur souhaité comme moteur de stockage par défaut pour votre serveur de base de données.

Si vous utilisez un service d’hébergement et que vous ne pouvez pas modifier le moteur de stockage par défaut sur votre serveur, vous avez plusieurs possibilités.

Après la création des tables, exécutez une commande SQL ALTER TABLE pour convertir une table vers un nouveau moteur de stockage (comme InnoDB) :
```
ALTER TABLE <tablename> ENGINE=INNODB;
```
Cela peut être fastidieux si vous avez beaucoup de tables.
Une autre possibilité est d’utiliser l’option init_command de MySQLdb avant de créer les tables :
```
'OPTIONS': {
   'init_command': 'SET storage_engine=INNODB',
}
```
Ceci définit le moteur de stockage par défaut lors de la connexion à la base de données. Une fois que les tables ont été créées, vous devriez supprimer cette option car elle ajoute une requête lors de chaque connexion à la base de données, alors que c’est uniquement nécessaire lors de la création d’une table.

Noms de tables¶

Certains problèmes connus, même dans les dernières versions de MySQL peuvent engendrer une modification d’un nom de table lorsque certaines instructions SQL sont exécutées sous certaines conditions. Il est recommandé d’utiliser des noms de table en minuscules, si possible, pour éviter les problèmes qui pourraient résulter de ce comportement. Django utilise des noms de tables en minuscules quand il génère automatiquement les noms de table à partir des modèles, c’est donc un élément à prendre en compte surtout si vous surchargez le nom de la table en utilisant le paramètre db_table.

Points de sauvegarde (« savepoints »)¶

L’ORM de Django tout comme MySQL (lorsque le moteur de stockage InnoDB est utilisé) prennent en charge les points de sauvegarde des bases de données.

Si vous utilisez le moteur de stockage MyISAM, vous recevrez des erreurs générées par la base de données si vous essayez d’utiliser les méthodes de l’API des transactions liées aux points de sauvegarde. En effet, comme la détection du moteur de stockage d’une table ou d’une base de données MySQL est une opération très coûteuse en ressources, il a été décidé de ne pas convertir dynamiquement ces méthodes en méthodes neutres en se basant sur ce genre de détection.

Notes sur des champs particuliers¶

Champs de type caractère¶

Tous les champs qui sont stockés dans des types de colonnes VARCHAR ont leur taille maximale (max_length) limitée à 255 caractères si vous utilisez unique=True pour ce champ. Cela concerne les champs CharField, SlugField et CommaSeparatedIntegerField.

Limites des champs¶

MySQL ne peut indexer que les N premiers caractères d’une colonne BLOB ou TEXT. Comme TextField n’a pas de longueur définie, il n’est pas possible de marquer un tel champ avec unique=True. MySQL produirait l’erreur : “BLOB/TEXT column ‘<db_column>’ used in key specification without a key length”.

Prise en charge des fractions de secondes pour les champs heure et date/heure¶

À partir de la version 5.6.4, MySQL est capable de stocker des fractions de secondes, pour autant que les définitions de colonnes contiennent une indication adéquate (par ex. DATETIME(6)). Dans les versions précédentes, ce n’était pas pris en charge du tout. De plus, les versions de MySQLdb plus anciennes que 1.2.5 contiennent une anomalie qui empêche également l’utilisation des fractions de secondes avec MySQL.

Django ne va pas mettre à jour lui-même les colonnes existantes pour que les fractions de secondes soient incluses si le serveur de base de données le prend en charge. Si vous souhaitez les activer dans une base de données existante, c’est à vous de mettre à jour la colonne manuellement dans la base de données en exécutant une commande du style :

ALTER TABLE `your_table` MODIFY `your_datetime_column` DATETIME(6)

ou en utilisant une opération RunSQL dans une migration de données.

Changed in Django 1.8:

Précédemment, Django tronquait les fractions de secondes des valeurs datetime et time avec le moteur MySQL. Il laisse maintenant la base de données décider si elle veut tenir compte de cette partie de la valeur ou non. Par défaut, les nouvelles colonnes DateTimeField ou TimeField sont dorénavant créées avec la prise en charge des fractions de secondes sur MySQL 5.6.4 ou plus récent et les moteurs mysqlclient ou MySQLdb 1.2.5 ou plus récent.

Colonnes `TIMESTAMP`¶

Si vous utilisez une base de données existante qui contient des colonnes TIMESTAMP, vous devez définir USE_TZ = False pour éviter de corrompre des données. inspectdb fait correspondre ces colonnes à des champs DateTimeField et si vous activez la prise en charge des fuseaux horaires, aussi bien MySQL que Django vont tenter de convertir les valeurs depuis le fuseau UTC vers le temps local.

Verrouillage de ligne avec `QuerySet.select_for_update()`¶

MySQL ne gère pas l’option NOWAIT de l’instruction SELECT ... FOR UPDATE. Si select_for_update() est utilisé avec nowait=True, une exception de type DatabaseError sera générée.

Le retypage automatique peut produire des résultats inattendus¶

Lors de l’exécution d’une requête sur un type chaîne mais avec une valeur nombre entier, MySQL force les types de toutes les valeurs de la table à des nombres entiers avant d’effectuer la comparaison. Si la table contient les valeurs 'abc', 'def' et que la requête cherche WHERE macolonne=0, les deux lignes vont correspondre. De la même manière, WHERE macolonne=1 correspond à la valeur 'abc1'. C’est pourquoi les champs de type chaîne inclus dans Django forcent toujours la valeur à une chaîne avant de l’utiliser dans une requête.

Si vous implémentez des champs de modèle personnalisés héritant directement de Field, que vous surchargez get_prep_value() ou que vous utilisez RawSQL, extra() ou raw(), vous devez vous assurer d’effectuer les forçages de type appropriés.

Notes sur SQLite¶

SQLite fournit une excellente alternative pour le développement d’applications qui sont essentiellement en lecture seule ou qui nécessitent une installation de plus petite taille. Comme avec tous les serveurs de base de données, cependant, il y a quelques différences spécifiques à SQLite à prendre en compte.

Recherche de portions de chaînes de caractères et sensibilité à la casse¶

Pour toutes les versions de SQLite, il y a un comportement peu intuitif lorsque l’on essaie de faire correspondre certains types de chaînes. Ce comportement est déclenché lors de l’utilisation des filtres iexact ou contains dans des QuerySets. Le comportement se divise en deux cas :

1. For substring matching, all matches are done case-insensitively. That is a filter such as filter(name__contains="aa") will match a name of "Aabb".

2. For strings containing characters outside the ASCII range, all exact string matches are performed case-sensitively, even when the case-insensitive options are passed into the query. So the iexact filter will behave exactly the same as the exact filter in these cases.

Il existe quelques solutions de contournement documentées sur sqlite.org, mais elles ne sont pas exploitées par le moteur SQLite par défaut de Django, car cela impliquerait des difficultés certaines pour le faire de manière robuste. Django présente donc le comportement SQLite par défaut et il faut en être bien conscient lors de filtrage de sous-chaînes ou de chaînes insensibles à la casse.

Expressions `CASE` et anciennes versions de SQLite¶

SQLite 3.6.23.1 et ses versions précédentes contiennent une anomalie lors du traitement des paramètres de requête dans une expression CASE contenant une clause ELSE et de l’arithmétique.

SQLite 3.6.23.1 a été publiée en mars 2010 et la plupart des distributions binaires actuelles sur diverses plates-formes contiennent une version plus récente de SQLite, à l’exception notable des installeurs Python 2.7 pour Windows.

Au moment d’écrire ces lignes, la dernière version pour Windows, Python 2.7.10, inclut SQLite 3.6.21. Vous pouvez installer pysqlite2 ou remplacer sqlite3.dll (installé par défaut dans C:\Python27\DLLs) par une version plus récente provenant de http://www.sqlite.org/ afin de remédier à ce problème.

Utilisation de versions plus récentes du pilote SQLite DB-API 2.0¶

Django utilise de préférence le module pysqlite2 au lieu du module sqlite3 livré avec la bibliothèque Python standard, s’il le trouve installé.

Cela donne la possibilité de mettre à niveau à la fois l’interface DB-API 2.0 ou SQLite 3 elle-même à des versions plus récentes que celles incluses dans votre distribution Python binaire, si le besoin s’en fait sentir.

Erreurs « Database is locked » (la base de données est verrouillée)¶

SQLite est supposé être une base de données légère et ne peut donc pas gérer un niveau élevé de concurrence. Les erreurs OperationalError: database is locked indiquent que l’application subit une concurrence plus élevée que ce que sqlite ne peut gérer dans sa configuration par défaut. Cette erreur signifie qu’un processus ou un fil d’exécution possède un verrou exclusif sur la connexion de base de données et qu’un autre fil d’exécution a dû attendre trop longtemps que le verrou se libère.

L’adaptateur SQLite de Python comporte une valeur d’expiration par défaut qui détermine le temps maximal d’attente de déverrouillage d’un autre fil d’exécution avant qu’il n’expire en générant une erreur OperationalError: database is locked.

Si vous obtenez cette erreur, vous pouvez résoudre le problème en :

Passant à un autre moteur de base de données. À un certain stade, SQLite devient vraiment trop léger pour des applications du monde réel, et ce type d’erreur de concurrence indique que ce point a été atteint.
Réécrivant le code pour réduire la concurrence et s’assurer que les transactions de base de données restent aussi brèves que possible.
Augmentant la valeur d’expiration par défaut en définissant l’option de base de données timeout:
```
'OPTIONS': {
    # ...
    'timeout': 20,
    # ...
}
```
Cela ne fera que prolonger un peu le temps d’attente de SQLite avant de produire des erreurs « database is locked » ; le problème de base n’en est pas résolu pour autant.

`QuerySet.select_for_update()` non pris en charge¶

SQLite ne prend pas en charge la syntaxe SELECT ... FOR UPDATE. L’appel de cette méthode n’a aucun effet.

Le style de paramètre « pyformat » dans les requêtes brutes n’est pas pris en charge¶

Pour la plupart des moteurs, les requêtes brutes (Manager.raw() ou cursor.execute()) peuvent exploiter le style de paramètre « pyformat » où les substituants dans la requête sont écrits sous la forme '%(nom)s' et les paramètres sont transmis sous forme de dictionnaire au lieu de liste. SQLite ne prend pas cette syntaxe en charge.

Paramètres sans guillemets dans `connection.queries`¶

sqlite3 ne donne aucun moyen de récupérer le code SQL après avoir mis entre guillemets et substitué les paramètres. De ce fait, le code SQL dans connection.queries est reconstruit par une simple interpolation de chaîne. Cela peut ne pas être correct. Prenez soin d’ajouter les guillemets là où ils sont nécessaires avant de copier une requête dans un shell SQLite.

Notes sur Oracle¶

Django prend en charge les versions 11.1 et plus récentes du serveur de base de données Oracle. Il est nécessaire de posséder au minimum la version 4.3.1 du pilote Python cx_Oracle, même si nous recommandons d’utiliser au minimum la version 5.1.3 car c’est la première version prenant en charge Python 3.

Notez qu’en raison d’un bogue de corruption Unicode dans cx_Oracle 5.0, cette version du pilote ne doit pas être utilisée avec Django ; cx_Oracle 5.0.1 résout ce problème, donc si vous avez besoin d’une version plus récente, utilisez au moins la version 5.0.1.

La version cx_Oracle 5.0.1 ou ultérieure peut être compilée de manière facultative avec la variable d’environnement WITH_UNICODE. C’est recommandé, mais pas obligatoire.

Pour que la commande python manage.py migrate fonctionne, l’utilisateur de base de données Oracle doit posséder les permissions d’exécuter les commandes suivantes :

CREATE TABLE
CREATE SEQUENCE
CREATE PROCEDURE
CREATE TRIGGER

Pour exécuter la suite de tests d’un projet, l’utilisateur doit généralement posséder les privilèges supplémentaires suivants :

CREATE USER
DROP USER
CREATE TABLESPACE
DROP TABLESPACE
CREATE SESSION WITH ADMIN OPTION
CREATE TABLE WITH ADMIN OPTION
CREATE SEQUENCE WITH ADMIN OPTION
CREATE PROCEDURE WITH ADMIN OPTION
CREATE TRIGGER WITH ADMIN OPTION

Notez que même si le rôle RESOURCE possède les privilèges requis CREATE TABLE, CREATE SEQUENCE, CREATE PROCEDURE et CREATE TRIGGER et qu’un utilisateur disposant de RESOURCE WITH ADMIN OPTION peut accorder le privilège RESOURCE, cet utilisateur ne peut pas accorder de privilèges individuels (par ex. CREATE TABLE), ce qui fait que RESOURCE WITH ADMIN OPTION n’est généralement pas suffisant pour exécuter les tests.

Certaines suites de tests créent aussi des vues ; pour exécuter celles-ci, l’utilisateur a aussi besoin du privilège CREATE VIEW WITH ADMIN OPTION. C’est nécessaire en particulier pour la propre suite de tests de Django.

Changed in Django 1.8:

Avant Django 1.8, l’utilisateur de test recevait les rôles CONNECT et RESOURCE, ce qui fait que les privilèges supplémentaires requis pour exécuter la suite de tests étaient différents.

Tous ces privilèges sont inclus dans le rôle DBA, qui est adéquat dans le cadre d’une base de données de développement privée.

Le moteur de base de données Oracle utilise les paquets SYS.DBMS_LOB et SYS.DBMS_RANDOM, il faut donc que l’utilisateur possède les droits d’exécution pour lui. Il est normalement accessible par défaut à tous les utilisateurs, mais si ce n’est pas le cas, il faut attribuer les permissions comme ceci :

GRANT EXECUTE ON SYS.DBMS_LOB TO user;
GRANT EXECUTE ON SYS.DBMS_RANDOM TO user;

Connexion à la base de données¶

Pour se connecter en utilisant le nom de service de la base de données Oracle, le fichier settings.py doit ressembler à quelque chose comme ceci :

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.oracle',
        'NAME': 'xe',
        'USER': 'a_user',
        'PASSWORD': 'a_password',
        'HOST': '',
        'PORT': '',
    }
}

Dans ce cas, il faut laisser vide les deux clés HOST et PORT. Cependant, si vous n’utilisez pas de fichier tnsnames.ora ou une méthode de nommage similaire et que vous vouliez vous connecter en utilisant le SID (« xe » dans cet exemple), remplissez alors à la fois HOST et PORT, comme ceci :

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.oracle',
        'NAME': 'xe',
        'USER': 'a_user',
        'PASSWORD': 'a_password',
        'HOST': 'dbprod01ned.mycompany.com',
        'PORT': '1540',
    }
}

Il faut soit remplir les deux clés HOST et PORT, soit les laisser toutes deux vides. Django utilise un descripteur de connexion différent en fonction de ce choix.

Option threaded¶

Si vous prévoyez de faire fonctionner Django dans un environnement à fils d’exécution multiples (multithread), par exemple avec Apache et le module MPM par défaut sur tout système d’exploitation moderne), vous devez définir à True l’option threaded de votre configuration de base de données Oracle :

'OPTIONS': {
    'threaded': True,
},

Si vous ne le faites pas, vous risquez d’obtenir des plantées et d’autres comportements bizarres.

INSERT ... RETURNING INTO¶

Par défaut, le moteur Oracle utilise une clause RETURNING INTO pour obtenir efficacement la valeur d’un champ AutoField lors de l’insertion de nouvelles lignes. Ce comportement peut aboutir à des erreurs DatabaseError dans certaines configurations particulières, comme lors de l’insertion dans une table distante ou dans une vue avec le déclencheur INSTEAD OF. La clause RETURNING INTO peut être désactivée en définissant l’option use_returning_into de la configuration de base de données à False:

'OPTIONS': {
    'use_returning_into': False,
},

Dans ce cas, le moteur Oracle utilise une requête SELECT séparée pour récupérer les valeurs AutoField.

Questions de nommage¶

Oracle impose une longueur limite de 30 caractères pour les noms. Pour respecter cela, le moteur tronque les identifiants de base de données si nécessaire, remplaçant les quatre caractères finaux du nom tronqué par une valeur de hachage MD5 reproductible. De plus, le moteur transforme les identifiants de base de données tout en majuscules.

Pour empêcher ces transformations (ce qui n’est généralement nécessaire que lorsqu’on a affaire à des bases de données existantes ou quand il faut accéder à des tables appartenant à d’autres utilisateurs), entourez la valeur de db_table par des guillemets :

class LegacyModel(models.Model):
    class Meta:
        db_table = '"name_left_in_lowercase"'

class ForeignModel(models.Model):
    class Meta:
        db_table = '"OTHER_USER"."NAME_ONLY_SEEMS_OVER_30"'

Les noms entre guillemets peuvent également être utilisés avec les autres moteurs de base de données pris en charge par Django ; mais ces guillemets n’ont un effet qu’avec Oracle.

Lors de l’exécution de migrate, une erreur ORA-06552 peut se produire si certains mots-clés Oracle sont employés comme noms de champs de modèle ou comme valeur de l’option db_column. Django place entre guillemets tous les identifiants utilisés dans les requêtes pour empêcher la plupart de ce genre de problèmes, mais cette erreur peut quand même se produire lorsqu’un type de données Oracle est utilisé comme nom de colonne. Plus particulièrement, essayez d’éviter d’utiliser les noms date, timestamp, number ou float comme noms de champs.

NULL et les chaînes vides¶

Django préfère généralement utiliser la chaîne vide (‘’) plutôt que NULL, mais Oracle considère ces deux valeurs comme identiques. Pour contourner cela, le moteur Oracle ignore l’option explicite null pour les champs où la chaîne vide est une valeur possible et génère les instructions SQL comme si null=True. Lors de la lecture à partir de la base de données, Django part du principe qu’une valeur NULL dans l’un de ces champs équivaut en réalité à la chaîne vide et les données sont silencieusement converties pour respecter ce principe.

Limites des champs¶

Le moteur Oracle stocke les champs TextFields dans des colonnes NCLOB. Oracle impose certaines limites à l’utilisation de telles colonnes LOB en général :

Les colonnes LOB ne peuvent pas être utilisées comme clés primaires.
Les colonnes LOB ne peuvent pas être utilisées dans les index.
Les colonnes LOB ne peuvent pas être utilisées dans une liste SELECT DISTINCT. Cela signifie qu’une tentative d’utiliser la méthode QuerySet.distinct pour un modèle qui contient des colonnes TextField produira une erreur ORA-00932``avec Oracle. Pour contourner ce problème, utilisez la méthode ``QuerySet.defer de concert avec distinct() afin d’éviter que des colonnes TextField ne se retrouvent incluses dans la liste SELECT DISTINCT.

Utilisation d’un moteur de base de données externe¶

En plus des bases de données prises en charge officiellement, il existe des moteurs externes à Django qui permettent d’utiliser d’autres bases de données avec Django :

Les versions de Django et les fonctionnalités ORM prises en charges par ces moteurs inofficiels varient considérablement. Si vous avez des questions concernant les capacités spécifiques de ces moteurs inofficiels ou des questions de support, vous devrez vous adresser aux canaux d’aide offerts par chacun de ces projets externes.

Protection contre le « Cross site request forgery » (CSRF)

django-admin et manage.py

Documentation

Bases de données¶

Remarques générales¶

Connexions persistantes¶

Gestion des connexions¶

Mises en garde¶

Codage de caractères¶

Notes sur PostgreSQL¶

Paramètres de connexion PostgreSQL¶

Optimisation de la configuration de PostgreSQL¶

Niveau d’isolement¶

Index pour les colonnes varchar et text¶

Notes sur MySQL¶

Versions prises en charge¶

Les moteurs de stockage¶

Pilotes DB API MySQL¶

MySQLdb¶

mysqlclient¶

MySQL Connector/Python¶

Définitions de fuseaux horaires¶

Création d’une base de données¶

Paramètres de tri¶

Connexion à la base de données¶

Création des tables¶

Noms de tables¶

Points de sauvegarde (« savepoints »)¶

Notes sur des champs particuliers¶

Champs de type caractère¶

Limites des champs¶

Prise en charge des fractions de secondes pour les champs heure et date/heure¶

Colonnes TIMESTAMP¶

Verrouillage de ligne avec QuerySet.select_for_update()¶

Le retypage automatique peut produire des résultats inattendus¶

Notes sur SQLite¶

Recherche de portions de chaînes de caractères et sensibilité à la casse¶

Expressions CASE et anciennes versions de SQLite¶

Utilisation de versions plus récentes du pilote SQLite DB-API 2.0¶

Erreurs « Database is locked » (la base de données est verrouillée)¶

QuerySet.select_for_update() non pris en charge¶

Le style de paramètre « pyformat » dans les requêtes brutes n’est pas pris en charge¶

Paramètres sans guillemets dans connection.queries¶

Notes sur Oracle¶

Connexion à la base de données¶

Option threaded¶

INSERT ... RETURNING INTO¶

Questions de nommage¶

NULL et les chaînes vides¶

Limites des champs¶

Utilisation d’un moteur de base de données externe¶

Additional Information

Support Django!

Contents

Browse

You are here:

Getting help

Download:

Index pour les colonnes `varchar` et `text`¶

Colonnes `TIMESTAMP`¶

Verrouillage de ligne avec `QuerySet.select_for_update()`¶

Expressions `CASE` et anciennes versions de SQLite¶

`QuerySet.select_for_update()` non pris en charge¶

Paramètres sans guillemets dans `connection.queries`¶