← Back to branch summary

~ubuntu-branches/ubuntu/utopic/python-django/utopic

« back to all changes in this revision

Viewing changes to docs/topics/db/sql.txt

  • Committer: Package Import Robot
  • Author(s): Luke Faraone, Jakub Wilk, Luke Faraone
  • Date: 2013-05-09 15:10:47 UTC
  • mfrom: (1.1.21) (4.4.27 sid)
  • Revision ID: package-import@ubuntu.com-20130509151047-aqv8d71oj9wvcv8c
[ Jakub Wilk ]
* Use canonical URIs for Vcs-* fields.

[ Luke Faraone ]
* Upload to unstable.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/topics/db/sql.txt
18
18
Performing raw queries
19
19
======================
20
20
 
21
 
.. versionadded:: 1.2
22
 
 
23
21
The ``raw()`` manager method can be used to perform raw SQL queries that
24
22
return model instances:
25
23
 
26
24
.. method:: Manager.raw(raw_query, params=None, translations=None)
27
25
 
28
26
This method method takes a raw SQL query, executes it, and returns a
29
 
:class:`~django.db.models.query.RawQuerySet` instance. This
30
 
:class:`~django.db.models.query.RawQuerySet` instance can be iterated
31
 
over just like an normal QuerySet to provide object instances.
 
27
``django.db.models.query.RawQuerySet`` instance. This ``RawQuerySet`` instance
 
28
can be iterated over just like an normal QuerySet to provide object instances.
32
29
 
33
30
This is best illustrated with an example. Suppose you've got the following model::
34
31
 
40
37
You could then execute custom SQL like so::
41
38
 
42
39
    >>> for p in Person.objects.raw('SELECT * FROM myapp_person'):
43
 
    ...     print p
 
40
    ...     print(p)
44
41
    John Smith
45
42
    Jane Jones
46
43
 
128
125
fields that are omitted from the query will be loaded on demand. For example::
129
126
 
130
127
    >>> for p in Person.objects.raw('SELECT id, first_name FROM myapp_person'):
131
 
    ...     print p.first_name, # This will be retrieved by the original query
132
 
    ...     print p.last_name # This will be retrieved on demand
 
128
    ...     print(p.first_name, # This will be retrieved by the original query
 
129
    ...           p.last_name) # This will be retrieved on demand
133
130
    ...
134
131
    John Smith
135
132
    Jane Jones
153
150
 
154
151
    >>> people = Person.objects.raw('SELECT *, age(birth_date) AS age FROM myapp_person')
155
152
    >>> for p in people:
156
 
    ...     print "%s is %s." % (p.first_name, p.age)
 
153
    ...     print("%s is %s." % (p.first_name, p.age))
157
154
    John is 37.
158
155
    Jane is 42.
159
156
    ...
229
226
 
230
227
        return row
231
228
 
232
 
If you are using more than one database you can use
233
 
``django.db.connections`` to obtain the connection (and cursor) for a
 
229
If you are using :doc:`more than one database </topics/db/multi-db>`, you can
 
230
use ``django.db.connections`` to obtain the connection (and cursor) for a
234
231
specific database. ``django.db.connections`` is a dictionary-like
235
232
object that allows you to retrieve a specific connection using its
236
233
alias::
244
241
names, which means you end up with a ``list`` of values, rather than a
245
242
``dict``. At a small performance cost, you can return results as a
246
243
``dict`` by using something like this::
247
 
    
 
244
 
248
245
    def dictfetchall(cursor):
249
246
        "Returns all rows from a cursor as a dict"
250
247
        desc = cursor.description
258
255
    >>> cursor.execute("SELECT id, parent_id from test LIMIT 2");
259
256
    >>> cursor.fetchall()
260
257
    ((54360982L, None), (54360880L, None))
261
 
    
 
258
 
262
259
    >>> cursor.execute("SELECT id, parent_id from test LIMIT 2");
263
260
    >>> dictfetchall(cursor)
264
261
    [{'parent_id': None, 'id': 54360982L}, {'parent_id': None, 'id': 54360880L}]
275
272
notes on the requirements of Django's transaction handling
276
273
<topics-db-transactions-requirements>` for more details.
277
274
 
278
 
.. versionchanged:: 1.3
279
 
 
280
 
Prior to Django 1.3, it was necessary to manually mark a transaction
281
 
as dirty using ``transaction.set_dirty()`` when using raw SQL calls.
282
 
 
283
275
Connections and cursors
284
276
-----------------------
285
277