head	1.54;
access;
symbols
	REL9_0_0:1.54
	REL9_1_ALPHA1:1.54
	REL9_0_RC1:1.54
	REL9_0_BETA4:1.54
	REL9_0_STABLE:1.54.0.2
	REL9_0_BETA3:1.54
	REL9_0_BETA2:1.54
	REL7_4_29:1.41
	REL8_0_25:1.45
	REL8_1_21:1.45
	REL8_2_17:1.48
	REL8_3_11:1.52
	REL8_4_4:1.53
	REL9_0_BETA1:1.54
	REL9_0_ALPHA5_BRANCH:1.53.0.12
	REL9_0_ALPHA5:1.53
	REL7_4_28:1.41
	REL8_0_24:1.45
	REL8_1_20:1.45
	REL8_2_16:1.48
	REL8_3_10:1.52
	REL8_4_3:1.53
	REL9_0_ALPHA4:1.53
	REL9_0_ALPHA4_BRANCH:1.53.0.10
	REL8_5_ALPHA3:1.53
	REL8_5_ALPHA3_BRANCH:1.53.0.8
	REL7_4_27:1.41
	REL8_0_23:1.45
	REL8_1_19:1.45
	REL8_2_15:1.48
	REL8_3_9:1.52
	REL8_4_2:1.53
	REL8_5_ALPHA2:1.53
	REL8_5_ALPHA2_BRANCH:1.53.0.6
	REL7_4_26:1.41
	REL8_0_22:1.45
	REL8_1_18:1.45
	REL8_2_14:1.48
	REL8_3_8:1.52
	REL8_4_1:1.53
	REL8_5_ALPHA1:1.53
	REL8_5_ALPHA1_BRANCH:1.53.0.4
	REL8_4_STABLE:1.53.0.2
	REL8_4_0:1.53
	REL8_4_RC2:1.53
	REL8_4_RC1:1.53
	REL8_4_BETA2:1.53
	REL8_4_BETA1:1.53
	REL7_4_25:1.41
	REL8_0_21:1.45
	REL8_1_17:1.45
	REL8_2_13:1.48
	REL8_3_7:1.52
	REL7_4_24:1.41
	REL8_0_20:1.45
	REL8_1_16:1.45
	REL8_2_12:1.48
	REL8_3_6:1.52
	REL7_4_23:1.41
	REL8_0_19:1.45
	REL8_1_15:1.45
	REL8_2_11:1.48
	REL8_3_5:1.52
	REL7_4_22:1.41
	REL8_0_18:1.45
	REL8_1_14:1.45
	REL8_2_10:1.48
	REL8_3_4:1.52
	REL7_4_21:1.41
	REL8_0_17:1.45
	REL8_1_13:1.45
	REL8_2_9:1.48
	REL8_3_3:1.52
	REL7_4_20:1.41
	REL8_0_16:1.45
	REL8_1_12:1.45
	REL8_2_8:1.48
	REL8_3_2:1.52
	REL8_2_7:1.48
	REL8_3_1:1.52
	REL8_3_STABLE:1.52.0.2
	REL8_3_0:1.52
	REL8_3_RC2:1.52
	REL7_3_21:1.37.2.1
	REL7_4_19:1.41
	REL8_0_15:1.45
	REL8_1_11:1.45
	REL8_2_6:1.48
	REL8_3_RC1:1.52
	REL8_3_BETA4:1.52
	REL8_3_BETA3:1.52
	REL8_3_BETA2:1.51
	REL8_3_BETA1:1.51
	REL7_3_20:1.37.2.1
	REL7_4_18:1.41
	REL8_0_14:1.45
	REL8_1_10:1.45
	REL8_2_5:1.48
	REL7_3_19:1.37.2.1
	REL7_4_17:1.41
	REL8_0_13:1.45
	REL8_1_9:1.45
	REL8_2_4:1.48
	REL8_0_12:1.45
	REL8_1_8:1.45
	REL8_2_3:1.48
	REL7_3_18:1.37.2.1
	REL7_4_16:1.41
	REL8_0_11:1.45
	REL8_1_7:1.45
	REL8_2_2:1.48
	REL8_0_10:1.45
	REL8_1_6:1.45
	REL8_2_1:1.48
	REL7_4_15:1.41
	REL7_3_17:1.37.2.1
	REL8_2_STABLE:1.48.0.2
	REL8_2_0:1.48
	REL8_2_RC1:1.48
	REL8_2_BETA3:1.48
	REL8_2_BETA2:1.48
	REL8_1_5:1.45
	REL8_0_9:1.45
	REL7_4_14:1.41
	REL7_3_16:1.37.2.1
	REL8_2_BETA1:1.48
	REL7_3_15:1.37.2.1
	REL7_4_13:1.41
	REL8_0_8:1.45
	REL8_1_4:1.45
	REL7_3_14:1.37.2.1
	REL7_4_12:1.41
	REL8_0_7:1.45
	REL8_1_3:1.45
	REL7_3_13:1.37.2.1
	REL7_4_11:1.41
	REL8_0_6:1.45
	REL8_1_2:1.45
	REL7_3_12:1.37.2.1
	REL7_4_10:1.41
	REL8_0_5:1.45
	REL8_1_1:1.45
	REL8_1_STABLE:1.45.0.6
	REL8_1_0:1.45
	REL8_1_0RC1:1.45
	REL8_1_0BETA4:1.45
	REL8_1_0BETA3:1.45
	REL7_3_11:1.37.2.1
	REL7_4_9:1.41
	REL8_0_4:1.45
	REL8_1_0BETA2:1.45
	REL8_1_0BETA1:1.45
	REL7_2_8:1.31
	REL7_3_10:1.37.2.1
	REL7_4_8:1.41
	REL8_0_3:1.45
	REL8_0_2:1.45
	REL7_2_7:1.31
	REL7_3_9:1.37.2.1
	REL7_4_7:1.41
	REL8_0_1:1.45
	REL8_0_STABLE:1.45.0.4
	REL8_0_0:1.45.0.2
	REL8_0_0RC5:1.45
	REL8_0_0RC4:1.45
	REL8_0_0RC3:1.44
	REL8_0_0RC2:1.44
	REL8_0_0RC1:1.44
	REL8_0_0BETA5:1.44
	REL8_0_0BETA4:1.44
	REL7_4_6:1.41
	REL7_3_8:1.37.2.1
	REL7_2_6:1.31
	REL8_0_0BETA3:1.44
	REL8_0_0BETA2:1.44
	REL7_2_5:1.31
	REL7_4_5:1.41
	REL7_3_7:1.37.2.1
	REL7_4_4:1.41
	REL8_0_0BETA1:1.44
	REL7_4_3:1.41
	REL7_4_2:1.41
	REL7_3_6:1.37.2.1
	REL7_4_1:1.41
	REL7_3_5:1.37.2.1
	REL7_4:1.41
	REL7_4_RC2:1.41
	REL7_4_STABLE:1.41.0.2
	REL7_4_RC1:1.41
	REL7_4_BETA5:1.41
	REL7_4_BETA4:1.41
	REL7_4_BETA3:1.41
	REL7_4_BETA2:1.39
	WIN32_DEV:1.39.0.2
	REL7_4_BETA1:1.39
	REL7_3_4:1.37.2.1
	REL7_3_2:1.37.2.1
	REL7_2_4:1.31
	REL7_3_STABLE:1.37.0.2
	REL7_2_3:1.31
	REL7_2_STABLE:1.31.0.2
	REL7_2:1.31
	REL7_2_RC2:1.31
	REL7_2_RC1:1.30
	REL7_2_BETA5:1.30
	REL7_2_BETA4:1.30
	REL7_2_BETA3:1.29
	REL7_2_BETA2:1.28
	REL7_2_BETA1:1.28
	REL7_1_2:1.22
	REL7_1_STABLE:1.22.0.2
	REL7_1_BETA:1.19
	REL7_1_BETA3:1.21
	REL7_1_BETA2:1.21
	REL7_1:1.22
	REL7_0_PATCHES:1.16.0.2
	REL7_0:1.15
	REL6_5_PATCHES:1.9.0.2
	REL6_5:1.9
	REL6_4:1.6.0.2;
