// src/backend/parser/gram.y（简化）
stmt:
    AlterStmt | AnalyzeStmt | CreateStmt | DeleteStmt | DropStmt
    | InsertStmt | SelectStmt | UpdateStmt | ViewStmt
    | ...
;

SelectStmt:
    select_no_parens    %prec UMINUS
    | select_with_parens  %prec UMINUS
;

select_no_parens:
    simple_select
    | select_clause sort_clause
    | select_clause sort_clause limit_clause
    | ...
;

simple_select:
    SELECT opt_all_clause opt_target_list
    into_clause from_clause where_clause
    group_clause having_clause window_clause
    {
        SelectStmt *n = makeNode(SelectStmt);
        n->targetList = $3;
        n->fromClause = $5;
        n->whereClause = $6;
        n->groupClause = $7;
        n->havingClause = $8;
        n->windowClause = $9;
        $$ = (Node *)n;
    }
;
```text

对于一条 `SELECT name, salary FROM employees WHERE dept_id = 3 ORDER BY salary DESC`，语法规则归约后的节点树（简化）为：

```text
RawStmt
  └── stmt: SelectStmt
        ├── targetList: [ResTarget(name="name"), ResTarget(name="salary")]
        ├── fromClause: [RangeVar(schemaname=NULL, relname="employees")]
        ├── whereClause: A_Expr
        │     ├── name: "="
        │     ├── lexpr: ColumnRef(fields=["dept_id"])
        │     └── rexpr: A_Const(val=Integer(3))
        ├── sortClause: [SortBy(node=ColumnRef(name="salary"), sortby_dir=SORTBY_DESC)]
        └── limitClause: ...

// src/backend/parser/parser.c
List *raw_parser(const char *str)
{
    core_yyscan_t yyscanner;
    yy_extra_type yyextra;
    int         yyresult;

    // 初始化 flex scanner
    yyscanner = scanner_init(str, &yyextra, ...);

    // 调用 Bison 生成的解析器
    yyresult = base_yyparse(yyscanner);

    // yyextra.parsetree 存的是 parsing 过程中积累的 RawStmt 链表
    return yyextra.parsetree;
}
```text

`raw_parser()` 在 `exec_simple_query()` 中被调用。返回的 `List` 可能包含多条 `RawStmt`（如果输入是多语句字符串，如 `SELECT 1; SELECT 2;`）。

---

## 三、Analyzer：语义分析

### 3.1 parse_analyze()：分发入口

`parse_analyze()` 是语义分析的入口：

```c
// src/backend/parser/analyze.c
Query *parse_analyze(RawStmt *parseTree, const char *sourceText,
                     Oid *paramTypes, int numParams,
                     QueryEnvironment *queryEnv)
{
    ParseState *pstate = make_parsestate(NULL);
    Query      *query;

    pstate->p_sourcetext = sourceText;

    // 分发到对应的 transform 函数
    query = transformTopLevelStmt(pstate, parseTree);

    // 检查是否有未解决的标识符或类型错误
    if (pstate->p_hasAggs || pstate->p_hasWindowFuncs)
        parseCheckAggregates(pstate, query);
    if (pstate->p_hasSubLinks)
        parseCheckSubLinks(pstate, query);

    free_parsestate(pstate);
    return query;
}

// src/backend/parser/analyze.c
Query *transformTopLevelStmt(ParseState *pstate, RawStmt *parseTree)
{
    switch (nodeTag(parseTree->stmt))
    {
    case T_SelectStmt:
        return transformSelectStmt(pstate, (SelectStmt *)parseTree->stmt);
    case T_InsertStmt:
        return transformInsertStmt(pstate, (InsertStmt *)parseTree->stmt);
    case T_DeleteStmt:
        return transformDeleteStmt(pstate, (DeleteStmt *)parseTree->stmt);
    case T_UpdateStmt:
        return transformUpdateStmt(pstate, (UpdateStmt *)parseTree->stmt);
    // ... CREATE TABLE, ALTER TABLE 等走 transformCreateStmt 等
    default:
        // 实用命令（DDL, VACUUM 等）走特殊路径
        return transformUtilityStmt(pstate, parseTree);
    }
}
```text

对于 `SELECT`，核心调用链为：

```text
transformSelectStmt()
  → transformFromClause()       // FROM 子句 → rtable
    → transformFromClauseItem()
      → addRangeTableEntry()    // 为每个表创建 RangeTblEntry
  → transformWhereClause()     // WHERE → qual 表达式
  → transformTargetList()      // SELECT 列表 → targetList
  → transformSortClause()      // ORDER BY → sortClause

