Re: [Doc] pg_restore documentation didn't explain how to use connection string

Hi all,

It seems my approach was quite candid because, of all postgres client
applications, some document usage of connection string whereas other don't.
Then, several ways of using connection strings are involved.

Here is a little digest:

| Postgres Client Application | Connection string syntax
| Documented ? |
|-----------------------------|------------------------------------------------------------------------------------|--------------|
| clusterdb | clusterdb -d <connection_string> or
clusterdb <connection_string> | No |
| createdb | createdb --maintenance-db
<connection_string> | No |
| createuser | Couldn't find if possible
| No |
| dropdb | dropdb --maintenance-db
<connection_string> | No |
| dropuser | Couldn't find if possible
| No |
| pg_basebackup | pg_basebackup -d <connection_string>
| Yes |
| pgbench | Couldn't find if possible
| No |
| pg_dump | pg_dump -d <connection_string>
| Yes |
| pg_dumpall | pg_dumpall -d <connection_string>
| Yes |
| pg_isready | pg_isready -d <connection_string>
| Yes |
| pg_receivewal | pg_receivewal -d <connection_string>
| Yes |
| pg_recvlogical | pg_recvlogical -d <connection_string>
| Yes |
| pg_restore | pg_restore -d <connection_string>
| No |
| psql | psql <connection_string> or psql -d
<connection_string> | Yes |
| reindexdb | reindexdb -d <connection_string> or
reindexdb --maintenance-db <connection_string> | No |
| vacuumdb | vacuumdb -d <connection_string> or vacuumdb
--maintenance-db <connection_string> | No |

And here are some statistics about connection string usage:

| | Number of tool using that syntax |
|------------------|----------------------------------|
| No switch | 2 |
| -d | 11 |
| --maintenance-db | 4 |

- Both tools that allow connection strings without strings also allow the
-d switch.
- From the 4 tools that use the --maintenance-db switch, only 2 won't allow
the -d switch. Those don't have a -d switch now.

Given that, I think it would be a good thing to generalize the -d switch
(and maybe the --maintenance-db switch too).

What do you think ?

Cheers,

Lætitia

Le mar. 30 avr. 2019 à 19:10, Lætitia Avrot <laetitia(dot)avrot(at)gmail(dot)com> a
écrit :

> Hi all,
>
> I'm a big fan a service file to connect to PostgreSQL client applications.
> However I know just a few people use them.
>
> I ran into an issue today: I wanted to user pg_restore with my service
> file and couldn't find a way to do so.
>
> Documentation didn't help. It was all about "basic" options like providing
> host, port, user and database... Nothing about how to connect using a
> connection string.
>
> I tried `pg_restore service=my_db <other options> <dumpfile>`, but it
> didn't work. `pg_restore` complaining about too many arguments.
>
> I had to ask people or IRC to find out that the `-d` switch accepted
> connection strings.
>
> It's really disturbing because :
> - It's undocumented
> - It doesn't work the way it works with the other PostgreSQL client
> applications (For example, `pg_dump` will accept `pg_dump service=my_db
> <other_options>`)
>
> ***I write a quick patch to document that feature***, but maybe we could
> go further. I suggest :
>
> - Creating a "Connection Options" section before the other options (as the
> synopsis is pg_restore [*connection-option*...] [*option*...] [*filename*]
> )
> - Put all connection parameters here (including the -d switch witch is
> somehow in the middle of the other options
> - Change other PostgreSQL client application documentation accordingly
> - As a bonus, I'd like pg_restore to accept connection strings just as
> other client accept them (without a switch), but maybe it's too difficult
>
> Could you please tell me what you think about it before I make such a huge
> change ?
>
> Cheers,
>
> Lætitia
> --
> *Paper doesn’t grow on trees. Please print responsibly.*
>

--
*Paper doesn’t grow on trees. Please print responsibly.*