<!--
doc/src/sgml/ref/create_policy.sgml
PostgreSQL documentation
-->

<refentry id="sql-createpolicy">
 <indexterm zone="sql-createpolicy">
  <primary>CREATE POLICY</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>CREATE POLICY</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE POLICY</refname>
  <refpurpose>define a new row-level security policy for a table</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table_name</replaceable>
    [ AS { PERMISSIVE | RESTRICTIVE } ]
    [ FOR { ALL | SELECT | INSERT | UPDATE | DELETE } ]
    [ TO { <replaceable class="parameter">role_name</replaceable> | PUBLIC | CURRENT_ROLE | CURRENT_USER | SESSION_USER } [, ...] ]
    [ USING ( <replaceable class="parameter">using_expression</replaceable> ) ]
    [ WITH CHECK ( <replaceable class="parameter">check_expression</replaceable> ) ]
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   The <command>CREATE POLICY</command> command defines a new row-level
   security policy for a table.  Note that row-level security must be
   enabled on the table (using <command>ALTER TABLE ... ENABLE ROW LEVEL
   SECURITY</command>) in order for created policies to be applied.
  </para>

  <para>
   A policy grants the permission to select, insert, update, or delete rows
   that match the relevant policy expression.  Existing table rows are
   checked against the expression specified in <literal>USING</literal>,
   while new rows that would be created via <literal>INSERT</literal>
   or <literal>UPDATE</literal> are checked against the expression specified
   in <literal>WITH CHECK</literal>.  When a <literal>USING</literal>
   expression returns true for a given row then that row is visible to the
   user, while if false or null is returned then the row is not visible.
   When a <literal>WITH CHECK</literal> expression returns true for a row
   then that row is inserted or updated, while if false or null is returned
   then an error occurs.
  </para>

  <para>
   For <command>INSERT</command>, <command>UPDATE</command>, and
   <command>MERGE</command> statements,
   <literal>WITH CHECK</literal> expressions are enforced after
   <literal>BEFORE</literal> triggers are fired, and before any actual data
   modifications are made.  Thus a <literal>BEFORE ROW</literal> trigger may
   modify the data to be inserted, affecting the result of the security
   policy check.  <literal>WITH CHECK</literal> expressions are enforced
   before any other constraints.
  </para>

  <para>
   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.
  </para>

  <para>
   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.  Multiple policies may apply to a single
   command; see below for more details.
   <xref linkend="sql-createpolicy-summary"/> summarizes how the different types
   of policy apply to specific commands.
  </para>

  <para>
   For policies that can have both <literal>USING</literal>
   and <literal>WITH CHECK</literal> expressions (<literal>ALL</literal>
   and <literal>UPDATE</literal>), if no <literal>WITH CHECK</literal>
   expression is defined, then the <literal>USING</literal> expression will be
   used both to determine which rows are visible (normal
   <literal>USING</literal> case) and which new rows will be allowed to be
   added (<literal>WITH CHECK</literal> case).
  </para>

  <para>
   If row-level security is enabled for a table, but no applicable policies
   exist, a <quote>default deny</quote> policy is assumed, so that no rows will
   be visible or updatable.
  </para>