mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-10-01 00:01:17 +02:00
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:
parent
451d280815
commit
3144e1b3c6
@ -24,7 +24,7 @@ PostgreSQL documentation
|
|||||||
ALTER POLICY <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table_name</replaceable>
|
ALTER POLICY <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table_name</replaceable>
|
||||||
[ RENAME TO <replaceable class="PARAMETER">new_name</replaceable> ]
|
[ RENAME TO <replaceable class="PARAMETER">new_name</replaceable> ]
|
||||||
[ TO { <replaceable class="parameter">role_name</replaceable> | PUBLIC } [, ...] ]
|
[ 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> ) ]
|
[ WITH CHECK ( <replaceable class="parameter">check_expression</replaceable> ) ]
|
||||||
</synopsis>
|
</synopsis>
|
||||||
</refsynopsisdiv>
|
</refsynopsisdiv>
|
||||||
@ -87,7 +87,7 @@ ALTER POLICY <replaceable class="parameter">name</replaceable> ON <replaceable c
|
|||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable class="parameter">expression</replaceable></term>
|
<term><replaceable class="parameter">using_expression</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The USING expression for the policy. This expression will be added as a
|
The USING expression for the policy. This expression will be added as a
|
||||||
|
@ -39,14 +39,21 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
|
|||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
A policy limits the ability to SELECT, INSERT, UPDATE, or DELETE rows
|
A policy grants the ability to SELECT, INSERT, UPDATE, or DELETE rows
|
||||||
in a table to those rows which match the relevant policy expression.
|
which match the relevant policy expression. Existing table rows are
|
||||||
Existing table rows are checked against the expression specified via
|
checked against the expression specified via USING, while new rows that
|
||||||
USING, while new rows that would be created via INSERT or UPDATE are
|
would be created via INSERT or UPDATE are checked against the expression
|
||||||
checked against the expression specified via WITH CHECK. Generally,
|
specified via WITH CHECK. When a USING expression returns true for a given
|
||||||
the system will enforce filter conditions imposed using security
|
row then that row is visible to the user, while if a false or null is
|
||||||
policies prior to qualifications that appear in the query itself, in
|
returned then the row is not visible. When a WITH CHECK expression
|
||||||
order to the prevent the inadvertent exposure of the protected data to
|
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,
|
user-defined functions which might not be trustworthy. However,
|
||||||
functions and operators marked by the system (or the system
|
functions and operators marked by the system (or the system
|
||||||
administrator) as LEAKPROOF may be evaluated before policy
|
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
|
Any <acronym>SQL</acronym> conditional expression (returning
|
||||||
<type>boolean</type>). The conditional expression cannot contain
|
<type>boolean</type>). The conditional expression cannot contain
|
||||||
any aggregate or window functions. This expression will be added
|
any aggregate or window functions. This expression will be added
|
||||||
to queries that refer to the table if row level security is enabled,
|
to queries that refer to the table if row level security is enabled
|
||||||
and will allow access to rows matching the expression.
|
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>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
@ -172,9 +181,10 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable
|
|||||||
<type>boolean</type>). The conditional expression cannot contain
|
<type>boolean</type>). The conditional expression cannot contain
|
||||||
any aggregate or window functions. This expression will be used with
|
any aggregate or window functions. This expression will be used with
|
||||||
<command>INSERT</command> and <command>UPDATE</command> queries against
|
<command>INSERT</command> and <command>UPDATE</command> queries against
|
||||||
the table if row level security is enabled and an error will be thrown
|
the table if row level security is enabled and only rows where the
|
||||||
if the expression evaluates to false for any of the records inserted
|
expression evaluates to true will be allowed. An error will be thrown
|
||||||
or any of the records which result from the update.
|
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>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
Loading…
Reference in New Issue
Block a user