Обсуждение: Docs pg_restore: Shouldn't there be a note about -n ?

Florents Tselai <florents.tselai@gmail.com> writes:
> Ah,  swapped them by mistake on the previous email:
> They're both available in the pg_dump and note on -n missing in pg_restore.
> The question remains though:
> Shouldn’t there be a note about -n in pg_restore ?

Probably.  I see that pg_dump has a third copy of the exact same
note for "-e".  pg_restore lacks that switch for some reason,
but this is surely looking mighty duplicative.  I propose getting
rid of the per-switch Notes and putting a para into the Notes
section, along the lines of

    When -e, -n, or -t is specified, pg_dump makes no attempt to dump
    any other database objects that the selected object(s) might
    depend upon. Therefore, there is no guarantee that the results of
    a selective dump can be successfully restored by themselves into a
    clean database.

and mutatis mutandis for pg_restore.

            regards, tom lane

> On 21 Sep 2024, at 9:22 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Florents Tselai <florents.tselai@gmail.com> writes:
>> Ah,  swapped them by mistake on the previous email:
>> They're both available in the pg_dump and note on -n missing in pg_restore.
>> The question remains though:
>> Shouldn’t there be a note about -n in pg_restore ?
>
> Probably.  I see that pg_dump has a third copy of the exact same
> note for "-e".  pg_restore lacks that switch for some reason,
> but this is surely looking mighty duplicative.  I propose getting
> rid of the per-switch Notes and putting a para into the Notes
> section, along the lines of
>
>    When -e, -n, or -t is specified, pg_dump makes no attempt to dump
>    any other database objects that the selected object(s) might
>    depend upon. Therefore, there is no guarantee that the results of
>    a selective dump can be successfully restored by themselves into a
>    clean database.

Agree with that, but I think there should be a pointer like “see Notes” .
Otherwise I’m pretty sure most would expect pg doing magic.
Can’t remember I scrolledl to the bottom of a page “notes” after finding the option I want.

I would also add an example of what “depend upon” means,
To underline that it’s really not that uncommon.
Something like:
“If you pg_dump only with -t A and A has foreign key constraints to table B,
Those constraints won’t succeed If B has not been already restored”



>
> and mutatis mutandis for pg_restore.
>
>             regards, tom lane

On 2024-Sep-26, Florents Tselai wrote:

> Attached an idea.
> The A/B example may be wordy / redundant,

Yeah, it seems a little wordy to me, how about something like the
attached?

> but the -e note on the distinction between installing binaries / creating
> an extension I think it's important.

Hmm, ok, but I think that's a slightly unrelated topic because the shlib
is not a database object.  Maybe it would be more appropriate to add a
mention of this directly in the docs for -e instead of trying to cram it
in the note about other database objects.  I'll wait for you to propose
something for that part.

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/