Thread: Patch for listing runtime option details through server executable (pg_guc)

The attached patch adds the --long-help option to the server executable.
This option displays all the available runtime options for that
particular server version, along with Max, Min and Reset values if
applicable and a description. It also groups the runtime options
together in accordance with the documentation.

--long-help -h provides details, (including):

With no options specified, it will output all available runtime options
in human friendly format, grouped by category and sorted by name.

Usage:
  Usage for --long-help option: [-g <group>] [-h] [-H] [-G] [-l]
[string]


General Options:
  [string]      All options with names that match this string
  -g GROUP      All options in categories that match GROUP
  -G            Do not sort output, by group or name

Output Options:
  -m            Machine friendly format. All fields are tab separated.
  -M            Same as m, except header with column names is suppressed
  -l            Prints list of all currently defined groups \ subgroups
  -h            Prints this help message


The human readable option can be used to help manually configure the
postgresql.conf file, while the machine readable format can be used by
server side utilities to help configure GUC variables. (for example a
GUI, for which this was created)


Thanks,
Aizaz Ahmed


Attachments
-----------
patch file: pg_guc.patch,
new files: src/include/utils/guc_vars.h, /src/include/utils/pg_guc.h,
src/backend/utils/misc/pg_guc.c

To be applied to 7.4 devel.

Aizaz Ahmed writes:

> The attached patch adds the --long-help option to the server executable.

Conceptual comments:

If the option is named --long-help, I'd expect a longer version of
--help, which this is not.  The name should probably involve "help"
and "config" to make it clearer what you get.  (Personally, I think
"help" should go before the qualifying word, but there may be other
opinions.)

Do we really want to encode the notion of option categories into the
source code?  This looks like a pretty large burden to me.  Organizing
the documentation or the sample files in user-friendly ways is one
thing, but if I need to organize the code and new options along those
lines, I'm not sure.

If, on the other hand, we like the code to know about categories,
should this code be capable of generating the sample file
automatically?

I don't think we need two different machine formats -m and -M.  The
machine isn't going to need the column headers anyway.

The help message should be printed by --help, not -h.  In fact, I
don't think there should be a separate subhelp message.  Users know
about --help, and that should give them all information about all
invocation modes right there.

Code comments:

To mark up string literals, where you use translatable(), there is
already a standard function gettext_noop() available.

When inserting lines into an existing help message, please observe the
style conventions (capitalization, punctuation, etc.) of the
surrounding lines.

There is already a file guc.c, why should there be a file pg_guc.c
now?  That doesn't make sense; the names should be differentiated
better.

Why have various things been moved from guc.h to guc_vars.h, which
seems to just split things up uselessly?

Why are there long explanations in some cases only?  Do you plan to
add others later?  I also think the messages should be made more
consistent in various ways, but that can be done later.

Should options not for general use (e.g., session_auth_is_superuser)
be hidden from this tool?  Are they?  What other provisions of this
kind does this tool make?

The GucContext_names are not translatable.  They aren't English words
either.

--
Peter Eisentraut   peter_e@gmx.net

Peter Eisentraut <peter_e@gmx.net> writes:
> If the option is named --long-help, I'd expect a longer version of
> --help, which this is not.  The name should probably involve "help"
> and "config" to make it clearer what you get.  (Personally, I think
> "help" should go before the qualifying word, but there may be other
> opinions.)

Yeah, I haven't thought of a real satisfactory name either.  Do you
like "--help-config"?

> If, on the other hand, we like the code to know about categories,
> should this code be capable of generating the sample file
> automatically?

There was something about that in the back of the mind, but I'd prefer
to take that as a long-term goal rather than try to make it happen
right now.

> To mark up string literals, where you use translatable(), there is
> already a standard function gettext_noop() available.

Ah.  The translatable() was my suggestion --- I'd forgotten we had
another macro already defined.  (But why doesn't nls.mk mention it?
Or is that name built into the gettext tools?)

> There is already a file guc.c, why should there be a file pg_guc.c
> now?  That doesn't make sense; the names should be differentiated
> better.

The name pg_guc.c is left over from the original intent of having
a standalone tool named pg_guc.  We could fold it together with
guc.c, but I think it is cleaner to keep it as a separate file.
If you have a better name for it, that's fine with me...

> Why have various things been moved from guc.h to guc_vars.h, which
> seems to just split things up uselessly?

So that pg_guc.c can get at the constant tables in guc.c.  Admittedly,
this would go away if we fold the two together, but I think that's
the wrong thing.  pg_guc is still a small standalone program in concept
;-) ... it is just sharing an executable with the backend.

> Why are there long explanations in some cases only?  Do you plan to
> add others later?  I also think the messages should be made more
> consistent in various ways, but that can be done later.

Yeah, I had some editorializing to do too.  This is not on the critical
path though.

> Should options not for general use (e.g., session_auth_is_superuser)
> be hidden from this tool?  Are they?  What other provisions of this
> kind does this tool make?

The original intent of the standalone tool was to display stuff that
could usefully be set in postgresql.conf, and I think it's important
to maintain that as an available behavior (though I wouldn't object
to making other subsets available as well).  The patch includes a
couple more flag bits to try to identify the behaviors of various
variables.  (I've not checked Aizaz' settings for the flags though,
there might be some mistakes.)

            regards, tom lane

Quoting Tom Lane <tgl@sss.pgh.pa.us>:

> > Should options not for general use (e.g., session_auth_is_superuser)
> > be hidden from this tool?  Are they?  What other provisions of this
> > kind does this tool make?
>
> The original intent of the standalone tool was to display stuff that
> could usefully be set in postgresql.conf, and I think it's important
> to maintain that as an available behavior (though I wouldn't object
> to making other subsets available as well).  The patch includes a
> couple more flag bits to try to identify the behaviors of various
> variables.  (I've not checked Aizaz' settings for the flags though,
> there might be some mistakes.)

There are two new flags as part of this patch, NOT_IN_SAMPLE_CONF and
DISALLOW_IN_CONF_FILE.

NOT_IN_SAMPLE_CONF are all the options that do not appear in
postgres.conf.sample, a subset of these variables may also be marked
DISALLOW_IN_CONF_FILE, indicating that it should not be possible to set them in
the conf file at all, (even though they can be set at runtime), for example:
server_encoding, server_version etc.

Options marked as NOT_IN_SAMPLE_CONF, DISALLOW_IN_SAMPLE_CONF_FILE, or
GUC_NO_SHOW_ALL, are not displayed by --long-help (or it's new named
counterpart), unless the variable is specifically asked for. So for example,
'postmaster --long-help server_version', would display information about
server_version, although a general listing, 'postmaster --long-help' would not.

I set these flags as best I could with my limited knowledge of each option, it's
possible that some of them may be set incorrectly.

Thanks for all the comments,
Aizaz