Support triggers on views.

This patch adds the SQL-standard concept of an INSTEAD OF trigger, which
is fired instead of performing a physical insert/update/delete.  The
trigger function is passed the entire old and/or new rows of the view,
and must figure out what to do to the underlying tables to implement
the update.  So this feature can be used to implement updatable views
using trigger programming style rather than rule hacking.

In passing, this patch corrects the names of some columns in the
information_schema.triggers view.  It seems the SQL committee renamed
them somewhere between SQL:99 and SQL:2003.

Dean Rasheed, reviewed by Bernd Helmle; some additional hacking by me.

Author: tglsfdc

doc/src/sgml/catalogs.sgml

@@ -4243,7 +4243,7 @@
 
   <para>
    The catalog <structname>pg_seclabel</structname> stores security
-   labels on database objects.  See the 
+   labels on database objects.  See the
    <xref linkend="sql-security-label"> statement.
   </para>
 
@@ -4795,7 +4795,8 @@
   </indexterm>
 
   <para>
-   The catalog <structname>pg_trigger</structname> stores triggers on tables.
+   The catalog <structname>pg_trigger</structname> stores triggers on tables
+   and views.
    See <xref linkend="sql-createtrigger">
    for more information.
   </para>
@@ -4839,7 +4840,7 @@
       <entry><structfield>tgtype</structfield></entry>
       <entry><type>int2</type></entry>
       <entry></entry>
-      <entry>Bit mask identifying trigger conditions</entry>
+      <entry>Bit mask identifying trigger firing conditions</entry>
      </row>
 
      <row>
@@ -4956,7 +4957,7 @@
   <note>
    <para>
     <literal>pg_class.relhastriggers</literal>
-    must be true if a table has any triggers in this catalog.
+    must be true if a relation has any triggers in this catalog.
    </para>
   </note>
 

doc/src/sgml/information_schema.sgml

@@ -4885,8 +4885,8 @@ ORDER BY c.ordinal_position;
 
   <para>
    The view <literal>triggers</literal> contains all triggers defined
-   in the current database on tables that the current user owns or has
-   some non-SELECT privilege on.
+   in the current database on tables and views that the current user owns
+   or has some non-SELECT privilege on.
   </para>
 
   <table>
@@ -4987,34 +4987,34 @@ ORDER BY c.ordinal_position;
      </row>
 
      <row>
-      <entry><literal>condition_timing</literal></entry>
+      <entry><literal>action_timing</literal></entry>
       <entry><type>character_data</type></entry>
       <entry>
-       Time at which the trigger fires (<literal>BEFORE</literal> or
-       <literal>AFTER</literal>)
+       Time at which the trigger fires (<literal>BEFORE</literal>,
+       <literal>AFTER</literal>, or <literal>INSTEAD OF</literal>)
       </entry>
      </row>
 
      <row>
-      <entry><literal>condition_reference_old_table</literal></entry>
+      <entry><literal>action_reference_old_table</literal></entry>
       <entry><type>sql_identifier</type></entry>
       <entry>Applies to a feature not available in <productname>PostgreSQL</></entry>
      </row>
 
      <row>
-      <entry><literal>condition_reference_new_table</literal></entry>
+      <entry><literal>action_reference_new_table</literal></entry>
       <entry><type>sql_identifier</type></entry>
       <entry>Applies to a feature not available in <productname>PostgreSQL</></entry>
      </row>
 
      <row>
-      <entry><literal>condition_reference_old_row</literal></entry>
+      <entry><literal>action_reference_old_row</literal></entry>
       <entry><type>sql_identifier</type></entry>
       <entry>Applies to a feature not available in <productname>PostgreSQL</></entry>
      </row>
 
      <row>
-      <entry><literal>condition_reference_new_row</literal></entry>
+      <entry><literal>action_reference_new_row</literal></entry>
       <entry><type>sql_identifier</type></entry>
       <entry>Applies to a feature not available in <productname>PostgreSQL</></entry>
      </row>
@@ -5032,9 +5032,9 @@ ORDER BY c.ordinal_position;
    Triggers in <productname>PostgreSQL</productname> have two
    incompatibilities with the SQL standard that affect the
    representation in the information schema.  First, trigger names are
-   local to the table in <productname>PostgreSQL</productname>, rather
+   local to each table in <productname>PostgreSQL</productname>, rather
    than being independent schema objects.  Therefore there can be duplicate