locks; strict;
comment	@# @;


1.54
date	2010.04.03.07.22.59;	author petere;	state Exp;
branches;
next	1.53;

1.53
date	2008.11.14.10.22.46;	author petere;	state Exp;
branches;
next	1.52;

1.52
date	2007.11.07.12.24.23;	author petere;	state Exp;
branches;
next	1.51;

1.51
date	2007.02.01.19.10.24;	author momjian;	state Exp;
branches;
next	1.50;

1.50
date	2007.02.01.00.28.18;	author momjian;	state Exp;
branches;
next	1.49;

1.49
date	2007.01.31.23.26.03;	author momjian;	state Exp;
branches;
next	1.48;

1.48
date	2006.09.16.00.30.17;	author momjian;	state Exp;
branches;
next	1.47;

1.47
date	2006.09.05.21.08.35;	author tgl;	state Exp;
branches;
next	1.46;

1.46
date	2006.09.02.17.06.52;	author tgl;	state Exp;
branches;
next	1.45;

1.45
date	2005.01.04.00.39.53;	author tgl;	state Exp;
branches;
next	1.44;

1.44
date	2004.03.09.19.30.21;	author neilc;	state Exp;
branches;
next	1.43;

1.43
date	2004.03.04.14.32.12;	author momjian;	state Exp;
branches;
next	1.42;

1.42
date	2003.11.29.19.51.38;	author pgsql;	state Exp;
branches;
next	1.41;

1.41
date	2003.09.09.18.28.52;	author tgl;	state Exp;
branches;
next	1.40;

1.40
date	2003.08.31.17.32.22;	author petere;	state Exp;
branches;
next	1.39;

1.39
date	2003.04.22.10.08.08;	author petere;	state Exp;
branches
	1.39.2.1;
next	1.38;

1.38
date	2002.11.21.23.34.43;	author petere;	state Exp;
branches;
next	1.37;

1.37
date	2002.09.02.20.04.39;	author tgl;	state Exp;
branches
	1.37.2.1;
next	1.36;

1.36
date	2002.05.18.15.44.47;	author petere;	state Exp;
branches;
next	1.35;

1.35
date	2002.04.19.23.13.53;	author tgl;	state Exp;
branches;
next	1.34;

1.34
date	2002.04.19.16.36.08;	author tgl;	state Exp;
branches;
next	1.33;

1.33
date	2002.03.22.19.20.39;	author petere;	state Exp;
branches;
next	1.32;

1.32
date	2002.03.10.06.00.13;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2002.01.24.18.28.15;	author tgl;	state Exp;
branches;
next	1.30;

1.30
date	2001.12.08.03.24.35;	author thomas;	state Exp;
branches;
next	1.29;

1.29
date	2001.11.06.23.54.32;	author tgl;	state Exp;
branches;
next	1.28;

1.28
date	2001.10.09.18.46.00;	author petere;	state Exp;
branches;
next	1.27;

1.27
date	2001.09.14.08.19.55;	author ishii;	state Exp;
branches;
next	1.26;

1.26
date	2001.09.07.20.52.30;	author tgl;	state Exp;
branches;
next	1.25;

1.25
date	2001.09.03.12.57.49;	author petere;	state Exp;
branches;
next	1.24;

1.24
date	2001.07.09.23.50.31;	author tgl;	state Exp;
branches;
next	1.23;

1.23
date	2001.05.27.09.59.27;	author petere;	state Exp;
branches;
next	1.22;

1.22
date	2001.01.13.23.58.55;	author petere;	state Exp;
branches;
next	1.21;

1.21
date	2001.01.06.04.14.35;	author tgl;	state Exp;
branches;
next	1.20;

1.20
date	2000.12.12.16.47.52;	author momjian;	state Exp;
branches;
next	1.19;

1.19
date	2000.10.05.19.48.17;	author momjian;	state Exp;
branches;
next	1.18;

1.18
date	2000.07.22.02.39.10;	author momjian;	state Exp;
branches;
next	1.17;

1.17
date	2000.07.21.04.22.54;	author momjian;	state Exp;
branches;
next	1.16;

1.16
date	2000.05.20.11.38.25;	author momjian;	state Exp;
branches;
next	1.15;

1.15
date	2000.04.12.20.07.13;	author momjian;	state Exp;
branches;
next	1.14;

1.14
date	2000.04.07.19.17.30;	author momjian;	state Exp;
branches;
next	1.13;

1.13
date	2000.04.07.17.37.24;	author momjian;	state Exp;
branches;
next	1.12;

1.12
date	2000.04.07.17.35.08;	author momjian;	state Exp;
branches;
next	1.11;

1.11
date	2000.04.07.17.23.11;	author momjian;	state Exp;
branches;
next	1.10;

1.10
date	99.07.22.15.09.08;	author thomas;	state Exp;
branches;
next	1.9;

1.9
date	99.07.06.17.16.35;	author thomas;	state Exp;
branches;
next	1.8;

1.8
date	99.02.02.17.46.13;	author momjian;	state Exp;
branches;
next	1.7;

1.7
date	98.12.29.02.24.35;	author thomas;	state Exp;
branches;
next	1.6;

1.6
date	98.10.30.19.33.48;	author thomas;	state Exp;
branches;
next	1.5;

1.5
date	98.09.16.14.43.07;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	98.09.07.15.58.15;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	98.08.15.07.00.32;	author thomas;	state Exp;
branches;
next	1.2;

1.2
date	98.07.29.06.21.57;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	98.07.14.03.47.34;	author thomas;	state Exp;
branches;
next	;

1.37.2.1
date	2002.11.21.23.31.57;	author petere;	state Exp;
branches;
next	;

1.39.2.1
date	2003.09.07.04.36.45;	author momjian;	state Exp;
branches;
next	;


desc
@@


1.54
log
@Remove unnecessary xref endterm attributes and title ids

