Changed manpages for create_rule/drop_rule to the semantics
of the rule system of v6.4 and descendants. Jan
This commit is contained in:
Jan Wieck
parent
fa0f24165c
commit
afd57dbb3a
|
|
@ -1,6 +1,6 @@
|
|||
.\" This is -*-nroff-*-
|
||||
.\" XXX standard disclaimer belongs here....
|
||||
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_rule.l,v 1.10 1999/02/02 17:46:17 momjian Exp $
|
||||
.\" $Header: /cvsroot/pgsql/src/man/Attic/create_rule.l,v 1.11 1999/02/07 22:10:09 wieck Exp $
|
||||
.TH "CREATE RULE" SQL 11/05/95 PostgreSQL PostgreSQL
|
||||
.SH NAME
|
||||
create rule - define a new rule
|
||||
|
|
@ -10,7 +10,7 @@ create rule - define a new rule
|
|||
\fBas\fR \fBon\fR event
|
||||
\fBto\fR object [\fBwhere\fR clause]
|
||||
\fBdo\fR [\fBinstead\fR]
|
||||
[action | nothing | \fB[\fPactions...\fB]\fP]
|
||||
[\fBnothing\fP | action | \fB(\fPactions...\fB)\fP]
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
|
|
@ -26,73 +26,53 @@ is one of
|
|||
or
|
||||
.IR insert .
|
||||
.IR Object
|
||||
is either:
|
||||
.nf
|
||||
a class name
|
||||
\fIor\fR
|
||||
class.column
|
||||
.fi
|
||||
is a class name.
|
||||
.PP
|
||||
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
|
||||
.BR old
|
||||
can appear instead of
|
||||
an instance variable whenever an instance
|
||||
variable is permissible in SQL.
|
||||
.PP
|
||||
Since v6.4 rules on
|
||||
.IR select
|
||||
are restricted to build
|
||||
.BR views .
|
||||
.BR "Create view"
|
||||
should be used instead.
|
||||
.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
|
||||
updated, inserted or deleted, there is an
|
||||
.BR old
|
||||
instance
|
||||
(for retrieves, updates and deletes) and a
|
||||
(for updates and deletes) and a
|
||||
.BR new
|
||||
instance (for updates and appends). If the event specified in the
|
||||
instance (for updates and inserts). 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
|
||||
clause are true, 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:
|
||||
the old instance and/or the new instance are substituted for:
|
||||
.nf
|
||||
current.attribute-name
|
||||
old.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.
|
||||
part of the rule executes with same transaction identifier
|
||||
before 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
|
||||
|
|
@ -104,116 +84,92 @@ 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 :
|
||||
.IR update
|
||||
command to one of the classes will cause
|
||||
Postgres to abort the transaction during the attempt to apply rules.
|
||||
.nf
|
||||
|
||||
--
|
||||
--Example of a circular rewrite rule combination.
|
||||
--
|
||||
create rule bad_rule_combination_1 as
|
||||
on select to EMP
|
||||
do instead select to TOYEMP
|
||||
on update to EMP
|
||||
do update TOY set ...;
|
||||
|
||||
create rule bad_rule_combination_2 as
|
||||
on select to TOYEMP
|
||||
do instead select to EMP
|
||||
on update to TOY
|
||||
do update EMP set ...;
|
||||
|
||||
--
|
||||
--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.
|
||||
.PP
|
||||
In contrast to queries run by trigger procedures,
|
||||
the rule actions are executed under the permissions of the owner
|
||||
of the
|
||||
.BR event
|
||||
class. Thus, if the owner of a class defines a rule that inserts something
|
||||
into another one (like in the log example below), the user updating the
|
||||
.BR event
|
||||
class must not have
|
||||
.IR insert
|
||||
permissions for the class specified in the
|
||||
.BR "rule actions" .
|
||||
This technique can safely be used to deny users from modifying event logging.
|
||||
.SH EXAMPLES
|
||||
.nf
|
||||
|
||||
--
|
||||
--Make Sam get the same salary adjustment as Joe
|
||||
--
|
||||
create rule example_1 as
|
||||
on update EMP.salary where current.name = "Joe"
|
||||
do update EMP (salary = new.salary)
|
||||
where EMP.name = "Sam"
|
||||
on update to EMP where old.name = "Joe"
|
||||
do update EMP set 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
|
||||
true and Joe's old 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
|
||||
part of the rule which is executed. This propagates
|
||||
Joe's salary on to Sam.
|
||||
.nf
|
||||
|
||||
--
|
||||
--Make Bill get Joe's salary when it is accessed
|
||||
-- Log changes to salary
|
||||
--
|
||||
create rule example_2 as
|
||||
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)
|
||||
--
|
||||
on insert to EMP
|
||||
do insert into EMP_LOG (name, newsal, when)
|
||||
values (new.name, new.salary, 'now'::text);
|
||||
|
||||
create rule example_3 as
|
||||
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 = name, salary = int4)
|
||||
on update to EMP where old.salary != new.salary
|
||||
do insert into EMP_LOG (name, oldsal, newsal, when)
|
||||
values (old.name, old.salary, new.salary, 'now'::text);
|
||||
|
||||
create rule example_4 as
|
||||
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 as
|
||||
on insert to EMP where new.salary > 5000
|
||||
do update newset salary = 5000
|
||||
on delete to EMP
|
||||
do insert into EMP_LOG (name, oldsal, when)
|
||||
values (old.name, old.salary, 'now'::text);
|
||||
|
||||
.fi
|
||||
.SH "SEE ALSO"
|
||||
drop_rule(l),
|
||||
create_view(l).
|
||||
create_view(l),
|
||||
create_trigger(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
|
||||
The rule system stores the rule definition as query plans into text
|
||||
attributes. This implies that creation of rules may fail if the
|
||||
rule plus its various internal representations exceed some value
|
||||
rule in its internal representations exceed some value
|
||||
that is on the order of one page (8KB).
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
.\" This is -*-nroff-*-
|
||||
.\" XXX standard disclaimer belongs here....
|
||||
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_rule.l,v 1.3 1998/06/23 17:52:36 momjian Exp $
|
||||
.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_rule.l,v 1.4 1999/02/07 22:10:10 wieck Exp $
|
||||
.TH "DROP RULE" SQL 11/05/95 PostgreSQL PostgreSQL
|
||||
.SH NAME
|
||||
drop rule \- removes a current rule from Postgres
|
||||
|
|
@ -21,7 +21,5 @@ drop rule example_1
|
|||
.fi
|
||||
.SH "SEE ALSO"
|
||||
create_rule(l),
|
||||
drop_view(l).
|
||||
.SH BUGS
|
||||
Once a rule is dropped, access to historical information the rule has
|
||||
written may disappear.
|
||||
drop_view(l),
|
||||
drop_trigger(l).
|
||||
|
|
|
|||
Loading…
Reference in New Issue