Re: Add a new table for Transaction Isolation?

On Fri, Apr 24, 2015 at 9:57 AM, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:

> On 4/17/15 7:36 PM, David G. Johnston wrote:
> > diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
> > index f88b16e..5002138 100644
> > --- a/doc/src/sgml/mvcc.sgml
> > +++ b/doc/src/sgml/mvcc.sgml
> > @@ -100,6 +100,14 @@
> > phenomena caused by interactions?)
> > </para>
> >
> > + <para>
> > + The concepts covered in this section are
> > + presented without examples of the behaviors described. The internet,
> > + including and espcially the <productname>PostgreSQL</productname>
> Wiki, is
> > + an excellent resource to learn more about circumstances under which
> these
> > + data phenomena occur, and what the results look like when they do.
> > + </para>
> > +
>
> I don't think our documentation should go out of its way to say, "our
> documentation is bad, look elsewhere". If we think examples are
> necessary, then we should add some. Otherwise, it's implied that
> improvement is always possible.
>

​I'm not - I am explicitly listing the assumptions the documentation makes
regarding reader experience (and ease of documenting) - and pointing out
were the reader can go if their experience is lacking in those areas.​ It
seems unproductive to move all of the SSI content on our Wiki into the
documentation and so, lacking such, we should point out where else content
can be found.

>
> > <para>
> > The phenomena which are prohibited at various levels are:
> >
> > @@ -150,12 +158,12 @@
> > <indexterm>
> > <primary>transaction isolation level</primary>
> > </indexterm>
> > - The four transaction isolation levels and the corresponding
> > - behaviors are described in <xref linkend="mvcc-isolevel-table">.
> > + The four SQL transaction isolation levels, and their corresponding
> > + behaviors, are described in <xref linkend="mvcc-isolevel-table">.
> > </para>
>
> I don't think this change is good.
>

I think it reads cleaner but not so much as to argue it.

>
> >
> > <table tocentry="1" id="mvcc-isolevel-table">
> > - <title>Standard <acronym>SQL</acronym> Transaction Isolation
> Levels</title>
> > + <title><acronym>SQL</acronym> Standard Transaction Isolation
> Levels</title>
> > <tgroup cols="4">
> > <thead>
> > <row>
>
> Why this change?
>

​The new table reads "PostgreSQL ..." and the corresponding noun is the
"SQL Standard". Writing "Standard SQL" can be read as implying the
existence of "Non-Standard SQL..." which is not correct. Just saying
"SQL..." seems to be too generic - though after reading the conclusion and
pondering that "SQL Standard" could also imply "SQL Non-Standard..." I'm
not so sure whether just saying SQL wouldn't be best. "Here are the four
words that can be used with SET TRANSACTION ISOLATION LEVEL..." - and then
show/describe the minimum required non-behaviors and the non-behaviors as
implemented in PostgreSQL.

​Maybe possessive would work "PostgreSQL's ..." and "SQL Standard's..."​

> > @@ -256,6 +264,89 @@
> > </para>
> >
> > <para>
> > + The three <productname>PostgreSQL</productname> transaction
> isolation levels, and their corresponding
> > + behaviors, are described in <xref
> linkend="mvcc-pgsql-isolevel-table">.
> > + </para>
>
> This isn't really correct. The PostgreSQL isolation levels were
> described in the paragraph above. The table is really just a summary of
> the previous explanation.
>

​"[...], are summarized in <xref...>" ?
​

>
> > + <para>
> > + As the table makes clear there is no difference in the potential
> phenomena
> > + at the REPEATABLE READ and SERIALIZABLE transaction isolation
> levels; but
> > + the phenomena listed only pertain to the data seen by the
> transaction.
>
> Please adapt the existing spelling and capitalization.
>

​OK
​

>
> > + The difference is that REPEATABLE READ will only serial-fail
>
> This term "serial-fail" would need further explanation.
>

​I will probably stick with the more verbose "serialization failure"...does
that require explaining here, or a xref?
​

>
> > + if two transactions attempt to modify the same record while
> SERIALIZABLE will
> > + also serial-fail if one transaction modifies a record that another
> transaction
> > + has only read.
> > + </para>
>
> I don't think this new table adds clarity. Users should generally have
> their applications use the appropriate standard isolation level.
> ​
>

​​Then why not sure write the entire section relative to the standard and
point out the differences between the standard and our implementation on
the command definition page in the compatibility section?

​http://www.postgresql.org/docs/devel/static/sql-set-transaction.html
​

> Adding
> another table that says, some of these are not actually different,
> following by text that says they are different in other ways, just
> repeats the point that was made earlier and will be explained in more
> detail in the following subsections.
>

> The real difference, in my mind, is that the SQL standard defines four
> levels in terms of three criteria, but PostgreSQL really has four
> criteria and only three different levels implemented. It might be worth
> visualizing that somehow.
>

​Well, I would at least add "Read uncommitted" to the PostgreSQL table and
have it setup the same as "Read committed". We do implement all four - by
name.

And, as to the prior point, visualizing the differences seems best
accomplished in a compatibility section and likely will just confuse the
issue here - if indeed the expectation is that users will define their
requirements relative to the standard and not relative to our
implementation.

​Otherwise, a summary table describing our implementation seems like a
self-evident need. We are already going to great lengths to describe
everything in the table anyway and we already are using a table to describe
the standard's definitions.​ Placing said table here seems easiest and if
summarizing what is already present in the text somehow makes the section
more confusing I posit that it must already be confusing without the
table. At least this way the confusing stuff is summarized and is readily
available for lookup by those who know what they are looking for.
​
For clarity - what is the 4th criteria that you are thinking of? More
specifically, how would you name it so that it could be a table column?

Two separate patches here:

1) ​pointing out that additional information is available on the wiki and
the internet

2) summarizing the PostgreSQL implementation into a table similar to that
already present for the Standard

#2 can be implemented in the MVCC section or a more extensive patch can
also update the SQL command SET TRANSACTION section - which will mean
someone feels strongly enough that the status quo is better than updating
MVCC while waiting for someone to write the more invasive patch.

​David J.​