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