From e5f3fe63011b9912f7297d8f18077308ac91c2be Mon Sep 17 00:00:00 2001
From: Dean Rasheed <dean.a.rasheed@gmail.com>
Date: Thu, 27 Mar 2025 14:19:15 +0000
Subject: [PATCH v2 2/2] doc: Improve the "Policies Applied by Command Type"
 table.

This table was missing MERGE ... THEN DELETE and some of the policies
applied during INSERT ... ON CONFLICT and MERGE. Fix that, and try to
improve readability by listing the various MERGE cases separately,
rather than together with INSERT/UPDATE/DELETE.

In addition, correct the paragraph above the table to note that an
INSERT ... ON CONFLICT DO NOTHING/UPDATE checks all new rows against
the INSERT policy expressions, regardless of whether the rows end up
being inserted.

Author: Dean Rasheed <dean.a.rasheed@gmail.com>
Reviewed-by: Viktor Holmberg <v@viktorh.net>
Discussion: https://postgr.es/m/CAEZATCWqnfeChjK=n1V_dYZT4rt4mnq+ybf9c0qXDYTVMsy8pg@mail.gmail.com
---
 doc/src/sgml/ref/create_policy.sgml | 72 +++++++++++++++++++++++------
 1 file changed, 58 insertions(+), 14 deletions(-)

diff --git a/doc/src/sgml/ref/create_policy.sgml b/doc/src/sgml/ref/create_policy.sgml
index e76c342d3da..d6299a40844 100644
--- a/doc/src/sgml/ref/create_policy.sgml
+++ b/doc/src/sgml/ref/create_policy.sgml
@@ -293,9 +293,9 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
        </para>
        <para>
          Note that <literal>INSERT</literal> with <literal>ON CONFLICT DO
-         UPDATE</literal> checks <literal>INSERT</literal> policies'
-         <literal>WITH CHECK</literal> expressions only for rows appended
-         to the relation by the <literal>INSERT</literal> path.
+         NOTHING/UPDATE</literal> checks <literal>INSERT</literal> policies'
+         <literal>WITH CHECK</literal> expressions for all rows, regardless
+         of whether they end up being inserted.
        </para>
       </listitem>
      </varlistentry>
@@ -424,7 +424,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
      </thead>
      <tbody>
       <row>
-       <entry><command>SELECT</command></entry>
+       <entry><command>SELECT</command> / <command>COPY ... TO</command> / <command>TABLE</command></entry>
        <entry>Existing row</entry>
        <entry>&mdash;</entry>
        <entry>&mdash;</entry>
@@ -440,15 +440,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
        <entry>&mdash;</entry>
       </row>
       <row>
-       <entry><command>INSERT</command> / <command>MERGE ... THEN INSERT</command></entry>
-       <entry>&mdash;</entry>
-       <entry>New row</entry>
-       <entry>&mdash;</entry>
-       <entry>&mdash;</entry>
-       <entry>&mdash;</entry>
-      </row>
-      <row>
-       <entry><command>INSERT ... RETURNING</command></entry>
+       <entry><command>INSERT</command></entry>
        <entry>
         New row <footnote id="rls-select-priv">
          <para>
@@ -464,7 +456,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
        <entry>&mdash;</entry>
       </row>
       <row>
-       <entry><command>UPDATE</command> / <command>MERGE ... THEN UPDATE</command></entry>
+       <entry><command>UPDATE</command></entry>
        <entry>
         Existing &amp; new rows <footnoteref linkend="rls-select-priv"/>
        </entry>
@@ -483,14 +475,66 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
        <entry>&mdash;</entry>
        <entry>Existing row</entry>
       </row>
+      <row>
+       <entry><command>INSERT ... ON CONFLICT</command></entry>
+       <entry>New row</entry>
+       <entry>New row</entry>
+       <entry>&mdash;</entry>
+       <entry>&mdash;</entry>
+       <entry>&mdash;</entry>
+      </row>
       <row>
        <entry><command>ON CONFLICT DO UPDATE</command></entry>
+       <entry>
+        Existing &amp; new rows <footnote id="rls-on-conflict-update-priv">
+         <para>
+          New row of the auxiliary <command>UPDATE</command> command, which
+          might be different from the new row of the original
+          <command>INSERT</command> command.
+         </para>
+        </footnote>
+       </entry>
+       <entry>&mdash;</entry>
+       <entry>Existing row</entry>
+       <entry>
+        New row <footnoteref linkend="rls-on-conflict-update-priv"/>
+       </entry>
+       <entry>&mdash;</entry>
+      </row>
+      <row>
+       <entry><command>MERGE</command></entry>
+       <entry>All candidate source &amp; target rows</entry>
+       <entry>&mdash;</entry>
+       <entry>&mdash;</entry>
+       <entry>&mdash;</entry>
+       <entry>&mdash;</entry>
+      </row>
+      <row>
+       <entry><command>MERGE ... THEN INSERT</command></entry>
+       <entry>
+        New row <footnoteref linkend="rls-select-priv"/>
+       </entry>
+       <entry>New row</entry>
+       <entry>&mdash;</entry>
+       <entry>&mdash;</entry>
+       <entry>&mdash;</entry>
+      </row>
+      <row>
+       <entry><command>MERGE ... THEN UPDATE</command></entry>
        <entry>Existing &amp; new rows</entry>
        <entry>&mdash;</entry>
        <entry>Existing row</entry>
        <entry>New row</entry>
        <entry>&mdash;</entry>
       </row>
+      <row>
+       <entry><command>MERGE ... THEN DELETE</command></entry>
+       <entry>Existing row</entry>
+       <entry>&mdash;</entry>
+       <entry>&mdash;</entry>
+       <entry>&mdash;</entry>
+       <entry>Existing row</entry>
+      </row>
      </tbody>
     </tgroup>
    </table>
-- 
2.51.0

