Allow EXCLUDED in RETURNING list of INSERT ON CONFLICT DO UPDATE.

This allows an INSERT ... ON CONFLICT DO UPDATE command to return the
excluded values, when conflicts occur. For rows that do not conflict,
the excluded values returned are NULL.

This builds on the infrastructure added to support OLD/NEW values in
the RETURNING list, except that in the case of EXCLUDED, there is no
need for the special syntax to change the name of the excluded
pseudo-relation in the RETURNING list. (That was required for OLD/NEW,
because those names were already used in some situations, such as
trigger functions, but there is no such problem with excluded.)

Discussion: https://postgr.es/m/CAEZATCXXu2ohYmn=4YrRQa9yNwD_fdEEOTBPgM_5jhQOFcaQ4g@mail.gmail.com

Author: deanrasheed

doc/src/sgml/dml.sgml

@@ -392,6 +392,19 @@ UPDATE products SET price = price * 1.10
    the new values may be non-<literal>NULL</literal>.
   </para>
 
+  <para>
+   In an <command>INSERT</command> with an <literal>ON CONFLICT DO UPDATE</literal>
+   clause, it is also possible to return the values excluded, if there is a
+   conflict.  For example:
+<programlisting>
+INSERT INTO products AS p SELECT * FROM new_products
+  ON CONFLICT (product_no) DO UPDATE SET name = excluded.name
+  RETURNING p.product_no, p.name, excluded.price;
+</programlisting>
+   Excluded values will be <literal>NULL</literal> for rows that do not
+   conflict.
+  </para>
+
   <para>
    If there are triggers (<xref linkend="triggers"/>) on the target table,
    the data available to <literal>RETURNING</literal> is the row as modified by

doc/src/sgml/ref/insert.sgml

@@ -183,7 +183,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
         This is particularly useful when <literal>ON CONFLICT DO UPDATE</literal>
         targets a table named <varname>excluded</varname>, since that will otherwise
         be taken as the name of the special table representing the row proposed
-        for insertion.
+        for insertion (see note below).
        </para>
       </listitem>
      </varlistentry>
@@ -343,6 +343,35 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
         with an <literal>ON CONFLICT DO UPDATE</literal> clause, the old
         values may be non-<literal>NULL</literal>.
        </para>
+
+       <para>
+        If the <command>INSERT</command> has an <literal>ON CONFLICT DO
+        UPDATE</literal> clause, a column name or <literal>*</literal> may be
+        qualified using <literal>EXCLUDED</literal> to return the values
+        excluded from insertion, in the event of a conflict.  If there is no
+        conflict, then all excluded values will be <literal>NULL</literal>.
+       </para>
+
+       <note>
+        <para>
+         The special <varname>excluded</varname> table is made available
+         whenever an <command>INSERT</command> has an <literal>ON CONFLICT DO
+         UPDATE</literal> clause.  It has the same columns as the target
+         table, and in the event of a conflict, it is populated with the
+         values that would have been inserted.  This includes any values that
+         were supplied by defaults, as well as the effects of any per-row
+         <literal>BEFORE INSERT</literal> triggers, since those may have
+         contributed to the row being excluded from insertion.
+        </para>
+        <para>
+         The <varname>excluded</varname> table is accessible from the
+         <literal>SET</literal> and <literal>WHERE</literal> clauses of the
+         <literal>ON CONFLICT DO UPDATE</literal> action, and the
+         <literal>RETURNING</literal> list.  <literal>SELECT</literal>
+         privilege is required on any columns in the target table where the
+         corresponding <varname>excluded</varname> columns are read.
+        </para>
+       </note>
       </listitem>
      </varlistentry>
 
@@ -440,16 +469,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
         <literal>WHERE</literal> clauses in <literal>ON CONFLICT DO
         UPDATE</literal> have access to the existing row using the
         table's name (or an alias), and to the row proposed for insertion
