PostgreSQL/contrib/pg_overexplain/pg_overexplain.c

/*-------------------------------------------------------------------------
 *
 * pg_overexplain.c
 *	  allow EXPLAIN to dump even more details
 *
 * Copyright (c) 2016-2025, PostgreSQL Global Development Group
 *
 *	  contrib/pg_overexplain/pg_overexplain.c
 *-------------------------------------------------------------------------
 */
#include "postgres.h"

#include "catalog/pg_class.h"
#include "commands/defrem.h"
#include "commands/explain.h"
#include "commands/explain_format.h"
#include "commands/explain_state.h"
#include "fmgr.h"
#include "parser/parsetree.h"
#include "storage/lock.h"
#include "utils/builtins.h"
#include "utils/lsyscache.h"

PG_MODULE_MAGIC_EXT(
					.name = "pg_overexplain",
					.version = PG_VERSION
);

typedef struct
{
	bool		debug;
	bool		range_table;
} overexplain_options;

static overexplain_options *overexplain_ensure_options(ExplainState *es);
static void overexplain_debug_handler(ExplainState *es, DefElem *opt,
									  ParseState *pstate);
static void overexplain_range_table_handler(ExplainState *es, DefElem *opt,
											ParseState *pstate);
static void overexplain_per_node_hook(PlanState *planstate, List *ancestors,
									  const char *relationship,
									  const char *plan_name,
									  ExplainState *es);
static void overexplain_per_plan_hook(PlannedStmt *plannedstmt,
									  IntoClause *into,
									  ExplainState *es,
									  const char *queryString,
									  ParamListInfo params,
									  QueryEnvironment *queryEnv);
static void overexplain_debug(PlannedStmt *plannedstmt, ExplainState *es);
static void overexplain_range_table(PlannedStmt *plannedstmt,
									ExplainState *es);
static void overexplain_alias(const char *qlabel, Alias *alias,
							  ExplainState *es);
static void overexplain_bitmapset(const char *qlabel, Bitmapset *bms,
								  ExplainState *es);
static void overexplain_intlist(const char *qlabel, List *list,
								ExplainState *es);

static int	es_extension_id;
static explain_per_node_hook_type prev_explain_per_node_hook;
static explain_per_plan_hook_type prev_explain_per_plan_hook;

/*
 * Initialization we do when this module is loaded.
 */
void
_PG_init(void)
{
	/* Get an ID that we can use to cache data in an ExplainState. */
	es_extension_id = GetExplainExtensionId("pg_overexplain");

	/* Register the new EXPLAIN options implemented by this module. */
	RegisterExtensionExplainOption("debug", overexplain_debug_handler);
	RegisterExtensionExplainOption("range_table",
								   overexplain_range_table_handler);

	/* Use the per-node and per-plan hooks to make our options do something. */
	prev_explain_per_node_hook = explain_per_node_hook;
	explain_per_node_hook = overexplain_per_node_hook;
	prev_explain_per_plan_hook = explain_per_plan_hook;
	explain_per_plan_hook = overexplain_per_plan_hook;
}

/*
 * Get the overexplain_options structure from an ExplainState; if there is
 * none, create one, attach it to the ExplainState, and return it.
 */
static overexplain_options *
overexplain_ensure_options(ExplainState *es)
{
	overexplain_options *options;

	options = GetExplainExtensionState(es, es_extension_id);

	if (options == NULL)
	{
		options = palloc0(sizeof(overexplain_options));
		SetExplainExtensionState(es, es_extension_id, options);
	}

	return options;
}

/*
 * Parse handler for EXPLAIN (DEBUG).
 */
static void
overexplain_debug_handler(ExplainState *es, DefElem *opt, ParseState *pstate)
{
	overexplain_options *options = overexplain_ensure_options(es);

	options->debug = defGetBoolean(opt);
}

/*
 * Parse handler for EXPLAIN (RANGE_TABLE).
 */
static void
overexplain_range_table_handler(ExplainState *es, DefElem *opt,
								ParseState *pstate)
{
	overexplain_options *options = overexplain_ensure_options(es);

	options->range_table = defGetBoolean(opt);
}

