Re: `pg_restore --if-exists` clarification

On Thu, Sep 28, 2023, 05:52 PG Doc comments form <noreply@postgresql.org>
wrote:

> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/16/app-pgrestore.html
> Description:
>
> Good Morning,
>
> In the `pg_restore` docs
> (https://www.postgresql.org/docs/current/app-pgrestore.html),
> `--if-exists`
> states that it is to
>
> > Use conditional commands (i.e., add an IF EXISTS clause)
> > to drop database objects. This option is not valid unless
> > --clean is also specified.", but not being a SQL expert,
> > I'm having a hard time deciphering this.
>
> Suggestion: Would you consider adding the sentence (or something similar)?
>
> > "--clean makes pg_restore drop all objects first,
> > and --if-exists prevents that non-existent objects
> > cause a failure."
> Source: https://stackoverflow.com/a/75136163/1498178
>
> This is succinct, and tells exactly what one needs to know. Thank you and
> have a great day!
>
> Appreciatively,
> Attila
>

But "failure" is not what happens.  If you read the part regarding --clean,
you will see that it says:

(Unless --if-exists is used, this might generate some *harmless error
messages*, if any objects were not present in the destination
database.) *[emphasis
added]*
with extra emphasis on the word "harmless" --  no failure is caused; the
restore proceeds just fine.
If anything were to change in this regard, it might be better to reconsider
what we call the message (i.e.what language pg_restore emits in this
scenario.)  It's true, I suppose, in a literal sense that it's an error in
that pg_restore couldn't drop a table when instructed to, where no such
table exists.  But pragmatically it doesn't matter, so why not reclassify
this as a "warning" or a "notice"?
--Kirk

>