Improve C comments about backend variables set by pg_upgrade_support

functions.

contrib/pg_upgrade/pg_upgrade.c

@@ -7,6 +7,28 @@
  *	contrib/pg_upgrade/pg_upgrade.c
  */
 
+/*
+ *	To simplify the upgrade process, we force certain system items to be
+ *	consistent between old and new clusters:
+ *
+ *	We control all assignments of pg_class.relfilenode so we can keep the
+ *	same relfilenodes for old and new files.  The only exception is
+ *	pg_largeobject, pg_largeobject_metadata, and its indexes, which can
+ *	change due to a cluster, reindex, or vacuum full.  (We don't create
+ *	those so have no control over their oid/relfilenode values.)
+ *
+ *	While pg_class.oid and pg_class.relfilenode are intially the same, they
+ *	can diverge due to cluster, reindex, or vacuum full.  The new cluster
+ *	will again have matching pg_class.relfilenode and pg_class.oid values,
+ *	but based on the new relfilenode value, so the old/new oids might
+ *	differ.
+ *
+ *	We control all assignments of pg_type.oid because these are stored
+ *	in composite types.
+ */
+
+
+ 
 #include "pg_upgrade.h"
 
 #ifdef HAVE_LANGINFO_H

src/backend/catalog/heap.c

@@ -73,7 +73,7 @@
 #include "utils/tqual.h"
 
 
-/* Kluge for upgrade-in-place support */
+/* Potentially set by contrib/pg_upgrade_support functions */
 Oid			binary_upgrade_next_heap_relfilenode = InvalidOid;
 Oid			binary_upgrade_next_toast_relfilenode = InvalidOid;
 
@@ -986,7 +986,10 @@ heap_create_with_catalog(const char *relname,
 	 */
 	if (!OidIsValid(relid))
 	{
-		/* Use binary-upgrade overrides if applicable */
+		/*
+		 *	Use binary-upgrade override for pg_class.relfilenode/oid,
+		 *	if supplied.
+		 */
 		if (OidIsValid(binary_upgrade_next_heap_relfilenode) &&
 			(relkind == RELKIND_RELATION || relkind == RELKIND_SEQUENCE ||
 			 relkind == RELKIND_VIEW || relkind == RELKIND_COMPOSITE_TYPE ||

src/backend/catalog/index.c

@@ -68,7 +68,7 @@
 #include "utils/tqual.h"
 
 
-/* Kluge for upgrade-in-place support */
+/* Potentially set by contrib/pg_upgrade_support functions */
 Oid			binary_upgrade_next_index_relfilenode = InvalidOid;
 
 /* state info for validate_index bulkdelete callback */
@@ -640,7 +640,10 @@ index_create(Oid heapRelationId,
 	 */
 	if (!OidIsValid(indexRelationId))
 	{
-		/* Use binary-upgrade override if applicable */
+		/*
+		 *	Use binary-upgrade override for pg_class.relfilenode/oid,
+		 *	if supplied.
+		 */
 		if (OidIsValid(binary_upgrade_next_index_relfilenode))
 		{
 			indexRelationId = binary_upgrade_next_index_relfilenode;

src/backend/catalog/pg_enum.c

@@ -28,6 +28,7 @@
 #include "utils/tqual.h"
 
 
+/* Potentially set by contrib/pg_upgrade_support functions */
 Oid      binary_upgrade_next_pg_enum_oid = InvalidOid;
 
 static void RenumberEnumType(Relation pg_enum, HeapTuple *existing, int nelems);
@@ -313,9 +314,9 @@ restart:
 	if (OidIsValid(binary_upgrade_next_pg_enum_oid))
 	{
 		/*
-		 * In binary upgrades, just add the new label with the predetermined
-		 * Oid.  It's pg_upgrade's responsibility that the Oid meets
-		 * requirements.
+		 *	Use binary-upgrade override for pg_enum.oid, if supplied.
+		 *	During binary upgrade, all pg_enum.oid's are set this way
+		 *	so they are guaranteed to be consistent.
 		 */
 		if (neighbor != NULL)
 			ereport(ERROR,

src/backend/catalog/pg_type.c

@@ -33,6 +33,7 @@
 #include "utils/rel.h"
 #include "utils/syscache.h"
 
+/* Potentially set by contrib/pg_upgrade_support functions */
 Oid			binary_upgrade_next_pg_type_oid = InvalidOid;
 
 /* ----------------------------------------------------------------
@@ -121,6 +122,7 @@ TypeShellMake(const char *typeName, Oid typeNamespace, Oid ownerId)
 	 */
 	tup = heap_form_tuple(tupDesc, values, nulls);
 
+	/* Use binary-upgrade override for pg_type.oid, if supplied. */
 	if (OidIsValid(binary_upgrade_next_pg_type_oid))
 	{
 		HeapTupleSetOid(tup, binary_upgrade_next_pg_type_oid);
@@ -422,6 +424,7 @@ TypeCreate(Oid newTypeOid,
 		/* Force the OID if requested by caller */
 		if (OidIsValid(newTypeOid))
 			HeapTupleSetOid(tup, newTypeOid);
+		/* Use binary-upgrade override for pg_type.oid, if supplied. */
 		else if (OidIsValid(binary_upgrade_next_pg_type_oid))
 		{
 			HeapTupleSetOid(tup, binary_upgrade_next_pg_type_oid);

src/backend/catalog/toasting.c

@@ -31,7 +31,7 @@
 #include "utils/builtins.h"
 #include "utils/syscache.h"
 
-/* Kluges for upgrade-in-place support */
+/* Potentially set by contrib/pg_upgrade_support functions */
 extern Oid	binary_upgrade_next_toast_relfilenode;
 
 Oid			binary_upgrade_next_pg_type_toast_oid = InvalidOid;
@@ -200,6 +200,7 @@ create_toast_table(Relation rel, Oid toastOid, Oid toastIndexOid, Datum reloptio
 	else
 		namespaceid = PG_TOAST_NAMESPACE;
 
+	/* Use binary-upgrade override for pg_type.oid, if supplied. */
 	if (OidIsValid(binary_upgrade_next_pg_type_toast_oid))
 	{
 		toast_typid = binary_upgrade_next_pg_type_toast_oid;

src/backend/commands/typecmds.c

@@ -74,6 +74,7 @@ typedef struct
 	/* atts[] is of allocated length RelationGetNumberOfAttributes(rel) */
 } RelToCheck;
 
+/* Potentially set by contrib/pg_upgrade_support functions */
 Oid			binary_upgrade_next_pg_type_array_oid = InvalidOid;
 
 static Oid	findTypeInputFunction(List *procname, Oid typeOid);
@@ -1517,7 +1518,7 @@ AssignTypeArrayOid(void)
 {
 	Oid			type_array_oid;
 
-	/* Pre-assign the type's array OID for use in pg_type.typarray */
+	/* Use binary-upgrade override for pg_type.typarray, if supplied. */
 	if (OidIsValid(binary_upgrade_next_pg_type_array_oid))
 	{
 		type_array_oid = binary_upgrade_next_pg_type_array_oid;