# @pgsql/traverse
AST traversal for the pgsql-parser ecosystem: a Babel-style visitor pattern for PostgreSQL SQL ASTs **and** PL/pgSQL ASTs. Traversal only — nothing here parses SQL, so the package stays free of WASM.
## Installation
```bash
npm install @pgsql/traverse
```
## Which function do I want?
| Function | Walks | Use when |
| --- | --- | --- |
| `walk(ast, visitors, opts?)` | **any** AST — parsed script, `ParseResult`, SQL node, PL/pgSQL node | default choice |
| `walkSqlAst(ast, visitor)` | SQL AST only | you want the raw primitive, no statement context |
| `walkPlpgsqlAst(ast, visitor, opts?)` | PL/pgSQL AST only | you already have a hydrated function body |
| `traverse(ast, mutableVisitor)` | SQL AST, mutation-safe | you need to replace/insert/remove nodes |
| [`walkSql(text, ...)`](../plpgsql-parser) in `plpgsql-parser` | SQL **text** | you start from a string and need parse + hydrate |
## Usage
### `walk` — one entry point for any AST
`walk` dispatches on the shape of what you hand it:
| Input | Walked |
| --- | --- |
| `{ sql, functions }` (a `ParsedScript` from `plpgsql-parser`) | every statement, then every hydrated PL/pgSQL body |
| `{ version, stmts }` (a `ParseResult`) | every statement, with statement context |
| `{ PLpgSQL_*: ... }` / `{ plpgsql_funcs: [...] }` | the PL/pgSQL body, descending into its hydrated SQL expressions |
| any other SQL node | that node |
| an array | each element |
```typescript
import { walk } from '@pgsql/traverse';
import type { NodePath, Visitor, Walker } from '@pgsql/traverse';
// A walker function fires on every node.
walk(ast, (path) => {
console.log(`Visiting ${path.tag} at path:`, path.path);
if (path.tag === 'SelectStmt') {
return false; // skip this node's children
}
});
// A visitor object fires per node tag. SQL and PL/pgSQL tags may be mixed.
walk(ast, {
SelectStmt: (path) => console.log('SELECT statement:', path.node),
RangeVar: (path) => console.log('Table:', path.node.relname),
PLpgSQL_stmt_dynexecute: (path) => console.log('dynamic EXECUTE:', path.node)
});
```
#### Statement context
Every callback gets a second argument describing the statement the node belongs
to. `NodePath` tells you *where* a node sits; `WalkContext` tells you *what it is
part of* — which is what a `RangeVar` handler needs to know it is the write
target of an `UPDATE`, or that it came from inside `auth.login`'s body.
```typescript
interface WalkContext {
stmtTag: string | null; // enclosing top-level statement, e.g. 'UpdateStmt'
stmtIndex: number; // its index in the script, -1 if unknown
isWrite: boolean; // INSERT/UPDATE/DELETE/MERGE/TRUNCATE/COPY
isRead: boolean; // SELECT/EXPLAIN/DECLARE/FETCH
insideFunction: boolean; // node came from a PL/pgSQL body
functionName: string | null; // dotted name of that function
abort(reason?: string): void;
}
walk(parsed, {
RangeVar: (path, ctx) => {
if (ctx.isWrite) console.log('writes to', path.node.relname);
if (ctx.insideFunction) console.log('...from inside', ctx.functionName);
}
});
```
The reserved `statement` key fires once per top-level statement, before its
children:
```typescript
walk(parseResult, {
statement: (path, ctx) => console.log(ctx.stmtIndex, path.tag)
});
```
#### Composing visitors
Pass an array to run several independent policies in a single pass:
```typescript
walk(parsed, [blockedSchemas, readOnlySchemas, blockedFunctions]);
```
#### Skip vs. abort
`return false` skips that node's children. `ctx.abort(reason?)` ends the entire
walk — what a validator wants when it has already decided to reject:
```typescript
const result = walk(parsed, {
PLpgSQL_stmt_dynexecute: (_path, ctx) => ctx.abort('dynamic EXECUTE is not allowed')
});
result.aborted; // true
result.reason; // 'dynamic EXECUTE is not allowed'
result.reasons; // every reason, in call order
```
### `walkSqlAst` — the SQL-only primitive
Recursion is derived from PostgreSQL's runtime schema, so it knows exactly which
fields hold nodes, including untagged typed fields such as
`CreatePolicyStmt.table`. `walk` is built on it.
```typescript
import { walkSqlAst } from '@pgsql/traverse';
import type { Visitor, Walker } from '@pgsql/traverse';
const visitor: Visitor = {
RangeVar: (path) => console.log('Table:', path.node.relname)
};
walkSqlAst(ast, visitor);
```
### `walkPlpgsqlAst` — the PL/pgSQL-only primitive
Walks the PL/pgSQL node universe (`PLpgSQL_stmt_block`, `PLpgSQL_stmt_if`,
`PLpgSQL_var`, ...), which the SQL parser never produces. A PL/pgSQL body is a
control-flow skeleton whose leaves are SQL expressions, so it bridges into
`walkSqlAst` for every hydrated expression:
```typescript
import { walkPlpgsqlAst } from '@pgsql/traverse';
walkPlpgsqlAst(hydratedBody, { PLpgSQL_var: (path) => console.log(path.node.refname) }, {
walkSqlExpressions: true,
sqlVisitor: { RangeVar: (path) => console.log('table in body:', path.node.relname) }
});
```
Hydration itself lives in `plpgsql-parser`.
### NodePath Class
The `NodePath` class provides rich context information:
```typescript
class NodePath {
tag: TTag; // Node type (e.g., 'SelectStmt', 'RangeVar')
node: Node[TTag]; // The actual node data
parent: NodePath | null; // Parent NodePath (null for root)
keyPath: readonly (string | number)[]; // Full path array
get path(): (string | number)[]; // Copy of keyPath
get key(): string | number; // Last element of path
}
```
### Working with ParseResult
```typescript
import { walk } from '@pgsql/traverse';
const visitor = {
ParseResult: (path) => {
console.log('Parse result version:', path.node.version);
console.log('Number of statements:', path.node.stmts.length);
},
SelectStmt: (path) => {
console.log('SELECT statement found');
}
};
walk(parseResult, visitor);
```
### Reading a node's position
`NodePath` describes where a node sits in the tree:
```typescript
const visitor = {
RangeVar: (path) => {
console.log('Table name:', path.node.relname);
console.log('Path to this node:', path.path);
console.log('Parent node:', path.parent?.tag);
console.log('Key in parent:', path.key);
}
};
```
### Collecting Information During Traversal
```typescript
import { walk } from '@pgsql/traverse';
import type { Visitor } from '@pgsql/traverse';
const tableNames: string[] = [];
const columnRefs: string[] = [];
const visitor: Visitor = {
RangeVar: (path) => {
if (path.node.relname) {
tableNames.push(path.node.relname);
}
},
ColumnRef: (path) => {
for (const field of path.node.fields ?? []) {
if (field.String?.sval) {
columnRefs.push(field.String.sval);
}
}
}
};
walk(ast, visitor);
console.log('Tables referenced:', tableNames);
console.log('Columns referenced:', columnRefs);
```
## API
### `walk(root, visitors, options?): WalkResult`
Walks any AST — SQL, PL/pgSQL, or a parsed script — with one or more visitors.
**Parameters:**
- `root`: the AST, parse result, or parsed script to traverse
- `visitors`: a walker function, a visitor object, or an array of either
- `options?`:
- `walkFunctionBodies` (default `true`) — walk hydrated PL/pgSQL bodies of a parsed script
- `walkSqlExpressions` (default `true`) — recurse into hydrated SQL expressions inside bodies
- `sqlVisitor` — override the visitor used for those SQL expressions
**Returns** `{ aborted, reason?, reasons }`.
### `walkSqlAst(root, callback, parent?, keyPath?)`
The SQL-only primitive. Walks PostgreSQL AST nodes using the runtime schema for
precise traversal.
**Parameters:**
- `root`: The AST node to traverse
- `callback`: A walker function or visitor object
- `parent?`: Optional parent NodePath (for internal use)
- `keyPath?`: Optional key path array (for internal use)
### `walkPlpgsqlAst(root, callback, options?, parent?, keyPath?)`
The PL/pgSQL-only primitive.
**Parameters:**
- `root`: The PL/pgSQL AST node to traverse
- `callback`: A walker function or visitor object keyed by `PLpgSQL_*` tags
- `options?`: `{ walkSqlExpressions?, sqlVisitor? }`
### `traverse(root, mutableVisitor)`
The mutation-capable walker: `enter`/`exit` hooks and sibling insert/remove/replace
through `MutablePath`. Use it when the walk needs to change the tree; `walk` is
read-only.
### Types
#### `WalkContext`
Statement context threaded into every `walk` callback:
```typescript
interface WalkContext {
readonly stmtTag: string | null;
readonly stmtIndex: number;
readonly isWrite: boolean;
readonly isRead: boolean;
readonly insideFunction: boolean;
readonly functionName: string | null;
abort(reason?: string): void;
}
```
#### `WalkResult`
What `walk` returns:
```typescript
interface WalkResult {
aborted: boolean; // a visitor called ctx.abort()
reason?: string; // the first reason given
reasons: string[]; // every reason, in call order
}
```
#### `Visitor`
An object type where keys are node type names and values are walker functions:
```typescript
type Visitor = {
[TTag in NodeTag]?: Walker>;
};
```
#### `Walker`
A function that receives a NodePath and can return false to skip children:
```typescript
type Walker = (
path: TNodePath,
) => boolean | void;
```
#### `NodePath`
A class that encapsulates node traversal context:
```typescript
class NodePath {
tag: TTag; // Node type
node: Node[TTag]; // Node data
parent: NodePath | null; // Parent path
keyPath: readonly (string | number)[]; // Full path
get path(): (string | number)[]; // Path copy
get key(): string | number; // Current key
}
```
#### `NodeTag`
Union type of all PostgreSQL AST node type names:
```typescript
type NodeTag = keyof Node;
```
## Supported Node Types
This package works with all PostgreSQL AST node types defined in `@pgsql/types`, including:
- `ParseResult` - Root parse result from libpg-query
- `SelectStmt` - SELECT statements
- `InsertStmt` - INSERT statements
- `UpdateStmt` - UPDATE statements
- `DeleteStmt` - DELETE statements
- `RangeVar` - Table references
- `ColumnRef` - Column references
- `A_Expr` - Expressions
- `A_Const` - Constants
- And many more...
## Integration with pgsql-parser
This package is designed to work seamlessly with the pgsql-parser ecosystem:
```typescript
import { parse } from 'pgsql-parser';
import { walk } from '@pgsql/traverse';
const sql = 'SELECT name, email FROM users WHERE age > 18';
const ast = await parse(sql);
walk(ast, {
RangeVar: (path) => {
console.log('Table:', path.node.relname);
},
ColumnRef: (path) => {
console.log('Column:', path.node.fields?.[0]?.String?.sval);
}
});
```
Starting from SQL text? `plpgsql-parser`'s `walkSql` does the parse and the
PL/pgSQL hydration for you, then hands off to `walk`.