-   trigger names defined in one schema, as long as they belong to
+   trigger names defined in one schema, so long as they belong to
    different tables.  (<literal>trigger_catalog</literal> and
    <literal>trigger_schema</literal> are really the values pertaining
    to the table that the trigger is defined on.)  Second, triggers can
@@ -5045,14 +5045,34 @@ ORDER BY c.ordinal_position;
    multiple rows in the information schema, one for each type of
    event.  As a consequence of these two issues, the primary key of
    the view <literal>triggers</literal> is really
-   <literal>(trigger_catalog, trigger_schema, trigger_name,
-   event_object_table, event_manipulation)</literal> instead of
+   <literal>(trigger_catalog, trigger_schema, event_object_table,
+   trigger_name, event_manipulation)</literal> instead of
    <literal>(trigger_catalog, trigger_schema, trigger_name)</literal>,
    which is what the SQL standard specifies.  Nonetheless, if you
    define your triggers in a manner that conforms with the SQL
    standard (trigger names unique in the schema and only one event
    type per trigger), this will not affect you.
   </para>
+
+  <note>
+   <para>
+    Prior to <productname>PostgreSQL</> 9.1, this view's columns
+    <structfield>action_timing</structfield>,
+    <structfield>action_reference_old_table</structfield>,
+    <structfield>action_reference_new_table</structfield>,
+    <structfield>action_reference_old_row</structfield>, and
+    <structfield>action_reference_new_row</structfield>
+    were named
+    <structfield>condition_timing</structfield>,
+    <structfield>condition_reference_old_table</structfield>,
+    <structfield>condition_reference_new_table</structfield>,
+    <structfield>condition_reference_old_row</structfield>, and
+    <structfield>condition_reference_new_row</structfield>
+    respectively.
+    That was how they were named in the SQL:1999 standard.
+    The new naming conforms to SQL:2003 and later.
+   </para>
+  </note>
  </sect1>
 
  <sect1 id="infoschema-usage-privileges">
@@ -5562,19 +5582,28 @@ ORDER BY c.ordinal_position;
      <row>
       <entry><literal>is_trigger_updatable</literal></entry>
       <entry><type>yes_or_no</type></entry>
-      <entry>Applies to a feature not available in <productname>PostgreSQL</></entry>
+      <entry>
+       <literal>YES</> if the view has an <literal>INSTEAD OF</>
+       <command>UPDATE</> trigger defined on it, <literal>NO</> if not
+      </entry>
      </row>
 
      <row>
       <entry><literal>is_trigger_deletable</literal></entry>
       <entry><type>yes_or_no</type></entry>
-      <entry>Applies to a feature not available in <productname>PostgreSQL</></entry>
+      <entry>
+       <literal>YES</> if the view has an <literal>INSTEAD OF</>
+       <command>DELETE</> trigger defined on it, <literal>NO</> if not
+      </entry>
      </row>
 
      <row>
       <entry><literal>is_trigger_insertable_into</literal></entry>
       <entry><type>yes_or_no</type></entry>
-      <entry>Applies to a feature not available in <productname>PostgreSQL</></entry>
+      <entry>
+       <literal>YES</> if the view has an <literal>INSTEAD OF</>
+       <command>INSERT</> trigger defined on it, <literal>NO</> if not
+      </entry>
      </row>
     </tbody>
    </tgroup>

doc/src/sgml/plperl.sgml

@@ -999,7 +999,9 @@ $$ LANGUAGE plperl;
      <term><literal>$_TD-&gt;{when}</literal></term>
      <listitem>
       <para>
-       When the trigger was called: <literal>BEFORE</literal>, <literal>AFTER</literal>, or <literal>UNKNOWN</literal>
+       When the trigger was called: <literal>BEFORE</literal>,
+       <literal>AFTER</literal>, <literal>INSTEAD OF</literal>, or
+       <literal>UNKNOWN</literal>
       </para>
      </listitem>
     </varlistentry>

doc/src/sgml/plpgsql.sgml

@@ -3112,9 +3112,9 @@ RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
      <term><varname>TG_WHEN</varname></term>
      <listitem>
       <para>
-       Data type <type>text</type>; a string of either
-       <literal>BEFORE</literal> or <literal>AFTER</literal>
-       depending on the trigger's definition.
+       Data type <type>text</type>; a string of
+       <literal>BEFORE</literal>, <literal>AFTER</literal>, or
+       <literal>INSTEAD OF</literal>, depending on the trigger's definition.
       </para>
      </listitem>
     </varlistentry>
