Ticket #13870: 13870.diff

docs/topics/db/transactions.txt

@@ -377 +377 @@
     there is no database transaction at all. The ``autocommit`` decorator
     still uses transactions, automatically committing each transaction when
     a database modifying operation occurs.
+
+Transaction management outside the web server
+=============================================
+
+Django's typical transaction and connection management does not work outside
+the web server context.
+
+You may, for example, setup Django to run some recurring tasks in their own
+threads and notice that they leave behind unfinished database connection
+processes (in PostgreSQL this manifests as the connections being listed as
+"Idle In Transaction").
+
+Looking through the Postgres logs, you may find that the transactions aren't
+being completed (no ``ROLLBACK``). Switching to manual transaction management
+and doing the rollback manually will work, but this still leaves the processes
+as "Idle". Finally, calling ``django.db.connection.close()`` will end these
+"Idle" processes. What's going on here and how can we fix it?
+
+Transactions
+------------
+
+Django's default :ref:`autocommit behavior<topics-db-transactions-autocommit>`
+holds true for threaded functions. However, as noted above:
+
+    As soon as you perform an action that needs to write to the database,
+    Django produces the ``INSERT/UPDATE/DELETE`` statements and then does the
+    ``COMMIT``. There’s no implicit ``ROLLBACK``.
+
+That last sentence is very literal. Django DOES NOT issue a ``ROLLBACK``
+command unless something in Django has set the dirty flag. If your functions
+are only performing ``SELECT`` statements, it won't set the dirty flag to
+trigger a ``COMMIT``.
+
+This goes against the fact that PostgreSQL thinks the transaction requires a
+``ROLLBACK`` because Django issued a ``SET`` command for the timezone.
+
+Connections
+-----------
+
+Connection management is where things get tricky. Django uses
+:data:`~django.core.signals.request_finished` to close the database connection
+it normally uses. Since nothing normally happens in Django that doesn't involve
+a request, you take this behavior for granted.
+
+In this case, though, there isn't a request because the thread is outside the
+web server process. No request means no signal. No signal means the database
+connection won't be closed.
+
+Going back to transactions, it turns out that simply issuing a call to
+``django.db.connection.close()`` in the absence of any changes to the
+transaction management also issues the meeded ``ROLLBACK`` statement.
+
+Solution
+--------
+
+The solution is to allow Django's transaction management to proceed as usual
+and to simply close the connection one of three ways:
+
+1. Write a decorator that closes the connection and wrap the necessary
+   functions in it.
+2. Hook into the existing :mod:`request signals<django.core.signals>` to
+   have Django close the connection.
+3. Close the connection manually (``django.db.connection.close()``) at the end
+   of the function.