Django propose trois manières d’exécuter des requêtes SQL brutes : vous pouvez intégrer des fragments de SQL bruts dans les requêtes ORM en utilisant RawSQL (voir Fragments SQL bruts), utiliser Manager.raw() pour exécuter des requêtes brutes et renvoyer des instances de modèles, ou outrepasser complètement la couche des modèles et exécuter directement du code SQL personnalisé.
Dans certains cas, il peut être nécessaire d’intégrer des fragments de code SQL brut directement dans les requêtes ORM, par exemple dans des appels à annotate() ou filter(). Utilisez des expressions Func() pour appeler des fonctions de base de données indépendamment du type de base de données, ou RawSQL pour des fragments directs de SQL paramétrisé.
La méthode de gestionnaire raw() peut être utilisée pour exécuter des requêtes SQL brutes qui renvoient des instances de modèles :
Cette méthode accepte une requête SQL brute, l’exécute et renvoie une instance django.db.models.query.RawQuerySet. Il est possible alors d’effectuer une boucle sur cette instance RawQuerySet comme pour un objet QuerySet normal afin d’accéder aux instances d’objets.
Un exemple vaut mieux que mille mots. Supposons que vous ayez créé le modèle suivant :
\nclass Person(models.Model):\n first_name = models.CharField(...)\n last_name = models.CharField(...)\n birth_date = models.DateField(...)\nVous pouvez alors exécuter du code SQL personnalisé comme ceci :
\n>>> for p in Person.objects.raw("SELECT * FROM myapp_person"):\n... print(p)\n...\nJohn Smith\nJane Jones\nCet exemple n’est pas des plus passionnants, car il correspond exactement à l’expression Person.objects.all(). Toutefois, raw() comporte quelques autres options qui en font un outil très puissant.
raw() fait automatiquement correspondre les champs de la requête avec les champs du modèle.
L’ordre des champs dans la requête n’est pas important. En d’autres termes, les deux requêtes suivantes donneront le même résultat :
\n>>> Person.objects.raw("SELECT id, first_name, last_name, birth_date FROM myapp_person")\n>>> Person.objects.raw("SELECT last_name, birth_date, first_name, id FROM myapp_person")\nLa correspondance se fait sur le nom. Cela signifie que vous pouvez utiliser les clauses SQL AS pour faire correspondre les champs de la requête aux champs du modèle. Ainsi, si vous disposez d’une autre table contenant les données de Person, vous pouvez facilement faire correspondre ces données avec des instances de Person:
>>> Person.objects.raw("""\n... SELECT first AS first_name,\n... last AS last_name,\n... bd AS birth_date,\n... pk AS id,\n... FROM some_other_table\n... """)\n...\nTant que les noms correspondent, les instances de modèle seront créées correctement.
\nIl est aussi possible de faire correspondre les champs de requête aux champs de modèle en utilisant le paramètre translations de raw(). Il s’agit d’un dictionnaire faisant correspondre les noms des champs de la requête aux noms des champs du modèle. Par exemple, la requête ci-dessus aurait aussi pu être écrite de cette manière :
>>> name_map = {"first": "first_name", "last": "last_name", "bd": "birth_date", "pk": "id"}\n>>> Person.objects.raw("SELECT * FROM some_other_table", translations=name_map)\nraw() autorise l’utilisation d’index ; dans le cas où vous souhaitez obtenir uniquement le premier résultat, vous pouvez écrire :
>>> first_person = Person.objects.raw("SELECT * FROM myapp_person")[0]\nCependant, l’indexation et la segmentation ne sont pas effectuées au niveau de la base de données. Si la base de données contient une grande quantité d’objets Person, il est plus efficace de limiter la requête au niveau SQL :
>>> first_person = Person.objects.raw("SELECT * FROM myapp_person LIMIT 1")[0]\nIl est aussi possible d’ignorer certains champs :
\n>>> people = Person.objects.raw("SELECT id, first_name FROM myapp_person")\nLes objets Person renvoyés par cette requête constitueront des instances de modèle différées (voir defer()). Cela signifie que les champs omis dans la requête seront chargés à la demande. Par exemple :
>>> for p in Person.objects.raw("SELECT id, first_name FROM myapp_person"):\n... print(\n... p.first_name, # This will be retrieved by the original query\n... p.last_name, # This will be retrieved on demand\n... )\n...\nJohn Smith\nJane Jones\nEn apparence, il semble que la requête ait récupéré à la fois le prénom et le nom. Cependant, cet exemple effectue en réalité 3 requêtes. Seuls les prénoms (first_name) ont été obtenus par la requête raw(), les noms (last_name) ont été obtenus chacun à la demande au moment où ils ont été affichés.
Un seul champ ne peut pas être omis, c’est le champ clé primaire. Django utilise la clé primaire pour identifier les instances de modèle, elle doit donc être obligatoirement incluse dans la requête brute. Une exception FieldDoesNotExist est générée si vous oubliez d’inclure la clé primaire.
raw()Lien vers cette rubrique#S’il est nécessaire d’effectuer des requêtes paramétrées, il est possible d’utiliser le paramètre params de raw():
>>> lname = "Doe"\n>>> Person.objects.raw("SELECT * FROM myapp_person WHERE last_name = %s", [lname])\nparams est une liste ou un dictionnaire de paramètres. Dans la chaîne de requête, il faut alors inclure des substituants %s pour une liste ou des substituants``%(clé)s`` pour un dictionnaire (où clé est remplacé par une clé de dictionnaire), quel que soit le moteur de base de données. Ces substituants seront remplacés par le contenu du paramètre params.
Dans certains cas, même Manager.raw() ne suffit pas : il se peut que des requêtes doivent être effectuées sans correspondre proprement à des modèles ou que vous vouliez exécuter directement des requêtes UPDATE, INSERT ou DELETE.
Dans ces situations, vous pouvez toujours accéder directement à la base de données, outrepassant complètement la couche des modèles.
\nL’objet django.db.connection représente la connexion à la base de données par défaut. Pour utiliser la connexion à la base de données, appelez connection.cursor() pour obtenir un objet curseur. Puis, appelez cursor.execute(sql, [params]) pour exécuter le code SQL et cursor.fetchone() ou cursor.fetchall() pour obtenir les lignes de résultat.
Par exemple :
\nfrom django.db import connection\n\n\ndef my_custom_sql(self):\n with connection.cursor() as cursor:\n cursor.execute("UPDATE bar SET foo = 1 WHERE baz = %s", [self.baz])\n cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz])\n row = cursor.fetchone()\n\n return row\nPour se protéger des injections SQL, vous devez vous abstenir de placer des guillemets autour des substituants %s dans la chaîne SQL.
Notez que si vous voulez inclure des signes « pour cent » littéraux dans la requête, vous devez les doubler dans le cas où vous transmettez des paramètres :
\ncursor.execute("SELECT foo FROM bar WHERE baz = '30%'")\ncursor.execute("SELECT foo FROM bar WHERE baz = '30%%' AND id = %s", [self.id])\nSi vous utilisez plus d’une base de données, vous pouvez utiliser django.db.connections pour obtenir la connexion (et le curseur) pour une base de données spécifique. django.db.connections est un objet de type dictionnaire permettant de récupérer une connexion spécifique en employant son alias :
from django.db import connections\n\nwith connections["my_db_alias"].cursor() as cursor:\n # Your code here\n ...\nPar défaut, l’API de base de données de Python renvoie les résultats sans les noms de champs, ce qui signifie que vous vous retrouvez avec une liste de valeurs plutôt qu’un dictionnaire. Pour un faible coût en performances et en mémoire, vous pouvez obtenir les résultats sous forme de dictionnaire en écrivant quelque chose comme :
\ndef dictfetchall(cursor):\n """\n Return all rows from a cursor as a dict.\n Assume the column names are unique.\n """\n columns = [col[0] for col in cursor.description]\n return [dict(zip(columns, row)) for row in cursor.fetchall()]\nUne autre option est d’utiliser une structure collections.namedtuple() de la bibliothèque Python standard. Un namedtuple est un objet de type tuple dont les champs sont accessibles sous forme d’attribut ; l’accès par indice est aussi possible et l’objet est itérable. Les résultats sont immuables et accessibles par nom de champ ou par indice, ce qui pourrait être pratique :
from collections import namedtuple\n\n\ndef namedtuplefetchall(cursor):\n """\n Return all rows from a cursor as a namedtuple.\n Assume the column names are unique.\n """\n desc = cursor.description\n nt_result = namedtuple("Result", [col[0] for col in desc])\n return [nt_result(*row) for row in cursor.fetchall()]\nLes exemples dictfetchall() et namedtuplefetchall() supposent que les noms de colonnes sont uniques, car un curseur ne peut pas distinguer les colonnes de tables différentes.
Voici un exemple de la différence entre les trois :
\n>>> cursor.execute("SELECT id, parent_id FROM test LIMIT 2")\n>>> cursor.fetchall()\n((54360982, None), (54360880, None))\n\n>>> cursor.execute("SELECT id, parent_id FROM test LIMIT 2")\n>>> dictfetchall(cursor)\n[{'parent_id': None, 'id': 54360982}, {'parent_id': None, 'id': 54360880}]\n\n>>> cursor.execute("SELECT id, parent_id FROM test LIMIT 2")\n>>> results = namedtuplefetchall(cursor)\n>>> results\n[Result(id=54360982, parent_id=None), Result(id=54360880, parent_id=None)]\n>>> results[0].id\n54360982\n>>> results[0][0]\n54360982\nconnection et cursor implémentent essentiellement l’API de base de données standard de Python décrite dans la PEP 249, à l’exception de ce qui concerne la gestion des transactions.
Si cette API DB de Python ne vous est pas familière, notez que l’instruction SQL dans cursor.execute() utilise des substituants, "%s", plutôt que d’ajouter directement les paramètres dans la chaîne SQL. Si vous utilisez cette technique, la bibliothèque sous-jacente de base de données s’occupe automatiquement d’échapper vos paramètres au besoin.
Notez également que Django compte sur des substituants "%s", pas de substituants "?" qui sont utilisés par la bibliothèque SQLite de Python, pour des raisons de cohérence et de bon sens.
L’utilisation d’un curseur en tant que gestionnaire de contexte :
\nwith connection.cursor() as c:\n c.execute(...)\nest équivalent à :
\nc = connection.cursor()\ntry:\n c.execute(...)\nfinally:\n c.close()\nAppelle une procédure stockée de base de données ayant le nom indiqué. Une liste (params) ou un dictionnaire (kparams) de paramètres d’entrée peuvent être fournis. La plupart des bases de données n’acceptent pas kparams. Parmi celles qui sont prises en charge nativement par Django, seule Oracle accepte kparams.
Par exemple, avec cette procédure stockée dans une base de données Oracle :
\nCREATE PROCEDURE "TEST_PROCEDURE"(v_i INTEGER, v_text NVARCHAR2(10)) AS\n p_i INTEGER;\n p_text NVARCHAR2(10);\nBEGIN\n p_i := v_i;\n p_text := v_text;\n ...\nEND;\nCeci l’appellera
\nwith connection.cursor() as cursor:\n cursor.callproc("test_procedure", [1, "test"])\n