public inbox for [email protected]help / color / mirror / Atom feed
Missing example for SAVEPOINT using the same savepoint name 3+ messages / 3 participants [nested] [flat]
* Missing example for SAVEPOINT using the same savepoint name @ 2022-04-11 16:00 PG Doc comments form <[email protected]> 2022-04-12 14:41 ` Re: Missing example for SAVEPOINT using the same savepoint name David G. Johnston <[email protected]> 0 siblings, 1 reply; 3+ messages in thread From: PG Doc comments form @ 2022-04-11 16:00 UTC (permalink / raw) To: [email protected]; +Cc: [email protected] The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/14/sql-savepoint.html Description: The "Compatibility" section deserves some code example to illustrate the behavior when reusing the same savepoint name. Maybe this could help: CREATE TABLE tab1 ( pk INT, name VARCHAR(50) ); BEGIN; INSERT INTO tab1 VALUES (101,'aaa'); SAVEPOINT mysp; /* mysp #1 */ UPDATE tab1 SET name = 'bbb' WHERE pk = 101; SAVEPOINT mysp; /* mysp #2 */ UPDATE tab1 SET name = 'ccc' WHERE pk = 101; ROLLBACK TO SAVEPOINT mysp; /* rolls back to mysp #2 */ SELECT * FROM tab1 ORDER BY pk; RELEASE SAVEPOINT mysp; /* releases mysp #2 */ ROLLBACK TO SAVEPOINT mysp; /* rolls back to mysp #1 */ SELECT * FROM tab1 ORDER BY pk; COMMIT; DROP TABLE tab1; First SELECT will show 101/bbb, second will show 101/aaa .... ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Missing example for SAVEPOINT using the same savepoint name 2022-04-11 16:00 Missing example for SAVEPOINT using the same savepoint name PG Doc comments form <[email protected]> @ 2022-04-12 14:41 ` David G. Johnston <[email protected]> 2022-04-12 14:48 ` Re: Missing example for SAVEPOINT using the same savepoint name Sebastien Flaesch <[email protected]> 0 siblings, 1 reply; 3+ messages in thread From: David G. Johnston @ 2022-04-12 14:41 UTC (permalink / raw) To: Sebastien Flaesch <[email protected]>; Pg Docs <[email protected]> On Mon, Apr 11, 2022 at 9:43 AM PG Doc comments form <[email protected]> wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/14/sql-savepoint.html > Description: > > The "Compatibility" section deserves some code example to illustrate the > behavior when reusing the same savepoint name. > > I agree with the premise but not the implementation. I've attached (and inlined) a patch that implements the example change, updates savepoint to introduce the behavior prior to the example, and updates the rollback to savepoint to note the behavior as well. commit e921441f22bad972393144628c7ee48845d5384c Author: David G. Johnston <[email protected]> Date: Tue Apr 12 14:30:11 2022 +0000 doc: Improve docs regarding savepoint name reuse 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. diff --git a/doc/src/sgml/ref/rollback_to.sgml b/doc/src/sgml/ref/rollback_to.sgml index 3d5a241e1a..7bd1b41feb 100644 --- a/doc/src/sgml/ref/rollback_to.sgml +++ b/doc/src/sgml/ref/rollback_to.sgml @@ -89,6 +89,12 @@ ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <replaceable>savepoint_name</re cannot-execute state, so while the transaction can be restored using <command>ROLLBACK TO SAVEPOINT</command>, the cursor can no longer be used. </para> + + <para> + If multiple savepoints have the same name, only the one that was most + recently defined is released. + </para> + </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/savepoint.sgml b/doc/src/sgml/ref/savepoint.sgml index b17342a1ee..fd017935ea 100644 --- a/doc/src/sgml/ref/savepoint.sgml +++ b/doc/src/sgml/ref/savepoint.sgml @@ -53,7 +53,9 @@ SAVEPOINT <replaceable>savepoint_name</replaceable> <term><replaceable>savepoint_name</replaceable></term> <listitem> <para> - The name to give to the new savepoint. + 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. </para> </listitem> </varlistentry> @@ -106,6 +108,25 @@ COMMIT; </programlisting> The above transaction will insert both 3 and 4. </para> + + <para> + To use a single savepoint name: +<programlisting> +BEGIN; + INSERT INTO table1 VALUES (1); + SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (2); + SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (3); + ROLLBACK TO SAVEPOINT my_savepoint; + SELECT * FROM table1; // 1, 2 + ROLLBACK TO SAVEPOINT my_savepoint; + SELECT * FROM table1; // just 1 +COMMIT; +</programlisting> + The above transaction shows row 3 being rolled back first then row 2. + </para> + </refsect1> <refsect1> Attachments: [application/octet-stream] v0001-doc-savepoint-name-reuse.patch (2.9K, 3-v0001-doc-savepoint-name-reuse.patch) download | inline diff: commit e921441f22bad972393144628c7ee48845d5384c Author: David G. Johnston <[email protected]> Date: Tue Apr 12 14:30:11 2022 +0000 doc: Improve docs regarding savepoint name reuse 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. diff --git a/doc/src/sgml/ref/rollback_to.sgml b/doc/src/sgml/ref/rollback_to.sgml index 3d5a241e1a..7bd1b41feb 100644 --- a/doc/src/sgml/ref/rollback_to.sgml +++ b/doc/src/sgml/ref/rollback_to.sgml @@ -89,6 +89,12 @@ ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <replaceable>savepoint_name</re cannot-execute state, so while the transaction can be restored using <command>ROLLBACK TO SAVEPOINT</command>, the cursor can no longer be used. </para> + + <para> + If multiple savepoints have the same name, only the one that was most + recently defined is released. + </para> + </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/savepoint.sgml b/doc/src/sgml/ref/savepoint.sgml index b17342a1ee..fd017935ea 100644 --- a/doc/src/sgml/ref/savepoint.sgml +++ b/doc/src/sgml/ref/savepoint.sgml @@ -53,7 +53,9 @@ SAVEPOINT <replaceable>savepoint_name</replaceable> <term><replaceable>savepoint_name</replaceable></term> <listitem> <para> - The name to give to the new savepoint. + 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. </para> </listitem> </varlistentry> @@ -106,6 +108,25 @@ COMMIT; </programlisting> The above transaction will insert both 3 and 4. </para> + + <para> + To use a single savepoint name: +<programlisting> +BEGIN; + INSERT INTO table1 VALUES (1); + SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (2); + SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (3); + ROLLBACK TO SAVEPOINT my_savepoint; + SELECT * FROM table1; // 1, 2 + ROLLBACK TO SAVEPOINT my_savepoint; + SELECT * FROM table1; // just 1 +COMMIT; +</programlisting> + The above transaction shows row 3 being rolled back first then row 2. + </para> + </refsect1> <refsect1> ^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Missing example for SAVEPOINT using the same savepoint name 2022-04-11 16:00 Missing example for SAVEPOINT using the same savepoint name PG Doc comments form <[email protected]> 2022-04-12 14:41 ` Re: Missing example for SAVEPOINT using the same savepoint name David G. Johnston <[email protected]> @ 2022-04-12 14:48 ` Sebastien Flaesch <[email protected]> 0 siblings, 0 replies; 3+ messages in thread From: Sebastien Flaesch @ 2022-04-12 14:48 UTC (permalink / raw) To: David G. Johnston <[email protected]>; Pg Docs <[email protected]> Hello! The new sample code looks clearer I agree! Seb ________________________________ From: David G. Johnston <[email protected]> Sent: Tuesday, April 12, 2022 4:41 PM To: Sebastien Flaesch <[email protected]>; Pg Docs <[email protected]> Subject: Re: Missing example for SAVEPOINT using the same savepoint name EXTERNAL: Do not click links or open attachments if you do not recognize the sender. On Mon, Apr 11, 2022 at 9:43 AM PG Doc comments form <[email protected]<mailto:[email protected]>> wrote: The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/14/sql-savepoint.html<https://urldefense.com/v3/__https://www.pos...; Description: The "Compatibility" section deserves some code example to illustrate the behavior when reusing the same savepoint name. I agree with the premise but not the implementation. I've attached (and inlined) a patch that implements the example change, updates savepoint to introduce the behavior prior to the example, and updates the rollback to savepoint to note the behavior as well. commit e921441f22bad972393144628c7ee48845d5384c Author: David G. Johnston <[email protected]<mailto:[email protected]>> Date: Tue Apr 12 14:30:11 2022 +0000 doc: Improve docs regarding savepoint name reuse 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. diff --git a/doc/src/sgml/ref/rollback_to.sgml b/doc/src/sgml/ref/rollback_to.sgml index 3d5a241e1a..7bd1b41feb 100644 --- a/doc/src/sgml/ref/rollback_to.sgml +++ b/doc/src/sgml/ref/rollback_to.sgml @@ -89,6 +89,12 @@ ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <replaceable>savepoint_name</re cannot-execute state, so while the transaction can be restored using <command>ROLLBACK TO SAVEPOINT</command>, the cursor can no longer be used. </para> + + <para> + If multiple savepoints have the same name, only the one that was most + recently defined is released. + </para> + </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/savepoint.sgml b/doc/src/sgml/ref/savepoint.sgml index b17342a1ee..fd017935ea 100644 --- a/doc/src/sgml/ref/savepoint.sgml +++ b/doc/src/sgml/ref/savepoint.sgml @@ -53,7 +53,9 @@ SAVEPOINT <replaceable>savepoint_name</replaceable> <term><replaceable>savepoint_name</replaceable></term> <listitem> <para> - The name to give to the new savepoint. + 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. </para> </listitem> </varlistentry> @@ -106,6 +108,25 @@ COMMIT; </programlisting> The above transaction will insert both 3 and 4. </para> + + <para> + To use a single savepoint name: +<programlisting> +BEGIN; + INSERT INTO table1 VALUES (1); + SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (2); + SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (3); + ROLLBACK TO SAVEPOINT my_savepoint; + SELECT * FROM table1; // 1, 2 + ROLLBACK TO SAVEPOINT my_savepoint; + SELECT * FROM table1; // just 1 +COMMIT; +</programlisting> + The above transaction shows row 3 being rolled back first then row 2. + </para> + </refsect1> <refsect1> ^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2022-04-12 14:48 UTC | newest] Thread overview: 3+ messages (download: mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2022-04-11 16:00 Missing example for SAVEPOINT using the same savepoint name PG Doc comments form <[email protected]> 2022-04-12 14:41 ` David G. Johnston <[email protected]> 2022-04-12 14:48 ` Sebastien Flaesch <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox