Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1neHiT-0000AF-0B for pgsql-docs@arkaria.postgresql.org; Tue, 12 Apr 2022 14:42:01 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1neHiR-00024c-TN for pgsql-docs@arkaria.postgresql.org; Tue, 12 Apr 2022 14:41:59 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1neHiR-00024S-Io for pgsql-docs@lists.postgresql.org; Tue, 12 Apr 2022 14:41:59 +0000 Received: from mail-ed1-x529.google.com ([2a00:1450:4864:20::529]) by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1neHiP-0005oC-3x for pgsql-docs@lists.postgresql.org; Tue, 12 Apr 2022 14:41:59 +0000 Received: by mail-ed1-x529.google.com with SMTP id c64so10474325edf.11 for ; Tue, 12 Apr 2022 07:41:56 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to; bh=JZ02384RkZMblICSEHtwB1epptN1S2h+h7PFdcbSqas=; b=VnC6H843g486UqkVwpIMjJOxDQ3FFgCOjDijI4eRNjlI7KVboaMQS73GzCMsE2vt+z mHRwFoNkch4dPKBAg0ALllC2XuplBBg/EWpFtttSFrS8Cdu/YeSCbsnYSyisgVPhKFNZ Wm/RCVatNj2ZPhh3/spcktLK+7pt6lkEJF+2v0JgYQ5E2z5oRZZjJCj9yZUFcmTGJfcF QBLtDaV9wVEySWAOTOR+7YotLT8pOI7AvqBe5vvxo/QbGN6hCCqnkyh1H0jw4nibmLfu bGn2awYBZZBBHZuancpIgIY6jEC7yiTU7aZ9UMHKrxo/zOygml/9k03hp2S/ixozYo52 72Ow== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to; bh=JZ02384RkZMblICSEHtwB1epptN1S2h+h7PFdcbSqas=; b=iDxP/ee1yyTiKuWcY34p3sTU/rhQUwx6qbqt1D4kHscjGLvbnteDxMTLVnA1GHEF87 hXHSwpaMdOCyIHnxGIvvrB3FPHylb9mwL+ynkO6i0v4/rL7t+eKHPd7k7nr66b3jfJGb 1bOnvmVMeO9sbqxizQ8BcVYHRR2UBMTeY1eLmhJz/bLAO5CFjCmU9BlQ5dosgEvFfJK9 BaWOJljU68nMfOtWU7SppGIiUc3rLQbX2nReDddoyuq3eaGbic0qer8+U4I7dqKpqtXv TeQSRNCITlVOORyJkO2Szmuv+xFMmTFKR1fWcm794+P5D0FYOIo3Y/8eQ/fBe96p3kWG gJzQ== X-Gm-Message-State: AOAM531LT13wvlIgAj8NlNPNGTbE1N0PvtdtWMijHV7+IeI00hAsHX45 d9sReZgXthaJVQDge5hPtGVgzC8sUeYRvAzWlF8= X-Google-Smtp-Source: ABdhPJwV/ivYOosIbzRGiZFolK2gp2iPNUjrs3gBs4+shwrnbjk0erwA/CULzDx+QtU3VnupWM0NbyMSD97F0POjiHw= X-Received: by 2002:a05:6402:1941:b0:413:2b5f:9074 with SMTP id f1-20020a056402194100b004132b5f9074mr38758223edz.414.1649774515664; Tue, 12 Apr 2022 07:41:55 -0700 (PDT) MIME-Version: 1.0 References: <164969280899.834802.7458840197227864320@wrigleys.postgresql.org> In-Reply-To: <164969280899.834802.7458840197227864320@wrigleys.postgresql.org> From: "David G. Johnston" Date: Tue, 12 Apr 2022 07:41:37 -0700 Message-ID: Subject: Re: Missing example for SAVEPOINT using the same savepoint name To: Sebastien Flaesch , Pg Docs Content-Type: multipart/mixed; boundary="000000000000f7625405dc760fde" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --000000000000f7625405dc760fde Content-Type: multipart/alternative; boundary="000000000000f7625305dc760fdc" --000000000000f7625305dc760fdc Content-Type: text/plain; charset="UTF-8" On Mon, Apr 11, 2022 at 9:43 AM PG Doc comments form 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 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 ] savepoint_nameROLLBACK TO SAVEPOINT, the cursor can no longer be used. + + + If multiple savepoints have the same name, only the one that was most + recently defined is released. + + 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 savepoint_name savepoint_name - 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. @@ -106,6 +108,25 @@ COMMIT; The above transaction will insert both 3 and 4. + + + To use a single savepoint name: + +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; + + The above transaction shows row 3 being rolled back first then row 2. + + --000000000000f7625305dc760fdc Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On Mon, Apr 11, 2022 at 9:43 AM PG Doc comments form <<= a href=3D"mailto:noreply@postgresql.org">noreply@postgresql.org> wro= te:
The following documentation comment has been lo= gged on the website:

