From: Tom Lane <tgl@sss.pgh.pa.us>
To: "Jonathan S. Katz" <jkatz@postgresql.org>
cc: Bruce Momjian <bruce@momjian.us>, emilioplatzer@gmail.com,
        pgsql-docs@lists.postgresql.org,
        Alvaro Herrera <alvherre@2ndquadrant.com>
Subject: Re: Documentation for create unique index is insuficient and (because
 of that) incorrect
In-reply-to: <11974.1542727002@sss.pgh.pa.us>
References: <154031939560.30897.14677735588262722042@wrigleys.postgresql.org>
 <20181120020542.GH28656@momjian.us>
 <9ba37df7-156b-b983-65b5-85ed096818b9@postgresql.org>
 <11323.1542725958@sss.pgh.pa.us>
 <c73feb8b-b0a7-23be-ce6b-f70d2529b70f@postgresql.org>
 <11974.1542727002@sss.pgh.pa.us>
Comments: In-reply-to Tom Lane <tgl@sss.pgh.pa.us>
	message dated "Tue, 20 Nov 2018 10:16:42 -0500"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <25341.1542736665.1@sss.pgh.pa.us>
Date: Tue, 20 Nov 2018 12:57:45 -0500
Message-ID: <25342.1542736665@sss.pgh.pa.us>
Precedence: bulk

I wrote:
> "Jonathan S. Katz" <jkatz@postgresql.org> writes:
>> Also +1 on having a section on covering indexes.

> I see Alvaro is on the same page here.  I'll go write something
> later today.

So looking closer ... not only is the unique-index section not a very
good fit, but there is already a section that this does fit into
pretty well, which is 11.11 on index-only scans.  Not only do you need
to understand index-only scans to understand why you'd want INCLUDE,
but there's already discussion there of making covering indexes the
hard way.

So what I think I should do is reformulate that discussion to talk
about making covering indexes with INCLUDE, and then mention in
passing that you can also do it without that as long as you don't mind
the payload columns being part of the index semantics.

I'm also wondering whether to move that section someplace earlier
in chapter 11.  Right now it's near the end because it's mostly
info about an implementation detail; but it wouldn't be hard to
make the argument that covering indexes are more important than,
say, indexes with custom collations.  Should we move it, and if
so to where?

			regards, tom lane