// src/backend/parser/parse_expr.c
Node *transformExpr(ParseState *pstate, Node *expr, ParseExprKind exprKind)
{
    switch (nodeTag(expr))
    {
    case T_ColumnRef:
        return transformColumnRef(pstate, (ColumnRef *)expr);
    case T_A_Const:
        return transformAConst(pstate, (A_Const *)expr);
    case T_A_Expr:
        return transformAExprOp(pstate, (A_Expr *)expr);   // 运算符类型推导
    case T_FuncCall:
        return transformFuncCall(pstate, (FuncCall *)expr); // 函数签名查找
    // ...
    }
}
```text

对于 `dept_id = 3` 这个表达式，Analyzer 需要：
1. 把 `ColumnRef("dept_id")` 解析为对应列的 `Var`（从该列的 `pg_attribute` 记录中拿到类型 OID 和 attnum）。
2. 把 `A_Const(Integer(3))` 从语法树的整数字面量转换为 `Const` 节点（标注类型为 `int4`）。
3. 查找 `=` 操作符的签名 `int4 = int4 → bool`（通过 `oper()` 函数查 `pg_operator` 系统表）。
4. 构造 `OpExpr` 节点，包含操作符 OID、两个参数的类型、结果类型 `bool`。

### 3.4 权限检查

PostgreSQL 在 Analyzer 阶段执行 DML 操作的权限检查，而不是在执行器阶段。这样做的优势是可以在执行开始前就发现权限不足的查询，避免执行到一半才报错。

权限检查通过 `ExecCheckRTPerms()` 执行，核心逻辑在 `ExecCheckRTEPerms()` 中：

```c
// src/backend/executor/execCheck.c（由 Analyzer 调用）
bool ExecCheckRTPerms(List *rangeTable, bool ereport_on_violation)
{
    foreach(l, rangeTable)
    {
        RangeTblEntry *rte = (RangeTblEntry *) lfirst(l);
        // 检查类型：SELECT / INSERT / UPDATE / DELETE
        aclresult = pg_class_aclmask(rte->relid,
                                     rte->checkAsUser,
                                     requiredPerms, ACLMASK_ALL);
        if (aclresult != requiredPerms)
            // 报错：permission denied
    }
}

// src/backend/rewrite/rewriteHandler.c
List *QueryRewrite(Query *parsetree)
{
    // 1. 应用 CMD 规则：查找所有匹配 pg_rewrite 规则的 DML 语句
    if (parsetree->commandType != CMD_UTILITY)
        results = QueryRewriteOne(parsetree);

    // 2. 替换为规则指定的动作
    //    对于 instead 规则，原查询被丢弃
    //    对于非 instead 规则，原查询和规则动作都执行

    // 3. 展开所有 RTE 中的子查询（视图、WITH CTE）
    foreach(l, results)
    {
        query = (Query *) lfirst(l);
        FireRIRrules(query, ...);  // 递归展开 RangeTblEntry 的子查询
    }
    return results;
}
```bash

### 4.2 视图展开的实质

视图在 PG 中并非独立的存储对象。`CREATE VIEW foo AS SELECT ...` 等价于创建了一条 `_RETURN` 规则。具体来说：

```sql
CREATE VIEW high_salary AS
SELECT name, salary FROM employees WHERE salary > 100000;

// src/backend/rewrite/rewriteHandler.c
RewriteQuery()
  → QueryRewrite()              // 入口
    → QueryRewriteOne()         // 应用匹配的 pg_rewrite 规则
      → RewriteQuery()          // 递归：规则动作本身可能触发更多规则
    → FireRIRrules()            // 展开子查询（视图、CTE、子查询 RTE）
      → fireRIRrules()
        → ApplyRetrieveRule()   // 应用 _RETURN 规则展开视图

ApplyRetrieveRule()
  → 从 pg_rewrite 提取 ev_action
  → 将 ev_action 的目标列表（targetList）和 WHERE 条件合入原查询
  → 将原查询的 WHERE 条件作为额外的 qual 添加到展开后的查询
  → 递归调用 FireRIRrules() 处理嵌套视图
