Re: Documentation of bt_page_items()'s ctid field

On Mon, Mar 9, 2015 at 5:34 PM, Peter Geoghegan <pg(at)heroku(dot)com> wrote:

> On Mon, Mar 9, 2015 at 5:18 PM, Jeff Janes <jeff(dot)janes(at)gmail(dot)com> wrote:
> >> It has a right-link (that's the easiest way to tell).
> >
> >
> > Meaning that btpo_next is not zero? Should we say that in the patch in
> so
> > many words? I think it will be hard to explain the page_items more
> without
> > also explaining the page_stats more.
>
> Yes. And my wording above was sloppy: By definition, a non-rightmost
> page is a page that has a rightlink (it will also have a highkey, but
> that's certainly not how we distinguish them).
>
> Attached patch adds a definition of non-rightmost in parenthesis,
> which I think helps.
>

Thanks. I think the sense of the definition is wrong (you are defining a
rightmost page, not a non-rightmost page), and the btpo_next field is zero,
not null, when on a rightmost page. Or at least, bt_page_stats presents it
as zero.

So more like the attached patch.

I think we do want this. It was asked how much we want to include
internals of the btree code into pageinspect documentation, but I think the
nature of pageinspect makes that unavoidable. Its docs have to tell you
what it does, and inspecting the internals is what it does. And since
those internals are unlikely to change other than in a way that breaks
pg_upgrade, I think we can safely assume that the work of updating the doc
would pale compared to the work of making the docs inaccurate.

I'd mark it ready for committer, but since I also attached a suggested
replacement patch it seems presumptuous to do that.

Cheers,

Jeff