Re: [Doc] pg_restore documentation didn't explain how to useconnection string - Mailing list pgsql-hackers

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.avrot@gmail.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.