Page: https://www.postgresql.org/docs/14/sql-sa= vepoint.html
Description:

The "Compatibility" section deserves some code example to illustr= ate the
behavior when reusing the same savepoint name.

I agree with the premise but not the implementation.=C2=A0 I= 've attached (and inlined) a patch that implements the example change, = updates savepoint to introduce the behavior prior to the example, and updat= es the rollback to savepoint to note the behavior as well.

<= div>
commit e921441f22bad972393144628c7ee48845d5384c
Autho= r: David G. Johnston <davi= d.g.johnston@gmail.com>
Date: =C2=A0 Tue Apr 12 14:30:11 2022 +00= 00

=C2=A0 =C2=A0 doc: Improve docs regarding savepoint name reuse=C2=A0 =C2=A0
=C2=A0 =C2=A0 Per documentation comment the savepoint co= mmand lacks an example
=C2=A0 =C2=A0 where the savepoint name is reused.= =C2=A0 The suggested example didn't
=C2=A0 =C2=A0 conform to the oth= ers on the page, nor did the suggested location
=C2=A0 =C2=A0 in compati= bility seem desirable, but the omission rang true. Add
=C2=A0 =C2=A0 ano= ther example to the examples section demonstrating this case.
=C2=A0 =C2= =A0 Additionally, document under the description for savepoint_name
=C2= =A0 =C2=A0 that we allow for the name to be repeated - and note what that=C2=A0 =C2=A0 means in terms of release and rollback. It seems desirable = to
=C2=A0 =C2=A0 place this comment in description rather than notes for= savepoint.
=C2=A0 =C2=A0 For the other two commands the behavior in the= presence of
=C2=A0 =C2=A0 duplicate savepoint names best fits as notes.= =C2=A0 In fact release
=C2=A0 =C2=A0 already had one.=C2=A0 This commit = copies the same verbiage over to
=C2=A0 =C2=A0 rollback.

