Ticket #9919: raw-sql-docs-r9690.patch

File raw-sql-docs-r9690.patch, 4.2 KB (added by Leo, 6 years ago)
  • docs/ref/models/querysets.txt

     
    566566Both the ``depth`` argument and the ability to specify field names in the call
    567567to ``select_related()`` are new in Django version 1.0.
    568568
     569.. _querysets-extra-modifier:
     570
    569571``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)``
    570572~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    571573
  • docs/topics/db/sql.txt

     
    33Performing raw SQL queries
    44==========================
    55
    6 Feel free to write custom SQL statements in custom model methods and
    7 module-level methods. The object ``django.db.connection`` represents the
    8 current database connection. To use it, call ``connection.cursor()`` to get a
    9 cursor object. Then, call ``cursor.execute(sql, [params])`` to execute the SQL
    10 and ``cursor.fetchone()`` or ``cursor.fetchall()`` to return the resulting
    11 rows. Example::
     6Django supports custom SQL statements in custom model methods and
     7module-level methods.
    128
     9.. note::
     10
     11    If all you want to do is a custom ``WHERE`` clause, the Query API supports
     12    the ``where``, ``tables`` and ``params`` arguments using the
     13    :ref:`extra modifier <querysets-extra-modifier>`.
     14
     15The object ``django.db.connection`` represents the current database
     16connection. To use it, call ``connection.cursor()`` to get a cursor object.
     17Then, call ``cursor.execute(sql, [params])`` to execute the SQL and
     18``cursor.fetchone()`` or ``cursor.fetchall()`` to return the resulting rows.
     19The ``connection`` and ``cursor`` objects mostly implement the standard
     20`Python DB-API`_. For example::
     21
    1322    def my_custom_sql(self):
    1423        from django.db import connection
    1524        cursor = connection.cursor()
     
    1726        row = cursor.fetchone()
    1827        return row
    1928
    20 ``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_
    21 (except when it comes to :ref:`transaction handling <topics-db-transactions>`).
    22 If you're not familiar with the Python DB-API, note that the SQL statement in
    23 ``cursor.execute()`` uses placeholders, ``"%s"``, rather than adding parameters
    24 directly within the SQL. If you use this technique, the underlying database
    25 library will automatically add quotes and escaping to your parameter(s) as
    26 necessary. (Also note that Django expects the ``"%s"`` placeholder, *not* the
    27 ``"?"`` placeholder, which is used by the SQLite Python bindings. This is for
    28 the sake of consistency and sanity.)
     29When using cursor ``cursor.execute()`` you should use placeholders rather
     30than putting the parameters directly within the SQL. Doing this will let the
     31underlying database library automatically add quotes and escape to your
     32parameters as necessary. For the sake of consistency and sanity, Django
     33expects the ``"%s"`` placeholder, *not* the ``"?"`` placeholder, which is used
     34by the SQLite Python bindings.
    2935
    30 A final note: If all you want to do is a custom ``WHERE`` clause, you can just
    31 use the ``where``, ``tables`` and ``params`` arguments to the standard lookup
    32 API.
     36A major difference from the Python DB-API is the transaction handling.
     37Automatic transaction management (which is enabled by default) will not work
     38for raw SQL queries that modify the database since Django has no way of
     39detecting the changes. You will need to commit the transaction yourself.
     40A simple way to do this is to use Django's ``transaction.commit_manually``
     41decorator::
    3342
    34 .. _Python DB-API: http://www.python.org/peps/pep-0249.html
     43    @transaction.commit_manually
     44    def my_custom_modifying_sql(self):
     45        from django.db import connection
     46        cursor = connection.cursor()
     47        cursor.execute('UPDATE foo SET bar = bar + 1')
     48        transaction.commit()
    3549
     50For more details, see :ref:`transaction handling <topics-db-transactions>`.
     51
     52.. _Python DB-API: http://www.python.org/peps/pep-0249.html
     53 No newline at end of file
Back to Top