Ticket #19442: 19442.diff

docs/topics/db/sql.txt

@@ -210 +210 @@
 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::
+to the database  (required only if you are using the default transaction
+management, :func:`~django.db.transaction.autocommit`, since Django doesn't
+know whether the raw SQL is a read or write). If your query is purely a data
+retrieval operation, no commit is required. For example::
 
     def my_custom_sql():
         from django.db import connection, transaction

docs/topics/db/transactions.txt

@@ -196 +196 @@
 Requirements for transaction handling
 =====================================
 
-Django requires that every transaction that is opened is closed before
-the completion of a request. If you are using :func:`autocommit` (the
-default commit mode) or :func:`commit_on_success`, this will be done
-for you automatically (with the exception of :ref:`executing custom SQL
-<executing-custom-sql>`). However, if you are manually managing
-transactions (using the :func:`commit_manually` decorator), you must
-ensure that the transaction is either committed or rolled back before
-a request is completed.
+Django requires that every transaction that is opened be closed before
+the completion of a request.
+
+If you are using :func:`autocommit` (the default commit mode) or
+:func:`commit_on_success`, this will be done for you automatically in most
+cases. The exception is if you are :ref:`executing custom SQL
+<executing-custom-sql>` and using :func:`autocommit`, in which case you'll need
+to explicitly commit any data changing queries.
+
+If you are manually managing transactions (using the :func:`commit_manually`
+decorator), you must ensure that the transaction is either committed or rolled
+back before a request is completed.
 
 This applies to all database operations, not just write operations. Even
 if your transaction only reads from the database, the transaction must