294 lines
9.1 KiB
Plaintext
294 lines
9.1 KiB
Plaintext
<!--
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.21 2001/01/06 04:14:35 tgl Exp $
|
|
Postgres documentation
|
|
-->
|
|
|
|
<refentry id="SQL-CREATERULE">
|
|
<refmeta>
|
|
<refentrytitle id="sql-createrule-title">
|
|
CREATE RULE
|
|
</refentrytitle>
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>
|
|
CREATE RULE
|
|
</refname>
|
|
<refpurpose>
|
|
Defines a new rule
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<refsynopsisdivinfo>
|
|
<date>2001-01-05</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>
|
|
|
|
where <replaceable class="PARAMETER">action</replaceable> can be:
|
|
|
|
NOTHING
|
|
|
|
|
<replaceable class="parameter">query</replaceable>
|
|
|
|
|
( <replaceable class="parameter">query</replaceable> ; <replaceable class="parameter">query</replaceable> ... )
|
|
|
|
|
[ <replaceable class="parameter">query</replaceable> ; <replaceable class="parameter">query</replaceable> ... ]
|
|
</synopsis>
|
|
|
|
<refsect2 id="R2-SQL-CREATERULE-1">
|
|
<refsect2info>
|
|
<date>2001-01-05</date>
|
|
</refsect2info>
|
|
<title>
|
|
Inputs
|
|
</title>
|
|
<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>. (Currently, only the
|
|
<replaceable class="parameter">table</replaceable> form is
|
|
actually implemented.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">condition</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Any SQL boolean-condition expression. The condition expression may not
|
|
refer to any tables except <literal>new</literal> and
|
|
<literal>old</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><replaceable class="parameter">query</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
The query or queries making up the
|
|
<replaceable class="PARAMETER">action</replaceable>
|
|
can be any SQL <literal>SELECT</literal>, <literal>INSERT</literal>,
|
|
<literal>UPDATE</literal>, <literal>DELETE</literal>, or
|
|
<literal>NOTIFY</literal> statement.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Within the <replaceable class="parameter">condition</replaceable>
|
|
and <replaceable class="PARAMETER">action</replaceable>, the special
|
|
table names <literal>new</literal> and <literal>old</literal> may be
|
|
used to refer to values in the referenced table (the
|
|
<replaceable class="parameter">object</replaceable>).
|
|
<literal>new</literal> is valid in ON INSERT and ON UPDATE rules
|
|
to refer to the new row being inserted or updated.
|
|
<literal>old</literal> is valid in ON SELECT, ON UPDATE, and ON DELETE
|
|
rules to refer to the existing row being selected, updated, or deleted.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2 id="R2-SQL-CREATERULE-2">
|
|
<refsect2info>
|
|
<date>1998-09-11</date>
|
|
</refsect2info>
|
|
<title>
|
|
Outputs
|
|
</title>
|
|
<para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><computeroutput>
|
|
CREATE
|
|
</computeroutput></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 <productname>Postgres</productname>
|
|
<firstterm>rule system</firstterm> allows one to define an
|
|
alternate action to be performed on inserts, updates, or deletions
|
|
from database tables. Rules are used to
|
|
implement table views as well.
|
|
</para>
|
|
|
|
<para>
|
|
The semantics of a rule is that at the time an individual instance (row)
|
|
is
|
|
accessed, inserted, updated, or deleted, there is an old instance (for
|
|
selects, updates and deletes) and a new instance (for inserts and
|
|
updates). All the rules for the given event type and the given target
|
|
object (table) are examined, in an unspecified order. If the
|
|
<replaceable class="parameter">condition</replaceable> specified in the
|
|
WHERE clause (if any) is true, the
|
|
<replaceable class="parameter">action</replaceable> part of the rule is
|
|
executed. The <replaceable class="parameter">action</replaceable> is
|
|
done instead of the original query if INSTEAD is specified; otherwise
|
|
it is done before the original query is performed.
|
|
Within both the <replaceable class="parameter">condition</replaceable>
|
|
and <replaceable class="parameter">action</replaceable>, values from
|
|
fields in the old instance and/or the new instance are substituted for
|
|
<literal>old.</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
|
|
can consist of one or more queries. To write multiple queries, surround
|
|
them with either parentheses or square brackets. Such queries will be
|
|
performed in the specified order (whereas there are no guarantees about
|
|
the execution order of multiple rules for an object). The
|
|
<replaceable class="parameter">action</replaceable> can also be NOTHING
|
|
indicating no action. Thus, a DO INSTEAD NOTHING rule suppresses the
|
|
original query from executing (when its condition is true); a DO NOTHING
|
|
rule is useless.
|
|
</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>2001-01-05</date>
|
|
</refsect2info>
|
|
<title>
|
|
Notes
|
|
</title>
|
|
<para>
|
|
Presently, ON SELECT rules must be unconditional INSTEAD rules and must
|
|
have actions that consist of a single SELECT query. Thus, an ON SELECT
|
|
rule effectively turns the object table into a view, whose visible
|
|
contents are the rows returned by the rule's SELECT query rather than
|
|
whatever had been stored in the table (if anything). It is considered
|
|
better style to write a CREATE VIEW command than to create a table and
|
|
define an ON SELECT rule for it.
|
|
</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>
|
|
|
|
<para>
|
|
It is very important to take care to avoid circular rules.
|
|
For example, though each
|
|
of the following two rule definitions are accepted by
|
|
<productname>Postgres</productname>, the
|
|
select command will cause <productname>Postgres</productname> to
|
|
report an error because the query cycled too many times:
|
|
|
|
<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 * FROM toyemp;
|
|
</programlisting>
|
|
|
|
<programlisting>
|
|
CREATE RULE bad_rule_combination_2 AS
|
|
ON SELECT TO toyemp
|
|
DO INSTEAD
|
|
SELECT * FROM emp;
|
|
</programlisting>
|
|
<para>
|
|
This attempt to select from EMP will cause
|
|
<productname>Postgres</productname> to issue an error
|
|
because the queries cycled too many times:
|
|
<programlisting>
|
|
SELECT * FROM emp;
|
|
</programlisting></para>
|
|
</example>
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1 id="R1-SQL-CREATERULE-4">
|
|
<title>
|
|
Compatibility
|
|
</title>
|
|
|
|
<refsect2 id="R2-SQL-CREATERULE-4">
|
|
<refsect2info>
|
|
<date>1998-09-11</date>
|
|
</refsect2info>
|
|
<title>
|
|
SQL92
|
|
</title>
|
|
|
|
<para>
|
|
<command>CREATE RULE</command> statement is a <productname>Postgres</productname>
|
|
language extension.
|
|
There is no <command>CREATE RULE</command> statement in <acronym>SQL92</acronym>.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:nil
|
|
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:
|
|
-->
|