On Thursday 12 February 2009 17:41:01 Peter Eisentraut wrote:
> I know we've already had a discussion on the naming of the pg_restore -m
> option, but in any case this description in pg_restore --help is confusing:
>
> -m, --multi-thread=NUM use this many parallel connections to restore
>
> Either it is using that many threads in the client, or it is using that
> many connections to the server. I assume the implementation does
> approximately both, but we should be clear about what we promise to the
> user. Either: Reserve this many connections on the server. Or: Reserve
> this many threads in the kernel of the client. The documentation in the
> reference/man page is equally confused.
>
> Also, the term "multi" is redundant, because whether it is multi or single
> is obviously determined by the value of NUM.
After reviewing the discussion and the implementation, I would say "workers"
would be the best description of the feature, but unfortunately the options -w
or -W are not available. I'd also avoid -n or -N for "num..." because pg_dump
already uses -n and -N for something else, and we are now trying to avoid
inconsistent options between these programs. Also, option names usually don't
start with units (imagine --num-shared-buffers or --num-port).
While I think "jobs" isn't a totally accurate description, I would still
propose to use -j/--jobs for the option name, because it is neutral about the
implementation and has a strong precedent as being used to increase the
parallelization to get the work done faster. I also noticed that Andrew D.
used "jobs" in his own emails to comment on the feature. :-)
The attached patch also updated the documentation to give some additional
advice about which numbers to use.
