rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Policy documentation improvements 

In ALTER POLICY, use 'check_expression' instead of 'expression' for the
parameter, to match up with the recent CREATE POLICY change.

In CREATE POLICY, frame the discussion as granting access to rows
instead of limiting access to rows.  Further, clarify that the
expression must return true for rows to be visible/allowed and that a
false or NULL result will mean the row is not visible/allowed.

Per discussion with Dean Rasheed and Robert.
This commit is contained in:
Stephen Frost 2015-01-30 16:09:41 -05:00
parent 451d280815
commit 3144e1b3c6
2 changed files with 25 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/sgml/ref/alter_policy.sgml
View File

@ -24,7 +24,7 @@ PostgreSQL documentation
ALTER POLICY <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table_name</replaceable>
[ RENAME TO <replaceable class="PARAMETER">new_name</replaceable> ]
[ TO { <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...] ]
[ USING ( <replaceable class="parameter">expression</replaceable> ) ]
[ USING ( <replaceable class="parameter">using_expression</replaceable> ) ]
[ WITH CHECK ( <replaceable class="parameter">check_expression</replaceable> ) ]
</synopsis>
</refsynopsisdiv>
@ -87,7 +87,7 @@ ALTER POLICY <replaceable class="parameter">name</replaceable> ON <replaceable c
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">expression</replaceable></term>
<term><replaceable class="parameter">using_expression</replaceable></term>
<listitem>
<para>
The USING expression for the policy. This expression will be added as a

36
doc/src/sgml/ref/create_policy.sgml
View File

@ -39,14 +39,21 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
</para>
<para>
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. Generally,
the system will enforce filter conditions imposed using security
policies prior to qualifications that appear in the query itself, in
order to the prevent the inadvertent exposure of the protected data to
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 true for a given
row then that row is visible to the user, while if a false or null is
returned then the row is not visible. When a WITH CHECK expression
returns true for a row then that row is added, while if a false or null is
returned then an error occurs.
</para>
<para>
Generally, the system will enforce filter conditions imposed using
security policies prior to 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
@ -158,8 +165,10 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
Any <acronym>SQL</acronym> conditional expression (returning
<type>boolean</type>). The conditional expression cannot contain
any aggregate or window functions. This expression will be added
to queries that refer to the table if row level security is enabled,
and will allow access to rows matching the expression.
to queries that refer to the table if row level security is enabled
and rows for which the expression returns true will be visible. Any
rows for which the expression returns false or null will not be
visible to the user.
</para>
</listitem>
</varlistentry>
@ -172,9 +181,10 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
<type>boolean</type>). The conditional expression cannot contain
any aggregate or window functions. This expression will be used with
<command>INSERT</command> and <command>UPDATE</command> queries against
the table if row level security is enabled and an error will be thrown
if the expression evaluates to false for any of the records inserted
or any of the records which result from the update.
the table if row level security is enabled and only rows where the
expression evaluates to true will be allowed. An error will be thrown
if the expression evaluates to false or null for any of the records
inserted or any of the records which result from the update.
</para>
</listitem>
</varlistentry>