diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 07cd7166a4..6aa035188f 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1623,10 +1623,21 @@ CREATE POLICY account_managers ON accounts TO managers
USING (manager = current_user);
+
+ The policy above implicitly provides a WITH CHECK
+ clause identical to its USING clause, so that the
+ constraint applies both to rows selected by a command (so a manager
+ cannot SELECT, UPDATE,
+ or DELETE existing rows belonging to a different
+ manager) and to rows modified by a command (so rows belonging to a
+ different manager cannot be created via INSERT
+ or UPDATE).
+
+
If no role is specified, or the special user name
PUBLIC is used, then the policy applies to all
- users on the system. To allow all users to access their own row in
+ users on the system. To allow all users to access only their own row in
a users table, a simple policy can be used:
@@ -1635,19 +1646,32 @@ CREATE POLICY user_policy ON users
USING (user_name = current_user);
+
+ This works similarly to the previous example.
+
+
To use a different policy for rows that are being added to the table
- compared to those rows that are visible, the WITH CHECK
- clause can be used. This policy would allow all users to view all rows
+ compared to those rows that are visible, multiple policies can be
+ combined. This pair of policies would allow all users to view all rows
in the users table, but only modify their own:
-CREATE POLICY user_policy ON users
- USING (true)
- WITH CHECK (user_name = current_user);
+CREATE POLICY user_sel_policy ON users
+ FOR SELECT
+ USING (true);
+CREATE POLICY user_mod_policy ON users
+ USING (user_name = current_user);
+
+ In a SELECT command, these two policies are combined
+ using OR, with the net effect being that all rows
+ can be selected. In other command types, only the second policy applies,
+ so that the effects are the same as before.
+
+
Row security can also be disabled with the ALTER TABLE
command. Disabling row security does not remove any policies that are