When the model query APIs don’t go far enough, you\ncan fall back to writing raw SQL. Django gives you two ways of performing raw\nSQL queries: you can use Manager.raw() to perform raw queries and\nreturn model instances, or you can avoid the model layer entirely and\nexecute custom SQL directly.
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 just like a normal\nQuerySet to provide object instances.
This is best illustrated with an example. Suppose you have the following model:
\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)\nJohn Smith\nJane Jones\nOf course, this example isn’t very exciting – it’s exactly the same as\nrunning Person.objects.all(). However, raw() has a bunch of other\noptions that make 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...\n>>> Person.objects.raw('SELECT last_name, birth_date, first_name, id FROM myapp_person')\n...\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('''SELECT first AS first_name,\n... last AS last_name,\n... bd AS birth_date,\n... pk AS id,\n... FROM some_other_table''')\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(p.first_name, # This will be retrieved by the original query\n... p.last_name) # This will be retrieved on demand\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.
\nThere 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. An InvalidQuery exception\nwill be raised if you forget to include the primary key.
You can also execute queries containing fields that aren’t defined on the\nmodel. For example, we could use PostgreSQL’s age() function to get a list\nof people with their ages calculated by the database:
\n>>> people = Person.objects.raw('SELECT *, age(birth_date) AS age FROM myapp_person')\n>>> for p in people:\n... print("%s is %s." % (p.first_name, p.age))\nJohn is 37.\nJane is 42.\n...\nraw()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, of course), regardless of your database engine. Such\nplaceholders will be replaced with parameters from the params\nargument.
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.
For example:
\nfrom django.db import connection\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\nNote that if you want to include literal percent signs in the query, you have to\ndouble 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\ncursor = connections['my_db_alias'].cursor()\n# Your code here...\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 "Return all rows from a cursor as a dict"\n columns = [col[0] for col in cursor.description]\n return [\n dict(zip(columns, row))\n for row in cursor.fetchall()\n ]\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\ndef namedtuplefetchall(cursor):\n "Return all rows from a cursor as a namedtuple"\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()]\nHere 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 and optional sequence\nof input parameters.
\nFor 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