Re: [PATCH] Docs: Make notes on sequences and rollback more obvious - Mailing list pgsql-hackers

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
rolledback 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
rolledback if the transaction that 
 
made the
!        changes aborts.  See <xref linkend="mvcc-exceptions">.       </para>     </important>

-- 1.7.11.2