Re: PG 18 release notes draft committed - Mailing list pgsql-hackers

On Sun, May  4, 2025 at 10:41:30PM +0900, Atsushi Torikoshi wrote:
> > I will continue improving it until beta 1, and until the final release.
> > I will probably add markup in 1-3 weeks.  Let the feedback begin.  ;-)
> 
> Thanks for your work!
> 
> > Add REJECT_LIMIT to control the number of invalid rows COPY IN can ignore (Atsushi Torikoshi)
> 
> Since REJECT_LIMIT cannot be used with COPY IN but can be used with
> COPY FROM, I think "IN" should be "FROM".
> 
>   =# COPY t1 TO '/tmp/a' WITH (REJECT_LIMIT 3);
>   ERROR:  COPY REJECT_LIMIT requires ON_ERROR to be set to IGNORE
>   =# COPY t1 TO '/tmp/a' WITH ( ON_ERROR ignore, REJECT_LIMIT 3);
>   ERROR:  COPY ON_ERROR cannot be used with COPY TO
>   LINE 1: COPY t1 to '/tmp/a' WITH (ON_ERROR ignore, REJECT_LIMIT 3);

Agreed.  A PG 18 commit had "COPY IN" and I ended up using that, even
though we have no COPY IN but only COPY FROM.  Fixed in all placed.

> > This is active when ON_ERROR = 'ignore'.
> 
> As a non-native English speaker, I may be misunderstanding this, but
> the word "active" might suggest that REJECT_LIMIT always takes effect
> by default, causing the COPY operation to stop after a certain number
> of errors.
> However, in reality, REJECT_LIMIT does not have any effect by default
> — unless explicitly set, there is no limit on the number of rows that
> can be skipped when ON_ERROR is set to ignore.
> To avoid this potential confusion, a phrasing like:
> 
>   This option must be used with ON_ERROR ignore.
> 
> might be clearer.

Uh, that might suggest you have to use REJECT_LIMIT with ON_ERROR, which
is untrue.  I used:

    This is available when ON_ERROR = 'ignore'.

> Also, in the v17 release notes, COPY option values are not enclosed in
> single quotes but written in <literal> tag.
> For consistency, it might be better to follow the same style in the
> v18 notes as well.
> 
>   -- https://www.postgresql.org/docs/current/release-17.html
>   Add new COPY option ON_ERROR ignore to discard error rows
>   The default behavior is ON_ERROR stop

The quotes will be removed when I add XML markup in 1-3 weeks.

> > Add COPY log_verbosity level "silent" to suppress all log output (Atsushi Torikoshi)
> 
> Similarly, in the v17 release notes, the log_verbosity option was
> written in uppercase (LOG_VERBOSITY).
>
> For consistency, it may be preferable to use the same case formatting
> in this entry as well.
> 
>   -- https://www.postgresql.org/docs/current/release-17.html
>   Add new COPY option LOG_VERBOSITY which reports COPY FROM ignored error rows

Same.

> Also, the phrase "suppress all log output" may be slightly misleading.
> Even with log_verbosity = 'silent', COPY still outputs logs — it only
> suppresses log messages related to skipped rows when ON_ERROR ignore
> is used.
> It might help to clarify this nuance to avoid confusion.
> For example, how about "Add COPY LOG_VERBOSITY silent to suppress logs
> related to skipped rows"?

I went with:

    Add COPY LOG_VERBOSITY level "silent" to suppress log output of ignored rows

because the docs call them "ignored" rows rather than "skipped" rows. 

> > Add on_error and log_verbosity options to file_fdw (Atsushi Torikoshi)
> > Add REJECT_LIMIT to control the number of invalid rows file_fdw can ignore (Atsushi Torikoshi)
> > This is active when ON_ERROR = 'ignore'.
> 
> The case of option names for file_fdw is inconsistent — some are
> lowercase (on_error, log_verbosity), while others use uppercase
> (REJECT_LIMIT, ON_ERROR).
> For consistency, it might be better to standardize the option names
> throughout the release notes.
> Since the file_fdw documentation consistently uses lowercase for all
> options, using lowercase in the release notes as well might feel more
> natural.

Case changed.  Patch attached.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Do not let urgent matters crowd out time for investment in the future.