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

File raw-sql-docs-r9690.patch, 4.2 KB (added by Leo, 5 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. 
     569.. _querysets-extra-modifier: 
    569571``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)`` 
  • docs/topics/db/sql.txt

    33Performing raw SQL queries 
    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. 
     9.. note:: 
     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>`. 
     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:: 
    1322    def my_custom_sql(self): 
    1423        from django.db import connection 
    1524        cursor = connection.cursor() 
    1726        row = cursor.fetchone() 
    1827        return row 
    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. 
    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`` 
    34 .. _Python DB-API: 
     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() 
     50For more details, see :ref:`transaction handling <topics-db-transactions>`. 
     52.. _Python DB-API: 
     53 No newline at end of file