Magnus noted to me off-list that the "et cetera" in the following sentence
in pg_upgrade's docs is doing quite a bit of heavy lifting:
The --jobs option allows multiple CPU cores to be used for
copying/linking of files, dumping and restoring database schemas in
parallel, etc.; a good place to start is the maximum of the number of
CPU cores and tablespaces.
I added the "et cetera" in commit 40e2e5e92b to cover the many follow-up
commits that parallelized various pg_upgrade tasks. I was initially
worried that trying to list all the parallelized stuff would be too
verbose, but looking again, I think all the changes can be grouped into
"gathering cluster information" and "performing cluster checks." The
attached patch replaces the "et cetera" with those two general categories.
--
nathan
>From 23c5a41c0b7a61433b1cd0e6315b9c4bbc536608 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nat...@postgresql.org>
Date: Tue, 4 Mar 2025 11:52:45 -0600
Subject: [PATCH v1 1/1] doc: Expand note about pg_upgrade's --jobs option.
Commit 40e2e5e92b and several follow-up commits parallelized many
pg_upgrade tasks but did not add much detail to the documentation.
This commit expands the existing note for --jobs to include the
general categories of newly-parallelized tasks.
Reported-by: Magnus Hagander <mag...@hagander.net>
Discussion: ???
---
doc/src/sgml/ref/pgupgrade.sgml | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 7bdd85c5cff..18c71355085 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -534,8 +534,9 @@ NET STOP postgresql-&majorversion;
<para>
The <option>--jobs</option> option allows multiple CPU cores to be used
- for copying/linking of files, dumping and restoring database schemas
- in parallel, etc.; a good place to start is the maximum of the number of
+ for copying/linking of files, dumping and restoring database schemas,
+ gathering cluster information, and performing cluster checks;
+ a good place to start is the maximum of the number of
CPU cores and tablespaces. This option can dramatically reduce the
time to upgrade a multi-database server running on a multiprocessor
machine.
--
2.39.5 (Apple Git-154)