-        using the special <varname>excluded</varname> table.
-        <literal>SELECT</literal> privilege is required on any column in the
-        target table where corresponding <varname>excluded</varname>
-        columns are read.
-       </para>
-       <para>
-        Note that the effects of all per-row <literal>BEFORE
-        INSERT</literal> triggers are reflected in
-        <varname>excluded</varname> values, since those effects may
-        have contributed to the row being excluded from insertion.
+        using the special <varname>excluded</varname> table (see note above).
        </para>
       </listitem>
      </varlistentry>

src/backend/executor/execExpr.c

@@ -455,6 +455,7 @@ ExecBuildProjectionInfo(List *targetList,
 					/*
 					 * Get the tuple from the relation being scanned, or the
 					 * old/new tuple slot, if old/new values were requested.
+					 * Should not see EXCLUDED here (should be INNER_VAR).
 					 */
 					switch (variable->varreturningtype)
 					{
@@ -469,6 +470,10 @@ ExecBuildProjectionInfo(List *targetList,
 							scratch.opcode = EEOP_ASSIGN_NEW_VAR;
 							state->flags |= EEO_FLAG_HAS_NEW;
 							break;
+						case VAR_RETURNING_EXCLUDED:
+							elog(ERROR, "wrong varno %d (expected %d) for variable returning excluded",
+								 variable->varno, INNER_VAR);
+							break;
 					}
 					break;
 			}
@@ -972,6 +977,10 @@ ExecInitExprRec(Expr *node, ExprState *state,
 									scratch.opcode = EEOP_NEW_SYSVAR;
 									state->flags |= EEO_FLAG_HAS_NEW;
 									break;
+								case VAR_RETURNING_EXCLUDED:
+									elog(ERROR, "wrong varno %d (expected %d) for variable returning excluded",
+										 variable->varno, INNER_VAR);
+									break;
 							}
 							break;
 					}
@@ -1007,6 +1016,10 @@ ExecInitExprRec(Expr *node, ExprState *state,
 									scratch.opcode = EEOP_NEW_VAR;
 									state->flags |= EEO_FLAG_HAS_NEW;
 									break;
+								case VAR_RETURNING_EXCLUDED:
+									elog(ERROR, "wrong varno %d (expected %d) for variable returning excluded",
+										 variable->varno, INNER_VAR);
+									break;
 							}
 							break;
 					}
@@ -2638,25 +2651,39 @@ ExecInitExprRec(Expr *node, ExprState *state,
 				ReturningExpr *rexpr = (ReturningExpr *) node;
 				int			retstep;
 
-				/* Skip expression evaluation if OLD/NEW row doesn't exist */
+				/*
+				 * Skip expression evaluation if OLD/NEW/EXCLUDED row doesn't
+				 * exist.
+				 */
 				scratch.opcode = EEOP_RETURNINGEXPR;
-				scratch.d.returningexpr.nullflag = rexpr->retold ?
-					EEO_FLAG_OLD_IS_NULL : EEO_FLAG_NEW_IS_NULL;
+				switch (rexpr->retkind)
+				{
+					case RETURNING_OLD_EXPR:
+						scratch.d.returningexpr.nullflag = EEO_FLAG_OLD_IS_NULL;
+						break;
+					case RETURNING_NEW_EXPR:
+						scratch.d.returningexpr.nullflag = EEO_FLAG_NEW_IS_NULL;
+						break;
+					case RETURNING_EXCLUDED_EXPR:
+						scratch.d.returningexpr.nullflag = EEO_FLAG_INNER_IS_NULL;
+						break;
+				}
 				scratch.d.returningexpr.jumpdone = -1;	/* set below */
 				ExprEvalPushStep(state, &scratch);
 				retstep = state->steps_len - 1;
 
 				/* Steps to evaluate expression to return */
 				ExecInitExprRec(rexpr->retexpr, state, resv, resnull);
 
-				/* Jump target used if OLD/NEW row doesn't exist */
+				/* Jump target used if OLD/NEW/EXCLUDED row doesn't exist */
 				state->steps[retstep].d.returningexpr.jumpdone = state->steps_len;
 
 				/* Update ExprState flags */
-				if (rexpr->retold)
+				if (rexpr->retkind == RETURNING_OLD_EXPR)
 					state->flags |= EEO_FLAG_HAS_OLD;
-				else
+				else if (rexpr->retkind == RETURNING_NEW_EXPR)
 					state->flags |= EEO_FLAG_HAS_NEW;
+				/* we don't bother recording references to EXCLUDED */
 
 				break;
 			}