The endterm attribute is mainly useful when the toolchain does not support
automatic link target text generation for a particular situation.  In  the
past, this was required by the man page tools for all reference page links,
but that is no longer the case, and it now actually gets in the way of
proper automatic link text generation.  The only remaining use cases are
currently xrefs to refsects.
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.53 2008/11/14 10:22:46 petere Exp $
PostgreSQL documentation
-->

<refentry id="SQL-CREATERULE">
 <refmeta>
  <refentrytitle>CREATE RULE</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE RULE</refname>
  <refpurpose>define a new rewrite rule</refpurpose>
 </refnamediv>

 <indexterm zone="sql-createrule">
  <primary>CREATE RULE</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS ON <replaceable class="parameter">event</replaceable>
    TO <replaceable class="parameter">table</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
    DO [ ALSO | INSTEAD ] { NOTHING | <replaceable class="parameter">command</replaceable> | ( <replaceable class="parameter">command</replaceable> ; <replaceable class="parameter">command</replaceable> ... ) }
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <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>

  <para>
   The <productname>PostgreSQL</productname> rule system allows one to
   define an alternative 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, an <literal>INSTEAD</literal>
   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">.
  </para>
  
  <para>
   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.
  </para>

  <para>
   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.  If you want to support
   <command>INSERT RETURNING</> and so on, then be sure to put a suitable
   <literal>RETURNING</> clause into each of these rules.
  </para>

  <para>
   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, 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 non-<literal>INSTEAD</literal>; in
   the cases where they are applied, they add to the default
   <literal>INSTEAD NOTHING</literal> action.  (This method does not
   currently work to support <literal>RETURNING</> queries, however.)
  </para>
 </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 event 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 <acronym>SQL</acronym> conditional expression (returning
      <type>boolean</type>).  The condition expression cannot refer
      to any tables except <literal>NEW</> and <literal>OLD</>, and
      cannot contain aggregate functions.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>INSTEAD</option></term>
    <listitem>
     <para>
      <literal>INSTEAD</literal> indicates that the commands should be
      executed <emphasis>instead of</> the original command.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>ALSO</option></term>
    <listitem>
     <para>
      <literal>ALSO</literal> indicates that the commands should be
      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.
     </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 <command>SELECT</command>,
      <command>INSERT</command>, <command>UPDATE</command>,
      <command>DELETE</command>, or <command>NOTIFY</command>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   Within <replaceable class="parameter">condition</replaceable> and
   <replaceable class="parameter">command</replaceable>, the special
   table names <literal>NEW</literal> and <literal>OLD</literal> can
   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.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   You must be the owner of a table to create or change rules for it.
  </para>

  <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>

  <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
   of recursive expansion of a rule:

<programlisting>
CREATE RULE "_RETURN" AS
    ON SELECT TO t1
    DO INSTEAD 
        SELECT * FROM t2;

CREATE RULE "_RETURN" AS
    ON SELECT TO t2
    DO INSTEAD 
        SELECT * FROM t1;

SELECT * FROM t1;
</programlisting>
  </para>

  <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>
CREATE RULE notify_me AS ON UPDATE TO mytable DO ALSO NOTIFY mytable;

UPDATE mytable SET name = 'foo' WHERE id = 42;
</programlisting>
   one <command>NOTIFY</command> event will be sent during the
   <command>UPDATE</command>, whether or not there are any rows that
   match the condition <literal>id = 42</literal>.  This is an
   implementation restriction that might be fixed in future releases.
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   <command>CREATE RULE</command> is a
   <productname>PostgreSQL</productname> language extension, as is the
   entire query rewrite system.
  </para>
 </refsect1>
</refentry>
@


1.53
log
@Set SQL man pages to be section 7 by default, and only transform them to
another section if required by the platform (instead of the old way of
building them in section "l" and always transforming them to the
platform-specific section).

This speeds up the installation on common platforms, and it avoids some
funny business with the man page tools and build process.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.52 2007/11/07 12:24:23 petere Exp $
d8 1
a8 1
  <refentrytitle id="sql-createrule-title">CREATE RULE</refentrytitle>
@


1.52
log
@Use "alternative" instead of "alternate" where it is clearer.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.51 2007/02/01 19:10:24 momjian Exp $
d9 1
@


1.51
log
@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".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.50 2007/02/01 00:28:18 momjian Exp $
d42 1
a42 1
   define an alternate action to be performed on insertions, updates,
@


1.50
log
@Consistenly use colons before '<programlisting>' blocks, where
appropriate.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.49 2007/01/31 23:26:03 momjian Exp $
d141 1
a141 1
      can not contain aggregate functions.
@


1.49
log
@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".
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.48 2006/09/16 00:30:17 momjian Exp $
d251 1
a251 1
   to.  For example, in
@


1.48
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.47 2006/09/05 21:08:35 tgl Exp $
d139 1
a139 1
      <type>boolean</type>).  The condition expression may not refer
d141 1
a141 1
      may not contain aggregate functions.
d189 1
a189 1
   table names <literal>NEW</literal> and <literal>OLD</literal> may
d260 1
a260 1
   implementation restriction that may be fixed in future releases.
@


1.47
log
@Get rid of the separate RULE privilege for tables: now only a table's owner
can create or modify rules for the table.  Do setRuleCheckAsUser() while
loading rules into the relcache, rather than when defining a rule.  This
ensures that permission checks for tables referenced in a rule are done with
respect to the current owner of the rule's table, whereas formerly ALTER TABLE
OWNER would fail to update the permission checking for associated rules.
Removal of separate RULE privilege is needed to prevent various scenarios
in which a grantee of RULE privilege could effectively have any privilege
of the table owner.  For backwards compatibility, GRANT/REVOKE RULE is still
accepted, but it doesn't do anything.  Per discussion here:
http://archives.postgresql.org/pgsql-hackers/2006-04/msg01138.php
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.46 2006/09/02 17:06:52 tgl Exp $
a273 17

<!-- 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:
-->
@


1.46
log
@Apply a simple solution to the problem of making INSERT/UPDATE/DELETE
RETURNING play nice with views/rules.  To wit, have the rule rewriter
rewrite any RETURNING clause found in a rule to produce what the rule's
triggering query asked for in its RETURNING clause, in particular drop
the RETURNING clause if no RETURNING in the triggering query.  This
leaves the responsibility for knowing how to produce the view's output
columns on the rule author, without requiring any fundamental changes
in rule semantics such as adding new rule event types would do.  The
initial implementation constrains things to ensure that there is
exactly one, unconditionally invoked RETURNING clause among the rules
for an event --- later we might be able to relax that, but for a post
feature freeze fix it seems better to minimize how much invention we do.
Per gripe from Jaime Casanova.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.45 2005/01/04 00:39:53 tgl Exp $
d203 1
a203 2
   You must have the privilege <literal>RULE</literal> on a table to
   be allowed to define a rule on it.
@


1.45
log
@More minor updates and copy-editing.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.44 2004/03/09 19:30:21 neilc Exp $
d73 3
a75 1
   with appropriate updates on other tables.
d92 2
a93 1
   <literal>INSTEAD NOTHING</literal> action.
d208 17
d230 1
a230 1
   the query cycled too many times:
@