```text

对于 `INSTEAD` 规则（`is_instead=true`），原查询被完全丢弃，只执行规则动作。对于非 `INSTEAD` 规则，规则动作在原查询之前或之后追加执行。

---

## 五、Query 结构体深度拆解

经过 Parser → Analyzer → Rewriter 三步后，一条 SQL 最终变成一个或多个 `Query` 结构体。这是查询编译流水线的核心输出，也是 Planner 的输入。

```c
// src/include/nodes/parsenodes.h
typedef struct Query
{
    NodeTag     type;
    CmdType     commandType;    // CMD_SELECT / CMD_INSERT / CMD_UPDATE / CMD_DELETE / CMD_UTILITY
    QuerySource querySource;    // 来源：原始 SQL / 规则展开 / 其他

    uint64      queryId;        // query identifier（如 pg_stat_statements 中用于聚合）

    bool        canSetTag;      // 这条 Query 是否是"主查询"（影响命令标签和行计数）

    Node       *utilityStmt;    // 对于 CMD_UTILITY，指向 DDL 等实用命令节点

    int         resultRelation; // 对于 INSERT/UPDATE/DELETE，目标表在 rtable 中的索引
                                // 对于 SELECT ... FOR UPDATE，也需要锁定结果表

    bool        hasAggs;        // 是否包含聚合函数（决定是否需要分组规划）
    bool        hasWindowFuncs; // 是否包含窗口函数
    bool        hasSubLinks;    // 是否包含子查询（SubLink 节点）
    bool        hasDistinctOn;  // 是否有 DISTINCT ON
    bool        hasRecursive;   // 是否有递归 CTE

    List       *cteList;        // WITH 子句定义的 CTE 列表
    List       *rtable;         // 范围表（Range Table）：查询涉及的所有关系
    FromExpr   *jointree;       // Join 树：FROM 和 WHERE 的组合表示
    List       *targetList;     // 目标列表：SELECT 的输出列

    OnConflictExpr *onConflict; // INSERT ... ON CONFLICT 的处理规范

    List       *groupClause;    // GROUP BY 子句
    List       *groupDistinct;  // GROUP BY 是否带有 DISTINCT
    List       *groupingSets;   // GROUPING SETS

    Node       *havingQual;     // HAVING 子句

    List       *windowClause;   // WINDOW 子句定义

    List       *distinctClause; // SELECT DISTINCT 的目标列表

    List       *sortClause;     // ORDER BY 子句

    Node       *limitOffset;    // LIMIT 偏移量
    Node       *limitCount;     // LIMIT 行数

    List       *rowMarks;       // 行级锁标记（FOR UPDATE / FOR SHARE / FOR KEY SHARE）

    Node       *setOperations;  // UNION / INTERSECT / EXCEPT 的集合操作树

    List       *constraintDeps; // 约束依赖（PL/pgSQL 使用）

    // PG 14+：合并聚合、窗口函数和子查询的标记
    bool        hasRowSecurity; // 是否启用了行级安全策略
    bool        hasForUpdate;   // 是否有 FOR UPDATE 子句
} Query;

// src/include/nodes/parsenodes.h
typedef struct RangeTblEntry
{
    NodeTag     type;
    RTEKind     rtekind;        // RTE_RELATION / RTE_SUBQUERY / RTE_JOIN
                                // RTE_FUNCTION / RTE_VALUES / RTE_CTE / ...

    Oid         relid;          // 关系 OID（RTE_RELATION 时有效）
    char        relkind;        // 'r'=普通表, 'v'=视图, 'm'=物化视图, 'f'=外部表
    int         rellockmode;    // 锁模式（AccessShareLock 等）

    Query      *subquery;       // RTE_SUBQUERY 时，指向子查询的 Query 树
    bool        security_barrier; // 安全屏障视图标志

    // JOIN RTE 相关
    JoinType    jointype;
    int         joinmergedcols;
    List       *joinaliasvars;
    List       *joinleftcols;
    List       *joinrightcols;

    // 函数 RTE 相关
    List       *functions;      // RangeTblFunction 链表

    // 别名
    Alias      *alias;          // 用户指定的表别名（如 FROM employees AS e）
    Alias      *eref;           // 系统内部引用名
    bool        lateral;        // 是否标记为 LATERAL

    // 安全性
    bool        inh;            // 是否包含继承子表
    Oid         userid;         // 检查权限的用户 ID
    int         securityQuals;  // 行级安全策略的 security_barrier 标记
} RangeTblEntry;
```text

对于查询 `SELECT e.name, d.dept_name FROM employees e JOIN departments d ON e.dept_id = d.id WHERE e.salary > 100000`，`rtable` 包含至少两个 `RangeTblEntry`：

- RTE[1]: `employees` (relid=employees表的OID, alias={aliasname="e"}, rtekind=RTE_RELATION)
- RTE[2]: `departments` (relid=departments表的OID, alias={aliasname="d"}, rtekind=RTE_RELATION)

如果在 Rewriter 阶段将视图展开，可能存在 RTE_SUBQUERY 类型的 RTE，指向展开后的子查询。

### 5.2 jointree：Join 树

`jointree` 是 `FromExpr *` 类型，它是 FROM 子句和 WHERE 子句的组合表示：

```c
// src/include/nodes/parsenodes.h
typedef struct FromExpr
{
    NodeTag     type;
    List       *fromlist;       // FROM 子句中的关系列表（指向 rtable 的索引节点）
    Node       *quals;          // WHERE 子句的表达式树
} FromExpr;

