From 42f66b27566798d9969791ec6d2acd399c41b60f Mon Sep 17 00:00:00 2001
From: Stephen Frost <sfrost@snowman.net>
Date: Wed, 28 Jan 2015 22:16:24 -0500
Subject: [PATCH] Improve CREATE POLICY documentation

The CREATE POLICY documention didn't sufficiently clarify what happens
when a given command type (eg: ALL or UPDATE) accepts both USING and
WITH CHECK clauses, but only the USING clause is defined.  Add language
to clarify that, in such a case, the USING clause will be used for both
USING and WITH CHECK cases.

Pointed out by Peter Geoghegan.
---
 doc/src/sgml/ref/create_policy.sgml | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/doc/src/sgml/ref/create_policy.sgml b/doc/src/sgml/ref/create_policy.sgml
index 8ef8556b51..18ab4a78f9 100644
--- a/doc/src/sgml/ref/create_policy.sgml
+++ b/doc/src/sgml/ref/create_policy.sgml
@@ -63,7 +63,11 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
    Policies can be applied for specific commands or for specific roles.  The
    default for newly created policies is that they apply for all commands and
    roles, unless otherwise specified.  If multiple policies apply to a given
-   query, they will be combined using OR.
+   query, they will be combined using OR.  Further, for commands which can have
+   both USING and WITH CHECK policies (ALL and UPDATE), if no WITH CHECK policy
+   is defined then the USING policy will be used for both what rows are visible
+   (normal USING case) and which rows will be allowed to be added (WITH CHECK
+   case).
   </para>
 
   <para>
@@ -204,8 +208,10 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
          (using the WITH CHECK expression, if defined, and the USING expression
          otherwise).  If an INSERT or UPDATE command attempts to add rows to
          the table which do not pass the <literal>ALL</literal> WITH CHECK
-         (or USING, if no WITH CHECK expression is defined) expression, the
-         command will error.
+         expression, the entire command will be aborted.  Note that if only a
+         <literal>USING</literal> clause is specified then that clause will be
+         used for both <literal>USING</literal> and
+         <literal>WITH CHECK</literal> cases.
        </para>
       </listitem>
      </varlistentry>
@@ -256,7 +262,10 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
          relation (similar to the <literal>INSERT</literal> policy).
          Any rows whose resulting values do not pass the
          <literal>WITH CHECK</literal> expression will cause an ERROR and the
-         entire command will be aborted.
+         entire command will be aborted.  Note that if only a
+         <literal>USING</literal> clause is specified then that clause will be
+         used for both <literal>USING</literal> and
+         <literal>WITH CHECK</literal> cases.
        </para>
       </listitem>
      </varlistentry>