1.44
log
@Add documentation for the recent 'ALSO' patch for CREATE RULE. Along
the way, fix a typo and make a few SGML cleanups.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_rule.sgml,v 1.43 2004/03/04 14:32:12 momjian Exp $
d85 1
a85 1
   conditional rules, you can; just add an unconditional <literal>DO
d88 1
a88 1
   Then make the conditional rules not <literal>INSTEAD</literal>; in
d216 1
a216 1
	SELECT * FROM t2;
d221 1
a221 1
	SELECT * FROM t1;
@


1.43
log
@Better document INSTEAD behavior for rules.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/ref/create_rule.sgml,v 1.42 2003/11/29 19:51:38 pgsql Exp $
d25 1
a25 1
    DO [ INSTEAD ] { NOTHING | <replaceable class="parameter">command</replaceable> | ( <replaceable class="parameter">command</replaceable> ; <replaceable class="parameter">command</replaceable> ... ) }
d46 7
a52 7
   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.  
d114 1
a114 1
      The even is one of <literal>SELECT</literal>,
d135 4
a138 4
      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.
d148 18
a165 2
      executed <emphasis>instead</> of the original command, not in
      addition to the original command.
d175 3
a177 3
      commands are <literal>SELECT</literal>,
      <literal>INSERT</literal>, <literal>UPDATE</literal>,
      <literal>DELETE</literal>, or <literal>NOTIFY</literal>.
d234 1
a234 1
CREATE RULE notify_me AS ON UPDATE TO mytable DO NOTIFY mytable;
d239 3
a241 3
   <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.
d251 1
a251 1
   entire rules system.
@


1.42
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/ref/create_rule.sgml,v 1.41 2003/09/09 18:28:52 tgl Exp $
d45 9
a53 9
   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">.
d139 11
@


1.41
log
@Remove a bunch of content-free Diagnostics sections, as per previous
discussion.  (Still have some work to do editing the remainder.)
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_rule.sgml,v 1.40 2003/08/31 17:32:22 petere Exp $
@


1.40
log
@Add/edit index entries.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_rule.sgml,v 1.39 2003/04/22 10:08:08 petere Exp $
a166 15
 </refsect1>

 <refsect1>
  <title>Diagnostics</title>

  <variablelist>
   <varlistentry>
    <term><computeroutput>CREATE RULE</computeroutput></term>
    <listitem>
     <para>
      Message returned if the rule was successfully created.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
@


1.39
log
@More editing of reference pages.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_rule.sgml,v 1.38 2002/11/21 23:34:43 petere Exp $
d16 4
@


1.39.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_rule.sgml,v 1.40 2003/08/31 17:32:22 petere Exp $
a15 4

 <indexterm zone="sql-createrule">
  <primary>CREATE RULE</primary>
 </indexterm>
@


1.38
log
@Fixups for man pages
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_rule.sgml,v 1.37 2002/09/02 20:04:39 tgl Exp $
d11 1
d13 2
a14 6
  <refname>
   CREATE RULE
  </refname>
  <refpurpose>
   define a new rewrite rule
  </refpurpose>
d16 1
d18 1
a18 4
  <refsynopsisdivinfo>
   <date>2001-01-05</date>
  </refsynopsisdivinfo>
  <synopsis>
d21 2
a22 108
    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> ... )
  </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.  This must be distinct from the name
	of any other rule for the same table.
       </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">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">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.
    <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 UPDATE and ON DELETE
    rules to refer to the existing row being 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 RULE
       </computeroutput></term>
      <listitem>
       <para>
	Message returned if the rule is successfully created.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
d25 2
a26 7
 <refsect1 id="R1-SQL-CREATERULE-1">
  <refsect1info>
   <date>1998-09-11</date>
  </refsect1info>
  <title>
   Description
  </title>
d37 25
a61 5
   The <productname>PostgreSQL</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.
d65 5
a69 18
   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
   table are examined successively (in order by name).  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 after the original query in the case of ON INSERT, or before
   the original query in the case of ON UPDATE or ON DELETE.
   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>.
d73 14
a86 8
   The <replaceable class="parameter">action</replaceable> part of the
   rule can consist of one or more queries. To write multiple queries,
   surround them with parentheses. Such queries will be performed in the
   specified order. 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.
d88 94
d184 2
a185 3
   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.
d189 6
a194 77
   It is important to realize that a rule is really a query transformation
   mechanism, or query macro.  The entire query is processed to convert it
   into a series of queries that include the rule actions.  This occurs
   before evaluation of the query starts.  So, conditional rules are
   handled by adding the rule condition to the WHERE clause of the action(s)
   derived from the rule.  The above description of a rule as an operation
   that executes for each row is thus somewhat misleading.  If you actually
   want an operation that fires independently for each physical row, you
   probably want to use a trigger not a rule.  Rules are most useful for
   situations that call for transforming entire queries independently of
   the specific data being handled.
  </para>
  
  <refsect2 id="R2-SQL-CREATERULE-3">
   <refsect2info>
    <date>2001-11-06</date>
   </refsect2info>
   <title>
    Rules and Views
   </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 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 real table
    and define an ON SELECT rule for it.
   </para>

   <para>
    <xref linkend="sql-createview" endterm="sql-createview-title"> creates a dummy table (with no underlying
    storage) and associates an ON SELECT rule with it.  The system will not
    allow updates to the view, since it knows there is no real table there.
    You can create the
    illusion of an updatable view by defining ON INSERT, ON UPDATE, and
    ON DELETE 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.
   </para>

   <para>
    There is a catch if you try to use conditional
    rules for view updates: there <emphasis>must</> be an unconditional
    INSTEAD rule for each action you wish to allow on the view.  If the
    rule is conditional, or is not INSTEAD, 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 in some cases.
    If you want to
    handle all the useful cases in conditional rules, you can; just add an
    unconditional DO INSTEAD NOTHING rule to ensure that the system
    understands it will never be called on to update the dummy table.  Then
    make the conditional rules non-INSTEAD; in the cases where they fire,
    they add to the default INSTEAD NOTHING action.
   </para>
  </refsect2>

  <refsect2 id="R2-SQL-CREATERULE-4">
   <refsect2info>
    <date>2001-01-05</date>
   </refsect2info>
   <title>
    Notes
   </title>
   <para>
    You must have rule definition access to a table 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>PostgreSQL</productname>, the
    select command will cause <productname>PostgreSQL</productname> to 
    report an error because the query cycled too many times:
d198 1
a198 1
    ON SELECT TO emp
d200 1
a200 1
	SELECT * FROM toyemp;
d203 1
a203 1
    ON SELECT TO toyemp
d205 1
a205 6
	SELECT * FROM emp;
</programlisting>

      This attempt to select from <literal>EMP</literal> will cause
      <productname>PostgreSQL</productname> to issue an error
      because the queries cycled too many times:
d207 1
a207 2
 <programlisting>
SELECT * FROM emp;
d209 1
a209 1
   </para>
d211 7
a217 5
   <para>
    Presently, if a rule contains a NOTIFY query, the NOTIFY will be executed
    unconditionally --- that is, the NOTIFY will be issued even if there are
    not any rows that the rule should apply to.  For example, in
      <programlisting>
