Lesson 5 of 12

One Tuple at a Time: How the Volcano Executor Runs Your Plan

Applies to PostgreSQL 13–17 Last reviewed Jun 2026 Grounded in source

The one thing to understand first

Once the planner hands over a plan tree, the executor runs it with a single, elegant rule: every node knows how to return one tuple when asked, and asks its children the same way. Rows are pulled up the tree one at a time, on demand, from the top. This is the Volcano <a class="sev1-termlink" href="https://thesev1database.com/glossary/demand-pull-volcano-model/" title="Demand-pull execution (Volcano model)">iterator model, and it explains why some queries return their first row instantly while others freeze until the very end.

Three verbs per node

Every plan node becomes a runtime node (a PlanState) that responds to three operations, all in src/backend/executor/execProcnode.c:

  • ExecInitNode() — set the node up: open relations, allocate state, recursively initialise children.
  • ExecProcNode()return exactly one tuple (or an empty slot when exhausted). Calling it again returns the next tuple.
  • ExecEndNode() — tear everything down.

The top-level driver is ExecutorRun() in execMain.c, whose inner loop (ExecutePlan) just calls ExecProcNode() on the root over and over, shipping each returned tuple to the client, until it gets an empty slot. There is no master scheduler moving data around — the pull from the top is the schedule.

This is a Pro lesson

Get every Learning Pathway and cookbook recipe — grounded in PostgreSQL source code, with diagnostics, fixes, and prevention for each topic.

Continue this lesson to learn:

  • How the pull cascades
  • The crucial split: pipelined vs blocking nodes
  • A note on row-at-a-time
  • Layer 3 — See pipelined vs blocking on your own database
  • Layer 4 — The levers this hands you
  • Layer 5 — What an Oracle DBA should expect vs what they get
  • All 36 Learning Pathway lessons
  • 170+ cookbook recipes
  • Source-grounded diagnostics & fixes

Secure checkout Cancel anytime Source-grounded

Was this helpful?

← Back to 05 — The Engine Room: How PostgreSQL Actually Executes