/*
 * Print out additional per-node information as appropriate. If the user didn't
 * specify any of the options we support, do nothing; else, print whatever is
 * relevant to the specified options.
 */
static void
overexplain_per_node_hook(PlanState *planstate, List *ancestors,
						  const char *relationship, const char *plan_name,
						  ExplainState *es)
{
	overexplain_options *options;
	Plan	   *plan = planstate->plan;

	if (prev_explain_per_node_hook)
		(*prev_explain_per_node_hook) (planstate, ancestors, relationship,
									   plan_name, es);

	options = GetExplainExtensionState(es, es_extension_id);
	if (options == NULL)
		return;

	/*
	 * If the "debug" option was given, display miscellaneous fields from the
	 * "Plan" node that would not otherwise be displayed.
	 */
	if (options->debug)
	{
		/*
		 * Normal EXPLAIN will display "Disabled: true" if the node is
		 * disabled; but that is based on noticing that plan->disabled_nodes
		 * is higher than the sum of its children; here, we display the raw
		 * value, for debugging purposes.
		 */
		ExplainPropertyInteger("Disabled Nodes", NULL, plan->disabled_nodes,
							   es);

		/*
		 * Normal EXPLAIN will display the parallel_aware flag; here, we show
		 * the parallel_safe flag as well.
		 */
		ExplainPropertyBool("Parallel Safe", plan->parallel_safe, es);

		/*
		 * The plan node ID isn't normally displayed, since it is only useful
		 * for debugging.
		 */
		ExplainPropertyInteger("Plan Node ID", NULL, plan->plan_node_id, es);

		/*
		 * It is difficult to explain what extParam and allParam mean in plain
		 * language, so we simply display these fields labelled with the
		 * structure member name. For compactness, the text format omits the
		 * display of this information when the bitmapset is empty.
		 */
		if (es->format != EXPLAIN_FORMAT_TEXT || !bms_is_empty(plan->extParam))
			overexplain_bitmapset("extParam", plan->extParam, es);
		if (es->format != EXPLAIN_FORMAT_TEXT || !bms_is_empty(plan->allParam))
			overexplain_bitmapset("allParam", plan->allParam, es);
	}

	/*
	 * If the "range_table" option was specified, display information about
	 * the range table indexes for this node.
	 */
	if (options->range_table)
	{
		switch (nodeTag(plan))
		{
			case T_SeqScan:
			case T_SampleScan:
			case T_IndexScan:
			case T_IndexOnlyScan:
			case T_BitmapHeapScan:
			case T_TidScan:
			case T_TidRangeScan:
			case T_SubqueryScan:
			case T_FunctionScan:
			case T_TableFuncScan:
			case T_ValuesScan:
			case T_CteScan:
			case T_NamedTuplestoreScan:
			case T_WorkTableScan:
				ExplainPropertyInteger("Scan RTI", NULL,
									   ((Scan *) plan)->scanrelid, es);
				break;
			case T_ForeignScan:
				overexplain_bitmapset("Scan RTIs",
									  ((ForeignScan *) plan)->fs_base_relids,
									  es);
				break;
			case T_CustomScan:
				overexplain_bitmapset("Scan RTIs",
									  ((CustomScan *) plan)->custom_relids,
									  es);
				break;
			case T_ModifyTable:
				ExplainPropertyInteger("Nominal RTI", NULL,
									   ((ModifyTable *) plan)->nominalRelation, es);
				ExplainPropertyInteger("Exclude Relation RTI", NULL,
									   ((ModifyTable *) plan)->exclRelRTI, es);
				break;
			case T_Append:
				overexplain_bitmapset("Append RTIs",
									  ((Append *) plan)->apprelids,
									  es);
				break;
			case T_MergeAppend:
				overexplain_bitmapset("Append RTIs",
									  ((MergeAppend *) plan)->apprelids,
									  es);
				break;
			default:
				break;
		}
	}
}