d221 6
a226 6
      </programlisting>
    one NOTIFY event will be sent during the UPDATE, whether or not there
    are any rows with id = 42.  This is an implementation restriction that
    may be fixed in future releases.
   </para>
  </refsect2>
d229 8
a236 19
 <refsect1 id="R1-SQL-CREATERULE-4">
  <title>
   Compatibility
  </title>

  <refsect2 id="R2-SQL-CREATERULE-5">
   <refsect2info>
    <date>1998-09-11</date>
   </refsect2info>
   <title>
    SQL92
   </title>

   <para>
    <command>CREATE RULE</command> is a <productname>PostgreSQL</productname>
    language extension.
    There is no <command>CREATE RULE</command> statement in <acronym>SQL92</acronym>.
   </para>
  </refsect2>
@


1.37
log
@Department of second thoughts: make checks for replacing a view slightly
more flexible, and improve the error reporting.  Also, add documentation
for REPLACE RULE/VIEW.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_rule.sgml,v 1.36 2002/05/18 15:44:47 petere Exp $
d230 1
a230 1
    <xref linkend="sql-createview"> creates a dummy table (with no underlying
@


1.37.2.1
log
@Fixups for man pages
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/ref/create_rule.sgml,v 1.37 2002/09/02 20:04:39 tgl Exp $
d230 1
a230 1
    <xref linkend="sql-createview" endterm="sql-createview-title"> creates a dummy table (with no underlying
@


1.36
log
@Revise command completion tags as per hackers message on 20 March.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.35 2002/04/19 23:13:53 tgl Exp $
d24 1
a24 1
CREATE RULE <replaceable class="parameter">name</replaceable> AS ON <replaceable class="parameter">event</replaceable>
d31 2
a32 4
|
<replaceable class="parameter">query</replaceable>
|
( <replaceable class="parameter">query</replaceable> ; <replaceable class="parameter">query</replaceable> ... )
d77 2
a78 1
	Any SQL conditional expression (returning <type>boolean</type>).  The condition expression may not
d80 1
a80 1
	<literal>old</literal>.
d145 8
d328 1
a328 1
    <command>CREATE RULE</command> statement is a <productname>PostgreSQL</productname>
@


1.35
log
@Change naming rule for ON SELECT rules of views: they're all just
_RETURN now, since there's no need to keep 'em unique anymore.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.34 2002/04/19 16:36:08 tgl Exp $
d124 1
a124 1
CREATE
@


1.34
log
@pg_trigger's index on tgrelid is replaced by a unique index on
(tgrelid, tgname).  This provides an additional check on trigger name
uniqueness per-table (which was already enforced by the code anyway).
With this change, RelationBuildTriggers will read the triggers in
order by tgname, since it's scanning using this index.  Since a
predictable trigger ordering has been requested for some time, document
this behavior as a feature.  Also document that rules fire in name
order, since yesterday's changes to pg_rewrite indexing cause that too.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.33 2002/03/22 19:20:39 petere Exp $
d271 1
a271 1
CREATE RULE "_RETemp" AS
d276 1
a276 1
CREATE RULE "_RETtoyemp" AS
@


1.33
log
@Spell checking and markup additions
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.32 2002/03/10 06:00:13 momjian Exp $
d25 1
a25 1
    TO <replaceable class="parameter">object</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
d51 2
a52 1
	The name of a rule to create.
d67 1
a67 1
      <term><replaceable class="parameter">object</replaceable></term>
d70 2
a71 5
	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.)
d104 1
a104 2
    used to refer to values in the referenced table (the
    <replaceable class="parameter">object</replaceable>).
d159 1
a159 1
   object (table) are examined, in an unspecified order.  If the
d178 1
a178 2
   specified order (whereas there are no guarantees about the execution
   order of multiple rules for an object). The <replaceable
d190 14
d215 1
a215 1
    rule effectively turns the object table into a view, whose visible
@


1.32
log
@Disable brackets in multi-statement rules, as discussed.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.31 2002/01/24 18:28:15 tgl Exp $
d81 1
a81 1
	Any SQL boolean-condition expression.  The condition expression may not
d272 1
a272 1
      This attempt to select from EMP will cause
@


1.31
log
@Fix documentation misstatement: OLD is not valid in ON SELECT.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.30 2001/12/08 03:24:35 thomas Exp $
a34 2
|
[ <replaceable class="parameter">query</replaceable> ; <replaceable class="parameter">query</replaceable> ... ]
d178 9
a186 9
   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.
@


1.30
log
@Use PostgreSQL consistantly throughout docs. Before, usage was split evenly
 between Postgres and PostgreSQL.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.29 2001/11/06 23:54:32 tgl Exp $
d112 2
a113 2
    <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.
@


1.29
log
@Add some notes about conditional rules used with views.
@
text
@d2 2
a3 2
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.28 2001/10/09 18:46:00 petere Exp $
Postgres documentation
d151 1
a151 1
   The <productname>Postgres</productname> 
d258 2
a259 2
    <productname>Postgres</productname>, the
    select command will cause <productname>Postgres</productname> to 
d275 1
a275 1
      <productname>Postgres</productname> to issue an error
d313 1
a313 1
    <command>CREATE RULE</command> statement is a <productname>Postgres</productname>
@


1.28
log
@Bunch of copy fitting and style sheet tweakage to get decent looking print
output (from pdfjadetex).  Also updated instructions to install documentation
processing toolchain.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.27 2001/09/14 08:19:55 ishii Exp $
d199 1
a199 1
    <date>2001-01-05</date>
d202 1
a202 1
    Notes
d210 13
a222 2
    better style to write a CREATE VIEW command than to create a table and
    define an ON SELECT rule for it.
d226 23
d304 1
a304 1
  <refsect2 id="R2-SQL-CREATERULE-4">
@


1.27
log
@Example rules do not work.

CREATE RULE bad_rule_combination_1 AS
    ON SELECT TO emp
    DO INSTEAD
        SELECT * FROM toyemp;

CREATE RULE bad_rule_combination_2 AS
    ON SELECT TO toyemp
    DO INSTEAD
        SELECT * FROM emp;

	Tatsuo Ishii
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.26 2001/09/07 20:52:30 tgl Exp $
d228 1
a228 3
    <example>
     <title>Example of a circular rewrite rule combination:</title>
     <programlisting>
a232 1
     </programlisting>
a233 1
     <programlisting>
d238 2
a239 2
     </programlisting>
     <para>
d243 2
a244 1
      <programlisting>
d246 1
a246 2
      </programlisting></para>
    </example>
@


1.26
log
@Revert treatment of NOTIFY in rules to its pre-7.1 behavior: notify will
occur unconditionally, even if the rule should otherwise execute
conditionally.  This is more useful than giving an error, even though it's
not truly the correct behavior.  Per today's pghackers discussion.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.25 2001/09/03 12:57:49 petere Exp $
d231 1
a231 1
CREATE RULE bad_rule_combination_1 AS
d238 1
a238 1
CREATE RULE bad_rule_combination_2 AS
@


1.25
log
@Put some kind of grammatical uniformity in the <refpurpose> lines.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.24 2001/07/09 23:50:31 tgl Exp $
d251 14
@


1.24
log
@Fix rule rewriter so that new ordering of ON INSERT actions applies
in cases of qualified rules as well as unqualified ones.  Tweak rules
test to avoid cluttering output with dummy SELECT results.  Update
documentation to match code.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.23 2001/05/27 09:59:27 petere Exp $
d16 1
a16 1
   Defines a new rule
@


1.23
log
@Make UPDATE and DELETE privileges distinct.  Add REFERENCES and TRIGGER
privileges.  INSERT and COPY FROM now require INSERT (only).  Add
privileges regression test.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.22 2001/01/13 23:58:55 petere Exp $
d170 2
a171 1
   it is done before the original query is performed.
@


1.22
log
@Terminology cleanup: class -> table, instance -> row, attribute -> column,
etc.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.21 2001/01/06 04:14:35 tgl Exp $
d8 1
a8 3
  <refentrytitle id="sql-createrule-title">
   CREATE RULE
  </refentrytitle>
@


1.21
log
@Bring CREATE RULE reference page into some semblance of agreement with
what's actually implemented.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.20 2000/12/12 16:47:52 momjian Exp $
d216 1
a216 1
    You must have rule definition access to a class in order
@


1.20
log
@In 'Joins between classes' in Section 5 of the tutorial we have, in
the first paragraph:

    As an example, say we wish to find all the records that
    are in the  temperature  range  of  other records. In
    effect, we need to compare the temp_lo and temp_hi
    attributes of each EMP instance to the temp_lo and
    temp_hi  attributes of all other EMP instances.

I believe that EMP should read WEATHER, as the example query that
follows joins WEATHER to itself.

EMP is often used in Oracle examples.

Regards,
Graham

Other RULE cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.19 2000/10/05 19:48:17 momjian Exp $
d23 1
a23 1
   <date>1999-07-20</date>
d28 11
a38 1
    DO [ INSTEAD ] [ <replaceable class="parameter">action</replaceable> | NOTHING ]
d43 1
a43 1
    <date>1998-09-11</date>
d63 3
a65 3
	Event is one of <literal>select</literal>,
	<literal>update</literal>, <literal>delete</literal>
	or <literal>insert</literal>.
d75 3
a77 1
	 class="parameter">column</replaceable>.
d85 3
a87 3
	Any SQL WHERE clause, <literal>new</literal> or
	<literal>old</literal>, can appear instead of an instance
	variable whenever an instance variable is permissible in SQL.
d92 1
a92 1
      <term><replaceable class="parameter">action</replaceable></term>
d95 5
a99 3
	Any SQL statement, <literal>new</literal> or
	<literal>old</literal>, can appear instead of an instance
	variable whenever an instance variable is permissible in SQL.
d105 12
d156 2
a157 2
   from database tables or classes. Currently, rules are used to
   implement table views.
d161 2
a162 1
   The semantics of a rule is that at the time an individual instance is
d165 2
a166 3
  updates).
  If the <replaceable class="parameter">event</replaceable>
   specified in the ON clause and the
