Documenting when to retry on serialization failure

"Applications using this level must be prepared to retry transactions
due to serialization failures."
...
"When an application receives this error message, it should abort the
current transaction and retry the whole transaction from the
beginning."

I note that the specific error codes this applies to are not
documented, so lets discuss what the docs for that would look like.

I had a conversation with Kevin Grittner about retry some years back
and it seemed clear that the application should re-execute application
logic from the beginning, rather than just slavishly re-execute the
same SQL. But that is not documented either.

Is *automatic* retry possible? In all cases? None? Or maybe Some?

ISTM that we can't retry anything where a transaction has replied to a
user and then the user issued a subsequent SQL statement, since we
have no idea whether the subsequent SQL was influenced by the initial
reply.

But what about the case of a single statement transaction? Can we just
re-execute then? I guess if it didn't run anything other than
IMMUTABLE functions then it should be OK, assuming the inputs
themselves were immutable, which we've no way for the user to declare.
Could we allow a user-defined auto_retry parameter?

We don't mention that a transaction might just repeatedly fail either.

Anyway, know y'all would have some opinions on this. Happy to document
whatever we agree.

--
Simon Riggs http://www.EnterpriseDB.com/