Re: System catalog documentation chapter - Mailing list pgsql-hackers

On Mon, Jul 18, 2022 at 09:22:24PM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > On Sat, Jul 16, 2022 at 10:53:17AM +0200, Peter Eisentraut wrote:
> >> Maybe this whole notion that "system views" is one thing is not suitable.
> 
> > Are you thinking we should just call the chapter "System Catalogs and
> > Views" and just place them alphabetically in a single chapter?
> 
> I didn't think that was Peter's argument at all.  He's complaining
> that "system views" isn't a monolithic category, which is a reasonable
> point, especially since we have a bunch of built-in views that appear
> in other chapters.  But to then also confuse them with catalogs isn't
> improving the situation.

I think I see now --- system _tables_ are really not for user consumption
but system views often are.  I am thinking the best approach is to move
most of the system views out of the system views section and into the
sections where they make sense.

> The views that are actually reinterpretations of catalog contents should
> probably be documented near the catalogs.  But a lot of stuff in that
> chapter is no such thing.  For example, it's really unclear why

Right.

> pg_backend_memory_contexts is documented here and not somewhere near
> the stats views.  We also have stuff like pg_available_extensions,

Right.

> pg_file_settings, and pg_timezone_names, which are reporting ground truth
> of some sort that didn't come from the catalogs.  I'm not sure if those
> belong near the catalogs or not.

I am thinking some of those need to be in the Server Configuration
chapter.

> The larger point, perhaps, is that this whole area is underneath
> "Part VII: Internals", and that being the case what you would expect
> to find here is stuff that we don't intend people to interact with
> in day-to-day usage.  Most of the "system views" are specifically
> intended for day-to-day use, maybe only by DBAs, but nonetheless they
> are user-facing in a way that the catalogs aren't.
> 
> Maybe we should move them all to Part IV, in a chapter or chapters
> adjacent to the Information Schema chapter.  Or maybe try to separate
> "user" views from "DBA" views, and put user views in Part IV while
> DBA views go into a new chapter in Part III, near the stats views.

I am going to look at moving system views that make sense into the
chapters where their contents are mentioned.  I don't think having a
central list of views is really helping us because we expect the views
to be used in ways the system catalogs would not be.

I will develop a proposed patch.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Indecision is a decision.  Inaction is an action.  Mark Batterson