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



--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

Reply via email to