d168 1
a168 1
   WHERE clause are true for the old instance, the
d170 6
a175 2
   executed. First, however, values from fields in the old instance
   and/or the new instance are substituted for
d182 12
d200 1
a200 1
    <date>1998-09-11</date>
d206 13
a218 32
    A caution about SQL rules is in  order.  If the same class name
    or instance variable appears in the
    <replaceable class="parameter">event</replaceable>,
    <replaceable class="parameter">condition</replaceable> and
    <replaceable class="parameter">action</replaceable> parts of a rule,
    they are all considered different tuple variables. More accurately,
    <literal>new</literal> and <literal>old</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 SET ... WHERE ...
    </programlisting>

    <programlisting>
ON UPDATE TO emp-1.salary WHERE emp-2.name = "Joe"
    DO 
	UPDATE emp-3 SET ...  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 latter case, the
    <replaceable class="parameter">action</replaceable> can be the keyword
    <literal>NOTHING</literal>.
d220 1
d222 1
a222 1
    It is very important to note to avoid circular rules.
a252 25

   <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>
    The object in a <acronym>SQL</acronym> 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>
a253 72
 </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 old.name = "Joe"
    DO 
	UPDATE emp 
	SET salary = new.salary
	WHERE emp.name = "Sam";
   </programlisting>

   At the time Joe receives a salary adjustment, the event
   will become true and Joe's old 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 old.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 old.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 INERT TO emp WHERE new.salary > 5000
    DO 
	UPDATE emp SET salary = 5000
	WHERE emp.oid = new.oid;
   </programlisting>
  </para>
@


1.19
log
@Add proofreader's changes to docs.
Fix misspelling of disbursion to dispersion.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.18 2000/07/22 02:39:10 momjian Exp $
d211 1
a211 1
	SELECT TO toyemp;
d218 1
a218 1
	SELECT TO emp;
@


1.18
log
@Cleanups
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.17 2000/07/21 04:22:54 momjian Exp $
d74 1
a74 1
	<literal>old</literal> can appear instead of an instance
d84 1
a84 1
	<literal>old</literal> can appear instead of an instance
