Re: Possible typo in create_policy.sgml

* Robert Haas (robertmhaas@gmail.com) wrote:
> On Fri, Jan 9, 2015 at 3:46 PM, Stephen Frost <sfrost@snowman.net> wrote:
> >    A policy permits SELECT, INSERT, UPDATE or DELETE commands to access rows
> >    in a table that has row level security enabled.  Access to existing table
> >    rows is granted if they match a policy expression specified via USING,
> >    while new rows that would be created via INSERT or UPDATE are checked
> >    against policy expressions specified via WITH CHECK.  For policy
> >    expressions specified via USING which grant access to existing rows, the
> >    system will generally test the policy expressions prior to any
> >    qualifications that appear in the query itself, in order to the prevent the
> >    inadvertent exposure of the protected data to user-defined functions which
> >    might not be trustworthy.  However, functions and operators marked by the
> >    system (or the system administrator) as LEAKPROOF may be evaluated before
> >    policy expressions, as they are assumed to be trustworthy.
>
> I think that sticking "while new rows that would be created via INSERT
> or UPDATE are checked against policy expressions specified via WITH
> CHECK" into the middle of this is horribly confusing, as it's a
> completely separate mechanism from the rest of what's being discussed
> here.  I think there needs to be some initial language that clarifies
> that USING expressions apply to old rows and WITH CHECK expressions to
> new rows, and then you can go into more detail.  But mentioning WITH
> CHECK parenthetically in the middle of the rest of this I think will
> not lead to clarity.

I agree, especially after going back and re-reading this while fixing
the issue mentioned earlier by Peter (which was an orthogonal complaint
about the shadowing of WITH CHECK by USING, if WITH CHECK isn't
specified).  We really need a paragraph on "USING" policies and another
on "WITH CHECK" policies.  How about a reword along these lines:
 When row level security is enabled on a table, all access to that table by users other than the owner or a superuser
mustbe through a policy.  This requirement applies to both selecting out existing rows from the table and to adding
rowsto the table (through either INSERT or UPDATE). 
 Granting access to existing rows in a table is done by specifying a USING expression which will be added to queries
whichreference the table.  Every row in the table which a USING expression returns true will be visible. 
 Granting access to add rows to a table is done by specifying a WITH CHECK expressison.  A WITH CHECK expression must
returntrue for every row being added to the table or an error will be returned and the command will be aborted.  For
policyexpressions specified via USING which grant access to existing rows, the system will generally test the policy
expressionsprior to any qualifications that appear in the query itself, in order to the prevent the inadvertent
exposureof the protected data to user-defined functions which might not be trustworthy.  However, functions and
operatorsmarked by the system (or the system administrator) as LEAKPROOF may be evaluated before policy expressions, as
theyare assumed to be trustworthy. 

Thoughts?
Thanks!
    Stephen