CREATE POLICY
CREATE POLICY
7
SQL - Language Statements
CREATE POLICY
define a new row-security policy for a table
CREATE POLICY name ON table_name
[ FOR { ALL | SELECT | INSERT | UPDATE | DELETE } ]
[ TO { role_name | PUBLIC } [, ...] ]
[ USING ( expression ) ]
[ WITH CHECK ( check_expression ) ]
Description
The CREATE POLICY command defines a new row-security
policy for a table. Note that row-security must also be enabled on the
table using ALTER TABLE in order for created policies
to be applied.
A row-security policy is an expression which is added to the security-barrier
qualifications of queries which are run against the table the policy is on,
or an expression which is added to the with-check options for a table and
which is applied to rows which would be added to the table.
The security-barrier qualifications will always be evaluated prior to any
user-defined functions or user-provided WHERE clauses, while the with-check
expression will be evaluated against the rows which are going to be added to
the table. By adding policies to a table, a user can limit the rows which a
given user can select, insert, update, or delete. This capability is also
known as Row-Level Security or RLS.
Policy names are per-table, therefore one policy name can be used for many
different tables and have a definition for each table which is appropriate to
that table.
Policies can be applied for specific commands or for specific roles. The
default for newly created policies is that they apply for all commands and
roles, unless otherwise specified. If multiple policies apply to a given
query, they will be combined using OR.
Note that while row-security policies will be applied for explicit queries
against tables in the system, they are not applied when the system is
performing internal referential integrity checks or validating constraints.
This means there are indirect ways to determine that a given value exists.
An example of this is attempting to insert a duplicate value
into a column which is the primary key or has a unique constraint. If the
insert fails then the user can infer that the value already exists (this
example assumes that the user is permitted by policy to insert
records which they are not allowed to see). Another example is where a user
is allowed to insert into a table which references another, otherwise hidden
table. Existence can be determined by the user inserting values into the
referencing table, where success would indicate that the value exists in the
referenced table. These issues can be addressed by carefully crafting
policies which prevent users from being able to insert, delete, or update
records at all which might possibly indicate a value they are not otherwise
able to see, or by using generated values (eg: surrogate keys) instead.
Regarding how policy expressions interact with the user: as the expressions
are added to the user's query directly, they will be run with the rights of
the user running the overall query. Therefore, users who are using a given
policy must be able to access any tables or functions referenced in the
expression or they will simply receive a permission denied error when
attempting to query the RLS-enabled table. This does not change how views
work, however. As with normal queries and views, permission checks and
policies for the tables which are referenced by a view will use the view
owner's rights and any policies which apply to the view owner.
Parameters
name
The name of the policy to be created. This must be distinct from the
name of any other policy for the table.
table_name
The name (optionally schema-qualified) of the table the
policy applies to.
command
The command to which the policy applies. Valid options are
ALL, SELECT,
INSERT, UPDATE,
and DELETE.
ALL is the default.
See below for specifics regarding how these are applied.
role_name
The roles to which the policy is to be applied. The default is
PUBLIC, which will apply the policy to all roles.
expression
Any SQL conditional expression (returning
boolean). The conditional expression cannot contain
any aggregate or window functions. This expression will be added
to queries to filter out the records which are visible to the query.
check_expression
Any SQL conditional expression (returning
boolean). The condition expression cannot contain
any aggregate or window functions. This expression will be added
to queries which are attempting to add records to the table as
with-check options, and an error will be thrown if this condition
returns false for any records being added.
Per-Command policies
ALL>
Using ALL for a policy means that it will apply
to all commands, regardless of the type of command. If an
ALL policy exists and more specific policies
exist, then both the ALL policy and the more
specific policy (or policies) will be combined using
OR, as usual for overlapping policies.
Additionally, ALL policies will be applied to
both the selection side of a query and the modification side, using
the USING policy for both if only a USING policy has been defined.
As an example, if an UPDATE is issued, then the
ALL policy will be applicable to both what the
UPDATE will be able to select out as rows to be
updated (with the USING expression being applied), and it will be
applied to rows which result from the UPDATE
statement, to check if they are permitted to be added to the table
(using the WITH CHECK expression, if defined, and the USING expression
otherwise). If an INSERT or UPDATE command attempts to add rows to
the table which do not pass the ALL WITH CHECK
(or USING, if no WITH CHECK expression is defined) expression, the
command will error.
SELECT>
Using SELECT for a policy means that it will apply
to SELECT commands. The result is that only those
records from the relation which pass the SELECT
policy will be returned, even if other records exist in the relation.
The SELECT policy only accepts the USING expression
as it only ever applies in cases where records are being retrived from
the relation.
INSERT>
Using INSERT for a policy means that it will apply
to INSERT commands. Rows being inserted which do
not pass this policy will result in a policy violation ERROR and the
entire INSERT command will be aborted. The
INSERT policy only accepts the WITH CHECK expression
as it only ever applies in cases where records are being added to the
relation.
UPDATE>
Using UPDATE for a policy means that it will apply
to UPDATE commands. As UPDATE
involves pulling an existing record and then making changes to some
portion (but possibly not all) of the record, the
UPDATE policy accepts both a USING expression and
a WITH CHECK expression. The USING expression will be used to
determine which records the UPDATE command will
see to operate against, while the WITH CHECK
expression defines what rows are allowed to be added back into the
relation (similar to the INSERT policy).
Any rows whose resulting values do not pass the
WITH CHECK expression will cause an ERROR and the
entire command will be aborted.
DELETE>
Using DELETE for a policy means that it will apply
to DELETE commands. Only rows which pass this
policy will be seen by a DELETE command. Rows may
be visible through a SELECT which are not seen by a
DELETE, as they do not pass the USING expression
for the DELETE, and rows which are not visible
through the SELECT policy may be deleted if they
pass the DELETE USING policy. The
DELETE policy only accept the USING expression as
it only ever applies in cases where records are being extracted from
the relation for deletion.
Notes
You must be the owner of a table to create or change policies for it.
In order to maintain referential integrity between
two related tables, row-security policies are not applied when the system
performs checks on foreign key constraints.
Compatibility
CREATE POLICY is a PostgreSQL
extension.
See Also