d136 1
a136 1
   accessed, inserted, updated, or deleted, there is a old instance (for
d193 1
a193 1
    instead of the user command. In this later case, the
@


1.17
log
@Cleanup
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.16 2000/05/20 11:38:25 momjian Exp $
d206 1
a206 1
     <title>Example of a circular rewrite rule combination.</title>
d223 1
a223 1
      because the queries cycled too many times.
@


1.16
log
@Update rules man pages.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.15 2000/04/12 20:07:13 momjian Exp $
d305 1
a305 1
   Create a view of the employees working in the toy department.
d318 1
a318 1
   All new employees must make 5,000 or less
@


1.15
log
@Update man page to prefer old over current.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.14 2000/04/07 19:17:30 momjian Exp $
d323 2
a324 1
	UPDATE NEWSET SET salary = 5000;
@


1.14
log
@Update create_rule manual page.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.13 2000/04/07 17:37:24 momjian Exp $
d74 1
a74 1
	<literal>current</literal> can appear instead of an instance
d84 1
a84 1
	<literal>current</literal> can appear instead of an instance
d136 1
a136 1
   accessed, inserted, updated, or deleted, there is a current instance (for
d142 1
a142 1
   WHERE clause are true for the current instance, the
d144 1
a144 1
   executed. First, however, values from fields in the current instance
d146 1
a146 1
   <literal>current.</literal><replaceable class="parameter">attribute-name</replaceable>
d170 1
a170 1
    <literal>new</literal> and <literal>current</literal> are the only tuple
d266 1
a266 1
    ON UPDATE emp.salary WHERE current.name = "Joe"
d274 1
a274 1
   will become true and Joe's current instance and proposed
d285 1
a285 1
    WHERE current.name = "Bill"
d300 1
a300 1
   	WHERE current.dept = "shoe" AND current_user = "Joe"
@


1.13
log
@Again update of rule manual page.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.12 2000/04/07 17:35:08 momjian Exp $
d129 1
a129 1
   alternate action to be performed on updates, inserts, or deletions
d136 4
a139 3
   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>
d166 2
a167 2
    <replaceable class="parameter">event</replaceable>, the
    <replaceable class="parameter">condition</replaceable> and the
d176 1
a176 1
	UPDATE emp ( ... ) WHERE ...
d182 1
a182 1
	UPDATE emp-3 ( ... ) WHERE ...
d198 2
a199 2
    It is very important to note that the rewrite rule system
    will neither detect nor process circular rules. For example, though each
d202 2
a203 1
    retrieve command will cause <productname>Postgres</productname> to crash:
d221 3
a223 2
      This attempt to retrieve from EMP will cause
      <productname>Postgres</productname> to crash.
d312 1
a312 1
    	SELECT (emp.name, emp.salary) 
d323 1
a323 1
	UPDATE NEWSET salary = 5000;
@


1.12
log
@Update rule examples
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.11 2000/04/07 17:23:11 momjian Exp $
d73 1
a73 1
	Any SQL WHERE clause. <literal>new</literal> or
d83 1
a83 1
	Any SQL statement. <literal>new</literal> or
@


1.11
log
@Remove mention of INSTANCE rule system, because it is gone.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.10 1999/07/22 15:09:08 thomas Exp $
d174 2
a175 1
    DO UPDATE emp ( ... ) WHERE ...
d180 2
a181 1
    DO UPDATE emp-3 ( ... ) WHERE ...
d208 2
a209 1
    DO INSTEAD SELECT TO toyemp;
d215 2
a216 1
    DO INSTEAD SELECT TO emp;
d264 4
a267 2
    DO UPDATE emp (salary = new.salary)
    WHERE emp.name = "Sam";
d284 3
a286 2
    SELECT (emp.salary) from emp
        WHERE emp.name = "Joe";
d295 3
a297 2
    ON SELECT TO emp.salary
    WHERE current.dept = "shoe" AND current_user = "Joe"
d309 2
a310 1
    SELECT (emp.name, emp.salary) FROM emp
d319 2
a320 1
    DO UPDATE NEWSET salary = 5000;
@


1.10
log
@Complete merge of all old man page information.
ecpg reference page still needs formatting.
@
text
@d2 1
a2 1
$Header$
a192 6
   </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).
@


1.9
log
@Fix markup for docbook2man man page generation.
No big deal; fixed lots of other markup at the same time.
Bigest change: make sure there is no whitespace
 in front of <term> contents.
This will probably help the other output types too.
@
text
@d1 5
d8 1
a8 1
  <refentrytitle>
d23 1
a23 1
   <date>1998-09-11</date>
d125 9
d148 1
d227 1
a228 1
   </para>
d234 19
a320 22
 <refsect1 id="R1-SQL-CREATERULE-3">
  <title>
   Bugs
  </title>
  <para>
   The object in a <acronym>SQL</acronym> 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>

a324 4
  <para>
   <command>CREATE RULE</command> statement is a <productname>Postgres</productname>
   language extension.
  </para>
d333 1
d335 2
@


1.8
log
@Fix create_rule is->as.
@
text
@d1 3
a3 3
<REFENTRY ID="SQL-CREATERULE">
 <REFMETA>
  <REFENTRYTITLE>
d5 5
a9 5
  </REFENTRYTITLE>
  <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
 </REFMETA>
 <REFNAMEDIV>
  <REFNAME>
d11 2
a12 2
  </REFNAME>
  <REFPURPOSE>
d14 1
a14 1
  </REFPURPOSE>
d16 6
a21 7
 <REFSYNOPSISDIV>
  <REFSYNOPSISDIVINFO>
   <DATE>1998-09-11</DATE>
  </REFSYNOPSISDIVINFO>
  <SYNOPSIS>
CREATE RULE <replaceable class="parameter">name</replaceable>
    AS ON <replaceable class="parameter">event</replaceable>
d24 7
a30 7
  </SYNOPSIS>
  
  <REFSECT2 ID="R2-SQL-CREATERULE-1">
   <REFSECT2INFO>
    <DATE>1998-09-11</DATE>
   </REFSECT2INFO>
   <TITLE>
d32 55
a86 62
   </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>
d88 5
a92 7
  </REFSECT2>
  
  <REFSECT2 ID="R2-SQL-CREATERULE-2">
   <REFSECT2INFO>
    <DATE>1998-09-11</DATE>
   </REFSECT2INFO>
   <TITLE>
d94 12
a105 11
   </TITLE>
   <PARA>
       <VARIABLELIST>
	<VARLISTENTRY>
	 <TERM>
	  <ReturnValue>CREATE</ReturnValue>
	 </TERM>
	 <LISTITEM>
	  <PARA>
	   Message returned if the rule is successfully created.
	</para>
d107 2
a108 2
     </VARLISTENTRY>
    </VARIABLELIST>
d110 8
a117 8
  </REFSECT2>
 </REFSYNOPSISDIV>
 
 <REFSECT1 ID="R1-SQL-CREATERULE-1">
  <REFSECT1INFO>
   <DATE>1998-09-11</DATE>
  </REFSECT1INFO>
  <TITLE>
d119 2
a120 2
  </TITLE>
  <PARA>
d140 5
a144 5
  <REFSECT2 ID="R2-SQL-CREATERULE-3">
   <REFSECT2INFO>
    <DATE>1998-09-11</DATE>
   </REFSECT2INFO>
   <TITLE>
d146 1
a146 1
   </TITLE>
d158 3
a160 2
on update to EMP.salary where EMP.name = "Joe"
    do update EMP ( ... ) where ...
d162 3
a164 2
on update to EMP-1.salary where EMP-2.name = "Joe"
    do update EMP-3 ( ... ) where ...
d166 1
d168 1
a168 1
Without
d177 1
a177 1
    NOTHING.
d189 1
a189 1
 <productname>Postgres</productname>, the
d195 3
a197 7
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
d199 7
a205 1
     <para>	 
d207 1
a207 1
 <productname>Postgres</productname> to crash.
d209 1
a209 1
select * from EMP
d218 2
a219 3
    
   </PARA>
  </REFSECT2>
d222 2
a223 2
 <REFSECT1 ID="R1-SQL-CREATERULE-2">
  <TITLE>
d225 2
a226 2
  </TITLE>
  <PARA>
d230 4
a233 4
create rule example_1 as
    on update EMP.salary where current.name = "Joe"
    do update EMP (salary = new.salary)
    where EMP.name = "Sam"
d235 1
a235 1
   
d246 6
a251 6
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"
d259 4
a262 4
create rule example_3 as
    on select to EMP.salary
    where current.dept = "shoe" and current_user = "Joe"
    do instead nothing
d268 1
a268 1
create TOYEMP(name = char16, salary = int4)
d270 5
a274 5
create rule example_4 as
    on select to TOYEMP
    do instead
    select (EMP.name, EMP.salary) from EMP
        where EMP.dept = "toy"
d280 3
a282 3
create rule example_5 as
    on insert to EMP where new.salary > 5000
    do update newset salary = 5000
d284 5
a288 5
  </PARA>
 </REFSECT1>
 
 <REFSECT1 ID="R1-SQL-CREATERULE-3">
  <TITLE>
d290 1
a290 1
  </TITLE>
d292 1
a292 1
   The object in a SQL rule cannot be an array reference and
d306 1
a306 1
   </PARA>
d308 3
a310 3
  
 <REFSECT1 ID="R1-SQL-CREATERULE-4">
  <TITLE>
d312 11
a322 11
  </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>
d324 1
a324 1
   </TITLE>
d326 1
a326 1
    There is no CREATE RULE statement in <acronym>SQL92</acronym>.
d330 1
a330 1
</REFENTRY>
d335 1
a335 1
sgml-omittag:t
@


1.7
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d201 1
a201 1
create rule bad_rule_combination_1 is
d205 1
a205 1
create rule bad_rule_combination_2 is
d235 1
a235 1
create rule example_1 is
d251 1
a251 1
create rule example_2 is
d264 1
a264 1
create rule example_3 is
d275 1
a275 1
create rule example_4 is
d285 1
a285 1
create rule example_5 is
@


1.6
log
@Minor cleanup in markup, especially in the Output section.
@
text
@d15 1
d114 5
a118 4

    </VARLISTENTRY>
   </VARIABLELIST>
   
d221 2
a222 2
and <command>REVOKE</command> to change permissions.

d312 1
@


1.5
log
@Markup and editing adjustments...
@
text
@a104 8
   </PARA>
   <VARIABLELIST>
    <VARLISTENTRY>
     <TERM>
<replaceable>status</replaceable>
     </TERM>
     <LISTITEM>
      <PARA>
d113 1
a113 5
	  </PARA>
	 </LISTITEM>
	</VARLISTENTRY>
       </variablelist>
     </LISTITEM>
d195 1
d214 1
@


1.4
log
@Very minor formatting fixup in the refentry id field to remove
 the trailing "-1". This makes a cleaner html output file name.
Clean up a few refpurpose fields.
@
text
@d17 1
a17 1
   <DATE>1998-04-15</DATE>
d20 4
a23 5
   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 ]
