Add some comments about division of labor between rewriter and planner.

The rationale for the way targetlist processing is done wasn't clearly
stated anywhere, and I for one had forgotten some of the details.  Having
just painfully re-learned them, add some breadcrumbs for the next person.

diff --git a/src/backend/optimizer/prep/preptlist.c b/src/backend/optimizer/prep/preptlist.c
index 6b0c689e0c9b1ffc212b8d78a294dc2a4de30054..7b2742e950057c9ce3c3fc04c17901137c77f3ba 100644 (file)
--- a/src/backend/optimizer/prep/preptlist.c
+++ b/src/backend/optimizer/prep/preptlist.c
@@ -9,9 +9,22 @@
  * list and row ID information needed for SELECT FOR UPDATE locking and/or
  * EvalPlanQual checking.
  *
- * NOTE: the rewriter's rewriteTargetListIU and rewriteTargetListUD
- * routines also do preprocessing of the targetlist.  The division of labor
- * between here and there is a bit arbitrary and historical.
+ * The rewriter's rewriteTargetListIU and rewriteTargetListUD routines
+ * also do preprocessing of the targetlist.  The division of labor between
+ * here and there is partially historical, but it's not entirely arbitrary.
+ * In particular, consider an UPDATE across an inheritance tree.  What the
+ * rewriter does need be done only once (because it depends only on the
+ * properties of the parent relation).  What's done here has to be done over
+ * again for each child relation, because it depends on the column list of
+ * the child, which might have more columns and/or a different column order
+ * than the parent.
+ *
+ * The fact that rewriteTargetListIU sorts non-resjunk tlist entries by column
+ * position, which expand_targetlist depends on, violates the above comment
+ * because the sorting is only valid for the parent relation.  In inherited
+ * UPDATE cases, adjust_inherited_tlist runs in between to take care of fixing
+ * the tlists for child tables to keep expand_targetlist happy.  We do it like
+ * that because it's faster in typical non-inherited cases.
  *
  *
  * Portions Copyright (c) 1996-2015, PostgreSQL Global Development Group