Search Postgresql Archives

Re: Information on savepoint requirement within transctions

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Mon, Jan 29, 2018 at 6:59 AM, Robert Zenz <robert.zenz@xxxxxxxxxxxxxx> wrote:
> It may be worth updating the docs here...

I'd vote for that. I would have expected to see this mentioned in the
documentation a little bit more prominent than just a single sentence at the end
of the transaction tutorial. A short section about how the transaction behaves
in an error cases (and what to do) would be nice.

​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>

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>

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Index of Archives]     [Postgresql Jobs]     [Postgresql Admin]     [Postgresql Performance]     [Linux Clusters]     [PHP Home]     [PHP on Windows]     [Kernel Newbies]     [PHP Classes]     [PHP Books]     [PHP Databases]     [Postgresql & PHP]     [Yosemite]

  Powered by Linux