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(at)ringerc(dot)id(dot)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>