Re: [PATCH] Docs: Make notes on sequences and rollback more obvious

Trying again with the attachments; the archiver only seemed to see the
first patch despite all three being attached. Including patches inline;
if you want 'em prettier, see:

https://github.com/ringerc/postgres/tree/sequence_documentation_fixes

Subject: [PATCH 1/3] Make sure you can't read through mvcc.sgml without
realising that not everything is MVCC.

---
doc/src/sgml/mvcc.sgml | 12 ++++++++++++
1 file changed, 12 insertions(+)

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
new file mode 100644
index 8f88582..9dc65f5
*** a/doc/src/sgml/mvcc.sgml
--- b/doc/src/sgml/mvcc.sgml
***************
*** 260,265 ****
--- 260,277 ----
command <xref linkend="sql-set-transaction">.
</para>

+ <important>
+ <para>
+ Some <productname>PostgreSQL</productname> data types and
functions have
+ special rules regarding transactional behaviour. In
particular, changes
+ made to a <literal>SEQUENCE</literal> (and therefore the
counter of a
+ <literal>SERIAL</literal>) are immediately visible to all other
+ transactions and are not rolled back if the transaction that
made the
+ changes aborts. See <xref linkend="functions-sequence"> and
+ <xref linkend="datatype-serial">.
+ </para>
+ </important>
+
<sect2 id="xact-read-committed">
<title>Read Committed Isolation Level</title>

-- 1.7.11.2

Subject: [PATCH 2/3] Collect a list of features with abberant
transactional behaviour

---
doc/src/sgml/mvcc.sgml | 67
++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 67 insertions(+)

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
new file mode 100644
index 9dc65f5..e2930c9
*** a/doc/src/sgml/mvcc.sgml
--- b/doc/src/sgml/mvcc.sgml
*************** SELECT pg_advisory_lock(q.id) FROM
*** 1540,1543 ****
--- 1540,1610 ----
indexes should be used instead.
</para>
</sect1>
+
+ <sect1 id="mvcc-exceptions">
+ <title>Exceptions to normal transactional rules</title>
+
+ <para>
+ Some PostgreSQL features, functions and data types differ from the
+ usual transactional behaviour described in this chapter. Differences
+ are generally mentioned in the documentation sections for the
+ features they affect. Such exceptions are collected here for
+ easy reference.
+ </para>
+
+ <para>
+ The following actions and features don't follow the typical
+ transactional rules:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Serial pseudo-types <xref linkend="datatype-serial">
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>SEQUENCE</literal>s - <xref linkend="functions-sequence">
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Advisory locks - <xref linkend="advisory-locks">
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Disk writes to files outside the database, as performed by
+ <literal>COPY ... TO</literal>, adminpack functions, and other
add-ons.
+ See <xref linkend="sql-copy">, <xref linkend="adminpack">.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Any network I/O or inter-process communication not explicitly
+ described as transactional in its documentation. For example,
+ sending an email from PL/PerlU would not be transactional;
+ the email would be sent before the transaction commits and
+ could not be un-sent if the transaction were to roll back.
+ </listitem>
+ </itemizedlist>
+
+ <note>
+ <para>
+ When working with external non-transactional resources like files
+ on disk or network sockets the two-phase commit feature can be
+ useful. See: <xref linkend="sql-prepare-transaction">
+ </para>
+ <para>
+ LISTEN/NOTIFY provides a lighter weight but still
transaction-friendly method of
+ triggering changes outside the database in response to changes
inside the
+ database. A LISTENing helper program running outside the database can
+ perform actions when it gets a NOTIFY after a transaction
commits. See:
+ <xref linkend="sql-notify">.
+ </para>
+ </note>
+
+ </sect1>
+
</chapter>
-- 1.7.11.2

Subject: [PATCH 3/3] Change xref of <important/> note re SERIAL to point
to mvcc-exceptions

---
doc/src/sgml/mvcc.sgml | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
new file mode 100644
index e2930c9..0de4b75
*** a/doc/src/sgml/mvcc.sgml
--- b/doc/src/sgml/mvcc.sgml
***************
*** 267,274 ****
made to a <literal>SEQUENCE</literal> (and therefore the
counter of a
<literal>SERIAL</literal>) are immediately visible to all other
transactions and are not rolled back if the transaction that
made the
! changes aborts. See <xref linkend="functions-sequence"> and
! <xref linkend="datatype-serial">.
</para>
</important>

--- 267,273 ----
made to a <literal>SEQUENCE</literal> (and therefore the
counter of a
<literal>SERIAL</literal>) are immediately visible to all other
transactions and are not rolled back if the transaction that
made the
! changes aborts. See <xref linkend="mvcc-exceptions">.
</para>
</important>

-- 1.7.11.2