Improve CREATE POLICY documentation

Clarify that SELECT policies are now applied when SELECT rights
are required for a given query, even if the query is an UPDATE or
DELETE query.  Pointed out by Noah.

Additionally, note the risk regarding concurrently open transactions
where a relation which controls access to the rows of another relation
are updated and the rows of the primary relation are also being
modified.  Pointed out by Peter Geoghegan.

Back-patch to 9.5.

diff --git a/doc/src/sgml/ref/create_policy.sgml b/doc/src/sgml/ref/create_policy.sgml
index 72bf6915823828adfacab81cadcd5644c884a904..b714cb29b49d77f2d74e242f7a03e2c1baacf6c4 100644 (file)
--- a/doc/src/sgml/ref/create_policy.sgml
+++ b/doc/src/sgml/ref/create_policy.sgml
@@ -217,12 +217,18 @@ CREATE POLICY name ON 
       
        
          Using SELECT for a policy means that it will apply
-         to SELECT commands.  The result is that only those
-         records from the relation that pass the SELECT
-         policy will be returned, even if other records exist in the relation.
-         The SELECT policy only accepts the USING expression
-         as it only ever applies in cases where records are being retrieved from
-         the relation.
+         to SELECT queries and whenever
+         SELECT permissions are required on the relation the
+         policy is defined for.  The result is that only those records from the
+         relation that pass the SELECT policy will be
+         returned during a SELECT query, even if other
+         records exist in the relation and that queries which require
+         SELECT permissions, such as
+         UPDATE, will also only see those records
+         which are allowed by the SELECT policy.
+         The SELECT policy only accepts the
+         USING expression as it only applies in cases where
+         records are being retrieved from the relation.
        
       
      
@@ -235,15 +241,15 @@ CREATE POLICY name ON 
          to INSERT commands.  Rows being inserted that do
          not pass this policy will result in a policy violation error, and the
          entire INSERT command will be aborted.  The
-         INSERT policy only accepts the WITH CHECK expression
-         as it only ever applies in cases where records are being added to the
-         relation.
+         INSERT policy only accepts the
+         WITH CHECK expression as it only applies in cases
+         where records are being added to the relation.
        
        
          Note that INSERT with ON CONFLICT DO
          UPDATE requires that any INSERT policy
-         WITH CHECK expression passes for any rows appended to the relation by
-         the INSERT path only.
+         WITH CHECK expression passes for any rows appended
+         to the relation by the INSERT path only.
        
       
      
@@ -259,17 +265,41 @@ CREATE POLICY name ON 
          record and then making changes to some portion (but possibly not all)
          of the record, the UPDATE policy accepts both a
          USING expression and a WITH CHECK
-         expression.  The USING expression will be used to
+         expression.
+       
+         
+       
+         The USING expression will be used to
          determine which records the UPDATE command will see
          to operate against, while the WITH CHECK expression
          defines what rows are allowed to be added back into the relation
-         (similar to the INSERT policy).  Any rows whose
-         resulting values do not pass the WITH CHECK
-         expression will cause an error, and the entire command will be aborted.
-         Note that if only a USING clause is specified, then
-         that clause will be used for both USING and
-         WITH CHECK cases.
+         (similar to the INSERT policy).  
        
+
+       
+         When an UPDATE command is used with a
+         WHERE clause or a RETURNING
+         clause, SELECT rights are also required on the
+         relation being updated and the appropriate SELECT
+         and ALL policies will be combined (using OR for any
+         overlapping SELECT related policies found) with the
+         USING clause of the UPDATE policy
+         using AND.  Therefore, in order for a user to be able to
+         UPDATE a specific set of rows using a
+         WHERE clause, the user must have access to the
+         row(s) through a SELECT or ALL
+         policy and the row(s) must be pass the UPDATE USING
+         expression.
+       
+         
+       
+         Any rows whose resulting values do not pass the
+         WITH CHECK expression will cause an error, and the
+         entire command will be aborted.  If only a USING
+         clause is specified, then that clause will be used for both
+         USING and WITH CHECK cases.
+       
+
        
          Note, however, that INSERT with ON CONFLICT
          DO UPDATE requires that an UPDATE policy
@@ -295,15 +325,32 @@ CREATE POLICY name ON 
        
          Using DELETE for a policy means that it will apply
          to DELETE commands.  Only rows that pass this
-         policy will be seen by a DELETE command.  There can be rows
-         that are visible through a SELECT that are not seen by a
-         DELETE, if they do not pass the USING expression
-         for the DELETE.  Conversely, there can be rows that are not visible
-         through the SELECT policy but may be deleted if they
-         pass the DELETE USING policy.  The
-         DELETE policy only accepts the USING expression as
-         it only ever applies in cases where records are being extracted from
-         the relation for deletion.
+         policy will be seen by a DELETE command.  There can
+         be rows that are visible through a SELECT that are
+         not seen by a DELETE, if they do not pass the
+         USING expression for the DELETE.
+       
+
+       
+         When a DELETE command is used with a
+         WHERE clause or a RETURNING
+         clause, SELECT rights are also required on the
+         relation being updated and the appropriate SELECT
+         and ALL policies will be combined (using OR for any
+         overlapping SELECT related policies found) with the
+         USING clause of the DELETE policy
+         using AND.  Therefore, in order for a user to be able to
+         DELETE a specific set of rows using a
+         WHERE clause, the user must have access to the
+         row(s) through a SELECT or ALL
+         policy and the row(s) must be pass the DELETE USING
+         expression.
+       
+         
+       
+         The DELETE policy only accepts the
+         USING expression as it only applies in cases where
+         records are being extracted from the relation for deletion.
        
       
      
@@ -349,6 +396,18 @@ CREATE POLICY name ON 
    policies for the tables which are referenced by a view will use the view
    owner's rights and any policies which apply to the view owner.
   
+
+  
+   When reducing the set of rows which a user has access to, through
+   modifications to relations referenced by Row-Level Security Policies or
+   Security Barrier Views, be aware that users with a currently open transaction
+   may be able to see updates to the rows that they are no longer allowed
+   access.  Therefore, the best practice to avoid any possible leak of
+   information when altering conditions that determine the visibility of
+   specific rows is to ensure that affected users do not have any open
+   transactions, perhaps by ensuring they have no concurrent sessions running.
+  
+