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