/*
 * Print out additional per-query information as appropriate. Here again, if
 * the user didn't specify any of the options implemented by this module, do
 * nothing; otherwise, call the appropriate function for each specified
 * option.
 */
static void
overexplain_per_plan_hook(PlannedStmt *plannedstmt,
						  IntoClause *into,
						  ExplainState *es,
						  const char *queryString,
						  ParamListInfo params,
						  QueryEnvironment *queryEnv)
{
	overexplain_options *options;

	if (prev_explain_per_plan_hook)
		(*prev_explain_per_plan_hook) (plannedstmt, into, es, queryString,
									   params, queryEnv);

	options = GetExplainExtensionState(es, es_extension_id);
	if (options == NULL)
		return;

	if (options->debug)
		overexplain_debug(plannedstmt, es);

	if (options->range_table)
		overexplain_range_table(plannedstmt, es);
}

/*
 * Print out various details from the PlannedStmt that wouldn't otherwise
 * be displayed.
 *
 * We don't try to print everything here. Information that would be displayed
 * anyway doesn't need to be printed again here, and things with lots of
 * substructure probably should be printed via separate options, or not at all.
 */
static void
overexplain_debug(PlannedStmt *plannedstmt, ExplainState *es)
{
	char	   *commandType = NULL;
	StringInfoData flags;

	/* Even in text mode, we want to set this output apart as its own group. */
	ExplainOpenGroup("PlannedStmt", "PlannedStmt", true, es);
	if (es->format == EXPLAIN_FORMAT_TEXT)
	{
		ExplainIndentText(es);
		appendStringInfoString(es->str, "PlannedStmt:\n");
		es->indent++;
	}

	/* Print the command type. */
	switch (plannedstmt->commandType)
	{
		case CMD_UNKNOWN:
			commandType = "unknown";
			break;
		case CMD_SELECT:
			commandType = "select";
			break;
		case CMD_UPDATE:
			commandType = "update";
			break;
		case CMD_INSERT:
			commandType = "insert";
			break;
		case CMD_DELETE:
			commandType = "delete";
			break;
		case CMD_MERGE:
			commandType = "merge";
			break;
		case CMD_UTILITY:
			commandType = "utility";
			break;
		case CMD_NOTHING:
			commandType = "nothing";
			break;
	}
	ExplainPropertyText("Command Type", commandType, es);

	/* Print various properties as a comma-separated list of flags. */
	initStringInfo(&flags);
	if (plannedstmt->hasReturning)
		appendStringInfoString(&flags, ", hasReturning");
	if (plannedstmt->hasModifyingCTE)
		appendStringInfoString(&flags, ", hasModifyingCTE");
	if (plannedstmt->canSetTag)
		appendStringInfoString(&flags, ", canSetTag");
	if (plannedstmt->transientPlan)
		appendStringInfoString(&flags, ", transientPlan");
	if (plannedstmt->dependsOnRole)
		appendStringInfoString(&flags, ", dependsOnRole");
	if (plannedstmt->parallelModeNeeded)
		appendStringInfoString(&flags, ", parallelModeNeeded");
	if (flags.len == 0)
		appendStringInfoString(&flags, ", none");
	ExplainPropertyText("Flags", flags.data + 2, es);

	/* Various lists of integers. */
	overexplain_bitmapset("Subplans Needing Rewind",
						  plannedstmt->rewindPlanIDs, es);
	overexplain_intlist("Relation OIDs",
						plannedstmt->relationOids, es);
	overexplain_intlist("Executor Parameter Types",
						plannedstmt->paramExecTypes, es);

	/*
	 * Print the statement location. (If desired, we could alternatively print
	 * stmt_location and stmt_len as two separate fields.)
	 */
	if (plannedstmt->stmt_location == -1)
		ExplainPropertyText("Parse Location", "Unknown", es);
	else if (plannedstmt->stmt_len == 0)
		ExplainPropertyText("Parse Location",
							psprintf("%d to end", plannedstmt->stmt_location),
							es);
	else
		ExplainPropertyText("Parse Location",
							psprintf("%d for %d bytes",
									 plannedstmt->stmt_location,
									 plannedstmt->stmt_len),
							es);

	/* Done with this group. */
	if (es->format == EXPLAIN_FORMAT_TEXT)
		es->indent--;
	ExplainCloseGroup("PlannedStmt", "PlannedStmt", true, es);
}

