On Wed, Mar 05, 2025 at 09:35:27AM -0600, Nathan Bossart wrote: > On Wed, Mar 05, 2025 at 01:52:40PM +0100, Magnus Hagander wrote: >> Another option that I think would also work is to just cut down the details >> to just "The <option>--jobs</option> option allows multiple CPU cores to be >> used". > > That's fine with me. It's probably not particularly actionable > information, anyway. If anything, IMHO we should make it clear to users > that the parallelization is per-database (except for file transfer, which > is per-tablespace). If you've just got one big database in the default > tablespace, --jobs won't help. > >> I think this is also slightly confusing, but maybe that's a >> non-native-english thing: "a good place to start is the maximum of the >> number of CPU cores and tablespaces.". Am I supposed to set it to >> max(cpucores, ntablespaces) or to max(cpucores+ntablespaces)? > > I've always read it to mean the former. But I'm not sure that's great > advice. If you have 8 cores and 100 tablespaces, does it make sense to use > --jobs=100? Ordinarily, I'd suggest the number of cores as the starting > point.
Here's another attempt at the patch based on the latest discussion. -- nathan
>From e7f8633672530fb06dac72271cda429ad873a640 Mon Sep 17 00:00:00 2001 From: Nathan Bossart <nat...@postgresql.org> Date: Wed, 5 Mar 2025 10:19:27 -0600 Subject: [PATCH v2 1/1] doc: Adjust note about pg_upgrade's --jobs option. Reported-by: Magnus Hagander <mag...@hagander.net> Reviewed-by: ??? Discussion: https://postgr.es/m/Z8dBn_5iGLNuYiPo%40nathan --- doc/src/sgml/ref/pgupgrade.sgml | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index 6ca20f19ec2..10911d81174 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -565,12 +565,11 @@ NET STOP postgresql-&majorversion; </para> <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 - CPU cores and tablespaces. This option can dramatically reduce the - time to upgrade a multi-database server running on a multiprocessor - machine. + Setting <option>--jobs</option> to 2 or higher allows pg_upgrade to + process multiple databases and tablespaces in parallel. A good starting + point is the number of CPU cores on the machine. This option can + substantially reduce the upgrade time for multi-database and + multi-tablespace servers. </para> <para> -- 2.39.5 (Apple Git-154)
