WARNING

This text was automatically converted from troff me macros to HTML. Information may have been lost, added, or changed in the process. Lars Aronsson and Lysator do not guarantee the correctness of this HTML document.

NAME

define rule Define a new rule

SYNOPSIS

define [instance | rewrite] rule rule_name
    [as exception to rule_name_2]
    is on event
      to object [[from clause] where clause]
    do [instead]
    [action | nothing | '[' action ... ']']

DESCRIPTION

Define rule is used to define a new rule. There are two implementations of the rules system, one based on query rewrite and the other based on instance-level processing. In general, the instance-level system is more efficient if there are many rules on a single class, each covering a small subset of the instances. The rewrite system is more efficient if large scope rules are being defined. The user can optionally choose which rule system to use by specifying rewrite or instance in the command. If the user does not specify which system to use, POSTGRES defaults to using the instance-level system. In the long run POSTGRES will automatically decide which rules system to use and the possibility of user selection will be removed.

Here, event is one of:

retrieve 
replace 
delete
append

Moreover, object is either:

a class name
or
class.column

The FROM clause, the WHERE clause, and the action are respectively normal POSTQUEL FROM clauses, WHERE clauses and collections of POSTQUEL commands with the following change: new or current can appear instead of an instance variable whenever an instance variable is permissible in POSTQUEL.

The semantics of a rule is that at the time an individual instance is accessed, updated, inserted or deleted, there is a current instance (for retrieves, replaces and deletes) and a new instance (for replaces and appends). If the event specified in the ON clause and the condition specified in the WHERE clause are true for the current instance, then the action part of the rule is executed. First, however, values from fields in the current instance and/or the new instance are substituted for:

current.attribute-name
new.attribute-name

The action part of the rule executes with same command and transaction identifier as the user command that caused activation.

A note of caution about POSTQUEL rules is in order. If the same class name or instance variable appears in the event, where clause and the action parts of a rule, they are all considered different tuple variables. More accurately, new and current are the only tuple variables that are shared between these clauses. For example the following two rules have the same semantics:

on replace to EMP.salary where EMP.name = "Joe"
 do replace EMP ( ... ) where ...

on replace to EMP-1.salary where EMP-2.name = "Joe"
 do replace EMP-3 ( ... ) where ...

Each rule can have the optional tag "instead". Without this tag the action will be performed in addition to the user command when the event in the condition part of the rule occurs. Alternately, the action part will be done instead of the user command. In this later case, the action can be the keyword nothing.

When choosing between the rewrite and instance rule systems for a particular rule application, remember that in the rewrite system 'current' refers to a relation and some qualifiers whereas in the instance system it refers to an instance (read tuple).

EXAMPLES

/* Make Sam get the same salary adjustment as Joe */

define rule example_1 is
    on replace to EMP.salary where current.name = "Joe"
    do replace EMP (salary = new.salary)
 where EMP.name = "Sam"

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 action part of the rule which is subsequently executed. This propagates Joe's salary on to Sam.

/* Make Bill get Joe's salary when it is accessed */

define rule example_2 is
    on retrieve to EMP.salary
        where current.name = "Bill"
    do instead
 retrieve (EMP.salary) where EMP.name = "Joe"

/* Deny Joe access to the salary of employees in */
/* the shoe department.  Note: pg_username()     */
/* returns the name of the current user          */

define rule example_3 is
    on retrieve to EMP.salary
 where current.dept = "shoe"
              and pg_username() = "Joe"
    do instead nothing

/* Create a view of the employees working in */
/* the toy department.                       */

create TOYEMP(name = char16, salary = int4)

define rule example_4 is
    on retrieve to TOYEMP
    do instead retrieve (EMP.name, EMP.salary)
 where EMP.dept = "toy"

/* All new employees must make 5,000 or less */

define rule example_5 is
 on append to EMP where new.salary > 5000
 do replace new(salary = 5000)

BUGS

Exceptions are not implemented in Version 4.0.

The object in a POSTQUEL rule cannot be an array reference and cannot have parameters.

The WHERE clause can not have a FROM clause.

Only one POSTQUEL command can be specified in the action part of a tuple rule and it can only be a replace, append, retrieve or delete command.

The rewrite rule system does support multiple action rules surrouas long as the event is not retrieve.