/*
 * Provide detailed information about the contents of the PlannedStmt's
 * range table.
 */
static void
overexplain_range_table(PlannedStmt *plannedstmt, ExplainState *es)
{
	Index		rti;

	/* Open group, one entry per RangeTblEntry */
	ExplainOpenGroup("Range Table", "Range Table", false, es);

	/* Iterate over the range table */
	for (rti = 1; rti <= list_length(plannedstmt->rtable); ++rti)
	{
		RangeTblEntry *rte = rt_fetch(rti, plannedstmt->rtable);
		char	   *kind = NULL;
		char	   *relkind;

		/* NULL entries are possible; skip them */
		if (rte == NULL)
			continue;

		/* Translate rtekind to a string */
		switch (rte->rtekind)
		{
			case RTE_RELATION:
				kind = "relation";
				break;
			case RTE_SUBQUERY:
				kind = "subquery";
				break;
			case RTE_JOIN:
				kind = "join";
				break;
			case RTE_FUNCTION:
				kind = "function";
				break;
			case RTE_TABLEFUNC:
				kind = "tablefunc";
				break;
			case RTE_VALUES:
				kind = "values";
				break;
			case RTE_CTE:
				kind = "cte";
				break;
			case RTE_NAMEDTUPLESTORE:
				kind = "namedtuplestore";
				break;
			case RTE_RESULT:
				kind = "result";
				break;
			case RTE_GROUP:
				kind = "group";
				break;
		}

		/* Begin group for this specific RTE */
		ExplainOpenGroup("Range Table Entry", NULL, true, es);

		/*
		 * In text format, the summary line displays the range table index and
		 * rtekind, plus indications if rte->inh and/or rte->inFromCl are set.
		 * In other formats, we display those as separate properties.
		 */
		if (es->format == EXPLAIN_FORMAT_TEXT)
		{
			ExplainIndentText(es);
			appendStringInfo(es->str, "RTI %u (%s%s%s):\n", rti, kind,
							 rte->inh ? ", inherited" : "",
							 rte->inFromCl ? ", in-from-clause" : "");
			es->indent++;
		}
		else
		{
			ExplainPropertyUInteger("RTI", NULL, rti, es);
			ExplainPropertyText("Kind", kind, es);
			ExplainPropertyBool("Inherited", rte->inh, es);
			ExplainPropertyBool("In From Clause", rte->inFromCl, es);
		}

		/* rte->alias is optional; rte->eref is requested */
		if (rte->alias != NULL)
			overexplain_alias("Alias", rte->alias, es);
		overexplain_alias("Eref", rte->eref, es);

		/*
		 * We adhere to the usual EXPLAIN convention that schema names are
		 * displayed only in verbose mode, and we emit nothing if there is no
		 * relation OID.
		 */
		if (rte->relid != 0)
		{
			const char *relname;
			const char *qualname;

			relname = quote_identifier(get_rel_name(rte->relid));

			if (es->verbose)
			{
				Oid			nspoid = get_rel_namespace(rte->relid);
				char	   *nspname;

				nspname = get_namespace_name_or_temp(nspoid);
				qualname = psprintf("%s.%s", quote_identifier(nspname),
									relname);
			}
			else
				qualname = relname;

			ExplainPropertyText("Relation", qualname, es);
		}

		/* Translate relkind, if any, to a string */
		switch (rte->relkind)
		{
			case RELKIND_RELATION:
				relkind = "relation";
				break;
			case RELKIND_INDEX:
				relkind = "index";
				break;
			case RELKIND_SEQUENCE:
				relkind = "sequence";
				break;
			case RELKIND_TOASTVALUE:
				relkind = "toastvalue";
				break;
			case RELKIND_VIEW:
				relkind = "view";
				break;
			case RELKIND_MATVIEW:
				relkind = "matview";
				break;
			case RELKIND_COMPOSITE_TYPE:
				relkind = "composite_type";
				break;
			case RELKIND_FOREIGN_TABLE:
				relkind = "foreign_table";
				break;
			case RELKIND_PARTITIONED_TABLE:
				relkind = "partitioned_table";
				break;
			case RELKIND_PARTITIONED_INDEX:
				relkind = "partitioned_index";
				break;
			case '\0':
				relkind = NULL;
				break;
			default:
				relkind = psprintf("%c", rte->relkind);
				break;
		}

		/* If there is a relkind, show it */
		if (relkind != NULL)
			ExplainPropertyText("Relation Kind", relkind, es);

		/* If there is a lock mode, show it */
		if (rte->rellockmode != 0)
			ExplainPropertyText("Relation Lock Mode",
								GetLockmodeName(DEFAULT_LOCKMETHOD,
												rte->rellockmode), es);

		/*
		 * If there is a perminfoindex, show it. We don't try to display
		 * information from the RTEPermissionInfo node here because they are
		 * just indexes plannedstmt->permInfos which could be separately
		 * dumped if someone wants to add EXPLAIN (PERMISSIONS) or similar.
		 */
		if (rte->perminfoindex != 0)
			ExplainPropertyInteger("Permission Info Index", NULL,
								   rte->perminfoindex, es);

		/*
		 * add_rte_to_flat_rtable will clear rte->tablesample and
		 * rte->subquery in the finished plan, so skip those fields.
		 *
		 * However, the security_barrier flag is not shown by the core code,
		 * so let's print it here.
		 */
		if (es->format != EXPLAIN_FORMAT_TEXT || rte->security_barrier)
			ExplainPropertyBool("Security Barrier", rte->security_barrier, es);

		/*
		 * If this is a join, print out the fields that are specifically valid
		 * for joins.
		 */
		if (rte->rtekind == RTE_JOIN)
		{
			char	   *jointype;

			switch (rte->jointype)
			{
				case JOIN_INNER:
					jointype = "Inner";
					break;
				case JOIN_LEFT:
					jointype = "Left";
					break;
				case JOIN_FULL:
					jointype = "Full";
					break;
				case JOIN_RIGHT:
					jointype = "Right";
					break;
				case JOIN_SEMI:
					jointype = "Semi";
					break;
				case JOIN_ANTI:
					jointype = "Anti";
					break;
				case JOIN_RIGHT_SEMI:
					jointype = "Right Semi";
					break;
				case JOIN_RIGHT_ANTI:
					jointype = "Right Anti";
					break;
				default:
					jointype = "???";
					break;
			}

			/* Join type */
			ExplainPropertyText("Join Type", jointype, es);

			/* # of JOIN USING columns */
			if (es->format != EXPLAIN_FORMAT_TEXT || rte->joinmergedcols != 0)
				ExplainPropertyInteger("JOIN USING Columns", NULL,
									   rte->joinmergedcols, es);

			/*
			 * add_rte_to_flat_rtable will clear joinaliasvars, joinleftcols,
			 * joinrightcols, and join_using_alias here, so skip those fields.
			 */
		}

		/*
		 * add_rte_to_flat_rtable will clear functions, tablefunc, and
		 * values_lists, but we can display funcordinality.
		 */
		if (rte->rtekind == RTE_FUNCTION)
			ExplainPropertyBool("WITH ORDINALITY", rte->funcordinality, es);

		/*
		 * If this is a CTE, print out CTE-related properties.
		 */
		if (rte->rtekind == RTE_CTE)
		{
			ExplainPropertyText("CTE Name", rte->ctename, es);
			ExplainPropertyUInteger("CTE Levels Up", NULL, rte->ctelevelsup,
									es);
			ExplainPropertyBool("CTE Self-Reference", rte->self_reference, es);
		}

		/*
		 * add_rte_to_flat_rtable will clear coltypes, coltypmods, and
		 * colcollations, so skip those fields.
		 *
		 * If this is an ephemeral named relation, print out ENR-related
		 * properties.
		 */
		if (rte->rtekind == RTE_NAMEDTUPLESTORE)
		{
			ExplainPropertyText("ENR Name", rte->enrname, es);
			ExplainPropertyFloat("ENR Tuples", NULL, rte->enrtuples, 0, es);
		}

		/*
		 * add_rte_to_flat_rtable will clear groupexprs and securityQuals, so
		 * skip that field. We have handled inFromCl above, so the only thing
		 * left to handle here is rte->lateral.
		 */
		if (es->format != EXPLAIN_FORMAT_TEXT || rte->lateral)
			ExplainPropertyBool("Lateral", rte->lateral, es);

		/* Done with this RTE */
		if (es->format == EXPLAIN_FORMAT_TEXT)
			es->indent--;
		ExplainCloseGroup("Range Table Entry", NULL, true, es);
	}

	/* Print PlannedStmt fields that contain RTIs. */
	if (es->format != EXPLAIN_FORMAT_TEXT ||
		!bms_is_empty(plannedstmt->unprunableRelids))
		overexplain_bitmapset("Unprunable RTIs", plannedstmt->unprunableRelids,
							  es);
	if (es->format != EXPLAIN_FORMAT_TEXT ||
		plannedstmt->resultRelations != NIL)
		overexplain_intlist("Result RTIs", plannedstmt->resultRelations, es);

	/* Close group, we're all done */
	ExplainCloseGroup("Range Table", "Range Table", false, es);
}