typedef struct JoinExpr
{
    NodeTag     type;
    JoinType    jointype;       // JOIN_INNER / JOIN_LEFT / JOIN_RIGHT / JOIN_FULL
    Node       *larg;           // 左子节点（RangeTblRef 或 JoinExpr）
    Node       *rarg;           // 右子节点
    List       *usingClause;    // USING(...) 子句
    Node       *quals;          // ON 子句的表达式
    Alias      *alias;          // JOIN 结果的别名
    int         rtindex;        // 在 rtable 中的索引
} JoinExpr;
```text

对于上面的查询，`jointree` 的结构（简化）为：

```text
FromExpr
  ├── fromlist:
  │     └── JoinExpr (INNER)
  │           ├── larg: RangeTblRef(rtindex=1)       // employees
  │           ├── rarg: RangeTblRef(rtindex=2)       // departments
  │           └── quals: OpExpr("=", Var(1,dept_id), Var(2,id))
  └── quals: OpExpr(">", Var(1,salary), Const(100000))

typedef struct TargetEntry
{
    Expr        xpr;
    Expr       *expr;           // 该列的表达式（Var / OpExpr / FuncExpr / Const 等）
    AttrNumber  resno;          // 结果列在输出中的序号（从 1 开始）
    char       *resname;        // 列名（如果用户指定了别名则为别名）
    Index       ressortgroupref; // ORDER BY 和 GROUP BY 使用的引用编号
    Oid         resorigtbl;     // 原始表 OID
    AttrNumber  resorigcol;     // 原始列号
    bool        resjunk;        // 是否为"垃圾"列（不输出给客户端，但用于内部计算）
} TargetEntry;
```text

对于 `SELECT e.name, e.salary * 1.1 AS adjusted FROM employees e`，`targetList` 包含两个 `TargetEntry`：

- TE(resno=1, resname="name"): expr = `Var(varno=1, varattno=name列的attnum, vartype=name列的类型)`, resjunk=false
- TE(resno=2, resname="adjusted"): expr = `OpExpr("*", Var(1,salary), Const(1.1))`, resjunk=false

Resjunk 列（`resjunk=true`）是优化器在执行阶段需要的中间计算列，但不返回给客户端。例如 `ORDER BY salary` 如果 `salary` 不在 SELECT 列表中，Optimizer 可能会创建一个 junk TargetEntry 来计算 `salary`，供排序使用。

---

## 六、实验：观察每一步的输出

### 6.1 启用 debug 输出

PG 提供了几个 developer-level 的 GUC 参数，让你可以在不重新编译的情况下观察 parse tree 和 rewritten tree：

```sql
-- 输出 parse tree（Analyzer 处理之后的 Query Tree）
SET debug_print_parse = on;

-- 输出 rewritten tree（Rewriter 处理之后的 Query Tree）
SET debug_print_rewritten = on;

-- 输出 planner 选择的 plan tree
SET debug_print_plan = on;

-- 单次执行时开启（避免全局日志污染）
-- 配合 client_min_messages 使用
SET client_min_messages = NOTICE;

CREATE TABLE employees (
    id      int PRIMARY KEY,
    name    text,
    salary  numeric,
    dept_id int
);

INSERT INTO employees VALUES
    (1, 'Alice', 120000, 1),
    (2, 'Bob',   85000, 2),
    (3, 'Charlie', 95000, 1);

CREATE VIEW high_salary AS
SELECT name, salary FROM employees WHERE salary > 90000;
```text

在 psql 中执行（需要超级用户）：

```sql
SET debug_print_parse = on;

SELECT * FROM high_salary WHERE name LIKE 'A%';