On 08/19/2012 03:01 AM, Jeff Janes wrote:
>Or would you instead say that
>"changes made to a sequence are immediately visible to all other
>transactions" ?
Yes, that sounds better.
OK, how about the attached series, then?
The 2nd probably needs improvement - and I expect I've missed some other
areas that aren't strictly transactional.
Comments?
Working branch:
https://github.com/ringerc/postgres/tree/sequence_documentation_fixes
--
Craig Ringer
>From 311ea8a493c939a70a89234246f662514687d8c2 Mon Sep 17 00:00:00 2001
From: Craig Ringer <ring...@ringerc.id.au>
Date: Sat, 18 Aug 2012 12:51:28 +0800
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
>From 69c892ed85070de8df41f2b00088f503453b2e97 Mon Sep 17 00:00:00 2001
From: Craig Ringer <ring...@ringerc.id.au>
Date: Mon, 20 Aug 2012 11:55:25 +0800
Subject: [PATCH 2/3] Collect a list of features with abberant transactional
behavour
---
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
>From 35b2aec7f6816c7ecd7bb1f8e2ecb2439043d982 Mon Sep 17 00:00:00 2001
From: Craig Ringer <ring...@ringerc.id.au>
Date: Mon, 20 Aug 2012 12:02:53 +0800
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
