Add INSERT/UPDATE/DELETE RETURNING, with basic docs and regression tests.

plpgsql support to come later.  Along the way, convert execMain's
SELECT INTO support into a DestReceiver, in order to eliminate some ugly
special cases.

Jonah Harris and Tom Lane

doc/src/sgml/ref/delete.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/delete.sgml,v 1.26 2006/01/22 05:20:33 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/delete.sgml,v 1.27 2006/08/12 02:52:03 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -23,6 +23,7 @@ PostgreSQL documentation
 DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ] <replaceable class="parameter">alias</replaceable> ]
     [ USING <replaceable class="PARAMETER">usinglist</replaceable> ]
     [ WHERE <replaceable class="PARAMETER">condition</replaceable> ]
+    [ RETURNING * | <replaceable class="parameter">output_expression</replaceable> [ AS <replaceable class="parameter">output_name</replaceable> ] [, ...] ]
 </synopsis>
  </refsynopsisdiv>
 
@@ -59,6 +60,15 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ]
    circumstances.
   </para>
 
+  <para>
+   The optional <literal>RETURNING</> clause causes <command>DELETE</>
+   to compute and return value(s) based on each row actually deleted.
+   Any expression using the table's columns, and/or columns of other
+   tables mentioned in <literal>USING</literal>, can be computed.
+   The syntax of the <literal>RETURNING</> list is identical to that of the
+   output list of <command>SELECT</>.
+  </para>
+
   <para>
    You must have the <literal>DELETE</literal> privilege on the table
    to delete from it, as well as the <literal>SELECT</literal>
@@ -130,6 +140,28 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ [ AS ]
      </para>
     </listitem>
    </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="PARAMETER">output_expression</replaceable></term>
+    <listitem>
+     <para>
+      An expression to be computed and returned by the <command>DELETE</>
+      command after each row is deleted.  The expression may use any
+      column names of the <replaceable class="PARAMETER">table</replaceable>
+      or table(s) listed in <literal>USING</>.
+      Write <literal>*</> to return all columns.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="PARAMETER">output_name</replaceable></term>
+    <listitem>
+     <para>
+      A name to use for a returned column.
+     </para>
+    </listitem>
+   </varlistentry>
   </variablelist>
  </refsect1>
 
@@ -148,6 +180,14 @@ DELETE <replaceable class="parameter">count</replaceable>
    class="parameter">condition</replaceable> (this is not considered
    an error).
   </para>
+
+  <para>
+   If the <command>DELETE</> command contains a <literal>RETURNING</>
+   clause, the result will be similar to that of a <command>SELECT</>
+   statement containing the columns and values defined in the
+   <literal>RETURNING</> list, computed over the row(s) deleted by the
+   command.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -189,6 +229,13 @@ DELETE FROM films WHERE kind &lt;&gt; 'Musical';
    Clear the table <literal>films</literal>:
 <programlisting>
 DELETE FROM films;
+</programlisting>      
+  </para>
+
+  <para>
+   Delete completed tasks, returning full details of the deleted rows:
+<programlisting>
+DELETE FROM tasks WHERE status = 'DONE' RETURNING *;
 </programlisting>      
   </para>
  </refsect1>
@@ -197,10 +244,9 @@ DELETE FROM films;
   <title>Compatibility</title>
 
   <para>
-   This command conforms to the SQL standard, except that the
-   <literal>USING</> clause and the ability to reference other tables
-   in the <literal>WHERE</> clause are <productname>PostgreSQL</>
-   extensions.
+   This command conforms to the <acronym>SQL</acronym> standard, except
+   that the <literal>USING</literal> and <literal>RETURNING</> clauses
+   are <productname>PostgreSQL</productname> extensions.
   </para>
  </refsect1>
 </refentry>