Address Transactions in documentation more thoroughly

[Jasconius]

I don't know if this is right and proper for a ticket, but today I stumbled across an issue where in my local instance of Django and I was programming for and testing a scenario where a view/form may have to address an IntegrityError concerned with Unique entities in a database, and respond to such an exception.

In local on SQLLite this is pretty easy to do.

When I deployed to production though, and Postgres, it didn't work due to the complexities of Postgres transactions that I didn't realize had such implications (in that I was aware of transactions but I figured they were for advanced users only).

The exact error I got was

Caught DatabaseError while rendering: current transaction is aborted, commands ignored until end of transaction block

Which is actually pretty hard to google on. I narrowly stumbled into the transactions documentation after several search attempts and phrasings.

I know that this is mostly due to my inexperience with Django and Postgres in particular

I guess my point is

If an issue is hard (or impossible) to search for quickly, that might be a good opportunity for Documentation improvement. It might be useful to add in footnotes or mentions of the implications of transactions in areas of the documentation that might deal with such things. A good example might be adding a note about transactions in the documentation for unique and unique_together. Those seem like fairly common things that most people would want to use, they do talk about IntegrityErrors, but not really about what that actually means for how you write a View.

If you guys agree I'd be happy to write the patch (although I've never contributed, I would like to start, documentation seems like a decent place to start, since I am relatively new to Django).

Thanks

[Russell Keith-Magee]

​This section describes the exact error message you have seen, and that document is linked from the documentation homepage under the title "Transactions". A Google search for "Django Postgres transaction" returns that page as the top result.

Documentation can *always* be improved. However, tickets that don't provide a clear course of action end up going stale in the ticket tracker. Given that (to my eyes), the documentation already addresses the problem you have described, it's not clear exactly what needs to be improved.

For that reason, I'm procedurally closing this ticket as a wontfix. However, if you feel that there is room for improvement, feel free to reopen this ticket and provide with a patch describing the specific change you would like to see.