raw/man7/create_rule.7

   1 .\\" auto-generated by docbook2man-spec $Revision: 1.1 $
   2 .TH "CREATE RULE" "7" "2003-11-02" "SQL - Language Statements" "SQL Commands"
   3 .SH NAME
   4 CREATE RULE \- define a new rewrite rule
   5
   6 .SH SYNOPSIS
   7 .sp
   8 .nf
   9 CREATE [ OR REPLACE ] RULE \fIname\fR AS ON \fIevent\fR
  10     TO \fItable\fR [ WHERE \fIcondition\fR ]
  11     DO [ INSTEAD ] { NOTHING | \fIcommand\fR | ( \fIcommand\fR ; \fIcommand\fR ... ) }
  12 .sp
  13 .fi
  14 .SH "DESCRIPTION"
  15 .PP
  16 \fBCREATE RULE\fR defines a new rule applying to a specified
  17 table or view.
  18 \fBCREATE OR REPLACE RULE\fR will either create a
  19 new rule, or replace an existing rule of the same name for the same
  20 table.
  21 .PP
  22 The PostgreSQL rule system allows one to
  23 define an alternate action to be performed on insertions, updates,
  24 or deletions in database tables. Roughly speaking, a rule causes
  25 additional commands to be executed when a given command on a given
  26 table is executed. Alternatively, a rule can replace a given
  27 command by another, or cause a command not to be executed at all.
  28 Rules are used to implement table views as well. It is important
  29 to realize that a rule is really a command transformation
  30 mechanism, or command macro. The transformation happens before the
  31 execution of the commands starts. If you actually want an
  32 operation that fires independently for each physical row, you
  33 probably want to use a trigger, not a rule. More information about
  34 the rules system is in the chapter called ``The Rule System'' in the documentation.
  35 .PP
  36 Presently, ON SELECT rules must be unconditional
  37 INSTEAD rules and must have actions that consist
  38 of a single \fBSELECT\fR command. Thus, an
  39 ON SELECT rule effectively turns the table into
  40 a view, whose visible contents are the rows returned by the rule's
  41 \fBSELECT\fR command rather than whatever had been
  42 stored in the table (if anything). It is considered better style
  43 to write a \fBCREATE VIEW\fR command than to create a
  44 real table and define an ON SELECT rule for it.
  45 .PP
  46 You can create the illusion of an updatable view by defining
  47 ON INSERT, ON UPDATE, and
  48 ON DELETE rules (or any subset of those that's
  49 sufficient for your purposes) to replace update actions on the view
  50 with appropriate updates on other tables.
  51 .PP
  52 There is a catch if you try to use conditional rules for view
  53 updates: there \fBmust\fR be an unconditional
  54 INSTEAD rule for each action you wish to allow
  55 on the view. If the rule is conditional, or is not
  56 INSTEAD, then the system will still reject
  57 attempts to perform the update action, because it thinks it might
  58 end up trying to perform the action on the dummy table of the view
  59 in some cases. If you want to handle all the useful cases in
  60 conditional rules, you can; just add an unconditional DO
  61 INSTEAD NOTHING rule to ensure that the system
  62 understands it will never be called on to update the dummy table.
  63 Then make the conditional rules not INSTEAD; in
  64 the cases where they are applied, they add to the default
  65 INSTEAD NOTHING action.
  66 .SH "PARAMETERS"
  67 .TP
  68 \fB\fIname\fB\fR
  69 The name of a rule to create. This must be distinct from the
  70 name of any other rule for the same table. Multiple rules on
  71 the same table and same event type are applied in alphabetical
  72 name order.
  73 .TP
  74 \fB\fIevent\fB\fR
  75 The even is one of SELECT,
  76 INSERT, UPDATE, or
  77 DELETE.
  78 .TP
  79 \fB\fItable\fB\fR
  80 The name (optionally schema-qualified) of the table or view the
  81 rule applies to.
  82 .TP
  83 \fB\fIcondition\fB\fR
  84 Any SQL conditional expression (returning \fBboolean\fR).
  85 The condition expression may not refer to any tables except
  86 NEW and OLD, and may not
  87 contain aggregate functions.
  88 .TP
  89 \fB\fIcommand\fB\fR
  90 The command or commands that make up the rule action. Valid
  91 commands are SELECT,
  92 INSERT, UPDATE,
  93 DELETE, or NOTIFY.
  94 .PP
  95 Within \fIcondition\fR and
  96 \fIcommand\fR, the special
  97 table names NEW and OLD may
  98 be used to refer to values in the referenced table.
  99 NEW is valid in ON INSERT and
 100 ON UPDATE rules to refer to the new row being
 101 inserted or updated. OLD is valid in
 102 ON UPDATE and ON DELETE rules
 103 to refer to the existing row being updated or deleted.
 104 .PP
 105 .SH "NOTES"
 106 .PP
 107 You must have the privilege RULE on a table to
 108 be allowed to define a rule on it.
 109 .PP
 110 It is very important to take care to avoid circular rules. For
 111 example, though each of the following two rule definitions are
 112 accepted by PostgreSQL, the
 113 \fBSELECT\fR command would cause
 114 PostgreSQL to report an error because
 115 the query cycled too many times:
 116 .sp
 117 .nf
 118 CREATE RULE "_RETURN" AS
 119     ON SELECT TO t1
 120     DO INSTEAD
 121         SELECT * FROM t2;
 122
 123 CREATE RULE "_RETURN" AS
 124     ON SELECT TO t2
 125     DO INSTEAD
 126         SELECT * FROM t1;
 127
 128 SELECT * FROM t1;
 129 .sp
 130 .fi
 131 .PP
 132 Presently, if a rule action contains a \fBNOTIFY\fR
 133 command, the \fBNOTIFY\fR command will be executed
 134 unconditionally, that is, the \fBNOTIFY\fR will be
 135 issued even if there are not any rows that the rule should apply
 136 to. For example, in
 137 .sp
 138 .nf
 139 CREATE RULE notify_me AS ON UPDATE TO mytable DO NOTIFY mytable;
 140
 141 UPDATE mytable SET name = 'foo' WHERE id = 42;
 142 .sp
 143 .fi
 144 one \fBNOTIFY\fR event will be sent during the
 145 \fBUPDATE\fR, whether or not there are any rows with
 146 id = 42. This is an implementation restriction
 147 that may be fixed in future releases.
 148 .SH "COMPATIBILITY"
 149 .PP
 150 \fBCREATE RULE\fR is a
 151 PostgreSQL language extension, as is the
 152 entire rules system.