On Tue, Jul 15, 2025 at 04:14:44PM +0100, Dean Rasheed wrote:
> On Tue, 15 Jul 2025 at 04:17, Robert Treat <r...@xzilla.net> wrote:
>> On Mon, Jul 14, 2025 at 3:22 PM David G. Johnston
>> > The pg_overexplain extends EXPLAIN with new options that provide...
>> > Suggest instead:
>> > The pg_overexplain module provides EXPLAIN with new options intended to
>> > assist with debugging of and development of the planner.
>> > (replacing the first two sentences of the existing paragraph)
>>
>> +1 for consistency, though I'd argue "intended to assist with
>> debugging and development of the planner" would be easier to read (in
>> either one sentence or two sentence format).
>
> +1. I find that easier to read.
I disagree. While it might sound nicer, the extra "of" establishes
parallelism to make it clear that the module is intended for debugging of
the planner and not debugging in general. I also see little need to
combine the two sentences. The first establishes at a high-level what the
module does, and the second provides more details. Combining the two as
proposed also loses context, i.e., "provide additional output" and "rather
than for general use" are removed. We could try to retain those pieces,
but then we're just combining two medium-sized sentences into a long one
that is more difficult to read.
FWIW there are counterexamples to the "The XXX module..." pattern, too
(e.g., auth_delay, basebackup_to_shell, basic_archive, bloom). But I'm
fine with using it here since that seems to be the preference.
> Something else that's missing is instructions on how to load the
> module, which usually follows this first paragraph.
Good point. That should probably look something like this, which is mostly
lifted from auto_explain:
To use it, simply load it into the server. You can load it into an
individual session:
LOAD 'pg_overexplain';
(You must be superuser to do that.) You can also preload it into some
or all sessions by including pg_overexplain in
session_preload_libraries or shared_preload_libraries in
postgresql.conf.
As an aside, the superuser note isn't totally true because administrators
can put stuff in $libdir/plugins/ to allow non-superusers to LOAD it.
Maybe we should just remove the superuser note in the module docs.
--
nathan
