mirror of
https://github.com/django/django.git
synced 2024-12-23 17:46:27 +00:00
87d3ff731b
git-svn-id: http://code.djangoproject.com/svn/django/trunk@10655 bcc190cf-cafb-0310-a4f2-bffc1f526a37
48 lines
2.1 KiB
Plaintext
48 lines
2.1 KiB
Plaintext
.. _topics-db-sql:
|
|
|
|
Performing raw SQL queries
|
|
==========================
|
|
|
|
Feel free to write custom SQL statements in custom model methods and
|
|
module-level methods. The object ``django.db.connection`` represents the
|
|
current database connection, and ``django.db.transaction`` represents the
|
|
current database transaction. To use the database connection, call
|
|
``connection.cursor()`` to get a cursor object. Then, call
|
|
``cursor.execute(sql, [params])`` to execute the SQL and ``cursor.fetchone()``
|
|
or ``cursor.fetchall()`` to return the resulting rows. After performing a data
|
|
changing operation, you should then call
|
|
``transaction.commit_unless_managed()`` to ensure your changes are committed
|
|
to the database. If your query is purely a data retrieval operation, no commit
|
|
is required. For example::
|
|
|
|
def my_custom_sql(self):
|
|
from django.db import connection, transaction
|
|
cursor = connection.cursor()
|
|
|
|
# Data modifying operation - commit required
|
|
cursor.execute("UPDATE bar SET foo = 1 WHERE baz = %s", [self.baz])
|
|
transaction.commit_unless_managed()
|
|
|
|
# Data retrieval operation - no commit required
|
|
cursor.execute("SELECT foo FROM bar WHERE baz = %s", [self.baz])
|
|
row = cursor.fetchone()
|
|
|
|
return row
|
|
|
|
``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_
|
|
(except when it comes to :ref:`transaction handling <topics-db-transactions>`).
|
|
If you're not familiar with the Python DB-API, note that the SQL statement in
|
|
``cursor.execute()`` uses placeholders, ``"%s"``, rather than adding parameters
|
|
directly within the SQL. If you use this technique, the underlying database
|
|
library will automatically add quotes and escaping to your parameter(s) as
|
|
necessary. (Also note that Django expects the ``"%s"`` placeholder, *not* the
|
|
``"?"`` placeholder, which is used by the SQLite Python bindings. This is for
|
|
the sake of consistency and sanity.)
|
|
|
|
A final note: If all you want to do is a custom ``WHERE`` clause, you can just
|
|
use the ``where``, ``tables`` and ``params`` arguments to the standard lookup
|
|
API.
|
|
|
|
.. _Python DB-API: http://www.python.org/peps/pep-0249.html
|
|
|