A line like SELECT name FROM users WHERE id = 1 is just text when the client sends it. The first thing the backend does after receiving it is figure out "what do these characters mean." This chapter covers the second of the five stages we saw in 1.1.1: the parser and analyzer.
By the time this stage finishes, the SQL text has been transformed twice. First into a raw parse tree that captures the grammatical structure, then into a Query tree with meaning attached after consulting the catalog. The catalog, in case you need a refresher, is the set of internal tables that PostgreSQL keeps to describe itself. Which tables exist, what columns they have, what argument types each function accepts, what data types are defined: all of it lives as rows in these tables. PostgreSQL treats user data and metadata uniformly, both as ordinary tables. The raw stage looks only at form (does this follow SELECT syntax, where are the IDENTs). The Query stage looks at substance (this identifier users is which table in which schema and what is its OID, id is which column and what is its type, can 1 be coerced to that column's type).
1.2 splits into three sections.
- 1.2.1 From SQL text to raw parse tree (lexer, grammar): how the flex-based lexer and Bison-based grammar turn an SQL string into a tree. This stage is pure syntactic work, no catalog access.
- 1.2.2 Semantic analysis: name resolution, type checking, catalog lookup: take the raw parse tree, dig into the catalog to find what each identifier really refers to, check types, resolve function overloads. This is the body of how PostgreSQL gives meaning to SQL text.
- 1.2.3 Query tree node types (Query, RangeTblEntry, TargetEntry): the core nodes of the Query tree, which is the output of semantic analysis. This node structure is the standard input format that rewriter, planner, and executor all consume.
By the end of this chapter, you should have a clear picture of how SQL text meets the catalog and acquires meaning, and what data structures carry that meaning into the next stage.
