Re: doc: Clarify Savepoint Behavior

On Thu, 9 Jun 2022 at 16:41, David G. Johnston
<david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>
> On Thu, Jun 9, 2022 at 8:36 AM David G. Johnston <david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
>>
>> Hi,
>>
>> Reposting this on its own thread.
>>
>> https://www.postgresql.org/message-id/flat/CAKFQuwby1aMsJDMeibaBaohgoaZhivAo4WcqHC1%3D9-GDZ3TSng%40mail.gmail.com
>>
>> Presently, the open item seems to be whether my novelty regarding the reworked example is too much.
>>
>
> Commentary:
>
> Per documentation comment the savepoint command lacks an example
> where the savepoint name is reused. The suggested example didn't
> conform to the others on the page, nor did the suggested location
> in compatibility seem desirable, but the omission rang true. Add
> another example to the examples section demonstrating this case.
> Additionally, document under the description for savepoint_name
> that we allow for the name to be repeated - and note what that
> means in terms of release and rollback. It seems desirable to
> place this comment in description rather than notes for savepoint.
> For the other two commands the behavior in the presence of
> duplicate savepoint names best fits as notes. In fact release
> already had one. This commit copies the same verbiage over to
> rollback.

Good idea.

"The name to give to the new savepoint. The name may already exist,
+ in which case a rollback or release to the same name will use the
+ one that was most recently defined."

instead I propose:

"The name to give to the new savepoint. If the name duplicates a
previously defined savepoint name then only the latest savepoint with that name
can be referenced in a later ROLLBACK TO SAVEPOINT."

+ <para>
+ If multiple savepoints have the same name, only the one that was most
+ recently defined is released.
+ </para>

instead I propose

"Searches backwards through previously defined savepoints until the
a savepoint name matches the request. If the savepoint name duplicated earlier
defined savepoints then those earlier savepoints can only be released if
multiple ROLLBACK TO SAVEPOINT commands are issued with the same
name, as shown in the following example."

Also, I would just call the savepoint "s" in the example, to declutter it.

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