Обсуждение: BUG #19042: Option --help not recognized at the end of command line in pg_restore

The following bug has been logged on the website:

Bug reference:      19042
Logged by:          Matthias Hörmann
Email address:      matthias.hoermann@saltation.com
PostgreSQL version: 17.6
Operating system:   Debian bookworm
Description:

When calling pg_restore trying to use --help at the end to see which other
options I might want to specify tells me that --help is an unrecognized
option and I am supposed to run pg_restore --help for more information.

```
# pg_restore --version
pg_restore (PostgreSQL) 17.6 (Debian 17.6-1.pgdg12+1)
# sudo -u postgres pg_restore -f /tmp/redacted_20250903_130108.pg_dump
--help
/usr/lib/postgresql/17/bin/pg_restore: unrecognized option '--help'
pg_restore: hint: Try "pg_restore --help" for more information.
```

> On 3 Sep 2025, at 13:07, PG Bug reporting form <noreply@postgresql.org> wrote:

> When calling pg_restore trying to use --help at the end to see which other
> options I might want to specify tells me that --help is an unrecognized
> option and I am supposed to run pg_restore --help for more information.

This is the intended behaviour, --help (and --version) is parsed specially and
must be the first parameter. We do this for all command line utilities.

--
Daniel Gustafsson

The 2025-09-03 13:45:15, Daniel Gustafsson wrote:
> > On 3 Sep 2025, at 13:07, PG Bug reporting form <noreply@postgresql.org> wrote:
> 
> > When calling pg_restore trying to use --help at the end to see which other
> > options I might want to specify tells me that --help is an unrecognized
> > option and I am supposed to run pg_restore --help for more information.
> 
> This is the intended behaviour, --help (and --version) is parsed specially and
> must be the first parameter. We do this for all command line utilities.
> 
> --
> Daniel Gustafsson
> 

Well, the use-case that comes up quite often for me (for any commands,
not just postgres) is that I add parameters I know or remember from my
last look at --help and then want to check again what else to add, for
that it is useful to be able to use --help as the last parameter.

-- 
Mit freundlichen Grüßen,

Matthias Hörmann

fon: +49 (0) 521 - 329647-29
fax: +49 (0) 521 - 329647-40
email: matthias.hoermann@saltation.com

---------------
saltation GmbH & Co. KG | Stapenhorststraße 42b | 33615 Bielefeld
Sitz Bielefeld | Amtsgericht Bielefeld HRA 15344
Persönlich haftende Gesellschafterin:
saltation Beteiligungs-GmbH | Stapenhorststraße 42b | 33615 Bielefeld
Sitz Bielefeld | Amtsgericht Bielefeld HRB 39339
Geschäftsführer: Daniel Brün
---------------

Wir erfüllen unsere Informationspflichten gem. Artt. 13-14 DS-GVO
durch Veröffentlichung auf unserer Internetseite unter

https://www.saltation.com/de/datenschutzerklaerung.html

oder durch Zusendung auf Ihre formlose Anfrage.

Matthias =?utf-8?Q?H=C3=B6rmann?= <matthias.hoermann@saltation.com> writes:
> The 2025-09-03 13:45:15, Daniel Gustafsson wrote:
>> This is the intended behaviour, --help (and --version) is parsed specially and
>> must be the first parameter. We do this for all command line utilities.

> Well, the use-case that comes up quite often for me (for any commands,
> not just postgres) is that I add parameters I know or remember from my
> last look at --help and then want to check again what else to add, for
> that it is useful to be able to use --help as the last parameter.

