The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/15/libpq-connect.html
Description:
Hi folks,
I feel like I'm going in circles trying to square `psql` options (15: psql)
with connection service file parameters (15: 34.17). I've lost exactly
which page I started on, but it was something like this...
- I start at https://www.postgresql.org/docs/15/app-psql.html
- Under "Options"
-c _command_ shows that I can run an arbitrary command on connection.
Great!
- But I'd like to specify something similar in the pg_service file, so I
look up I look up the Connection Service File, section 34.17 -
https://www.postgresql.org/docs/15/libpq-pgservice.html
- So far, so good. The "parameters are connection parameters; see [Section
34.1.2](https://www.postgresql.org/docs/15/libpq-connect.html#LIBPQ-PARAMKEYWORDS)
for a list."
- Following that link, I scroll down to the key word "options" which
"Specifies command line options" presumably like those for psql. Then it
says "For a detailed discussion of the available options, consult [Chapter
20](https://www.postgresql.org/docs/15/runtime-config.html)."
- Suddenly, I don't know why I'm in "Server Configuration" (Chapter 20).
Sure, it is a TOC with sections that document options, but mostly only
relevant to a superuser.
- I thought I'd get a list of options valid as arguments to the
'options' keyword. What am I suddenly doing here? It seems an odd landing
point for the link.
What I have found particularly confusing is some of the keywords for the
pg_service file clearly duplicate the options for `psql` but some of them
are equivalent, but not identical keywords (eg, `psql --username` vs
pg_service.conf keyword 'user'). Are both valid, or are they restricted to
their respective realm? (That's a question I'm asking the documentation to
answer, not a question I'm directly asking you.)
There is also no particularly clear connection between psql options and the
connection service file; it's even hard to find where the app-psql.html page
indicates that using a service name in conjunction with a connection service
file can make invoking psql so much easier :- )
Additionally, since the concepts are so similar to each other, and the pages
are reasonable long, it's easy to lose track of exactly which piece of
documentation I am looking at for which feature. (not an easy problem to
solve there, just an additional curveball)
Hopefully, I've kept this all objective, and not let any of my frustration
spill out; if I did, that certainly wasn't my intention!
Thanks for all your work,
-Randall