Django gives you three ways of performing raw SQL queries: you can embed raw\nSQL fragments into ORM queries using\nRawSQL (see Raw SQL fragments),\nuse Manager.raw() to perform raw queries and return model instances,\nor avoid the model layer entirely and execute custom SQL directly.
In some cases, you may need to embed raw SQL fragments directly into ORM\nqueries — for example, in annotate() or\nfilter() calls. Use Func()\nexpressions for calling database functions across\nbackends, or\nRawSQL for arbitrary parameterized SQL\nfragments.
The raw() manager method can be used to perform raw SQL queries that\nreturn model instances:
This method takes a raw SQL query, executes it, and returns a\ndjango.db.models.query.RawQuerySet instance. This RawQuerySet instance\ncan be iterated over like a normal QuerySet to\nprovide object instances.
This is best illustrated with an example. Suppose you have the following\nmodel:
\nclass Person(models.Model):\n first_name = models.CharField(...)\n last_name = models.CharField(...)\n birth_date = models.DateField(...)\nYou could then execute custom SQL like so:
\n>>> for p in Person.objects.raw("SELECT * FROM myapp_person"):\n... print(p)\n...\nJohn Smith\nJane Jones\nThis example isn’t very exciting – it’s exactly the same as running\nPerson.objects.all(). However, raw() has a bunch of other options that\nmake it very powerful.
raw() automatically maps fields in the query to fields on the model.
The order of fields in your query doesn’t matter. In other words, both\nof the following queries work identically:
\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")\nMatching is done by name. This means that you can use SQL’s AS clauses to\nmap fields in the query to model fields. So if you had some other table that\nhad Person data in it, you could easily map it into Person instances:
>>> 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...\nAs long as the names match, the model instances will be created correctly.
\nAlternatively, you can map fields in the query to model fields using the\ntranslations argument to raw(). This is a dictionary mapping names of\nfields in the query to names of fields on the model. For example, the above\nquery could also be written:
>>> 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() supports indexing, so if you need only the first result you can\nwrite:
>>> first_person = Person.objects.raw("SELECT * FROM myapp_person")[0]\nHowever, the indexing and slicing are not performed at the database level. If\nyou have a large number of Person objects in your database, it is more\nefficient to limit the query at the SQL level:
>>> first_person = Person.objects.raw("SELECT * FROM myapp_person LIMIT 1")[0]\nFields may also be left out:
\n>>> people = Person.objects.raw("SELECT id, first_name FROM myapp_person")\nThe Person objects returned by this query will be deferred model instances\n(see defer()). This means that the\nfields that are omitted from the query will be loaded on demand. For example:
>>> 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\nFrom outward appearances, this looks like the query has retrieved both\nthe first name and last name. However, this example actually issued 3\nqueries. Only the first names were retrieved by the raw() query – the\nlast names were both retrieved on demand when they were printed.
There is only one field that you can’t leave out - the primary key\nfield. Django uses the primary key to identify model instances, so it\nmust always be included in a raw query. A\nFieldDoesNotExist exception will be raised if\nyou forget to include the primary key.
raw()Link to this heading#If you need to perform parameterized queries, you can use the params\nargument to raw():
>>> lname = "Doe"\n>>> Person.objects.raw("SELECT * FROM myapp_person WHERE last_name = %s", [lname])\nparams is a list or dictionary of parameters. You’ll use %s\nplaceholders in the query string for a list, or %(key)s\nplaceholders for a dictionary (where key is replaced by a\ndictionary key), regardless of your database engine. Such placeholders will be\nreplaced with parameters from the params argument.
Sometimes even Manager.raw() isn’t quite enough: you might need to\nperform queries that don’t map cleanly to models, or directly execute\nUPDATE, INSERT, or DELETE queries.
In these cases, you can always access the database directly, routing around\nthe model layer entirely.
\nThe object django.db.connection represents the default database\nconnection. To use the database connection, call connection.cursor() to\nget a cursor object. Then, call cursor.execute(sql, [params]) to execute\nthe SQL and cursor.fetchone() or cursor.fetchall() to return the\nresulting rows.
Na przykład:
\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\nTo protect against SQL injection, you must not include quotes around the %s\nplaceholders in the SQL string.
Note that if you want to include literal percent signs in the query, you have\nto double them in the case you are passing parameters:
\ncursor.execute("SELECT foo FROM bar WHERE baz = '30%'")\ncursor.execute("SELECT foo FROM bar WHERE baz = '30%%' AND id = %s", [self.id])\nIf you are using more than one database, you can\nuse django.db.connections to obtain the connection (and cursor) for a\nspecific database. django.db.connections is a dictionary-like\nobject that allows you to retrieve a specific connection using its\nalias:
from django.db import connections\n\nwith connections["my_db_alias"].cursor() as cursor:\n # Your code here\n ...\nBy default, the Python DB API will return results without their field names,\nwhich means you end up with a list of values, rather than a dict. At a\nsmall performance and memory cost, you can return results as a dict by\nusing something like this:
def 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()]\nAnother option is to use collections.namedtuple() from the Python\nstandard library. A namedtuple is a tuple-like object that has fields\naccessible by attribute lookup; it’s also indexable and iterable. Results are\nimmutable and accessible by field names or indices, which might be useful:
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()]\nThe dictfetchall() and namedtuplefetchall() examples assume unique\ncolumn names, since a cursor cannot distinguish columns from different tables.
Here is an example of the difference between the three:
\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 and cursor mostly implement the standard Python DB-API\ndescribed in PEP 249 — except when it comes to transaction handling.
If you’re not familiar with the Python DB-API, note that the SQL statement in\ncursor.execute() uses placeholders, "%s", rather than adding\nparameters directly within the SQL. If you use this technique, the underlying\ndatabase library will automatically escape your parameters as necessary.
Also note that Django expects the "%s" placeholder, not the "?"\nplaceholder, which is used by the SQLite Python bindings. This is for the sake\nof consistency and sanity.
Using a cursor as a context manager:
\nwith connection.cursor() as c:\n c.execute(...)\nis equivalent to:
\nc = connection.cursor()\ntry:\n c.execute(...)\nfinally:\n c.close()\nCalls a database stored procedure with the given name. A sequence\n(params) or dictionary (kparams) of input parameters may be\nprovided. Most databases don’t support kparams. Of Django’s built-in\nbackends, only Oracle supports it.
For example, given this stored procedure in an Oracle database:
\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;\nThis will call it:
\nwith connection.cursor() as cursor:\n cursor.callproc("test_procedure", [1, "test"])\n