FWIW, I agree with this.  While I don't try to do that with PG
utilities (since I know it doesn't work), I frequently rely on that
behavior of our configure script.  I'd be in favor of recognizing
--help (though probably not -?) in any argument position.  Less sure
about --version.

            regards, tom lane

> On 3 Sep 2025, at 16:57, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Matthias =?utf-8?Q?H=C3=B6rmann?= <matthias.hoermann@saltation.com> writes:
>> The 2025-09-03 13:45:15, Daniel Gustafsson wrote:
>>> This is the intended behaviour, --help (and --version) is parsed specially and
>>> must be the first parameter. We do this for all command line utilities.
>
>> Well, the use-case that comes up quite often for me (for any commands,
>> not just postgres) is that I add parameters I know or remember from my
>> last look at --help and then want to check again what else to add, for
>> that it is useful to be able to use --help as the last parameter.
>
> FWIW, I agree with this.

Same here, it's a totally reasonable ask.

> I'd be in favor of recognizing
> --help (though probably not -?) in any argument position.

Any particular reason to restrict -? from this?

> Less sure about --version.

Agreed, I think --version should require being the sole parameter.

--
Daniel Gustafsson

Daniel Gustafsson <daniel@yesql.se> writes:
> On 3 Sep 2025, at 16:57, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> I'd be in favor of recognizing
>> --help (though probably not -?) in any argument position.  

> Any particular reason to restrict -? from this?

I'm not set on that either way.  It just seems like --help is
quite unambiguous and unlikely to be a typo, whereas I'm less
sure about -?.  I won't stand in the way of a consensus to
do this for both.

            regards, tom lane

Hi,

On 2025-09-03 10:57:53 -0400, Tom Lane wrote:
> Matthias =?utf-8?Q?H=C3=B6rmann?= <matthias.hoermann@saltation.com> writes:
> > The 2025-09-03 13:45:15, Daniel Gustafsson wrote:
> >> This is the intended behaviour, --help (and --version) is parsed specially and
> >> must be the first parameter. We do this for all command line utilities.
>
> > Well, the use-case that comes up quite often for me (for any commands,
> > not just postgres) is that I add parameters I know or remember from my
> > last look at --help and then want to check again what else to add, for
> > that it is useful to be able to use --help as the last parameter.
>
> FWIW, I agree with this.  While I don't try to do that with PG
> utilities (since I know it doesn't work), I frequently rely on that
> behavior of our configure script.  I'd be in favor of recognizing
> --help (though probably not -?) in any argument position.  Less sure
> about --version.

I've been annoyed by this behaviour for a long time.

So +many for recognizing --help (and I'd say -?) everywhere, not just as the
first argument. I never understood why we don't do that.

I don't think the argument for --version is particularly strong from a
usability perspective, but I don't see what we gain from parsing --version/-V
differently than we do all the other arguments. It seems best to just handle
--version the same as all the other arguments.

Greetings,

Andres

On 03.09.25 21:34, Andres Freund wrote:
> So +many for recognizing --help (and I'd say -?) everywhere, not just as the
> first argument. I never understood why we don't do that.

I think in the olden days we didn't have universal getopt_long() 
support, so it was hardcoded.  I don't see a problem with changing it.

> I don't think the argument for --version is particularly strong from a
> usability perspective, but I don't see what we gain from parsing --version/-V
> differently than we do all the other arguments. It seems best to just handle
> --version the same as all the other arguments.

Right.  If you try the usual GNU utilities, they handle --help and
--version at any argument position.

> On 10 Sep 2025, at 07:26, Peter Eisentraut <peter@eisentraut.org> wrote:
>
> On 03.09.25 21:34, Andres Freund wrote:
>> So +many for recognizing --help (and I'd say -?) everywhere, not just as the
>> first argument. I never understood why we don't do that.
>
> I think in the olden days we didn't have universal getopt_long() support, so it was hardcoded.  I don't see a problem
withchanging it. 

That's probably an accurate description.  I am writing up a patch to move it
into long option processing to see what it would look like, will share soon.

--
Daniel Gustafsson

On Wed, Sep 10, 2025 at 11:24:36AM +0200, Daniel Gustafsson wrote:
> I am writing up a patch to move it into long option processing to see
> what it would look like, will share soon.

Are you still planning to work on this one?

-- 
nathan

> On 22 Oct 2025, at 23:23, Nathan Bossart <nathandbossart@gmail.com> wrote:
> 
> On Wed, Sep 10, 2025 at 11:24:36AM +0200, Daniel Gustafsson wrote:
>> I am writing up a patch to move it into long option processing to see
>> what it would look like, will share soon.
> 
> Are you still planning to work on this one?

It's mostly done but got bumped off the TODO due to finalizing talk for
PGConf.EU, will send a patch shortly.

--
Daniel Gustafsson

> On 22 Oct 2025, at 23:23, Nathan Bossart <nathandbossart@gmail.com> wrote:
>
> On Wed, Sep 10, 2025 at 11:24:36AM +0200, Daniel Gustafsson wrote:
>> I am writing up a patch to move it into long option processing to see
>> what it would look like, will share soon.
>
> Are you still planning to work on this one?

Attached is a v1 which converts all the apps in the tree to allow version and
help arguments at any position.

There was quite the variety of how the help/version arguments were handled,
some apps had partial support in the longopts, some had full support and some
had none.  The idea was to make handling consistent across the binaries without
introducing any dependencies or build time changes.

While hacking on this it seemed like a good idea to move to using progname
consistently, and reduce scope in some places from global variables, but
looking at it now I'm less convinced.  At the very least it should be ripped
out into its own patch but for now those changes are left in there.

It's far from an exciting patchset but it would be nice to get it done once and
for all.  0002 is a small change to make sure all apps exit with the same code,
I was unable to find a documented rationale for exit(2) so I think it's an
oversight.

--
Daniel Gustafsson

On Sat, Oct 25, 2025 at 12:26:01AM +0200, Daniel Gustafsson wrote:
> While hacking on this it seemed like a good idea to move to using progname
> consistently, and reduce scope in some places from global variables, but
> looking at it now I'm less convinced.  At the very least it should be ripped
> out into its own patch but for now those changes are left in there.

Yeah, that does feel like it ought to be its own patch.  After a
read-through, 0001 looks like the right idea to me, though.  It's a larger
patch, but the majority of the changes are pretty mechanical.

+/* port/pg_option_utils.c */
+extern bool is_help_param(int argc, char *argv[], int optind);

And fe_utils/option_utils.c, right (since it has a copy of this function)?
Or is the idea to use pg_option_utils.c for both the frontend and the
backend?

> It's far from an exciting patchset but it would be nice to get it done once and
> for all.  0002 is a small change to make sure all apps exit with the same code,
> I was unable to find a documented rationale for exit(2) so I think it's an
> oversight.

0002 LGTM

-- 
nathan

> On 27 Oct 2025, at 16:30, Nathan Bossart <nathandbossart@gmail.com> wrote:

Thanks for review!

> On Sat, Oct 25, 2025 at 12:26:01AM +0200, Daniel Gustafsson wrote:
>> While hacking on this it seemed like a good idea to move to using progname
>> consistently, and reduce scope in some places from global variables, but
>> looking at it now I'm less convinced.  At the very least it should be ripped
>> out into its own patch but for now those changes are left in there.
>
> Yeah, that does feel like it ought to be its own patch.

Absolutely agree, will move that out in the next version.

> After a
> read-through, 0001 looks like the right idea to me, though.  It's a larger
> patch, but the majority of the changes are pretty mechanical.

It’s indeed pretty boring, and considering what the patch want to achieve I guess that’s a good thing.

> +/* port/pg_option_utils.c */
> +extern bool is_help_param(int argc, char *argv[], int optind);
>
> And fe_utils/option_utils.c, right (since it has a copy of this function)?
> Or is the idea to use pg_option_utils.c for both the frontend and the
> backend?

I originally placed it in fe_utils but then moved to src/port to avoid adding libpq depesencies where we dont have them
today.If there is a second copy then I missed that in my rebase (am travelling without laptop so cant comfortably read
patchesright now to check). Not sure what the best option is and how big of a deal it is. Do you have any suggestions? 

./daniel

On Mon, Oct 27, 2025 at 09:49:06PM +0200, Daniel Gustafsson wrote:
> I originally placed it in fe_utils but then moved to src/port to avoid
> adding libpq depesencies where we dont have them today. If there is a
> second copy then I missed that in my rebase (am travelling without laptop
> so cant comfortably read patches right now to check). Not sure what the
> best option is and how big of a deal it is. Do you have any suggestions?

Oh.  Unless my eyes deceive me, I think you forgot to remove the fe_utils
one.

-- 
nathan

On 25.10.25 00:26, Daniel Gustafsson wrote:
> While hacking on this it seemed like a good idea to move to using progname
> consistently, and reduce scope in some places from global variables, but
> looking at it now I'm less convinced.  At the very least it should be ripped
> out into its own patch but for now those changes are left in there.

The --version outputs intentionally do not use progname, so that you get 
a proper identification of the program and version independent of what 
the binary might be called.  Please don't change that.

Peter Eisentraut <peter@eisentraut.org> writes:
> On 25.10.25 00:26, Daniel Gustafsson wrote:
>> While hacking on this it seemed like a good idea to move to using progname
>> consistently, and reduce scope in some places from global variables, but
>> looking at it now I'm less convinced.  At the very least it should be ripped
>> out into its own patch but for now those changes are left in there.

> The --version outputs intentionally do not use progname, so that you get
> a proper identification of the program and version independent of what
> the binary might be called.  Please don't change that.

Hmm, that's important institutional knowledge that should be captured
somewhere.

            regards, tom lane

> On 29 Oct 2025, at 17:54, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Peter Eisentraut <peter@eisentraut.org> writes:
>>> On 25.10.25 00:26, Daniel Gustafsson wrote:
>>> While hacking on this it seemed like a good idea to move to using progname
>>> consistently, and reduce scope in some places from global variables, but
>>> looking at it now I'm less convinced.  At the very least it should be ripped
>>> out into its own patch but for now those changes are left in there.
>
>> The --version outputs intentionally do not use progname, so that you get
>> a proper identification of the program and version independent of what
>> the binary might be called.  Please don't change that.

All callsites using handle_help_version_opts were already using progname for —version, this just made it consistent.
Thatbeing said, I can change it to be consistent in the other direction.  

> Hmm, that's important institutional knowledge that should be captured
> somewhere.

Maybe a README in src/bin?

./daniel

On 29.10.25 21:19, Daniel Gustafsson wrote:
> 
> 
>> On 29 Oct 2025, at 17:54, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>
>> Peter Eisentraut <peter@eisentraut.org> writes:
>>>> On 25.10.25 00:26, Daniel Gustafsson wrote:
>>>> While hacking on this it seemed like a good idea to move to using progname
>>>> consistently, and reduce scope in some places from global variables, but
>>>> looking at it now I'm less convinced.  At the very least it should be ripped
>>>> out into its own patch but for now those changes are left in there.
>>
>>> The --version outputs intentionally do not use progname, so that you get
>>> a proper identification of the program and version independent of what
>>> the binary might be called.  Please don't change that.
> 
> All callsites using handle_help_version_opts were already using progname for —version, this just made it consistent.
Thatbeing said, I can change it to be consistent in the other direction.
 

AFAICT, handle_help_version_opts() does this correctly: It takes an 
argument fixed_progname that is used for --version output, while for the 
--help output it uses argv.  And most callers provide a fixed string for 
fixed_progname, but I see that some don't.

>> Hmm, that's important institutional knowledge that should be captured
>> somewhere.
> 
> Maybe a README in src/bin?

Maybe just a better code comment at handle_help_version_opts().