353 lines
10 KiB
Plaintext
353 lines
10 KiB
Plaintext
<REFENTRY ID="SQL-CREATERULE">
|
|
<REFMETA>
|
|
<REFENTRYTITLE>
|
|
CREATE RULE
|
|
</REFENTRYTITLE>
|
|
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
|
|
</REFMETA>
|
|
<REFNAMEDIV>
|
|
<REFNAME>
|
|
CREATE RULE
|
|
</REFNAME>
|
|
<REFPURPOSE>
|
|
Defines a new rule
|
|
</REFPURPOSE>
|
|
</refnamediv>
|
|
<REFSYNOPSISDIV>
|
|
<REFSYNOPSISDIVINFO>
|
|
<DATE>1998-09-11</DATE>
|
|
</REFSYNOPSISDIVINFO>
|
|
<SYNOPSIS>
|
|
CREATE RULE <replaceable class="parameter">name</replaceable>
|
|
AS ON <replaceable class="parameter">event</replaceable>
|
|
TO <replaceable class="parameter">object</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
|
|
DO [ INSTEAD ] [ <replaceable class="parameter">action</replaceable> | NOTHING ]
|
|
</SYNOPSIS>
|
|
|
|
<REFSECT2 ID="R2-SQL-CREATERULE-1">
|
|
<REFSECT2INFO>
|
|
<DATE>1998-09-11</DATE>
|
|
</REFSECT2INFO>
|
|
<TITLE>
|
|
Inputs
|
|
</TITLE>
|
|
<PARA>
|
|
</PARA>
|
|
<VARIABLELIST>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
<replaceable class="parameter">name</replaceable>
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
The name of a rule to create.
|
|
</PARA>
|
|
</LISTITEM>
|
|
</VARLISTENTRY>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
<replaceable class="parameter">event</replaceable>
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
Event is one of <literal>select</literal>,
|
|
<literal>update</literal>, <literal>delete</literal>
|
|
or <literal>insert</literal>.
|
|
</PARA>
|
|
</LISTITEM>
|
|
</VARLISTENTRY>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
<replaceable class="parameter">object</replaceable>
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
Object is either <replaceable class="parameter">table</replaceable>
|
|
or <replaceable class="parameter">table</replaceable>.<replaceable class="parameter">column</replaceable>.
|
|
</PARA>
|
|
</LISTITEM>
|
|
</VARLISTENTRY>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
<replaceable class="parameter">condition</replaceable>
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
Any SQL WHERE clause. <literal>new</literal> or
|
|
<literal>current</literal> can appear instead of an instance
|
|
variable whenever an instance variable is permissible in SQL.
|
|
</PARA>
|
|
</LISTITEM>
|
|
</VARLISTENTRY>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
<replaceable class="parameter">action</replaceable>
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
Any SQL statement. <literal>new</literal> or
|
|
<literal>current</literal> can appear instead of an instance
|
|
variable whenever an instance variable is permissible in SQL.
|
|
</PARA>
|
|
</LISTITEM>
|
|
</VARLISTENTRY>
|
|
</VARIABLELIST>
|
|
|
|
</REFSECT2>
|
|
|
|
<REFSECT2 ID="R2-SQL-CREATERULE-2">
|
|
<REFSECT2INFO>
|
|
<DATE>1998-09-11</DATE>
|
|
</REFSECT2INFO>
|
|
<TITLE>
|
|
Outputs
|
|
</TITLE>
|
|
<PARA>
|
|
<VARIABLELIST>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
<ReturnValue>CREATE</ReturnValue>
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
Message returned if the rule is successfully created.
|
|
</para>
|
|
</listitem>
|
|
</VARLISTENTRY>
|
|
</VARIABLELIST>
|
|
</para>
|
|
</REFSECT2>
|
|
</REFSYNOPSISDIV>
|
|
|
|
<REFSECT1 ID="R1-SQL-CREATERULE-1">
|
|
<REFSECT1INFO>
|
|
<DATE>1998-09-11</DATE>
|
|
</REFSECT1INFO>
|
|
<TITLE>
|
|
Description
|
|
</TITLE>
|
|
<PARA>
|
|
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, updates and deletes) and a new instance (for updates and
|
|
appends). If the <replaceable class="parameter">event</replaceable>
|
|
specified in the ON clause and the
|
|
<replaceable class="parameter">condition</replaceable> specified in the
|
|
WHERE clause are true for the current instance, the
|
|
<replaceable class="parameter">action</replaceable> part of the rule is
|
|
executed. First, however, values from fields in the current instance
|
|
and/or the new instance are substituted for
|
|
<literal>current.</literal><replaceable class="parameter">attribute-name</replaceable>
|
|
and <literal>new.</literal><replaceable class="parameter">attribute-name</replaceable>.
|
|
</para>
|
|
<para>
|
|
The <replaceable class="parameter">action</replaceable> part of the rule
|
|
executes with the same command and transaction identifier as the user
|
|
command that caused activation.
|
|
</para>
|
|
|
|
<REFSECT2 ID="R2-SQL-CREATERULE-3">
|
|
<REFSECT2INFO>
|
|
<DATE>1998-09-11</DATE>
|
|
</REFSECT2INFO>
|
|
<TITLE>
|
|
Notes
|
|
</TITLE>
|
|
<para>
|
|
A caution about SQL rules is in order. If the same class name
|
|
or instance variable appears in the
|
|
<replaceable class="parameter">event</replaceable>, the
|
|
<replaceable class="parameter">condition</replaceable> and the
|
|
<replaceable class="parameter">action</replaceable> parts of a rule,
|
|
they are all considered different tuple variables. More accurately,
|
|
<literal>new</literal> and <literal>current</literal> are the only tuple
|
|
variables that are shared between these clauses. For example, the following
|
|
two rules have the same semantics:
|
|
<programlisting>
|
|
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 ...
|
|
</programlisting>
|
|
Each rule can have the optional tag INSTEAD.
|
|
Without
|
|
this tag, <replaceable class="parameter">action</replaceable> will be
|
|
performed in addition to the user command when the
|
|
<replaceable class="parameter">event</replaceable> in the
|
|
<replaceable class="parameter">condition</replaceable> part of the rule
|
|
occurs. Alternately, the
|
|
<replaceable class="parameter">action</replaceable> part will be done
|
|
instead of the user command. In this later case, the
|
|
<replaceable class="parameter">action</replaceable> can be the keyword
|
|
NOTHING.
|
|
</para>
|
|
<para>
|
|
When choosing between the rewrite and instance rule systems for a
|
|
particular rule application, remember that in the rewrite system,
|
|
<literal>current</literal> refers to a relation and some qualifiers
|
|
whereas in the instance system it refers to an instance (tuple).
|
|
</para>
|
|
<para>
|
|
It is very important to note that the rewrite rule system
|
|
will neither detect nor process circular rules. For example, though each
|
|
of the following two rule definitions are accepted by
|
|
<productname>Postgres</productname>, the
|
|
retrieve command will cause <productname>Postgres</productname> to crash:
|
|
|
|
<example>
|
|
<title>Example of a circular rewrite rule combination.</title>
|
|
<programlisting>
|
|
create rule bad_rule_combination_1 as
|
|
on select to EMP
|
|
do instead select to TOYEMP
|
|
|
|
create rule bad_rule_combination_2 as
|
|
on select to TOYEMP
|
|
do instead select to EMP
|
|
</programlisting>
|
|
<para>
|
|
This attempt to retrieve from EMP will cause
|
|
<productname>Postgres</productname> to crash.
|
|
<programlisting>
|
|
select * from EMP
|
|
</programlisting></para>
|
|
</example>
|
|
|
|
</para>
|
|
<para>
|
|
You must have rule definition access to a class in order
|
|
to define a rule on it. Use <command>GRANT</command>
|
|
and <command>REVOKE</command> to change permissions.
|
|
|
|
</PARA>
|
|
</REFSECT2>
|
|
</refsect1>
|
|
|
|
<REFSECT1 ID="R1-SQL-CREATERULE-2">
|
|
<TITLE>
|
|
Usage
|
|
</TITLE>
|
|
<PARA>
|
|
Make Sam get the same salary adjustment as Joe:
|
|
|
|
<programlisting>
|
|
create rule example_1 as
|
|
on update EMP.salary where current.name = "Joe"
|
|
do update EMP (salary = new.salary)
|
|
where EMP.name = "Sam"
|
|
</programlisting>
|
|
|
|
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.
|
|
</para>
|
|
<para>
|
|
Make Bill get Joe's salary when it is accessed:
|
|
<programlisting>
|
|
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"
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Deny Joe access to the salary of employees in the shoe
|
|
department (<function>current_user</function> returns the name of
|
|
the current user):
|
|
<programlisting>
|
|
create rule example_3 as
|
|
on select to EMP.salary
|
|
where current.dept = "shoe" and current_user = "Joe"
|
|
do instead nothing
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Create a view of the employees working in the toy department.
|
|
<programlisting>
|
|
create TOYEMP(name = char16, salary = int4)
|
|
|
|
create rule example_4 as
|
|
on select to TOYEMP
|
|
do instead
|
|
select (EMP.name, EMP.salary) from EMP
|
|
where EMP.dept = "toy"
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
All new employees must make 5,000 or less
|
|
<programlisting>
|
|
create rule example_5 as
|
|
on insert to EMP where new.salary > 5000
|
|
do update newset salary = 5000
|
|
</programlisting>
|
|
</PARA>
|
|
</REFSECT1>
|
|
|
|
<REFSECT1 ID="R1-SQL-CREATERULE-3">
|
|
<TITLE>
|
|
Bugs
|
|
</TITLE>
|
|
<para>
|
|
The object in a SQL rule cannot be an array reference and
|
|
cannot have parameters.
|
|
</para>
|
|
<para>
|
|
Aside from the "oid" field, system attributes cannot be
|
|
referenced anywhere in a rule. Among other things, this
|
|
means that functions of instances (e.g., "<literal>foo(emp)</literal>" where
|
|
"<literal>emp</literal>" is a class) cannot be called anywhere in a rule.
|
|
</para>
|
|
<para>
|
|
The rule system stores 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).
|
|
</PARA>
|
|
</refsect1>
|
|
|
|
<REFSECT1 ID="R1-SQL-CREATERULE-4">
|
|
<TITLE>
|
|
Compatibility
|
|
</TITLE>
|
|
<PARA>
|
|
CREATE RULE statement is a <productname>Postgres</productname>
|
|
language extension.
|
|
</PARA>
|
|
|
|
<REFSECT2 ID="R2-SQL-CREATERULE-4">
|
|
<REFSECT2INFO>
|
|
<DATE>1998-09-11</DATE>
|
|
</REFSECT2INFO>
|
|
<TITLE>
|
|
SQL92
|
|
</TITLE>
|
|
<para>
|
|
There is no CREATE RULE statement in <acronym>SQL92</acronym>.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
</REFENTRY>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../reference.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:"/usr/lib/sgml/catalog"
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|