Re: Correct docs re: rewriting indexes when table rewrite is skipped

On Wed, Mar 30, 2022 at 11:41 AM Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>
> On Wed, Mar 30, 2022 at 10:04 AM James Coleman <jtc331(at)gmail(dot)com> wrote:
> > Admittedly I hadn't thought of that case. But isn't it already covered
> > in the existing docs by the phrase "or an unconstrained domain over
> > the new type"? I don't love the word "or" there because there's a
> > sense in which the first clause "binary coercible to the new type" is
> > still accurate for your example unless you narrowly separate "domain"
> > and "type", but I think that narrow distinction is what's technically
> > there already.
> >
> > That being said, I could instead of removing the clause entirely
> > replace it with something like "indexes may still need to be rebuilt
> > when the new type is a constrained domain".
>
> You're talking about this as if the normal cases is that indexes don't
> need to rebuilt, but sometimes they do. However, if I recall
> correctly, the way the code is structured, it supposes that the
> indexes do need a rebuild, and then tries to prove that they actually
> don't. That disconnect makes me nervous, because it seems to me that
> it could easily lead to a situation where our documentation contains
> subtle errors. I think somebody should go through and study the
> algorithm as it exists in the code, and then write documentation to
> match it. And I think that when they do that, they should approach it
> from the same point of view that the code does i.e. "these are the
> conditions for skipping the index rebuild" rather than "these are the
> conditions for performing an index rebuild." By doing it that way, I
> think we minimize the likelihood of disconnects between code and
> documentation, and also make it easier to update in future if the
> algorithm gets changed.

Hmm, having it match the way it works makes sense. Would you feel
comfortable with an intermediate step (queueing up that as a larger
change) changing the clause to something like "indexes will still have
to be rebuilt unless the system can guarantee that the sort order is
proven to be unchanged" (with appropriate wordsmithing to be a bit
less verbose if possible)?

Thanks,
James Coleman