Date: Sun, 4 May 2025 22:36:33 -0400
From: Bruce Momjian <bruce@momjian.us>
To: Atsushi Torikoshi <torikoshia.tech@gmail.com>
Cc: PostgreSQL-development <pgsql-hackers@lists.postgresql.org>
Subject: Re: PG 18 release notes draft committed
Message-ID: <aBgkMf_sstOe32cI@momjian.us>
References: <aBQxop9YxQDad8-W@momjian.us>
 <CAM6-o=CEF6tKAjtGMEOd45YySwNRXPu8d_zyYq=fhnia9hOU6Q@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="5Fg/N0Lz9g11MB63"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: 
 <CAM6-o=CEF6tKAjtGMEOd45YySwNRXPu8d_zyYq=fhnia9hOU6Q@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/aBgkMf_sstOe32cI%40momjian.us>
Precedence: bulk


--5Fg/N0Lz9g11MB63
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

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.

--5Fg/N0Lz9g11MB63
Content-Type: text/x-diff; charset=utf-8
Content-Disposition: attachment; filename="master.diff"
Content-Transfer-Encoding: 8bit

diff --git a/doc/src/sgml/release-18.sgml b/doc/src/sgml/release-18.sgml
index 764c929823f..6054df4f818 100644
--- a/doc/src/sgml/release-18.sgml
+++ b/doc/src/sgml/release-18.sgml
@@ -111,7 +111,7 @@ Author: Tom Lane <tgl@sss.pgh.pa.us>
 
 <listitem>
 <para>
-Prevent COPY IN from treating \. as an end-of-file marker when reading CSV files (Daniel Vérité, Tom Lane)
+Prevent COPY FROM from treating \. as an end-of-file marker when reading CSV files (Daniel Vérité, Tom Lane)
 <ulink url="&commit_baseurl;770233748">&sect;</ulink>
 <ulink url="&commit_baseurl;da8a4c166">&sect;</ulink>
 </para>
@@ -1655,12 +1655,12 @@ Author: Fujii Masao <fujii@postgresql.org>
 
 <listitem>
 <para>
-Add REJECT_LIMIT to control the number of invalid rows COPY IN can ignore (Atsushi Torikoshi)
+Add REJECT_LIMIT to control the number of invalid rows COPY FROM can ignore (Atsushi Torikoshi)
 <ulink url="&commit_baseurl;4ac2a9bec">&sect;</ulink>
 </para>
 
 <para>
-This is active when ON_ERROR = 'ignore'.
+This is available when ON_ERROR = 'ignore'.
 </para>
 </listitem>
 
@@ -1678,12 +1678,12 @@ Allow COPY TO to copy rows from populated materialized view (Jian He)
 
 <!--
 Author: Fujii Masao <fujii@postgresql.org>
-2024-10-03 [e7834a1a2] Add log_verbosity = 'silent' support to COPY command.
+2024-10-03 [e7834a1a2] Add LOG_VERBOSITY = 'silent' support to COPY command.
 -->
 
 <listitem>
 <para>
-Add COPY log_verbosity level "silent" to suppress all log output (Atsushi Torikoshi)
+Add COPY LOG_VERBOSITY level "silent" to suppress log output of ignored rows (Atsushi Torikoshi)
 <ulink url="&commit_baseurl;e7834a1a2">&sect;</ulink>
 </para>
 
@@ -3246,7 +3246,7 @@ Author: Fujii Masao <fujii@postgresql.org>
 
 <listitem>
 <para>
-Add REJECT_LIMIT to control the number of invalid rows file_fdw can ignore (Atsushi Torikoshi)
+Add "reject_limit" to control the number of invalid rows file_fdw can ignore (Atsushi Torikoshi)
 <ulink url="&commit_baseurl;6c8f67032">&sect;</ulink>
 </para>
 

--5Fg/N0Lz9g11MB63--