@@ -3234,8 +3234,25 @@ RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
     effect, but it has to be nonnull to allow the trigger action to
     proceed.  Note that <varname>NEW</varname> is null
     in <command>DELETE</command> triggers, so returning that is
-    usually not sensible.  A useful idiom in <command>DELETE</command>
-    triggers might be to return <varname>OLD</varname>.
+    usually not sensible.  The usual idiom in <command>DELETE</command>
+    triggers is to return <varname>OLD</varname>.
+   </para>
+
+   <para>
+    <literal>INSTEAD OF</> triggers (which are always row-level triggers,
+    and may only be used on views) can return null to signal that they did
+    not perform any updates, and that the rest of the operation for this
+    row should be skipped (i.e., subsequent triggers are not fired, and the
+    row is not counted in the rows-affected status for the surrounding
+    <command>INSERT</>/<command>UPDATE</>/<command>DELETE</>).
+    Otherwise a nonnull value should be returned, to signal
+    that the trigger performed the requested operation. For
+    <command>INSERT</> and <command>UPDATE</> operations, the return value
+    should be <varname>NEW</>, which the trigger function may modify to
+    support <command>INSERT RETURNING</> and <command>UPDATE RETURNING</>
+    (this will also affect the row value passed to any subsequent triggers).
+    For <command>DELETE</> operations, the return value should be
+    <varname>OLD</>.
    </para>
 
    <para>
@@ -3354,6 +3371,85 @@ AFTER INSERT OR UPDATE OR DELETE ON emp
 </programlisting>
    </example>
 
+   <para>
+    A variation of the previous example uses a view joining the main table
+    to the audit table, to show when each entry was last modified. This
+    approach still records the full audit trail of changes to the table,
+    but also presents a simplified view of the audit trail, showing just
+    the last modified timestamp derived from the audit trail for each entry.
+    <xref linkend="plpgsql-view-trigger-audit-example"> shows an example
+    of an audit trigger on a view in <application>PL/pgSQL</application>.
+   </para>
+
+   <example id="plpgsql-view-trigger-audit-example">
+    <title>A <application>PL/pgSQL</application> View Trigger Procedure For Auditing</title>
+
+    <para>
+     This example uses a trigger on the view to make it updatable, and
+     ensure that any insert, update or delete of a row in the view is
+     recorded (i.e., audited) in the emp_audit table. The current time
+     and user name are recorded, together with the type of operation
+     performed, and the view displays the last modified time of each row.
+    </para>
+
+<programlisting>
+CREATE TABLE emp (
+    empname           text PRIMARY KEY,
+    salary            integer
+);
+
+CREATE TABLE emp_audit(
+    operation         char(1)   NOT NULL,
+    userid            text      NOT NULL,
+    empname           text      NOT NULL,
+    salary            integer,
+    stamp             timestamp NOT NULL
+);
+
+CREATE VIEW emp_view AS
+    SELECT e.empname,
+           e.salary,
+           max(ea.stamp) AS last_updated
+      FROM emp e
+      LEFT JOIN emp_audit ea ON ea.empname = e.empname
+     GROUP BY 1, 2;
+
+CREATE OR REPLACE FUNCTION update_emp_view() RETURNS TRIGGER AS $$
+    BEGIN
+        --
+        -- Perform the required operation on emp, and create a row in emp_audit
+        -- to reflect the change made to emp.
+        --
+        IF (TG_OP = 'DELETE') THEN
+            DELETE FROM emp WHERE empname = OLD.empname;
+            IF NOT FOUND THEN RETURN NULL; END IF;
+
+            OLD.last_updated = now();
+            INSERT INTO emp_audit VALUES('D', user, OLD.*);
+            RETURN OLD;
+        ELSIF (TG_OP = 'UPDATE') THEN
+            UPDATE emp SET salary = NEW.salary WHERE empname = OLD.empname;
+            IF NOT FOUND THEN RETURN NULL; END IF;
+
+            NEW.last_updated = now();
+            INSERT INTO emp_audit VALUES('U', user, NEW.*);
+            RETURN NEW;
+        ELSIF (TG_OP = 'INSERT') THEN
+            INSERT INTO emp VALUES(NEW.empname, NEW.salary);
+
+            NEW.last_updated = now();
+            INSERT INTO emp_audit VALUES('I', user, NEW.*);
+            RETURN NEW;
+        END IF;
+    END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER emp_audit
+INSTEAD OF INSERT OR UPDATE OR DELETE ON emp_view
+    FOR EACH ROW EXECUTE PROCEDURE update_emp_view();
+</programlisting>
+   </example>
+
    <para>
     One use of triggers is to maintain a summary table
     of another table. The resulting summary can be used in place of the

