Re: proposal: psql –help reflecting service or URI usage

Hi Euler,

> On 01. Mar, 2021, at 15:42, Euler Taveira <euler(at)eulerto(dot)com> wrote:
>
> We try to limit it to 80 characters but it is not a hard limit. Long descriptions should certainly be split into multiple lines.

got that, thanks.

> The question is: how popular is service and connection URIs?

well, we use them exclusively at work, because we have a lot of Patroni clusters which may fail/switch over and we don't have an haproxy or similar. So our usual way to connect is a URI with targetServerType set.

> We cannot certainly include all possibilities in the --help that's why we have the documentation. IMO we could probably include "connection string" that accepts 2 formats: (i) multiple keyword - value string and URIs ("service" is included in the (i)).
>
> Usage:
> psql [OPTION]... [DBNAME [USERNAME]|CONNINFO]
>
> Usage:
> psql [OPTION]... [DBNAME [USERNAME]]
> psql [OPTION]... [CONNINFO]
>
> Connection options:
> CONNINFO connection string to connect to (key = value strings
> or connection URI)

I could live with the second variant, though I'd still prefer two descriptions, one "service=name" and the second for the URI, as I initially suggested.

> It might be a different topic but since we are talking about --help improvements, I have some suggestions:
>
> * an Example section could help newbies to Postgres command-line tools to figure out how to inform the connection parameters. In this case, we could include at least 3 examples: (i) -h, -p, -U parameters, (ii) key/value connection string and (iii) connection URI.

there's an example in the USAGE/Connecting to a Database section of the man page already. Also, it is documented how an URI works, so I wouldn't include an example here. Just reflecting its existence in the syntax should do. Same goes for service names.

> * Connection options could be moved to the top (maybe after General options) if we consider that it is more important than the other sections (you cannot probably execute psql without using a connection parameter in production).

moving it up is IMHO merely a matter of personal taste. Making sure it's there was my initial point.

But as Mark pointed out, there's too much linked to it for me (man pages, docs, etc.). So I drop the proposal altogether. Thanks for you thoughts anyway.

Now we at least have this topic finally in the mail archives. ;-)

P.S.: Just curious, why do you right-pad your posts?

Cheers,
Paul