Lesson 3 of 12

From SQL Text to Result: The Parse, Plan, Execute Pipeline

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

The one thing to understand first

A query string is just text. Between the moment PostgreSQL receives it and the moment a row comes back, that text passes through four distinct machines, each producing a different tree: the <a class="sev1-termlink" href="https://thesev1database.com/glossary/raw-parse-tree/" title="Raw parse tree">raw parse tree (syntax), the query tree (meaning), the plan tree (strategy), and finally the executor that walks the plan to produce rows. Knowing which stage owns which problem is what lets you debug the right thing — a syntax error, a missing table, a bad plan, or a slow execution are four different failures in four different machines.

Where the journey begins: postgres.c

Every backend runs a loop in src/backend/tcop/postgres.c. A simple query (the protocol most tools use) lands in exec_simple_query(), which drives the whole pipeline end to end. The extended protocol splits the same work across exec_parse_message(), exec_bind_message(), and exec_execute_message() — that split is what makes prepared statements and bind parameters possible, but the underlying stages are identical.

Stage 1 — Raw parsing (syntax only)

pg_parse_query() calls raw_parser(), the flex/bison front end (scan.l is the lexer, gram.y the grammar). Its output is a raw parse tree — a list of RawStmt nodes that mirror the SQL’s structure. Crucially, this stage does no catalog lookups: it does not know whether your table exists, only whether the sentence is grammatically valid. A syntax error is the only thing that can fail here.

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:

  • Stage 2 — Analysis and rewrite (meaning)
  • Stage 3 — Planning and optimization (strategy)
  • Stage 4 — Execution (do the work)
  • The side door: utility statements
  • Layer 3 — See every stage on your own database
  • Layer 4 — The levers this hands you
  • 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