Re: INSERT ... ON CONFLICT documentation clean-up patch

From: Peter Geoghegan <pg(at)heroku(dot)com>
To: Andres Freund <andres(at)anarazel(dot)de>
Cc: Pg Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: INSERT ... ON CONFLICT documentation clean-up patch
Date: 2015-11-10 22:28:16
Message-ID: CAM3SWZSdCHrzzrwspso_CC2zUprr2-y5t-a2vUX+W=Yf5uHUeg@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

As discussed on IM, I think we should make the insert.sgml
documentation even close to select.sgml than before, in that
parameters ought to be discussed in different sections, and not in one
large block. insert.sgml is too complicated for that approach now.

Attached revision (rebase) of your modified version of my patch (the
modification you provided privately) has the following notable
changes:

* New section for "Inserting" parameters. Now, "On Conflict Clause"
section is a subsection of the Standard Parameters' parent section (so
they're siblings).

This seemed like the best division of parameters here. It didn't seem
to make much sense to imagine that we ought to have multiple very
specific categories in the style of select.sgml (meaning that the old
insert text would have to be integrated with this new section
discussing "Insertion" parameters, I suppose) -- we didn't go far
enough in this direction before, now but that would be too far IMV.

* The term "unique index inference clause" has been removed. Inference
is now something that conflict_target sometimes (or usually) does.
There is no clause that does inference that isn't exactly
conflict_target.

* As in my original, NOT DEFERRABLE constraints are the only type
supported -- we should not mention "deferred" constraints at all. You
changed that back. I changed it back again here.

* "ON CONFLICT Clause" section now mentions ON CONFLICT DO
UPDATE/NOTHING far sooner. I think this is far clearer.

* output_expression currently said to not project updated columns from
RETURNING, which is just wrong. This is fixed.

* General further copy-editing. Establishing the ON CONFLICT context
significantly improved the flow of discussing the new-to-9.5
parameters. I did more than I'd planned to here, but I think it's
shorter overall, and is certainly more consistent. I'd also say that
it reads better.

Thoughts?
--
Peter Geoghegan

Attachment Content-Type Size
0001-Improve-ON-CONFLICT-documentation.patch text/x-patch 30.9 KB

In response to

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Tom Lane 2015-11-11 00:03:02 Re: bootstrap pg_shseclabel in relcache initialization
Previous Message Tom Lane 2015-11-10 20:55:44 Re: Uh-oh: documentation PDF output no longer builds in HEAD