doc/src/sgml/plpython.sgml

@@ -609,7 +609,7 @@ CREATE TYPE greeting AS (
   who text
 );
 </programlisting>
-   
+
    A set result can be returned from a:
 
    <variablelist>
@@ -751,8 +751,7 @@ $$ LANGUAGE plpythonu;
       <para>
        contains the event as a string:
        <literal>INSERT</>, <literal>UPDATE</>,
-       <literal>DELETE</>, <literal>TRUNCATE</>,
-       or <literal>UNKNOWN</>.
+       <literal>DELETE</>, or <literal>TRUNCATE</>.
       </para>
      </listitem>
     </varlistentry>
@@ -761,8 +760,8 @@ $$ LANGUAGE plpythonu;
      <term><literal>TD["when"]</></term>
      <listitem>
       <para>
-       contains one of <literal>BEFORE</>, <literal>AFTER</>,
-       or <literal>UNKNOWN</>.
+       contains one of <literal>BEFORE</>, <literal>AFTER</>, or
+       <literal>INSTEAD OF</>.
       </para>
      </listitem>
     </varlistentry>
@@ -771,8 +770,7 @@ $$ LANGUAGE plpythonu;
      <term><literal>TD["level"]</></term>
      <listitem>
       <para>
-       contains one of <literal>ROW</>,
-       <literal>STATEMENT</>, or <literal>UNKNOWN</>.
+       contains <literal>ROW</> or <literal>STATEMENT</>.
       </para>
      </listitem>
     </varlistentry>
@@ -838,12 +836,14 @@ $$ LANGUAGE plpythonu;
   </para>
 
   <para>
-   If <literal>TD["when"]</literal> is <literal>BEFORE</> and
+   If <literal>TD["when"]</literal> is <literal>BEFORE</> or
+   <literal>INSTEAD OF</> and
    <literal>TD["level"]</literal> is <literal>ROW</>, you can
    return <literal>None</literal> or <literal>"OK"</literal> from the
    Python function to indicate the row is unmodified,
-   <literal>"SKIP"</> to abort the event, or <literal>"MODIFY"</> to
-   indicate you've modified the row.
+   <literal>"SKIP"</> to abort the event, or if <literal>TD["event"]</>
+   is <command>INSERT</> or <command>UPDATE</> you can return
+   <literal>"MODIFY"</> to indicate you've modified the new row.
    Otherwise the return value is ignored.
   </para>
  </sect1>

doc/src/sgml/pltcl.sgml

@@ -591,8 +591,8 @@ SELECT 'doesn''t' AS ret
        <term><varname>$TG_when</varname></term>
        <listitem>
         <para>
-         The string <literal>BEFORE</> or <literal>AFTER</> depending on the
-         type of trigger event.
+         The string <literal>BEFORE</>, <literal>AFTER</>, or
+         <literal>INSTEAD OF</>, depending on the type of trigger event.
         </para>
        </listitem>
       </varlistentry>
@@ -665,10 +665,14 @@ SELECT 'doesn''t' AS ret
      the operation (<command>INSERT</>/<command>UPDATE</>/<command>DELETE</>) that fired the trigger will proceed
      normally. <literal>SKIP</> tells the trigger manager to silently suppress
      the operation for this row. If a list is returned, it tells PL/Tcl to
-     return a modified row to the trigger manager that will be inserted
-     instead of the one given in <varname>$NEW</>.  (This works for <command>INSERT</> and <command>UPDATE</>
-     only.) Needless to say that all this is only meaningful when the trigger
-     is <literal>BEFORE</> and <command>FOR EACH ROW</>; otherwise the return value is ignored.
+     return a modified row to the trigger manager. This is only meaningful
+     for row-level <literal>BEFORE</> <command>INSERT</> or <command>UPDATE</>
+     triggers for which the modified row will be inserted instead of the one
+     given in <varname>$NEW</>; or for row-level <literal>INSTEAD OF</>
+     <command>INSERT</> or <command>UPDATE</> triggers where the returned row
+     is used to support <command>INSERT RETURNING</> and
+     <command>UPDATE RETURNING</> commands. The return value is ignored for
+     other types of triggers.
     </para>
 
     <para>