@@ -3013,6 +3040,10 @@ expr_setup_walker(Node *node, ExprSetupInfo *info)
 					case VAR_RETURNING_NEW:
 						info->last_new = Max(info->last_new, attnum);
 						break;
+					case VAR_RETURNING_EXCLUDED:
+						elog(ERROR, "wrong varno %d (expected %d) for variable returning excluded",
+							 variable->varno, INNER_VAR);
+						break;
 				}
 				break;
 		}
@@ -3178,6 +3209,7 @@ ExecInitWholeRowVar(ExprEvalStep *scratch, Var *variable, ExprState *state)
 		state->flags |= EEO_FLAG_HAS_OLD;
 	else if (variable->varreturningtype == VAR_RETURNING_NEW)
 		state->flags |= EEO_FLAG_HAS_NEW;
+	/* we don't bother recording references to EXCLUDED */
 
 	/*
 	 * If the input tuple came from a subquery, it might contain "resjunk"

src/backend/executor/execExprInterp.c

@@ -5339,7 +5339,21 @@ ExecEvalWholeRowVar(ExprState *state, ExprEvalStep *op, ExprContext *econtext)
 	switch (variable->varno)
 	{
 		case INNER_VAR:
-			/* get the tuple from the inner node */
+
+			/*
+			 * Get the tuple from the inner node.
+			 *
+			 * In a RETURNING expression, this is used for EXCLUDED values in
+			 * an INSERT ... ON CONFLICT DO UPDATE.  If the non-conflicting
+			 * branch is taken, the EXCLUDED row is NULL, and we return NULL
+			 * rather than an all-NULL record.
+			 */
+			if (state->flags & EEO_FLAG_INNER_IS_NULL)
+			{
+				*op->resvalue = (Datum) 0;
+				*op->resnull = true;
+				return;
+			}
 			slot = econtext->ecxt_innertuple;
 			break;
 
@@ -5384,6 +5398,11 @@ ExecEvalWholeRowVar(ExprState *state, ExprEvalStep *op, ExprContext *econtext)
 					}
 					slot = econtext->ecxt_newtuple;
 					break;
+
+				case VAR_RETURNING_EXCLUDED:
+					elog(ERROR, "wrong varno %d (expected %d) for variable returning excluded",
+						 variable->varno, INNER_VAR);
+					break;
 			}
 			break;
 	}

src/backend/executor/execPartition.c

@@ -642,12 +642,26 @@ ExecInitPartitionInfo(ModifyTableState *mtstate, EState *estate,
 
 		/*
 		 * Convert Vars in it to contain this partition's attribute numbers.
+		 * If we're doing an INSERT ... ON CONFLICT DO UPDATE, the RETURNING
+		 * list might contain references to the EXCLUDED pseudo-relation
+		 * (INNER_VAR), so we must map their attribute numbers too.
 		 */
 		if (part_attmap == NULL)
 			part_attmap =
 				build_attrmap_by_name(RelationGetDescr(partrel),
 									  RelationGetDescr(firstResultRel),
 									  false);
+
+		if (node->onConflictAction == ONCONFLICT_UPDATE)
+		{
+			returningList = (List *)
+				map_variable_attnos((Node *) returningList,
+									INNER_VAR, 0,
+									part_attmap,
+									RelationGetForm(partrel)->reltype,
+									&found_whole_row);
+			/* We ignore the value of found_whole_row. */
+		}
 		returningList = (List *)
 			map_variable_attnos((Node *) returningList,
 								firstVarno, 0,