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

1 files changed, 33 insertions, 9 deletions

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 0460d76fece..13a10017614 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1624,10 +1624,21 @@ CREATE POLICY account_managers ON accounts TO managers
 </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>
@@ -1636,20 +1647,33 @@ CREATE POLICY user_policy ON users
 </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