Support Docs & Contrib

doc/man/create_rule.l

@@ -0,0 +1,221 @@
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_rule.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
+.TH "CREATE RULE" SQL 11/05/95 Postgres95 Postgres95
+.SH NAME
+create rule \(em define a new rule
+.SH SYNOPSIS
+.nf
+\fBcreate\fR \fBrule\fR rule_name
+    \fBas\fR \fBon\fR event
+      \fBto\fR object [\fBwhere\fR clause]
+    \fBdo\fR [\fBinstead\fR]
+    [action | nothing | \fB[\fPactions...\fB]\fP]
+.fi
+.SH DESCRIPTION
+.IR "The current rule system implementation is very brittle and is unstable.  Users are discouraged from using rules at this time."
+.PP
+.BR "Create rule"
+is used to define a new rule.
+.PP
+Here, 
+.IR event
+is one of 
+.IR select ,
+.IR update ,
+.IR delete
+or
+.IR insert .
+.IR Object
+is either:
+.nf
+a class name
+    \fIor\fR
+class.column
+.fi
+The 
+.BR "from"
+clause, the 
+.BR "where"
+clause, and the
+.IR action
+are respectively normal SQL
+.BR "from"
+clauses,
+.BR "where"
+clauses and collections of SQL commands with the following change:
+.IP
+.BR new
+or
+.BR current
+can appear instead of 
+an instance variable whenever an instance 
+variable is permissible in SQL.
+.PP
+The semantics of a rule is that at the time an individual instance is
+accessed, updated, inserted or deleted, there is a 
+.BR current
+instance
+(for retrieves, updates and deletes) and a 
+.BR new
+instance (for updates and appends).  If the event specified in the
+.BR "on"
+clause and the condition specified in the
+.BR "where"
+clause are true for the current instance, then the 
+.IR action
+part of the rule is executed.  First, however, values from fields in
+the current instance and/or the new instance are substituted for:
+.nf
+current.attribute-name
+new.attribute-name
+.fi
+The
+.IR action
+part of the rule executes with same command and transaction identifier
+as the user command that caused activation.
+.PP
+A note of caution about SQL rules is in order.  If the same class
+name or instance variable appears in the event, 
+.BR where
+clause and the 
+.IR action
+parts of a rule, they are all considered different tuple variables.
+More accurately,
+.BR new
+and
+.BR current
+are the only tuple variables that are shared between these clauses.
+For example, the following two rules have the same semantics:
+.nf
+on update to EMP.salary where EMP.name = "Joe"
+	do update EMP ( ... ) where ...
+
+on update to EMP-1.salary where EMP-2.name = "Joe"
+	do update EMP-3 ( ... ) where ...
+.fi
+Each rule can have the optional tag 
+.BR "instead" .
+Without this tag 
+.IR action
+will be performed in addition to the user command when the event in
+the condition part of the rule occurs.  Alternately, the
+.IR action 
+part will be done instead of the user command.
+In this later case, the action can be the keyword
+.BR nothing .
+.PP
+When choosing between the rewrite and instance rule systems for a
+particular rule application, remember that in the rewrite system
+.BR current
+refers to a relation and some qualifiers whereas in the instance
+system it refers to an instance (tuple).
+.PP
+It is very important to note that the 
+.BR rewrite 
+rule system will 
+neither detect nor process circular
+rules. For example, though each of the following two rule
+definitions are accepted by Postgres, the  
+.IR retrieve 
+command will cause 
+Postgres to 
+.IR crash :
+.nf
+--
+--Example of a circular rewrite rule combination. 
+--
+create rule bad_rule_combination_1 is
+	on select to EMP 
+	do instead select to TOYEMP
+
+create rule bad_rule_combination_2 is
+	on select to TOYEMP
+	do instead select to EMP
+
+--
+--This attempt to retrieve from EMP will cause Postgres to crash.
+--
+select * from EMP
+.fi
+.PP
+You must have
+.IR "rule definition"
+access to a class in order to define a rule on it (see
+.IR "change acl" (l).
+.SH EXAMPLES
+.nf
+--
+--Make Sam get the same salary adjustment as Joe
+--
+create rule example_1 is
+    on update EMP.salary where current.name = "Joe"
+    do update EMP (salary = new.salary)
+	where EMP.name = "Sam"
+.fi
+At the time Joe receives a salary adjustment, the event will become
+true and Joe's current instance and proposed new instance are available
+to the execution routines.  Hence, his new salary is substituted into the 
+.IR action
+part of the rule which is subsequently executed.  This propagates
+Joe's salary on to Sam.
+.nf
+--
+--Make Bill get Joe's salary when it is accessed
+--
+create rule example_2 is
+    on select to EMP.salary
+        where current.name = "Bill"
+    do instead
+	select (EMP.salary) from EMP where EMP.name = "Joe"
+.fi
+.nf
+--
+--Deny Joe access to the salary of employees in the shoe
+--department.  (pg_username() returns the name of the current user)
+--
+create rule example_3 is
+    on select to EMP.salary
+	where current.dept = "shoe"
+              and pg_username() = "Joe"
+    do instead nothing
+.fi
+.nf
+--
+--Create a view of the employees working in the toy department.
+--
+create TOYEMP(name = char16, salary = int4)
+
+create rule example_4 is
+    on select to TOYEMP
+    do instead select (EMP.name, EMP.salary) from EMP
+	where EMP.dept = "toy"
+.fi
+.nf
+--
+--All new employees must make 5,000 or less
+--
+create rule example_5 is
+	on insert to EMP where new.salary > 5000
+	do update newset salary = 5000
+.fi
+.SH "SEE ALSO"
+drop rule(l),
+create view(l).
+.SH BUGS
+.PP
+.BR "instead"
+rules do not work properly.
+.PP
+The object in a SQL rule cannot be an array reference and cannot
+have parameters.
+.PP
+Aside from the \*(lqoid\*(rq field, system attributes cannot be
+referenced anywhere in a rule.  Among other things, this means that
+functions of instances (e.g., \*(lqfoo(emp)\*(rq where \*(lqemp\*(rq
+is a class) cannot be called anywhere in a rule.
+.PP
+The rule system store the rule text and query plans as text 
+attributes.  This implies that creation of rules may fail if the
+rule plus its various internal representations exceed some value
+that is on the order of one page (8KB).