On 30.01.2018 03:07, David G. Johnston wrote:
> So, my first pass at this.
Nice, thank you.
> + 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.
Personally, I'd reword this to something like this:
> These are of particular use for client software which is executing
> user-supplied SQL statements and wants to provide try/catch behavior
> with the ability to continue to use the transaction after a failure.
Or maybe something like this:
> These are of particular use for client software which requires
> fine-grained support over failure behavior within a transaction.
> They allow to provide a try/catch behavior with the ability
> to continue to use a transaction after a failure.
Given three options, and re-reading the paragraph, I figured dropping the last part altogether was probably the best; though of the three "continue to use a transaction after a failure" was close.
Also I'd like to see something like this in the docs at roughly the same position:
> If a failure occurs during a transaction, the transaction enters
> an aborted state. An aborted or failed transaction cannot be used
> anymore to issue more commands, ROLLBACK or ROLLBACK TO must be used
> to regain control of the aborted transaction. A commit issued while
> the transaction is aborted is automatically converted into a
> <xref linkend="sql-rollback"/>.
Now that I've skimmed the tutorial again I think pointing the reader of the SQL Commands there to learn how it works in practice is better than trying to explain it in BEGIN and/or SAVEPOINT.
I decided to add a title to the part of SAVEPOINTS and introduce the term "Sub-Transaction" there though I'm not married to it - re-wording it using only "savepoint" is something that should be tried still.
A title and a paragraph or two on aborted transaction behavior probably should be added as well.
Not compiled, not sure how the tutorial modifications would (want to) interplay with the table of contents.
Diff from v1 and full v2 diff attached.
David J.
diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index ae5f3fac75..9ef9abf07d 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -247,7 +247,13 @@ COMMIT;
is sometimes called a <firstterm>transaction block</firstterm>.
</para>
+ <para>
+ Issuing <command>ROLLBACK</command> is only mandatory if you wish to end an otherwise
+ successfully executed transaction by rolling back its work. Issuing
+ <command>COMMIT</command> on an aborted transaction will cause a rollback to occur
+ anyways.
<note>
+
<para>
Some client libraries issue <command>BEGIN</command> and <command>COMMIT</command>
commands automatically, so that you might get the effect of transaction
@@ -256,14 +262,16 @@ COMMIT;
</para>
</note>
+ <title>Sub-Transactions via Savepoints</title>
+
<para>
It's possible to control the statements in a transaction in a more
granular fashion through the use of <firstterm>savepoints</firstterm>. Savepoints
allow you to selectively discard parts of the transaction, while
committing the rest. After defining a savepoint with
- <command>SAVEPOINT</command>, you can if needed roll back to the savepoint
+ <command>SAVEPOINT</command>, you can roll back to the savepoint
with <command>ROLLBACK TO</command>. All the transaction's database changes
- between defining the savepoint and rolling back to it are discarded, but
+ between defining the savepoint and rolling back to it are discarded while
changes earlier than the savepoint are kept.
</para>
@@ -272,8 +280,8 @@ COMMIT;
roll back to it several times. Conversely, if you are sure you won't need
to roll back to a particular savepoint again, it can be released, so the
system can free some resources. Keep in mind that either releasing or
- rolling back to a savepoint
- will automatically release all savepoints that were defined after it.
+ rolling back to a savepoint will automatically release or rollback,
+ respectively, all savepoints that were defined after it.
</para>
<para>
diff --git a/doc/src/sgml/ref/begin.sgml b/doc/src/sgml/ref/begin.sgml
index c23bbfb4e7..7cdd272974 100644
--- a/doc/src/sgml/ref/begin.sgml
+++ b/doc/src/sgml/ref/begin.sgml
@@ -49,6 +49,14 @@ BEGIN [ WORK | TRANSACTION ] [ <replaceable class="parameter">transaction_mode</
</para>
<para>
+ 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.
+ See the advanced tutorial section <xref linkend="tutorial-transactions"/>
+ to learn how tranasctions and sub-transactions work in practice.
+ </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/advanced.sgml b/doc/src/sgml/advanced.sgml
index ae5f3fac75..9ef9abf07d 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -247,7 +247,13 @@ COMMIT;
is sometimes called a <firstterm>transaction block</firstterm>.
</para>
+ <para>
+ Issuing <command>ROLLBACK</command> is only mandatory if you wish to end an otherwise
+ successfully executed transaction by rolling back its work. Issuing
+ <command>COMMIT</command> on an aborted transaction will cause a rollback to occur
+ anyways.
<note>
+
<para>
Some client libraries issue <command>BEGIN</command> and <command>COMMIT</command>
commands automatically, so that you might get the effect of transaction
@@ -256,14 +262,16 @@ COMMIT;
</para>
</note>
+ <title>Sub-Transactions via Savepoints</title>
+
<para>
It's possible to control the statements in a transaction in a more
granular fashion through the use of <firstterm>savepoints</firstterm>. Savepoints
allow you to selectively discard parts of the transaction, while
committing the rest. After defining a savepoint with
- <command>SAVEPOINT</command>, you can if needed roll back to the savepoint
+ <command>SAVEPOINT</command>, you can roll back to the savepoint
with <command>ROLLBACK TO</command>. All the transaction's database changes
- between defining the savepoint and rolling back to it are discarded, but
+ between defining the savepoint and rolling back to it are discarded while
changes earlier than the savepoint are kept.
</para>
@@ -272,8 +280,8 @@ COMMIT;
roll back to it several times. Conversely, if you are sure you won't need
to roll back to a particular savepoint again, it can be released, so the
system can free some resources. Keep in mind that either releasing or
- rolling back to a savepoint
- will automatically release all savepoints that were defined after it.
+ rolling back to a savepoint will automatically release or rollback,
+ respectively, all savepoints that were defined after it.
</para>
<para>
diff --git a/doc/src/sgml/ref/begin.sgml b/doc/src/sgml/ref/begin.sgml
index c1b3ef9306..7cdd272974 100644
--- a/doc/src/sgml/ref/begin.sgml
+++ b/doc/src/sgml/ref/begin.sgml
@@ -49,13 +49,11 @@ BEGIN [ WORK | TRANSACTION ] [ <replaceable class="parameter">transaction_mode</
</para>
<para>
- Pseudo sub-transactions are created using <xref linkend="sql-savepoint"/>.
+ 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"/>.
+ user-supplied SQL statements and want to provide try/catch behavior.
+ See the advanced tutorial section <xref linkend="tutorial-transactions"/>
+ to learn how tranasctions and sub-transactions work in practice.
</para>
<para>
