Thread: Not clear sentence
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/14/backup-dump.html Description: URL: https://www.postgresql.org/docs/current/backup-dump.html Text: This is necessary to fully backup the cluster if running the pg_dump command on individual databases. Please provide an explanation or re-write the same, thanks.
On Thu, 2022-01-20 at 19:46 +0000, PG Doc comments form wrote: > Page: https://www.postgresql.org/docs/14/backup-dump.html > Description: > > Text: This is necessary to fully backup the cluster if running the pg_dump > command on individual databases. > > Please provide an explanation or re-write the same, thanks. Hm, yes, that could be improved. Perhaps: This is required for a full backup of the cluster that is performed by pg_dump on the individual databases. Yours, Laurenz Albe
On Fri, Jan 21, 2022 at 5:37 AM Laurenz Albe <laurenz.albe@cybertec.at> wrote:
On Thu, 2022-01-20 at 19:46 +0000, PG Doc comments form wrote:
> Page: https://www.postgresql.org/docs/14/backup-dump.html
> Description:
>
> Text: This is necessary to fully backup the cluster if running the pg_dump
> command on individual databases.
>
> Please provide an explanation or re-write the same, thanks.
Hm, yes, that could be improved. Perhaps:
This is required for a full backup of the cluster that is performed
by pg_dump on the individual databases.
I don't see a problem with the existing wording. And as the OP hasn't really described what is confusing them it is difficult to contemplate a rewrite that would remove that confusion.
The sentence means that one must run pg_dumpall --globals-only (that is what "this" is referring to without doubt) and add the result to their backup (implied by the wording "necessary to fully backup"; this data is missing...) if their backup routine consists of backing up individual databases using the pg_dump command (exact wording).
If anything, whether one chooses to backup all databases in a cluster individually using pg_dump is immaterial. Any single database backed up using pg_dump is incomplete if it is restored into an empty cluster. One must also restore the globals into that cluster first to produce a valid restoration of that database. The existing wording implies as much (and we rightly assume restoration into a freshly initialized cluster) so still no word-smithing seems needed here.
But hopefully the OP is less confused now.
David J.
Thanks David for the explanation - balancing between TLDR and simplistic.
Those two sentences (from David) make easier to read and understand.
On Jan 21, 2022, at 10:05 AM, David G. Johnston <david.g.johnston@gmail.com> wrote:On Fri, Jan 21, 2022 at 5:37 AM Laurenz Albe <laurenz.albe@cybertec.at> wrote:On Thu, 2022-01-20 at 19:46 +0000, PG Doc comments form wrote:
> Page: https://www.postgresql.org/docs/14/backup-dump.html
> Description:
>
> Text: This is necessary to fully backup the cluster if running the pg_dump
> command on individual databases.
>
> Please provide an explanation or re-write the same, thanks.
Hm, yes, that could be improved. Perhaps:
This is required for a full backup of the cluster that is performed
by pg_dump on the individual databases.I don't see a problem with the existing wording. And as the OP hasn't really described what is confusing them it is difficult to contemplate a rewrite that would remove that confusion.The sentence means that one must run pg_dumpall --globals-only (that is what "this" is referring to without doubt) and add the result to their backup (implied by the wording "necessary to fully backup"; this data is missing...) if their backup routine consists of backing up individual databases using the pg_dump command (exact wording).If anything, whether one chooses to backup all databases in a cluster individually using pg_dump is immaterial. Any single database backed up using pg_dump is incomplete if it is restored into an empty cluster. One must also restore the globals into that cluster first to produce a valid restoration of that database. The existing wording implies as much (and we rightly assume restoration into a freshly initialized cluster) so still no word-smithing seems needed here.But hopefully the OP is less confused now.David J.