Docs pg_restore: Shouldn't there be a note about -n ?

I’m in the process of trying to restore some PG15/16 backups in PG17.

While playing with different -t and -n combinations I was browsing through the docs.

In pg_restore there are two notes about both -t / -n

> When -n / -t is specified, pg_dump makes no attempt to ...

In pg_dump though there’s the equivalent note only for the -t option.

Shouldn’t it be a note as well for -n ?

Otherwise I would expect -n to cascade the restore to objects in other schemas;
Which I don’t think it does.

Am I missing something?

On Sat, Sep 21, 2024 at 8:34 PM Florents Tselai <florents(dot)tselai(at)gmail(dot)com>
wrote:

> I’m in the process of trying to restore some PG15/16 backups in PG17.
>
> While playing with different -t and -n combinations I was browsing through
> the docs.
>
> In *pg_restore* there are two notes about both -t / -n
>
> > When -n / -t is specified, pg_dump makes no attempt to ...
>
> In pg_dump though there’s the equivalent note only for the -t option.
>
> Shouldn’t it be a note as well for -n ?
>
> Otherwise I would expect -n to cascade the restore to objects in other
> schemas;
> Which I don’t think it does.
>
> Am I missing something?
>

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 ?

Florents Tselai <florents(dot)tselai(at)gmail(dot)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(at)sss(dot)pgh(dot)pa(dot)us> wrote:
>
> Florents Tselai <florents(dot)tselai(at)gmail(dot)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 Sat, Sep 21, 2024 at 9:48 PM Florents Tselai <florents(dot)tselai(at)gmail(dot)com>
wrote:

>
>
> > On 21 Sep 2024, at 9:22 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> >
> > Florents Tselai <florents(dot)tselai(at)gmail(dot)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”
>
>
Attached an idea.
The A/B example may be wordy / redundant,
but the -e note on the distinction between installing binaries / creating
an extension I think it's important.

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/

On Sun, 26 Oct 2025 at 05:32, Álvaro Herrera <alvherre(at)kurilemu(dot)de> wrote:
>
> On 2024-Sep-26, Florents Tselai wrote:
> > 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.

This seems to be waiting on Florents. I've adjusted the CF entry to
reflect that.

Florents, are you planning on coming back to this?

David

On Mon, Jan 5, 2026 at 1:25 AM David Rowley <dgrowleyml(at)gmail(dot)com> wrote:

> On Sun, 26 Oct 2025 at 05:32, Álvaro Herrera <alvherre(at)kurilemu(dot)de> wrote:
> >
> > On 2024-Sep-26, Florents Tselai wrote:
> > > 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.
>
> This seems to be waiting on Florents. I've adjusted the CF entry to
> reflect that.
>
> Florents, are you planning on coming back to this?
>

Thanks for pushing.

I consolidated the dependency warnings into the main "Notes" section for
both pg_dump and pg_restore, removing the repetitive per-switch notes.

For the -e switch in pg_dump, I replaced the removed dependency note
with a specific warning that extension installation files (shared libs,
control files) are not included.
I agree that maintaining a specific note for -e is the right move.
Given the broad usage of pg_dump, it is helpful to be explicit that the
dump only captures the SQL definitions and not the underlying system
binaries.

On 2026-Jan-05, Florents Tselai wrote:

> I consolidated the dependency warnings into the main "Notes" section for
> both pg_dump and pg_restore, removing the repetitive per-switch notes.
>
> For the -e switch in pg_dump, I replaced the removed dependency note
> with a specific warning that extension installation files (shared libs,
> control files) are not included.
> I agree that maintaining a specific note for -e is the right move.
> Given the broad usage of pg_dump, it is helpful to be explicit that the
> dump only captures the SQL definitions and not the underlying system
> binaries.

Makes sense. I have pushed this.

I just noticed though, that the issue in pg_restore applies not only to
the -n and -t switches, but also to -L (where you specify a file with a
list of objects to restore) and --filter. Maybe we can this new
paragraph mention that as well.

--
Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/
"No renuncies a nada. No te aferres a nada."