1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2003-11-29 20:52:15 +01:00
|
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.42 2003/11/29 19:51:38 pgsql Exp $
|
2001-12-08 04:24:40 +01:00
|
|
|
PostgreSQL documentation
|
1999-07-22 17:09:15 +02:00
|
|
|
-->
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refentry id="SQL-CREATERULE">
|
|
|
|
<refmeta>
|
2001-05-27 11:59:30 +02:00
|
|
|
<refentrytitle id="sql-createrule-title">CREATE RULE</refentrytitle>
|
1999-07-06 19:16:42 +02:00
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refnamediv>
|
2003-04-22 12:08:08 +02:00
|
|
|
<refname>CREATE RULE</refname>
|
|
|
|
<refpurpose>define a new rewrite rule</refpurpose>
|
1998-12-29 03:24:47 +01:00
|
|
|
</refnamediv>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm zone="sql-createrule">
|
|
|
|
<primary>CREATE RULE</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refsynopsisdiv>
|
2003-04-22 12:08:08 +02:00
|
|
|
<synopsis>
|
2002-09-02 22:04:40 +02:00
|
|
|
CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS ON <replaceable class="parameter">event</replaceable>
|
2002-04-19 18:36:08 +02:00
|
|
|
TO <replaceable class="parameter">table</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
|
2003-04-22 12:08:08 +02:00
|
|
|
DO [ INSTEAD ] { NOTHING | <replaceable class="parameter">command</replaceable> | ( <replaceable class="parameter">command</replaceable> ; <replaceable class="parameter">command</replaceable> ... ) }
|
|
|
|
</synopsis>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refsynopsisdiv>
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
2002-09-02 22:04:40 +02:00
|
|
|
<para>
|
|
|
|
<command>CREATE RULE</command> defines a new rule applying to a specified
|
|
|
|
table or view.
|
|
|
|
<command>CREATE OR REPLACE RULE</command> will either create a
|
|
|
|
new rule, or replace an existing rule of the same name for the same
|
|
|
|
table.
|
|
|
|
</para>
|
|
|
|
|
1999-07-22 17:09:15 +02:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
The <productname>PostgreSQL</productname> rule system allows one to
|
|
|
|
define an alternate action to be performed on insertions, updates,
|
|
|
|
or deletions in database tables. Roughly speaking, a rule causes
|
|
|
|
additional commands to be executed when a given command on a given
|
|
|
|
table is executed. Alternatively, a rule can replace a given
|
|
|
|
command by another, or cause a command not to be executed at all.
|
|
|
|
Rules are used to implement table views as well. It is important
|
|
|
|
to realize that a rule is really a command transformation
|
|
|
|
mechanism, or command macro. The transformation happens before the
|
|
|
|
execution of the commands starts. If you actually want an
|
|
|
|
operation that fires independently for each physical row, you
|
|
|
|
probably want to use a trigger, not a rule. More information about
|
|
|
|
the rules system is in <xref linkend="rules">.
|
1999-07-22 17:09:15 +02:00
|
|
|
</para>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
Presently, <literal>ON SELECT</literal> rules must be unconditional
|
|
|
|
<literal>INSTEAD</literal> rules and must have actions that consist
|
|
|
|
of a single <command>SELECT</command> command. Thus, an
|
|
|
|
<literal>ON SELECT</literal> rule effectively turns the table into
|
|
|
|
a view, whose visible contents are the rows returned by the rule's
|
|
|
|
<command>SELECT</command> command rather than whatever had been
|
|
|
|
stored in the table (if anything). It is considered better style
|
|
|
|
to write a <command>CREATE VIEW</command> command than to create a
|
|
|
|
real table and define an <literal>ON SELECT</literal> rule for it.
|
1998-07-14 05:47:34 +02:00
|
|
|
</para>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
2001-01-06 05:14:35 +01:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
You can create the illusion of an updatable view by defining
|
|
|
|
<literal>ON INSERT</literal>, <literal>ON UPDATE</literal>, and
|
|
|
|
<literal>ON DELETE</literal> rules (or any subset of those that's
|
|
|
|
sufficient for your purposes) to replace update actions on the view
|
|
|
|
with appropriate updates on other tables.
|
2001-01-06 05:14:35 +01:00
|
|
|
</para>
|
|
|
|
|
1998-07-14 05:47:34 +02:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
There is a catch if you try to use conditional rules for view
|
|
|
|
updates: there <emphasis>must</> be an unconditional
|
|
|
|
<literal>INSTEAD</literal> rule for each action you wish to allow
|
|
|
|
on the view. If the rule is conditional, or is not
|
|
|
|
<literal>INSTEAD</literal>, then the system will still reject
|
|
|
|
attempts to perform the update action, because it thinks it might
|
|
|
|
end up trying to perform the action on the dummy table of the view
|
|
|
|
in some cases. If you want to handle all the useful cases in
|
|
|
|
conditional rules, you can; just add an unconditional <literal>DO
|
|
|
|
INSTEAD NOTHING</literal> rule to ensure that the system
|
|
|
|
understands it will never be called on to update the dummy table.
|
|
|
|
Then make the conditional rules not <literal>INSTEAD</literal>; in
|
|
|
|
the cases where they are applied, they add to the default
|
|
|
|
<literal>INSTEAD NOTHING</literal> action.
|
1998-07-14 05:47:34 +02:00
|
|
|
</para>
|
2003-04-22 12:08:08 +02:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">name</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of a rule to create. This must be distinct from the
|
|
|
|
name of any other rule for the same table. Multiple rules on
|
|
|
|
the same table and same event type are applied in alphabetical
|
|
|
|
name order.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">event</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The even is one of <literal>SELECT</literal>,
|
|
|
|
<literal>INSERT</literal>, <literal>UPDATE</literal>, or
|
|
|
|
<literal>DELETE</literal>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">table</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name (optionally schema-qualified) of the table or view the
|
|
|
|
rule applies to.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">condition</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Any SQL conditional expression (returning <type>boolean</type>).
|
|
|
|
The condition expression may not refer to any tables except
|
|
|
|
<literal>NEW</literal> and <literal>OLD</literal>, and may not
|
|
|
|
contain aggregate functions.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">command</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The command or commands that make up the rule action. Valid
|
|
|
|
commands are <literal>SELECT</literal>,
|
|
|
|
<literal>INSERT</literal>, <literal>UPDATE</literal>,
|
|
|
|
<literal>DELETE</literal>, or <literal>NOTIFY</literal>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
2002-04-19 18:36:08 +02:00
|
|
|
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
Within <replaceable class="parameter">condition</replaceable> and
|
|
|
|
<replaceable class="parameter">command</replaceable>, the special
|
|
|
|
table names <literal>NEW</literal> and <literal>OLD</literal> may
|
|
|
|
be used to refer to values in the referenced table.
|
|
|
|
<literal>NEW</literal> is valid in <literal>ON INSERT</literal> and
|
|
|
|
<literal>ON UPDATE</literal> rules to refer to the new row being
|
|
|
|
inserted or updated. <literal>OLD</literal> is valid in
|
|
|
|
<literal>ON UPDATE</literal> and <literal>ON DELETE</literal> rules
|
|
|
|
to refer to the existing row being updated or deleted.
|
2002-04-19 18:36:08 +02:00
|
|
|
</para>
|
2003-04-22 12:08:08 +02:00
|
|
|
</refsect1>
|
2001-11-07 00:54:32 +01:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
2001-11-07 00:54:32 +01:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<para>
|
|
|
|
You must have the privilege <literal>RULE</literal> on a table to
|
|
|
|
be allowed to define a rule on it.
|
|
|
|
</para>
|
2001-01-06 05:14:35 +01:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<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>PostgreSQL</productname>, the
|
|
|
|
<command>SELECT</command> command would cause
|
|
|
|
<productname>PostgreSQL</productname> to report an error because
|
|
|
|
the query cycled too many times:
|
1998-10-30 20:34:40 +01:00
|
|
|
|
2001-10-09 20:46:00 +02:00
|
|
|
<programlisting>
|
2002-04-20 01:13:54 +02:00
|
|
|
CREATE RULE "_RETURN" AS
|
2003-04-22 12:08:08 +02:00
|
|
|
ON SELECT TO t1
|
2000-04-07 19:35:08 +02:00
|
|
|
DO INSTEAD
|
2003-04-22 12:08:08 +02:00
|
|
|
SELECT * FROM t2;
|
1998-07-14 05:47:34 +02:00
|
|
|
|
2002-04-20 01:13:54 +02:00
|
|
|
CREATE RULE "_RETURN" AS
|
2003-04-22 12:08:08 +02:00
|
|
|
ON SELECT TO t2
|
2000-04-07 19:35:08 +02:00
|
|
|
DO INSTEAD
|
2003-04-22 12:08:08 +02:00
|
|
|
SELECT * FROM t1;
|
2001-10-09 20:46:00 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
SELECT * FROM t1;
|
2001-10-09 20:46:00 +02:00
|
|
|
</programlisting>
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
2001-09-07 22:52:31 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<para>
|
|
|
|
Presently, if a rule action contains a <command>NOTIFY</command>
|
|
|
|
command, the <command>NOTIFY</command> command will be executed
|
|
|
|
unconditionally, that is, the <command>NOTIFY</command> will be
|
|
|
|
issued even if there are not any rows that the rule should apply
|
|
|
|
to. For example, in
|
|
|
|
<programlisting>
|
2001-09-07 22:52:31 +02:00
|
|
|
CREATE RULE notify_me AS ON UPDATE TO mytable DO NOTIFY mytable;
|
|
|
|
|
|
|
|
UPDATE mytable SET name = 'foo' WHERE id = 42;
|
2003-04-22 12:08:08 +02:00
|
|
|
</programlisting>
|
|
|
|
one <command>NOTIFY</command> event will be sent during the
|
|
|
|
<command>UPDATE</command>, whether or not there are any rows with
|
|
|
|
<literal>id = 42</literal>. This is an implementation restriction
|
|
|
|
that may be fixed in future releases.
|
|
|
|
</para>
|
1998-07-14 05:47:34 +02:00
|
|
|
</refsect1>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Compatibility</title>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<para>
|
|
|
|
<command>CREATE RULE</command> is a
|
|
|
|
<productname>PostgreSQL</productname> language extension, as is the
|
|
|
|
entire rules system.
|
|
|
|
</para>
|
1998-07-14 05:47:34 +02:00
|
|
|
</refsect1>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refentry>
|
1998-07-14 05:47:34 +02:00
|
|
|
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
|
|
Local variables:
|
|
|
|
mode: sgml
|
1999-07-06 19:16:42 +02:00
|
|
|
sgml-omittag:nil
|
1998-07-14 05:47:34 +02:00
|
|
|
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:
|
1998-08-15 09:00:37 +02:00
|
|
|
-->
|