Re: Documentation of bt_page_items()'s ctid field

On 12/30/2014 04:08 AM, Peter Geoghegan wrote:
> Attached documentation patch describes the purpose of
> bt_page_items()'s ctid field. This has come up enough times in
> disaster recovery or testing scenarios that I feel it's worth drawing
> particular attention to.

How much detail on the b-tree internals do we want to put in the
pageinspect documentation? I can see that being useful, but should we
also explain e.g. that the first item on each (non-rightmost) page is
the high key?

> + Note that <structfield>ctid</> addresses a heap tuple if the
> + page under consideration is a B-Tree leaf page. Otherwise, for
> + internal B-Tree pages <structfield>ctid</> addresses a page in
> + the B-Tree itself (excluding the root page if and only if there
> + has not yet been a root page split, as in the example above).
> + These internally referenced pages are child pages, and may
> + themselves be leaf pages or internal pages.

I had a hard time understanding the remark about the root page. But in
any case, if you look at the flags set e.g. with bt_page_stats(), the
root page is flagged as also being a leaf page, when it is the only page
in the index. So the root page is considered also a leaf page in that case.

I'd suggest saying the same thing (or more) with fewer words:

In a B-tree leaf page, <structfield>ctid</> points to a heap tuple. In
an internal page, it points to another page in the index itself, and the
offset number part (the second number) of the ctid field is ignored.

- Heikki