begriffs open source - ai-pg/blob - full-docs/man7/CREATE_RULE.7

   1 '\" t
   2 .\"     Title: CREATE RULE
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "CREATE RULE" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 CREATE_RULE \- define a new rewrite rule
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE [ OR REPLACE ] RULE \fIname\fR AS ON \fIevent\fR
  36     TO \fItable_name\fR [ WHERE \fIcondition\fR ]
  37     DO [ ALSO | INSTEAD ] { NOTHING | \fIcommand\fR | ( \fIcommand\fR ; \fIcommand\fR \&.\&.\&. ) }
  38
  39 where \fIevent\fR can be one of:
  40
  41     SELECT | INSERT | UPDATE | DELETE
  42 .fi
  43 .SH "DESCRIPTION"
  44 .PP
  45 \fBCREATE RULE\fR
  46 defines a new rule applying to a specified table or view\&.
  47 \fBCREATE OR REPLACE RULE\fR
  48 will either create a new rule, or replace an existing rule of the same name for the same table\&.
  49 .PP
  50 The
  51 PostgreSQL
  52 rule system allows one to define an alternative action to be performed on insertions, updates, or deletions in database tables\&. Roughly speaking, a rule causes additional commands to be executed when a given command on a given table is executed\&. Alternatively, an
  53 INSTEAD
  54 rule can replace a given command by another, or cause a command not to be executed at all\&. Rules are used to implement SQL views as well\&. It is important to realize that a rule is really a command transformation mechanism, or command macro\&. The transformation happens before the execution of the command starts\&. If you actually want an operation that fires independently for each physical row, you probably want to use a trigger, not a rule\&. More information about the rules system is in
  55 Chapter\ \&39\&.
  56 .PP
  57 Presently,
  58 ON SELECT
  59 rules can only be attached to views\&. Such a rule must be named
  60 "_RETURN", must be an unconditional
  61 INSTEAD
  62 rule, and must have an action that consists of a single
  63 \fBSELECT\fR
  64 command\&. This command defines the visible contents of the view\&. (The view itself is basically a dummy table with no storage\&.) It\*(Aqs best to regard such a rule as an implementation detail\&. While a view can be redefined via
  65 CREATE OR REPLACE RULE "_RETURN" AS \&.\&.\&., it\*(Aqs better style to use
  66 CREATE OR REPLACE VIEW\&.
  67 .PP
  68 You can create the illusion of an updatable view by defining
  69 ON INSERT,
  70 ON UPDATE, and
  71 ON DELETE
  72 rules (or any subset of those that\*(Aqs sufficient for your purposes) to replace update actions on the view with appropriate updates on other tables\&. If you want to support
  73 \fBINSERT RETURNING\fR
  74 and so on, then be sure to put a suitable
  75 RETURNING
  76 clause into each of these rules\&.
  77 .PP
  78 There is a catch if you try to use conditional rules for complex view updates: there
  79 \fImust\fR
  80 be an unconditional
  81 INSTEAD
  82 rule for each action you wish to allow on the view\&. If the rule is conditional, or is not
  83 INSTEAD, then the system will still reject attempts to perform the update action, because it thinks it might end up trying to perform the action on the dummy table of the view in some cases\&. If you want to handle all the useful cases in conditional rules, add an unconditional
  84 DO INSTEAD NOTHING
  85 rule to ensure that the system understands it will never be called on to update the dummy table\&. Then make the conditional rules non\-INSTEAD; in the cases where they are applied, they add to the default
  86 INSTEAD NOTHING
  87 action\&. (This method does not currently work to support
  88 RETURNING
  89 queries, however\&.)
  90 .if n \{\
  91 .sp
  92 .\}
  93 .RS 4
  94 .it 1 an-trap
  95 .nr an-no-space-flag 1
  96 .nr an-break-flag 1
  97 .br
  98 .ps +1
  99 \fBNote\fR
 100 .ps -1
 101 .br
 102 .PP
 103 A view that is simple enough to be automatically updatable (see
 104 CREATE VIEW (\fBCREATE_VIEW\fR(7))) does not require a user\-created rule in order to be updatable\&. While you can create an explicit rule anyway, the automatic update transformation will generally outperform an explicit rule\&.
 105 .PP
 106 Another alternative worth considering is to use
 107 INSTEAD OF
 108 triggers (see
 109 CREATE TRIGGER (\fBCREATE_TRIGGER\fR(7))) in place of rules\&.
 110 .sp .5v
 111 .RE
 112 .SH "PARAMETERS"
 113 .PP
 114 \fIname\fR
 115 .RS 4
 116 The name of a rule to create\&. This must be distinct from the name of any other rule for the same table\&. Multiple rules on the same table and same event type are applied in alphabetical name order\&.
 117 .RE
 118 .PP
 119 \fIevent\fR
 120 .RS 4
 121 The event is one of
 122 SELECT,
 123 INSERT,
 124 UPDATE, or
 125 DELETE\&. Note that an
 126 \fBINSERT\fR
 127 containing an
 128 ON CONFLICT
 129 clause cannot be used on tables that have either
 130 INSERT
 131 or
 132 UPDATE
 133 rules\&. Consider using an updatable view instead\&.
 134 .RE
 135 .PP
 136 \fItable_name\fR
 137 .RS 4
 138 The name (optionally schema\-qualified) of the table or view the rule applies to\&.
 139 .RE
 140 .PP
 141 \fIcondition\fR
 142 .RS 4
 143 Any
 144 SQL
 145 conditional expression (returning
 146 boolean)\&. The condition expression cannot refer to any tables except
 147 NEW
 148 and
 149 OLD, and cannot contain aggregate functions\&.
 150 .RE
 151 .PP
 152 \fBINSTEAD\fR
 153 .RS 4
 154 INSTEAD
 155 indicates that the commands should be executed
 156 \fIinstead of\fR
 157 the original command\&.
 158 .RE
 159 .PP
 160 \fBALSO\fR
 161 .RS 4
 162 ALSO
 163 indicates that the commands should be executed
 164 \fIin addition to\fR
 165 the original command\&.
 166 .sp
 167 If neither
 168 ALSO
 169 nor
 170 INSTEAD
 171 is specified,
 172 ALSO
 173 is the default\&.
 174 .RE
 175 .PP
 176 \fIcommand\fR
 177 .RS 4
 178 The command or commands that make up the rule action\&. Valid commands are
 179 \fBSELECT\fR,
 180 \fBINSERT\fR,
 181 \fBUPDATE\fR,
 182 \fBDELETE\fR, or
 183 \fBNOTIFY\fR\&.
 184 .RE
 185 .PP
 186 Within
 187 \fIcondition\fR
 188 and
 189 \fIcommand\fR, the special table names
 190 NEW
 191 and
 192 OLD
 193 can be used to refer to values in the referenced table\&.
 194 NEW
 195 is valid in
 196 ON INSERT
 197 and
 198 ON UPDATE
 199 rules to refer to the new row being inserted or updated\&.
 200 OLD
 201 is valid in
 202 ON UPDATE
 203 and
 204 ON DELETE
 205 rules to refer to the existing row being updated or deleted\&.
 206 .SH "NOTES"
 207 .PP
 208 You must be the owner of a table to create or change rules for it\&.
 209 .PP
 210 In a rule for
 211 INSERT,
 212 UPDATE, or
 213 DELETE
 214 on a view, you can add a
 215 RETURNING
 216 clause that emits the view\*(Aqs columns\&. This clause will be used to compute the outputs if the rule is triggered by an
 217 \fBINSERT RETURNING\fR,
 218 \fBUPDATE RETURNING\fR, or
 219 \fBDELETE RETURNING\fR
 220 command respectively\&. When the rule is triggered by a command without
 221 RETURNING, the rule\*(Aqs
 222 RETURNING
 223 clause will be ignored\&. The current implementation allows only unconditional
 224 INSTEAD
 225 rules to contain
 226 RETURNING; furthermore there can be at most one
 227 RETURNING
 228 clause among all the rules for the same event\&. (This ensures that there is only one candidate
 229 RETURNING
 230 clause to be used to compute the results\&.)
 231 RETURNING
 232 queries on the view will be rejected if there is no
 233 RETURNING
 234 clause in any available rule\&.
 235 .PP
 236 It is very important to take care to avoid circular rules\&. For example, though each of the following two rule definitions are accepted by
 237 PostgreSQL, the
 238 \fBSELECT\fR
 239 command would cause
 240 PostgreSQL
 241 to report an error because of recursive expansion of a rule:
 242 .sp
 243 .if n \{\
 244 .RS 4
 245 .\}
 246 .nf
 247 CREATE RULE "_RETURN" AS
 248     ON SELECT TO t1
 249     DO INSTEAD
 250         SELECT * FROM t2;
 251
 252 CREATE RULE "_RETURN" AS
 253     ON SELECT TO t2
 254     DO INSTEAD
 255         SELECT * FROM t1;
 256
 257 SELECT * FROM t1;
 258 .fi
 259 .if n \{\
 260 .RE
 261 .\}
 262 .PP
 263 Presently, if a rule action contains a
 264 \fBNOTIFY\fR
 265 command, the
 266 \fBNOTIFY\fR
 267 command will be executed unconditionally, that is, the
 268 \fBNOTIFY\fR
 269 will be issued even if there are not any rows that the rule should apply to\&. For example, in:
 270 .sp
 271 .if n \{\
 272 .RS 4
 273 .\}
 274 .nf
 275 CREATE RULE notify_me AS ON UPDATE TO mytable DO ALSO NOTIFY mytable;
 276
 277 UPDATE mytable SET name = \*(Aqfoo\*(Aq WHERE id = 42;
 278 .fi
 279 .if n \{\
 280 .RE
 281 .\}
 282 .sp
 283 one
 284 \fBNOTIFY\fR
 285 event will be sent during the
 286 \fBUPDATE\fR, whether or not there are any rows that match the condition
 287 id = 42\&. This is an implementation restriction that might be fixed in future releases\&.
 288 .SH "COMPATIBILITY"
 289 .PP
 290 \fBCREATE RULE\fR
 291 is a
 292 PostgreSQL
 293 language extension, as is the entire query rewrite system\&.
 294 .SH "SEE ALSO"
 295 ALTER RULE (\fBALTER_RULE\fR(7)), DROP RULE (\fBDROP_RULE\fR(7))