Re: Possible typo in create_policy.sgml

On Wed, Jan 28, 2015 at 10:45 PM, Stephen Frost <sfrost(at)snowman(dot)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."

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company