Extend documentation about transaction rollbacks to mention global state mutations such as caching

[Sebastian Wagner]

ATOMIC_REQUESTS=True essentially creates nested transactions. And nested transactions might not play well with custom caching.

A small example of how to use nested transactions and caching to get inconsistent data:

my_mem_cache_a = ...
my_mem_cache_b = ...

def set_a(x):
    with transaction.atomic():
        a = ...
        a.x = x
        a.save()
    my_mem_cache_a = x 

def set_a_b(x, y):
    with transaction.atomic():
        set_a(x)
        b = ...
        b.y = y
        raise Exception()
        # at this point, my_mem_cache_a is out of sync with the database. 
        b.save()
    my_mem_cache_b = x 

set_a_b(...)

(this example also works without transaction.atomic() )

Would be nice to add a warning to

​https://docs.djangoproject.com/en/2.2/topics/db/transactions/#tying-transactions-to-http-requests

that ATOMIC_REQUESTS=True might be harmful, if code

• uses caching
• proactively updates data in the cache
• makes the assumption that values are updated in the database after a transaction is finished.

[Simon Charette]

I'm not sure how related to ATOMIC_REQUEST this issue actually is, it seems like a common pitfall of mixing database transactions and caching and a good reason to rely on transaction.on_commit to defer cache alterations instead.

The atomic documentation already mentions that model state should be reverted (#28479) so maybe we could adjust this block to mention that all form of state, including global one such as caching, should be reverted and that using transaction.on_commit can be used to deal with global state alterations.

Tentatively accepting based on the premise you might be interested in submitting a patch yourself.

[Angelica Ferlin]

Link to PR: ​https://github.com/django/django/pull/16848

[Lufafa Joshua]

Link to PR: ​https://github.com/django/django/pull/17413

[Natalia <124304+nessita@…>]

In aa80b357:

Fixed #30601 -- Doc'd the need to manually revert all app state on transaction rollbacks.

[Natalia <124304+nessita@…>]

In c8ac50c:

[5.0.x] Fixed #30601 -- Doc'd the need to manually revert all app state on transaction rollbacks.

Backport of aa80b357fbef46e5b6faa08d63bcfd4fe21f3776 from main

[Natalia <124304+nessita@…>]

In 696fbc3:

[4.2.x] Fixed #30601 -- Doc'd the need to manually revert all app state on transaction rollbacks.

Backport of aa80b357fbef46e5b6faa08d63bcfd4fe21f3776 from main

[Natalia <124304+nessita@…>]

In 9b18af4f:

Refs #30601 -- Fixed typos in docs/topics/db/transactions.txt.

[Natalia <124304+nessita@…>]

In acd4595:

[5.0.x] Refs #30601 -- Fixed typos in docs/topics/db/transactions.txt.

Backport of 9b18af4f6f12b9d25157e0b5afc3dca198f6dd06 from main

[Natalia <124304+nessita@…>]

In 3fae5d9:

[4.2.x] Refs #30601 -- Fixed typos in docs/topics/db/transactions.txt.

Backport of 9b18af4f6f12b9d25157e0b5afc3dca198f6dd06 from main