De-emphasize SAVEPOINT retries

[bdarnell]

Re: Transactions

Issue Description

The SAVEPOINT-based retry protocol is best considered an advanced optimization. It was more important in CRDB 1.x, but these days most apps are fine without it as long as they have a simple retry loop.

Implementing savepoint retries correctly is fairly subtle and most application writers shouldn't try; it should be left to framework developers, and users of frameworks that don't support this should be fine without it.

Suggested Resolution

At a minimum, remove "strongly recommended" from the savepoint option in "client-side intervention". Move the "client-side transaction retries" separate to a separate "advanced client-side retries" page and in this document only talk about basic non-savepoint retries.

[awoods187]

@jseldess I think this should be a p-0 since its one of the most confusing aspects of this problem to implement. If users only need a retry loop, without any fancy adaptation, it could unblock many use cases. It doesn't solve those customers who are unwilling to add retry loops, but it does lower the burden of doing so, which may be enough.

[jseldess]

Interesting! Does this mean that we should re-factor all of our "build an app" code samples to NOT emphasize SAVEPOINT? That's probably one of the most visible representations of our historical guidance.

[awoods187]

I think so--but will let @bdarnell weigh in

[bdarnell]

Yeah, we should remove those from the "build an app" samples. Maybe keep them around as examples on the "advanced retries" page, but not on the main docs. The idea is that if you're using SQLAlchemy, for example, you can take advantage of the built-in savepoint retries, but if your framework doesn't do it for you you shouldn't worry about it.

[jseldess]

OK, I'd say this needs to be considered a larger "docs project" then. @awoods187, we'll need to review and reprioritize this with Rich. My understanding is, once he's back in office, he'll finish up #4621. Prior to this discussion, the next project was either Hibernate retries or #4693. We can't do all of it this quarter, let alone for 19.2.