d28 1
a28 1
    <DATE>1998-04-15</DATE>
a34 6
   <VARIABLELIST>
    <VARLISTENTRY>
     <TERM>
     </TERM>
     <LISTITEM>
      <PARA>
d38 1
a38 1
	  <ReturnValue><replaceable class="parameter">name</replaceable></ReturnValue>
d48 1
a48 1
	  <ReturnValue><replaceable class="parameter">event</replaceable></ReturnValue>
d52 3
a54 1
	   Event is one of <literal>select</literal>, <literal>update</literal>, <literal>delete</literal> or <literal>insert</literal>.
d60 1
a60 1
	  <ReturnValue><replaceable class="parameter">object</replaceable></ReturnValue>
d64 2
a65 1
	   Object is either <replaceable class="parameter">table</replaceable> or <replaceable class="parameter">table</replaceable>.<replaceable class="parameter">column</replaceable>.
d71 1
a71 1
	  <ReturnValue><replaceable class="parameter">condition</replaceable></ReturnValue>
d75 1
a75 1
	   Any SQL <literal>where</literal> clause. <literal>new</literal> or
d83 1
a83 1
	  <ReturnValue><replaceable class="parameter">action</replaceable></ReturnValue>
d87 1
a87 1
	   Any SQL-statement. <literal>new</literal> or
d94 1
a94 3
     </LISTITEM>
    </VARLISTENTRY>
   </VARIABLELIST>
d99 1
a99 1
    <DATE>1998-04-15</DATE>
d109 1
d134 1
a134 1
   <DATE>1998-04-15</DATE>
d144 1
a144 1
   specified in the <literal>on</literal> clause and the
d146 1
a146 1
   <literal>where</literal> clause are true for the current instance, the
d150 1
a150 1
   <literal> current.</literal><replaceable class="parameter">attribute-name</replaceable>
d161 1
a161 1
    <DATE>1998-04-15</DATE>
d167 1
a167 1
    A note of caution about SQL rules is in  order.  If the same class name
d177 2
a178 2
     on update to EMP.salary where EMP.name = "Joe"
	  do update EMP ( ... ) where ...
d180 2
a181 2
     on update to EMP-1.salary where EMP-2.name = "Joe"
	  do update EMP-3 ( ... ) where ...
d183 2
a184 1
    Each rule can have the optional tag <literal>instead</literal>. Without
d193 1
a193 1
    <literal>nothing</literal>.
d204 3
a206 2
    of the following two rule definitions are accepted by Postgres, the
    retrieve command will cause Postgres to crash:
d210 3
a212 3
	  create rule bad_rule_combination_1 is
		  on select to EMP
		  do instead select to TOYEMP
d214 3
a216 3
	  create rule bad_rule_combination_2 is
		  on select to TOYEMP
		  do instead select to EMP
d219 2
a220 1
      This attempt to retrieve from EMP will cause Postgres to crash.
d222 1
a222 1
	  select * from EMP
d228 3
a230 4
    to define a rule on it (see change acl(l)).
    <comment>
     There is no manpage change or change_acl.  What is intended?
    </comment>
d240 1
a240 1
   Make Sam get the same salary adjustment as Joe
d243 4
a246 4
	  create rule example_1 is
		 on update EMP.salary where current.name = "Joe"
		 do update EMP (salary = new.salary)
		  where EMP.name = "Sam"
d257 1
a257 1
   Make Bill get Joe's salary when it is accessed
d259 6
a264 6
	  create rule example_2 is

		 on select to EMP.salary
			where current.name = "Bill"
		 do instead
		  select (EMP.salary) from EMP where EMP.name = "Joe"
d269 2
a270 2
   department. (<function>pg_username()</function> returns the name of
   the current user)
d272 4
a275 4
	  create rule example_3 is
		 on select to EMP.salary
		 where current.dept = "shoe" and pg_username() = "Joe"
		 do instead nothing
d281 1
a281 1
	  create TOYEMP(name = char16, salary = int4)
d283 5
a287 4
	  create rule example_4 is
		 on select to TOYEMP
		 do instead select (EMP.name, EMP.salary) from EMP
		 where EMP.dept = "toy"
d293 3
a295 3
	  create rule example_5 is
		  on insert to EMP where new.salary > 5000
		  do update newset salary = 5000
a303 3
  <PARA>
   <literal>instead</literal> rules do not work properly.
  </para>
d326 2
a327 1
   CREATE RULE statement is a PostgreSQL language extension.
d332 1
a332 1
    <DATE>1998-04-15</DATE>
d338 1
a338 1
    There is no CREATE RULE statement in SQL92.
@


1.3
log
@Make minor formatting improvements to statement synopses.
Make sure all files end with a newline.
@
text
@d1 1
a1 1
<REFENTRY ID="SQL-CREATERULE-1">
@


1.2
log
@Fix minor end-of-file formatting.
@
text
@d13 1
a13 1
   Defines a new rule.
d363 1
a363 1
-->@


1.1
log
@First version of files from Oliver Elphick.
@
text
@d363 1
a363 1
-->
@