diff --g= it a/doc/src/sgml/ref/rollback_to.sgml b/doc/src/sgml/ref/rollback_to.sgml<= br>index 3d5a241e1a..7bd1b41feb 100644
--- a/doc/src/sgml/ref/rollback_t= o.sgml
+++ b/doc/src/sgml/ref/rollback_to.sgml
@@ -89,6 +89,12 @@ ROL= LBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <replaceable>savepoint_= name</re
=C2=A0 =C2=A0 cannot-execute state, so while the transaction= can be restored using
=C2=A0 =C2=A0 <command>ROLLBACK TO SAVEPOIN= T</command>, the cursor can no longer be used.
=C2=A0 =C2=A0</p= ara>
+
+ =C2=A0<para>
+ =C2=A0 If multiple savepoints hav= e the same name, only the one that was most
+ =C2=A0 recently defined is= released.
+ =C2=A0</para>
+
=C2=A0 </refsect1>
=C2= =A0
=C2=A0 <refsect1>
diff --git a/doc/src/sgml/ref/savepoint.s= gml b/doc/src/sgml/ref/savepoint.sgml
index b17342a1ee..fd017935ea 10064= 4
--- a/doc/src/sgml/ref/savepoint.sgml
+++ b/doc/src/sgml/ref/savepo= int.sgml
@@ -53,7 +53,9 @@ SAVEPOINT <replaceable>savepoint_name&l= t;/replaceable>
=C2=A0 =C2=A0 =C2=A0<term><replaceable>sa= vepoint_name</replaceable></term>
=C2=A0 =C2=A0 =C2=A0<li= stitem>
=C2=A0 =C2=A0 =C2=A0 <para>
- =C2=A0 =C2=A0 =C2=A0Th= e name to give to the new savepoint.
+ =C2=A0 =C2=A0 =C2=A0The name to g= ive to the new savepoint.=C2=A0 The name may already exist,
+ =C2=A0 =C2= =A0 =C2=A0in which case a rollback or release to the same name will use the=
+ =C2=A0 =C2=A0 =C2=A0one that was most recently defined.
=C2=A0 =C2= =A0 =C2=A0 </para>
=C2=A0 =C2=A0 =C2=A0</listitem>
=C2=A0= =C2=A0 </varlistentry>
@@ -106,6 +108,25 @@ COMMIT;
=C2=A0<= /programlisting>
=C2=A0 =C2=A0 The above transaction will insert both= 3 and 4.
=C2=A0 =C2=A0</para>
+
+ =C2=A0<para>
+ = =C2=A0To use a single savepoint name:
+<programlisting>
+BEGIN;=
+ =C2=A0 =C2=A0INSERT INTO table1 VALUES (1);
+ =C2=A0 =C2=A0SAVEPOI= NT my_savepoint;
+ =C2=A0 =C2=A0INSERT INTO table1 VALUES (2);
+ =C2= =A0 =C2=A0SAVEPOINT my_savepoint;
+ =C2=A0 =C2=A0INSERT INTO table1 VALU= ES (3);
+ =C2=A0 =C2=A0ROLLBACK TO SAVEPOINT my_savepoint;
+ =C2=A0 = =C2=A0SELECT * FROM table1; // 1, 2
+ =C2=A0 =C2=A0ROLLBACK TO SAVEPOINT= my_savepoint;
+ =C2=A0 =C2=A0SELECT * FROM table1; // just 1
+COMMIT= ;
+</programlisting>
+ =C2=A0The above transaction shows row 3 = being rolled back first then row 2.
+ =C2=A0</para>
+
=C2=A0= </refsect1>
=C2=A0
=C2=A0 <refsect1>
=C2= =A0
--000000000000f7625305dc760fdc-- --000000000000f7625405dc760fde Content-Type: application/octet-stream; name="v0001-doc-savepoint-name-reuse.patch" Content-Disposition: attachment; filename="v0001-doc-savepoint-name-reuse.patch" Content-Transfer-Encoding: base64 Content-ID: X-Attachment-Id: f_l1w90b1n0 Y29tbWl0IGU5MjE0NDFmMjJiYWQ5NzIzOTMxNDQ2MjhjN2VlNDg4NDVkNTM4NGMKQXV0aG9yOiBE YXZpZCBHLiBKb2huc3RvbiA8ZGF2aWQuZy5qb2huc3RvbkBnbWFpbC5jb20+CkRhdGU6ICAgVHVl IEFwciAxMiAxNDozMDoxMSAyMDIyICswMDAwCgogICAgZG9jOiBJbXByb3ZlIGRvY3MgcmVnYXJk aW5nIHNhdmVwb2ludCBuYW1lIHJldXNlCiAgICAKICAgIFBlciBkb2N1bWVudGF0aW9uIGNvbW1l bnQgdGhlIHNhdmVwb2ludCBjb21tYW5kIGxhY2tzIGFuIGV4YW1wbGUKICAgIHdoZXJlIHRoZSBz YXZlcG9pbnQgbmFtZSBpcyByZXVzZWQuICBUaGUgc3VnZ2VzdGVkIGV4YW1wbGUgZGlkbid0CiAg ICBjb25mb3JtIHRvIHRoZSBvdGhlcnMgb24gdGhlIHBhZ2UsIG5vciBkaWQgdGhlIHN1Z2dlc3Rl ZCBsb2NhdGlvbgogICAgaW4gY29tcGF0aWJpbGl0eSBzZWVtIGRlc2lyYWJsZSwgYnV0IHRoZSBv bWlzc2lvbiByYW5nIHRydWUuIEFkZAogICAgYW5vdGhlciBleGFtcGxlIHRvIHRoZSBleGFtcGxl cyBzZWN0aW9uIGRlbW9uc3RyYXRpbmcgdGhpcyBjYXNlLgogICAgQWRkaXRpb25hbGx5LCBkb2N1 bWVudCB1bmRlciB0aGUgZGVzY3JpcHRpb24gZm9yIHNhdmVwb2ludF9uYW1lCiAgICB0aGF0IHdl IGFsbG93IGZvciB0aGUgbmFtZSB0byBiZSByZXBlYXRlZCAtIGFuZCBub3RlIHdoYXQgdGhhdAog ICAgbWVhbnMgaW4gdGVybXMgb2YgcmVsZWFzZSBhbmQgcm9sbGJhY2suIEl0IHNlZW1zIGRlc2ly YWJsZSB0bwogICAgcGxhY2UgdGhpcyBjb21tZW50IGluIGRlc2NyaXB0aW9uIHJhdGhlciB0aGFu IG5vdGVzIGZvciBzYXZlcG9pbnQuCiAgICBGb3IgdGhlIG90aGVyIHR3byBjb21tYW5kcyB0aGUg YmVoYXZpb3IgaW4gdGhlIHByZXNlbmNlIG9mCiAgICBkdXBsaWNhdGUgc2F2ZXBvaW50IG5hbWVz IGJlc3QgZml0cyBhcyBub3Rlcy4gIEluIGZhY3QgcmVsZWFzZQogICAgYWxyZWFkeSBoYWQgb25l LiAgVGhpcyBjb21taXQgY29waWVzIHRoZSBzYW1lIHZlcmJpYWdlIG92ZXIgdG8KICAgIHJvbGxi YWNrLgoKZGlmZiAtLWdpdCBhL2RvYy9zcmMvc2dtbC9yZWYvcm9sbGJhY2tfdG8uc2dtbCBiL2Rv Yy9zcmMvc2dtbC9yZWYvcm9sbGJhY2tfdG8uc2dtbAppbmRleCAzZDVhMjQxZTFhLi43YmQxYjQx ZmViIDEwMDY0NAotLS0gYS9kb2Mvc3JjL3NnbWwvcmVmL3JvbGxiYWNrX3RvLnNnbWwKKysrIGIv ZG9jL3NyYy9zZ21sL3JlZi9yb2xsYmFja190by5zZ21sCkBAIC04OSw2ICs4OSwxMiBAQCBST0xM QkFDSyBbIFdPUksgfCBUUkFOU0FDVElPTiBdIFRPIFsgU0FWRVBPSU5UIF0gPHJlcGxhY2VhYmxl PnNhdmVwb2ludF9uYW1lPC9yZQogICAgY2Fubm90LWV4ZWN1dGUgc3RhdGUsIHNvIHdoaWxlIHRo ZSB0cmFuc2FjdGlvbiBjYW4gYmUgcmVzdG9yZWQgdXNpbmcKICAgIDxjb21tYW5kPlJPTExCQUNL IFRPIFNBVkVQT0lOVDwvY29tbWFuZD4sIHRoZSBjdXJzb3IgY2FuIG5vIGxvbmdlciBiZSB1c2Vk LgogICA8L3BhcmE+CisKKyAgPHBhcmE+CisgICBJZiBtdWx0aXBsZSBzYXZlcG9pbnRzIGhhdmUg dGhlIHNhbWUgbmFtZSwgb25seSB0aGUgb25lIHRoYXQgd2FzIG1vc3QKKyAgIHJlY2VudGx5IGRl ZmluZWQgaXMgcmVsZWFzZWQuCisgIDwvcGFyYT4KKwogIDwvcmVmc2VjdDE+CiAKICA8cmVmc2Vj dDE+CmRpZmYgLS1naXQgYS9kb2Mvc3JjL3NnbWwvcmVmL3NhdmVwb2ludC5zZ21sIGIvZG9jL3Ny Yy9zZ21sL3JlZi9zYXZlcG9pbnQuc2dtbAppbmRleCBiMTczNDJhMWVlLi5mZDAxNzkzNWVhIDEw MDY0NAotLS0gYS9kb2Mvc3JjL3NnbWwvcmVmL3NhdmVwb2ludC5zZ21sCisrKyBiL2RvYy9zcmMv c2dtbC9yZWYvc2F2ZXBvaW50LnNnbWwKQEAgLTUzLDcgKzUzLDkgQEAgU0FWRVBPSU5UIDxyZXBs YWNlYWJsZT5zYXZlcG9pbnRfbmFtZTwvcmVwbGFjZWFibGU+CiAgICAgPHRlcm0+PHJlcGxhY2Vh YmxlPnNhdmVwb2ludF9uYW1lPC9yZXBsYWNlYWJsZT48L3Rlcm0+CiAgICAgPGxpc3RpdGVtPgog ICAgICA8cGFyYT4KLSAgICAgIFRoZSBuYW1lIHRvIGdpdmUgdG8gdGhlIG5ldyBzYXZlcG9pbnQu CisgICAgICBUaGUgbmFtZSB0byBnaXZlIHRvIHRoZSBuZXcgc2F2ZXBvaW50LiAgVGhlIG5hbWUg bWF5IGFscmVhZHkgZXhpc3QsCisgICAgICBpbiB3aGljaCBjYXNlIGEgcm9sbGJhY2sgb3IgcmVs ZWFzZSB0byB0aGUgc2FtZSBuYW1lIHdpbGwgdXNlIHRoZQorICAgICAgb25lIHRoYXQgd2FzIG1v c3QgcmVjZW50bHkgZGVmaW5lZC4KICAgICAgPC9wYXJhPgogICAgIDwvbGlzdGl0ZW0+CiAgICA8 L3Zhcmxpc3RlbnRyeT4KQEAgLTEwNiw2ICsxMDgsMjUgQEAgQ09NTUlUOwogPC9wcm9ncmFtbGlz dGluZz4KICAgIFRoZSBhYm92ZSB0cmFuc2FjdGlvbiB3aWxsIGluc2VydCBib3RoIDMgYW5kIDQu CiAgIDwvcGFyYT4KKworICA8cGFyYT4KKyAgVG8gdXNlIGEgc2luZ2xlIHNhdmVwb2ludCBuYW1l OgorPHByb2dyYW1saXN0aW5nPgorQkVHSU47CisgICAgSU5TRVJUIElOVE8gdGFibGUxIFZBTFVF UyAoMSk7CisgICAgU0FWRVBPSU5UIG15X3NhdmVwb2ludDsKKyAgICBJTlNFUlQgSU5UTyB0YWJs ZTEgVkFMVUVTICgyKTsKKyAgICBTQVZFUE9JTlQgbXlfc2F2ZXBvaW50OworICAgIElOU0VSVCBJ TlRPIHRhYmxlMSBWQUxVRVMgKDMpOworICAgIFJPTExCQUNLIFRPIFNBVkVQT0lOVCBteV9zYXZl cG9pbnQ7CisgICAgU0VMRUNUICogRlJPTSB0YWJsZTE7IC8vIDEsIDIKKyAgICBST0xMQkFDSyBU TyBTQVZFUE9JTlQgbXlfc2F2ZXBvaW50OworICAgIFNFTEVDVCAqIEZST00gdGFibGUxOyAvLyBq dXN0IDEKK0NPTU1JVDsKKzwvcHJvZ3JhbWxpc3Rpbmc+CisgIFRoZSBhYm92ZSB0cmFuc2FjdGlv biBzaG93cyByb3cgMyBiZWluZyByb2xsZWQgYmFjayBmaXJzdCB0aGVuIHJvdyAyLgorICA8L3Bh cmE+CisKICA8L3JlZnNlY3QxPgogCiAgPHJlZnNlY3QxPgo= --000000000000f7625405dc760fde--