Doc: fix oversimplified example for CREATE POLICY.

As written, this policy constrained only the post-image not the pre-image
of rows, meaning that users could delete other users' rows or take
ownership of such rows, contrary to what the docs claimed would happen.
We need two separate policies to achieve the documented effect.

While at it, try to explain what's happening a bit more fully.

Per report from Олег Самойлов.  Back-patch to 9.5 where this was added.
Thanks to Stephen Frost for off-list discussion.

Discussion: https://postgr.es/m/3298321532002010@sas1-2b3c3045b736.qloud-c.yandex.net

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 4504925f9d992ac4114cbcd7a7f8785bcd6d51f6..bfbb3003b3f13dca71389a516880f9cc1b2f3a1e 100644 (file)
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1620,11 +1620,22 @@ CREATE POLICY account_managers ON accounts TO managers
     USING (manager = current_user);
 </programlisting>
 
+  <para>
+   The policy above implicitly provides a <literal>WITH CHECK</literal>
+   clause identical to its <literal>USING</literal> clause, so that the
+   constraint applies both to rows selected by a command (so a manager
+   cannot <command>SELECT</command>, <command>UPDATE</command>,
+   or <command>DELETE</command> existing rows belonging to a different
+   manager) and to rows modified by a command (so rows belonging to a
+   different manager cannot be created via <command>INSERT</command>
+   or <command>UPDATE</command>).
+  </para>
+
   <para>
    If no role is specified, or the special user name
    <literal>PUBLIC</literal> is used, then the policy applies to all
-   users on the system.  To allow all users to access their own row in
-   a <literal>users</> table, a simple policy can be used:
+   users on the system.  To allow all users to access only their own row in
+   a <literal>users</literal> table, a simple policy can be used:
   </para>
 
 <programlisting>
@@ -1632,21 +1643,34 @@ CREATE POLICY user_policy ON users
     USING (user_name = current_user);
 </programlisting>
 
+  <para>
+   This works similarly to the previous example.
+  </para>
+
   <para>
    To use a different policy for rows that are being added to the table
-   compared to those rows that are visible, the <literal>WITH CHECK</>
-   clause can be used.  This policy would allow all users to view all rows
-   in the <literal>users</> table, but only modify their own:
+   compared to those rows that are visible, multiple policies can be
+   combined.  This pair of policies would allow all users to view all rows
+   in the <literal>users</literal> table, but only modify their own:
   </para>
 
 <programlisting>
-CREATE POLICY user_policy ON users
-    USING (true)
-    WITH CHECK (user_name = current_user);
+CREATE POLICY user_sel_policy ON users
+    FOR SELECT
+    USING (true);
+CREATE POLICY user_mod_policy ON users
+    USING (user_name = current_user);
 </programlisting>
 
   <para>
-   Row security can also be disabled with the <command>ALTER TABLE</>
+   In a <command>SELECT</command> command, these two policies are combined
+   using <literal>OR</literal>, with the net effect being that all rows
+   can be selected.  In other command types, only the second policy applies,
+   so that the effects are the same as before.
+  </para>
+
+  <para>
+   Row security can also be disabled with the <command>ALTER TABLE</command>
    command.  Disabling row security does not remove any policies that are
    defined on the table; they are simply ignored.  Then all rows in the
    table are visible and modifiable, subject to the standard SQL privileges