/*
 * Emit a text property describing the contents of an Alias.
 *
 * Column lists can be quite long here, so perhaps we should have an option
 * to limit the display length by # of column or # of characters, but for
 * now, just display everything.
 */
static void
overexplain_alias(const char *qlabel, Alias *alias, ExplainState *es)
{
	StringInfoData buf;
	bool		first = true;

	Assert(alias != NULL);

	initStringInfo(&buf);
	appendStringInfo(&buf, "%s (", quote_identifier(alias->aliasname));

	foreach_node(String, cn, alias->colnames)
	{
		appendStringInfo(&buf, "%s%s",
						 first ? "" : ", ",
						 quote_identifier(cn->sval));
		first = false;
	}

	appendStringInfoChar(&buf, ')');
	ExplainPropertyText(qlabel, buf.data, es);
	pfree(buf.data);
}

/*
 * Emit a text property describing the contents of a bitmapset -- either a
 * space-separated list of integer members, or the word "none" if the bitmapset
 * is empty.
 */
static void
overexplain_bitmapset(const char *qlabel, Bitmapset *bms, ExplainState *es)
{
	int			x = -1;

	StringInfoData buf;

	if (bms_is_empty(bms))
	{
		ExplainPropertyText(qlabel, "none", es);
		return;
	}

	initStringInfo(&buf);
	while ((x = bms_next_member(bms, x)) >= 0)
		appendStringInfo(&buf, " %d", x);
	Assert(buf.data[0] == ' ');
	ExplainPropertyText(qlabel, buf.data + 1, es);
	pfree(buf.data);
}

/*
 * Emit a text property describing the contents of a list of integers, OIDs,
 * or XIDs -- either a space-separated list of integer members, or the word
 * "none" if the list is empty.
 */
static void
overexplain_intlist(const char *qlabel, List *list, ExplainState *es)
{
	StringInfoData buf;

	initStringInfo(&buf);

	if (list == NIL)
	{
		ExplainPropertyText(qlabel, "none", es);
		return;
	}

	if (IsA(list, IntList))
	{
		foreach_int(i, list)
			appendStringInfo(&buf, " %d", i);
	}
	else if (IsA(list, OidList))
	{
		foreach_oid(o, list)
			appendStringInfo(&buf, " %u", o);
	}
	else if (IsA(list, XidList))
	{
		foreach_xid(x, list)
			appendStringInfo(&buf, " %u", x);
	}
	else
	{
		appendStringInfoString(&buf, " not an integer list");
		Assert(false);
	}

	if (buf.len > 0)
		ExplainPropertyText(qlabel, buf.data + 1, es);

	pfree(buf.data);
}