1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2010-09-20 22:08:53 +02:00
|
|
|
doc/src/sgml/ref/create_rule.sgml
|
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">
|
2014-02-24 03:25:35 +01:00
|
|
|
<indexterm zone="sql-createrule">
|
|
|
|
<primary>CREATE RULE</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refmeta>
|
2010-04-03 09:23:02 +02:00
|
|
|
<refentrytitle>CREATE RULE</refentrytitle>
|
2008-11-14 11:22:48 +01:00
|
|
|
<manvolnum>7</manvolnum>
|
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
|
|
|
|
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>
|
2012-06-22 00:06:14 +02:00
|
|
|
TO <replaceable class="parameter">table_name</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
|
2004-03-09 20:30:21 +01:00
|
|
|
DO [ ALSO | INSTEAD ] { NOTHING | <replaceable class="parameter">command</replaceable> | ( <replaceable class="parameter">command</replaceable> ; <replaceable class="parameter">command</replaceable> ... ) }
|
2014-04-22 23:54:42 +02:00
|
|
|
|
|
|
|
<phrase>where <replaceable class="parameter">event</replaceable> can be one of:</phrase>
|
|
|
|
|
|
|
|
SELECT | INSERT | UPDATE | DELETE
|
2003-04-22 12:08:08 +02:00
|
|
|
</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
|
2007-11-07 13:24:24 +01:00
|
|
|
define an alternative action to be performed on insertions, updates,
|
2003-04-22 12:08:08 +02:00
|
|
|
or deletions in database tables. Roughly speaking, a rule causes
|
|
|
|
additional commands to be executed when a given command on a given
|
2004-03-04 15:32:12 +01:00
|
|
|
table is executed. Alternatively, an <literal>INSTEAD</literal>
|
2004-03-09 20:30:21 +01:00
|
|
|
rule can replace a given command by another, or cause a command
|
2012-12-09 00:25:48 +01:00
|
|
|
not to be executed at all. Rules are used to implement SQL
|
2004-03-09 20:30:21 +01:00
|
|
|
views as well. It is important to realize that a rule is really
|
|
|
|
a command transformation mechanism, or command macro. The
|
2012-12-09 00:25:48 +01:00
|
|
|
transformation happens before the execution of the command starts.
|
2004-03-09 20:30:21 +01:00
|
|
|
If you actually want an operation that fires independently for each
|
|
|
|
physical row, you probably want to use a trigger, not a rule.
|
2004-03-04 15:32:12 +01:00
|
|
|
More information about the rules system is in <xref linkend="rules">.
|
1999-07-22 17:09:15 +02:00
|
|
|
</para>
|
2010-10-10 19:43:33 +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
|
2006-09-02 19:06:52 +02:00
|
|
|
with appropriate updates on other tables. If you want to support
|
|
|
|
<command>INSERT RETURNING</> and so on, then be sure to put a suitable
|
2012-12-09 00:25:48 +01:00
|
|
|
<literal>RETURNING</> clause into each of these rules.
|
2001-01-06 05:14:35 +01:00
|
|
|
</para>
|
|
|
|
|
1998-07-14 05:47:34 +02:00
|
|
|
<para>
|
2012-12-09 00:25:48 +01:00
|
|
|
There is a catch if you try to use conditional rules for complex view
|
2003-04-22 12:08:08 +02:00
|
|
|
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
|
2005-01-04 01:39:53 +01:00
|
|
|
conditional rules, add an unconditional <literal>DO
|
2003-04-22 12:08:08 +02:00
|
|
|
INSTEAD NOTHING</literal> rule to ensure that the system
|
|
|
|
understands it will never be called on to update the dummy table.
|
2005-01-04 01:39:53 +01:00
|
|
|
Then make the conditional rules non-<literal>INSTEAD</literal>; in
|
2003-04-22 12:08:08 +02:00
|
|
|
the cases where they are applied, they add to the default
|
2006-09-02 19:06:52 +02:00
|
|
|
<literal>INSTEAD NOTHING</literal> action. (This method does not
|
|
|
|
currently work to support <literal>RETURNING</> queries, however.)
|
1998-07-14 05:47:34 +02:00
|
|
|
</para>
|
2012-12-09 00:25:48 +01:00
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>
|
|
|
|
A view that is simple enough to be automatically updatable (see <xref
|
|
|
|
linkend="sql-createview">) does not require a user-created rule in
|
|
|
|
order to be updatable. While you can create an explicit rule anyway,
|
|
|
|
the automatic update transformation will generally outperform an
|
|
|
|
explicit rule.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Another alternative worth considering is to use <literal>INSTEAD OF</>
|
|
|
|
triggers (see <xref linkend="sql-createtrigger">) in place of rules.
|
|
|
|
</para>
|
|
|
|
</note>
|
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>
|
2004-03-09 20:30:21 +01:00
|
|
|
The event is one of <literal>SELECT</literal>,
|
2003-04-22 12:08:08 +02:00
|
|
|
<literal>INSERT</literal>, <literal>UPDATE</literal>, or
|
|
|
|
<literal>DELETE</literal>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2012-06-22 00:06:14 +02:00
|
|
|
<term><replaceable class="parameter">table_name</replaceable></term>
|
2003-04-22 12:08:08 +02:00
|
|
|
<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>
|
2004-03-09 20:30:21 +01:00
|
|
|
Any <acronym>SQL</acronym> conditional expression (returning
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
<type>boolean</type>). The condition expression cannot refer
|
2004-03-09 20:30:21 +01:00
|
|
|
to any tables except <literal>NEW</> and <literal>OLD</>, and
|
Wording cleanup for error messages. Also change can't -> cannot.
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 20:10:30 +01:00
|
|
|
cannot contain aggregate functions.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2004-03-04 15:32:12 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>INSTEAD</option></term>
|
|
|
|
<listitem>
|
2011-08-07 09:49:45 +02:00
|
|
|
<para><literal>INSTEAD</literal> indicates that the commands should be
|
2004-03-09 20:30:21 +01:00
|
|
|
executed <emphasis>instead of</> the original command.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>ALSO</option></term>
|
|
|
|
<listitem>
|
2011-08-07 09:49:45 +02:00
|
|
|
<para><literal>ALSO</literal> indicates that the commands should be
|
2004-03-09 20:30:21 +01:00
|
|
|
executed <emphasis>in addition to</emphasis> the original
|
|
|
|
command.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If neither <literal>ALSO</literal> nor
|
|
|
|
<literal>INSTEAD</literal> is specified, <literal>ALSO</literal>
|
|
|
|
is the default.
|
2004-03-04 15:32:12 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">command</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The command or commands that make up the rule action. Valid
|
2004-03-09 20:30:21 +01:00
|
|
|
commands are <command>SELECT</command>,
|
|
|
|
<command>INSERT</command>, <command>UPDATE</command>,
|
|
|
|
<command>DELETE</command>, or <command>NOTIFY</command>.
|
2003-04-22 12:08:08 +02:00
|
|
|
</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
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
table names <literal>NEW</literal> and <literal>OLD</literal> can
|
2003-04-22 12:08:08 +02:00
|
|
|
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>
|
2006-09-05 23:08:36 +02:00
|
|
|
You must be the owner of a table to create or change rules for it.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
2001-01-06 05:14:35 +01:00
|
|
|
|
2006-09-02 19:06:52 +02:00
|
|
|
<para>
|
|
|
|
In a rule for <literal>INSERT</literal>, <literal>UPDATE</literal>, or
|
|
|
|
<literal>DELETE</literal> on a view, you can add a <literal>RETURNING</>
|
|
|
|
clause that emits the view's columns. This clause will be used to compute
|
|
|
|
the outputs if the rule is triggered by an <command>INSERT RETURNING</>,
|
|
|
|
<command>UPDATE RETURNING</>, or <command>DELETE RETURNING</> command
|
|
|
|
respectively. When the rule is triggered by a command without
|
|
|
|
<literal>RETURNING</>, the rule's <literal>RETURNING</> clause will be
|
|
|
|
ignored. The current implementation allows only unconditional
|
|
|
|
<literal>INSTEAD</> rules to contain <literal>RETURNING</>; furthermore
|
|
|
|
there can be at most one <literal>RETURNING</> clause among all the rules
|
|
|
|
for the same event. (This ensures that there is only one candidate
|
|
|
|
<literal>RETURNING</> clause to be used to compute the results.)
|
|
|
|
<literal>RETURNING</> queries on the view will be rejected if
|
|
|
|
there is no <literal>RETURNING</> clause in any available rule.
|
|
|
|
</para>
|
|
|
|
|
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
|
2006-09-02 19:06:52 +02:00
|
|
|
of recursive expansion of a rule:
|
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
|
2010-10-10 19:43:33 +02:00
|
|
|
DO INSTEAD
|
2005-01-04 01:39:53 +01: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
|
2010-10-10 19:43:33 +02:00
|
|
|
DO INSTEAD
|
2005-01-04 01:39:53 +01: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
|
2007-02-01 01:28:19 +01:00
|
|
|
to. For example, in:
|
2003-04-22 12:08:08 +02:00
|
|
|
<programlisting>
|
2004-03-09 20:30:21 +01:00
|
|
|
CREATE RULE notify_me AS ON UPDATE TO mytable DO ALSO NOTIFY mytable;
|
2001-09-07 22:52:31 +02:00
|
|
|
|
|
|
|
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
|
2004-03-09 20:30:21 +01:00
|
|
|
<command>UPDATE</command>, whether or not there are any rows that
|
|
|
|
match the condition <literal>id = 42</literal>. This is an
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
implementation restriction that might be fixed in future releases.
|
2003-04-22 12:08:08 +02:00
|
|
|
</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
|
2004-03-09 20:30:21 +01:00
|
|
|
entire query rewrite system.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
1998-07-14 05:47:34 +02:00
|
|
|
</refsect1>
|
2013-02-09 05:58:40 +01:00
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
|
|
|
<member><xref linkend="sql-alterrule"></member>
|
|
|
|
<member><xref linkend="sql-droprule"></member>
|
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
</refentry>
|