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

On 08/21/2012 11:18 PM, Robert Haas wrote:
> On Mon, Aug 20, 2012 at 4:45 AM, Craig Ringer <ringerc@ringerc.id.au> wrote:
>> 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.
>>
>
> The first of these three patches looks good to me, so I committed it.
> I am not convinced that the others are ready to go in.  AFAICS, there
> hasn't been any discussion of whether a list of non-transactional
> features would be a useful thing to have, or if so where it should be
> located in the docs and what should go into it.  I'm not necessarily
> opposed to adding something, but I think it needs some actual
> discussion before we commit anything.

Fine by me; I just thought a concrete proposed change might get people 
talking about it better than my doing some more broad hand-waving on the 
topic.

Anyone?

Should we add a section that lists exceptions to normal transactional 
behaviour in one place, so instead of having to say "SEQUENCEs and some 
other features" or "various types, functions and features" there's 
something *concrete* to point to when discussing transactional oddities?


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