Re: Possible typo in create_policy.sgml

* Robert Haas (robertmhaas@gmail.com) wrote:
> On Wed, Jan 28, 2015 at 10:45 PM, Stephen Frost <sfrost@snowman.net> wrote:
> > 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 must be through a
> >   policy.  This requirement applies to both selecting out existing rows
> >   from the table and to adding rows to 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 which reference 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 return true for
> >   every row being added to the table or an error will be returned and
> >   the command will be aborted.
>
> I hate to be a critic, but this existing sentence in the documentation
> seems to explain nearly all of the above: "A policy limits the ability
> to SELECT, INSERT, UPDATE, or DELETE rows in a table to those rows
> which match the relevant policy expression. Existing table rows are
> checked against the expression specified via USING, while new rows
> that would be created via INSERT or UPDATE are checked against the
> expression specified via WITH CHECK."  The only thing I can see we
> might need to add is a sentence that says something like "If the USING
> clause returns false for a particular row, that row will not be
> visible to the user; if a WITH CHECK expression does not return true,
> an error occurs."

Well, I agree (I suppose perhaps that I have to, since I'm pretty sure I
wrote that.. :D), but what Dean was suggesting was a reword that
approached it from the other direction- that is, talk about policies as
granting access, instead of limiting it.  I thought that was an
excellent approach which will hopefully reduce confusion.  To that end,
how about this reword:

-----------------
A policy grants the ability to SELECT, INSERT, UPDATE, or DELETE rows
which match the relevant policy expression. Existing table rows are
checked against the expression specified via USING, while new rows
that would be created via INSERT or UPDATE are checked against the
expression specified via WITH CHECK.  When a USING expression returns
false for a given row, that row is not visible to the user.  When a WITH
CHECK expression returns false for a row which is to be added, an error
occurs.
-----------------

This would need to be after we talk about row level security being
enabled for a table and the default-deny policy or it might not make
sense, but otherwise I'm thinking it works.

Thoughts?
Thanks!
    Stephen