Re: Information on savepoint requirement within transctions - Mailing list pgsql-general

​So, my first pass at this.  I'm probably going a bit outside what would normally be covered in the SQL Command section but it does feel right at first blush.

Also attached; not compiled.

As a bug fix I've updated the description of "COMMIT" here since it can cause a ROLLBACK to be issued and that isn't documented.

"(pseudo) sub-transaction" seemed like a reasonable choice of terminology to introduce rather than just "mark".  Having it mentioned in context in the BEGIN docs, instead of just a "see also", should aid in understanding how the whole transaction system fits together.  The advanced features of the tutorial cover this to some degree (I didn't re-read it prior to writing this up) but I'm inclined to believe people wanting to understand transactions, lacking a top-level chapter on the topic, will know of BEGIN and start their discovery there.

David J.

​diff --git a/doc/src/sgml/ref/begin.sgml b/doc/src/sgml/ref/begin.sgml

index c23bbfb4e7..c1b3ef9306 100644

--- a/doc/src/sgml/ref/begin.sgml

+++ b/doc/src/sgml/ref/begin.sgml

@@ -49,6 +49,16 @@ BEGIN [ WORK | TRANSACTION ] [ <replaceable class="parameter">transaction_mode</

   </para>

 

   <para>

+   Pseudo sub-transactions are created using <xref linkend="sql-savepoint"/>.

+   These are of particular use for client software to use when executing

+   user-supplied SQL statements and want to provide try/catch behavior

+   where failures are ignored. The server cannot be configured to do this

+   automatically: all (sub-)transaction blocks either commit or rollback in their

+   entirety. A commit issued while the transaction has an active failure

+   is automatically converted into a <xref linkend="sql-rollback"/>.

+  </para>

+

+  <para>

    Statements are executed more quickly in a transaction block, because

    transaction start/commit requires significant CPU and disk

    activity. Execution of multiple statements inside a transaction is

diff --git a/doc/src/sgml/ref/commit.sgml b/doc/src/sgml/ref/commit.sgml

index b2e8d5d180..8bb368b771 100644

--- a/doc/src/sgml/ref/commit.sgml

+++ b/doc/src/sgml/ref/commit.sgml

@@ -29,9 +29,11 @@ COMMIT [ WORK | TRANSACTION ]

   <title>Description</title>

 

   <para>

-   <command>COMMIT</command> commits the current transaction. All

+   <command>COMMIT</command> ends the current transaction. All

    changes made by the transaction become visible to others

-   and are guaranteed to be durable if a crash occurs.

+   and are guaranteed to be durable if a crash occurs. However,

+   if the transaction has failed a <xref linkend="sql-rollback"/>

+   will be processed instead.

   </para>

  </refsect1>

 

diff --git a/doc/src/sgml/ref/savepoint.sgml b/doc/src/sgml/ref/savepoint.sgml

index 87243b1d20..66cee63966 100644

--- a/doc/src/sgml/ref/savepoint.sgml

+++ b/doc/src/sgml/ref/savepoint.sgml

@@ -41,7 +41,8 @@ SAVEPOINT <replaceable>savepoint_name</replaceable>

   <para>

    A savepoint is a special mark inside a transaction that allows all commands

    that are executed after it was established to be rolled back, restoring

-   the transaction state to what it was at the time of the savepoint.

+   the transaction state to what it was at the time of the savepoint. It can be

+   thought of as a kind of a pseudo sub-transaction.

   </para>

  </refsect1>

 

@@ -74,6 +75,11 @@ SAVEPOINT <replaceable>savepoint_name</replaceable>

    Savepoints can only be established when inside a transaction block.

    There can be multiple savepoints defined within a transaction.

   </para>

+

+  <para>

+    <application>psql</application> makes use of savepoints to implment its

+    <literal>ON_ERROR_ROLLBACK</literal> behavior.

+  </para>

  </refsect1>

 

  <refsect1>