Node Infrastructure

node-infrastructure — the Node type system

PG uses a tagged union pattern for every intermediate representation: parse tree, query tree, plan tree, execution state. Each node is a struct starting with NodeTag type; (an enum value); code that operates on trees switches on type to dispatch.

This is what enables expression_tree_walker and expression_tree_mutator to traverse and transform trees generically — they use the tag to look up per-node behavior.

The file map

The T_ enum

NodeTag is a big enum:

typedef enum NodeTag {
    T_Invalid = 0,
    T_IndexInfo,
    T_ExprContext,
    T_Query,
    T_RangeTblEntry,
    T_TargetEntry,
    T_Var,
    T_Const,
    T_Param,
    ...
    T_SeqScan,
    T_HashJoin,
    T_Agg,
    ...
    T_SortState,
    T_HashState,
    ...
    T_XxxStmt,
} NodeTag;

Adding a new Node = adding a new enum value + a struct definition. gen_node_support.pl regenerates all the support files from the struct definitions.

The Node struct pattern

typedef struct MyNewNode {
    Node xpr;         /* MUST be first for Expr subclasses */
    /* OR */
    NodeTag type;     /* MUST be first for plain Node subclasses */

    /* fields */
    Oid    myoid;
    List  *mylist;
    /* etc */
} MyNewNode;

The first field is a discriminator. Expr-subtype nodes start with Expr xpr (which itself starts with NodeTag type), enabling the tree-walker infrastructure to know "this is an Expr" without further checks.

Generated code — what gen_node_support.pl does

For a Node struct like:

typedef struct SomeNode {
    NodeTag type;
    Node   *someChild;
    List   *someList;
    Oid    someOid;
    /* pg_node_attr(...) attributes */
} SomeNode;

gen_node_support.pl produces four function bodies:

1. Copy (in copyfuncs.c) — allocates a new SomeNode, recursively copies each field.
2. Equal (in equalfuncs.c) — recursively compares each field.
3. Out (in outfuncs.c) — writes {SOMENODE :someChild ... :someList ... :someOid ...} text.
4. Read (in readfuncs.c) — parses that text back.

You edit the header; the perl script regenerates everything. NEVER hand-edit the generated files.

pg_node_attr attributes

Special annotations on Node fields:

• pg_node_attr(equal_ignore) — field skipped in equal(). Useful for cached data.
• pg_node_attr(read_write_ignore) — field skipped in out/read. Useful for pointers to non-serializable state.
• pg_node_attr(copy_as_scalar) — for opaque fields (function pointers, etc.).
• pg_node_attr(no_read) — no read support (only in one direction).

Tree walkers + mutators

The pattern for tree traversal:

static bool my_walker(Node *node, MyContext *ctx) {
    if (node == NULL) return false;

    /* Check for the specific node types you care about */
    if (IsA(node, Var)) {
        /* Do something with the Var */
    }

    /* Recurse into children */
    return expression_tree_walker(node, my_walker, ctx);
}

/* Call it */
my_walker((Node *) query, &ctx);

expression_tree_walker knows how to descend into every Node type — that's the payoff of the tagged-union design.

Mutators are similar but return a transformed tree.

Common patch shapes

Add a new Node type

Scenario add-new-node-type covers this end-to-end. Sequence:

1. Add T_MyNewNode to the appropriate section of nodes.h (parsenodes / primnodes / plannodes).
2. Add the struct definition to that header.
3. Run make — the perl script regenerates copyfuncs/equalfuncs/outfuncs/readfuncs.
4. Wire the new node into whatever hook produces it (parser production, planner rewrite, etc.).
5. Update walkers/mutators if the new node has children that need traversal.
6. Add IsA uses at consumer sites.
7. Regress test.

Change a Node struct field

• Add / rename / remove fields in the header.
• Run make — regenerated code adapts.
• Update every hand-written consumer using the field.

Add a walker case

• Simple: expression_tree_walker handles it automatically if the new node's children are in known-walker fields.
• Complex: for uncommon child-field patterns (e.g. List of custom-struct), extend the walker in nodeFuncs.c.

Debug "castNode returned NULL"

• castNode(SomeType, node) uses IsA — check node->type == T_SomeType.
• If NULL: the Node is a different type than you expected. Check upstream production.
• nodeTag(node) shows the actual tag.

Pitfalls

• NEVER hand-edit generated files — copyfuncs/equalfuncs/outfuncs/readfuncs are regenerated by gen_node_support.pl. Hand edits get overwritten.
• memcpy a Node = wrong — use copyObject for deep copy. memcpy shares child pointers, then double-frees.
• Adding a Node without walker support — if you don't extend the walker for a new node's children, tree traversal won't descend. Bugs surface as "planner sees only some Vars, not all".
• equal_ignore on functional-difference fields = subtle bugs — the equality check is used in cached-plan invalidation, hashing, etc. Ignoring a field that DOES matter for behavior breaks these.
• readfuncs.c version-guarding — a Node struct changed between PG versions means old serialized plans (e.g. in a plan cache before upgrade) may fail to deserialize. Plan cache reset on major-version upgrade.
• Node ordering matters for T_ enum — enums are dense but sections have historical meaning (parsenodes / primnodes / plannodes are grouped). Don't scatter.
• NodeTag reuse after deletion is impossible — a T_ enum value assigned to a removed node CAN'T be reused for a new one, because stored plans might have that tag. Always add new tags at the end of their section.
• Extensions can register Node types via T_ExtensibleNode — for custom-scan private data + others. Uses RegisterExtensibleNodeMethods.

Related corpus

• Idiom: node-types-and-lists, node-types (Node shapes — parse tree vs Expr).
• Scenario: add-new-node-type — the definitive patch guide.
• Subsystem: parser-and-rewrite (parse-tree production), optimizer (Plan production), executor (PlanState production).
• Related planning: planning/pgstat_progress_leak/ — not directly, but plan-cache bugs often surface through Node serialization.

Corpus-chain shortcut

python3 scripts/corpus-chain.py --scenario add-new-node-type
python3 scripts/corpus-chain.py --file src/backend/nodes/nodeFuncs.c
python3 scripts/corpus-chain.py --idiom node-types-and-lists

Boundary

Use this skill for Node type-system + gen_node_support.pl + copy/equal/out/read + walker/mutator.

Don't use for:

• Specific Node types (Var / Const / Plan subtypes) — see the type's owning subsystem.
• Grammar changes — see parser-and-nodes skill.
• Executor state changes — see executor-and-planner.
• Reading .h files that mention pg_node_attr — the attribute is meaningful only to gen_node_support.pl; consumers ignore it.