# Views AST Reference for safe-migrate
## Status
Verified against squawk_syntax 2.58.0 — July 2026
---
## Documentation Contract
1. Only document AST behavior that has been directly verified.
2. Do not infer PostgreSQL semantics from missing AST accessors.
3. Distinguish verified facts from unresolved areas.
4. Assume additional nodes or helpers may exist outside the inspected surface.
---
## Handwritten Extension Policy
No handwritten extensions exist for any view node.
Verified by exhaustive grep documented in `columns.md`.
No view-related nodes appear in the complete handwritten extension inventory.
---
# High-Level View Model
The verified AST surface exposes:
**Regular views:**
- `CreateView`
- `AlterView`
- `DropView`
**Materialized views:**
- `CreateMaterializedView`
- `AlterMaterializedView`
- `DropMaterializedView`
- `Refresh`
**Synthetic unification node:**
- `CreateViewLike` — unifies `CreateView` and `CreateMaterializedView`
**Alter dispatch:**
- `AlterMaterializedViewAction` (5-member enum)
---
# Regular Views
## CreateView
### Verified Accessors (line 6983)
```rust
pub fn column_list(&self) -> Option<ColumnList>
pub fn or_replace(&self) -> Option<OrReplace>
pub fn path(&self) -> Option<Path>
pub fn persistence(&self) -> Option<Persistence>
pub fn query(&self) -> Option<SelectVariant>
pub fn with_params(&self) -> Option<WithParams>
pub fn semicolon_token(&self) -> Option<SyntaxToken>
pub fn as_token(&self) -> Option<SyntaxToken>
pub fn cascaded_token(&self) -> Option<SyntaxToken>
pub fn check_token(&self) -> Option<SyntaxToken>
pub fn create_token(&self) -> Option<SyntaxToken>
pub fn local_token(&self) -> Option<SyntaxToken>
pub fn option_token(&self) -> Option<SyntaxToken>
pub fn recursive_token(&self) -> Option<SyntaxToken>
pub fn view_token(&self) -> Option<SyntaxToken>
pub fn with_token(&self) -> Option<SyntaxToken>
```
### Membership
Member of `SchemaElement` enum (line 39392).
Member of `Stmt` enum (line 40736).
### Key Accessor Notes
**OR REPLACE detection:** `or_replace().is_some()`
**RECURSIVE detection:** `recursive_token().is_some()`
**TEMP/TEMPORARY detection:** `persistence().is_some()`
`Persistence` is a two-variant enum: `Temp` and `Unlogged`.
**WITH CHECK OPTION detection:**
Three tokens encode this:
- `check_token()` — CHECK keyword presence
- `local_token()` — LOCAL form
- `cascaded_token()` — CASCADED form
Detection:
```
check_token present + local_token present → WITH LOCAL CHECK OPTION
check_token present + cascaded_token present → WITH CASCADED CHECK OPTION
check_token present alone → WITH CHECK OPTION (default cascaded)
```
**Column alias list:** `column_list()` — optional explicit column names.
**Query:** `query()` → `SelectVariant` — the view definition query.
### safe-migrate guidance
```rust
CreateViewFact {
name: QualifiedName, // from path()
or_replace: bool,
recursive: bool,
temporary: bool, // from persistence()
column_aliases: Vec<String>, // from column_list()
query: SelectVariantIr, // from query()
check_option: Option<CheckOptionKind>, // from token inspection
}
enum CheckOptionKind {
Local,
Cascaded,
}
```
---
## AlterView
### Verified Accessors (line 2908)
```rust
pub fn expr(&self) -> Option<Expr>
pub fn if_exists(&self) -> Option<IfExists>
pub fn name(&self) -> Option<Name>
pub fn name_ref(&self) -> Option<NameRef>
pub fn owner_to(&self) -> Option<OwnerTo>
pub fn path(&self) -> Option<Path>
pub fn rename_to(&self) -> Option<RenameTo>
pub fn reset_options(&self) -> Option<ResetOptions>
pub fn set_options(&self) -> Option<SetOptions>
pub fn set_schema(&self) -> Option<SetSchema>
pub fn semicolon_token(&self) -> Option<SyntaxToken>
pub fn alter_token(&self) -> Option<SyntaxToken>
pub fn column_token(&self) -> Option<SyntaxToken>
pub fn default_token(&self) -> Option<SyntaxToken>
pub fn drop_token(&self) -> Option<SyntaxToken>
pub fn rename_token(&self) -> Option<SyntaxToken>
pub fn set_token(&self) -> Option<SyntaxToken>
pub fn to_token(&self) -> Option<SyntaxToken>
pub fn view_token(&self) -> Option<SyntaxToken>
```
### Membership
Member of `Stmt` enum (line 40424).
### Grammar Definition
The ungrammar definition shows substantial action options beyond path():
```
AlterView =
'alter' 'view' IfExists? Path
(
'alter' 'column'? NameRef (('set' 'default' Expr) | ('drop' 'default'))
| OwnerTo
| RenameTo
| 'rename' 'column'? NameRef 'to' Name
| SetSchema
| SetOptions
| ResetOptions
) ';'?
```
### Important Finding — Grammar Confirmed Capabilities
`AlterView` genuinely supports multiple action forms in this grammar:
- Column default modification via `expr()` — `ALTER [COLUMN] col SET DEFAULT expr` or `ALTER [COLUMN] col DROP DEFAULT`
- Ownership change via `owner_to()` — `OWNER TO role`
- Rename via `rename_to()` — `RENAME TO new_name`
- Column rename via `rename_token()` + `name_ref()` + `to_token()` + `name()` — `RENAME COLUMN col TO new_col`
- Schema change via `set_schema()` — `SET SCHEMA new_schema`
- Configuration options via `set_options()`/`reset_options()` — `SET option=value` / `RESET option`
This is a grammar-confirmation of substantial capabilities, not an extraction gap.
### Status
```
AST verified
Grammar-confirmed: AlterView supports multiple action forms via dedicated accessors
```
---
## DropView
### Verified Accessors (line 9781)
```rust
pub fn if_exists(&self) -> Option<IfExists>
pub fn paths(&self) -> AstChildren<Path>
pub fn semicolon_token(&self) -> Option<SyntaxToken>
pub fn cascade_token(&self) -> Option<SyntaxToken>
pub fn drop_token(&self) -> Option<SyntaxToken>
pub fn restrict_token(&self) -> Option<SyntaxToken>
pub fn view_token(&self) -> Option<SyntaxToken>
```
### Membership
Member of `Stmt` enum (line 41030).
### Important Finding
`DropView.paths()` returns `AstChildren<Path>` — multiple names supported.
### safe-migrate guidance
```rust
DropViewFact {
names: Vec<QualifiedName>, // from paths() — may be multiple
if_exists: bool,
cascade: bool,
}
```
---
# Materialized Views
## CreateMaterializedView
### Verified Accessors (line 5678)
```rust
pub fn column_list(&self) -> Option<ColumnList>
pub fn if_not_exists(&self) -> Option<IfNotExists>
pub fn path(&self) -> Option<Path>
pub fn query(&self) -> Option<SelectVariant>
pub fn tablespace(&self) -> Option<Tablespace>
pub fn using_method(&self) -> Option<UsingMethod>
pub fn with_data(&self) -> Option<WithData>
pub fn with_no_data(&self) -> Option<WithNoData>
pub fn with_params(&self) -> Option<WithParams>
pub fn semicolon_token(&self) -> Option<SyntaxToken>
pub fn as_token(&self) -> Option<SyntaxToken>
pub fn create_token(&self) -> Option<SyntaxToken>
pub fn materialized_token(&self) -> Option<SyntaxToken>
pub fn view_token(&self) -> Option<SyntaxToken>
```
### Membership
Member of `Stmt` enum (line 40574).
Member of `ExplainStmt` enum (line 37790).
### Key Accessor Notes
**WITH DATA / WITH NO DATA detection:**
- `with_data().is_some()` → `WITH DATA` (populate immediately)
- `with_no_data().is_some()` → `WITH NO DATA` (create empty)
- Both `None` → default behavior (same as `WITH DATA`)
**Access method:** `using_method()` → `UsingMethod` → `name_ref()`.
Materialized views support custom access methods.
**Differences from CreateView:**
- Has `if_not_exists`, `tablespace`, `using_method`, `with_data`, `with_no_data`
- Does NOT have `or_replace`, `recursive`, `persistence`, `check_option` tokens
### safe-migrate guidance
```rust
CreateMaterializedViewFact {
name: QualifiedName,
if_not_exists: bool,
column_aliases: Vec<String>, // from column_list()
query: SelectVariantIr, // from query()
with_data: WithDataState, // WithData | WithNoData | Default
tablespace: Option<String>,
using_method: Option<String>,
}
```
---
## AlterMaterializedView
### Verified Accessors (line 1443)
```rust
pub fn action(&self) -> AstChildren<AlterMaterializedViewAction>
pub fn if_exists(&self) -> Option<IfExists>
pub fn name(&self) -> Option<Name>
pub fn name_ref(&self) -> Option<NameRef>
pub fn owned_by_roles(&self) -> Option<OwnedByRoles>
pub fn path(&self) -> Option<Path>
pub fn semicolon_token(&self) -> Option<SyntaxToken>
pub fn all_token(&self) -> Option<SyntaxToken>
pub fn alter_token(&self) -> Option<SyntaxToken>
pub fn in_token(&self) -> Option<SyntaxToken>
pub fn materialized_token(&self) -> Option<SyntaxToken>
pub fn nowait_token(&self) -> Option<SyntaxToken>
pub fn set_token(&self) -> Option<SyntaxToken>
pub fn tablespace_token(&self) -> Option<SyntaxToken>
pub fn view_token(&self) -> Option<SyntaxToken>
```
### Membership
Member of `Stmt` enum (line 40262).
### Key Accessor Notes
**Action dispatch:** `action()` returns `AstChildren<AlterMaterializedViewAction>` —
note this is a children iterator, not a single optional child.
**ALL IN TABLESPACE form:**
`all_token()` and `in_token()` presence indicates:
```sql
ALTER MATERIALIZED VIEW ALL IN TABLESPACE old [OWNED BY role] SET TABLESPACE new [NOWAIT]
```
**NOWAIT detection:** `nowait_token().is_some()`
**View identification:**
Both `name_ref()` and `path()` are present — one identifies the target view,
the other may identify a tablespace in the ALL IN TABLESPACE form.
### AlterMaterializedViewAction Enum (line 21882)
```rust
pub enum AlterMaterializedViewAction {
DependsOnExtension(DependsOnExtension),
NoDependsOnExtension(NoDependsOnExtension),
RenameColumn(RenameColumn),
RenameTo(RenameTo),
SetSchema(SetSchema),
AlterTableAction(AlterTableAction), // note: also contains AlterTableAction
}
```
Verified via `From<X> for AlterMaterializedViewAction` impls at lines 36535-36563.
### Individual Variant Accessors — Resolved via Cross-Reference
All 6 members are nodes already fully documented elsewhere in this AST
reference set — no new accessor inspection is needed, only cross-reference:
| `DependsOnExtension` | triggers.md (AlterTrigger context) | `name_ref()` → extension name |
| `NoDependsOnExtension` | triggers.md (AlterTrigger context) | `name_ref()` → extension name |
| `RenameColumn` | columns.md | `from()`/`to()` — see columns.md's documented grammar/implementation discrepancy note for this node |
| `RenameTo` | cross-cutting, used throughout | `name()` → new name |
| `SetSchema` | cross-cutting, used throughout | `name_ref()` → new schema name |
| `AlterTableAction` | columns.md / constraints.md / partitions.md (large 38-member enum) | See "Important Finding" below |
### Important Finding — AlterTableAction Wrapping Is Intentional
`AlterMaterializedViewAction::AlterTableAction` wraps the **entire**
`AlterTableAction` enum (38 members, documented piecemeal across columns.md,
constraints.md, and partitions.md wherever each member's primary node lives)
as a single variant. This means a materialized view's `ALTER` statement can
in principle carry any `AlterTableAction` member — `AddColumn`,
`AddConstraint`, `SetAccessMethod`, `ClusterOn`, etc. — even though many of
these (like `DetachPartition` or `MergePartitions`) make no semantic sense
for a materialized view.
**This is confirmed to be the actual grammar shape, not a parser
implementation artifact** — postgresql.ungram's `AlterMaterializedView` rule
directly lists `action:AlterMaterializedViewAction*` with `AlterTableAction`
as one of its own alternation members, meaning the grammar itself permits
this broad surface. PostgreSQL's actual `ALTER MATERIALIZED VIEW` syntax in
practice only supports a small subset of `ALTER TABLE`-style actions (mainly
column-storage/statistics-related ones like `ALTER COLUMN ... SET
STATISTICS`, plus `OWNER TO`, `CLUSTER ON`, `SET WITHOUT CLUSTER`) — the
grammar being permissive here mirrors the same "grammar is broader than
PostgreSQL semantics" pattern already noted for `CreateDomain`'s constraint
list in domains.md. The rule engine, not the AST layer, must reject
semantically invalid combinations (e.g. a materialized view `ALTER`
statement containing `DetachPartition`, which PostgreSQL would reject at
execution time).
### Status
```
AlterMaterializedViewAction membership: fully verified
Individual variant accessor surfaces: fully resolved via cross-reference
to existing documentation (no new inspection required, all 6 members
documented elsewhere in this reference set)
AlterTableAction wrapping: confirmed intentional per grammar, with the
same "grammar permissive, PostgreSQL semantics stricter" caveat already
established for domains.md
```
---
## DropMaterializedView
### Verified Accessors (line 8504)
```rust
pub fn if_exists(&self) -> Option<IfExists>
pub fn paths(&self) -> AstChildren<Path>
pub fn semicolon_token(&self) -> Option<SyntaxToken>
pub fn cascade_token(&self) -> Option<SyntaxToken>
pub fn drop_token(&self) -> Option<SyntaxToken>
pub fn materialized_token(&self) -> Option<SyntaxToken>
pub fn restrict_token(&self) -> Option<SyntaxToken>
pub fn view_token(&self) -> Option<SyntaxToken>
```
### Membership
Member of `Stmt` enum (line 40862).
### Symmetry with DropView
Both `DropMaterializedView` and `DropView` support multiple names per statement via `paths()` returning `AstChildren<Path>`.
```sql
DROP MATERIALIZED VIEW mv1, mv2, mv3; -- supported, paths() gives all three
DROP VIEW v1, v2, v3; -- supported, paths() gives all three
```
### safe-migrate guidance
```rust
DropMaterializedViewFact {
names: Vec<QualifiedName>, // from paths() — may be multiple
if_exists: bool,
cascade: bool,
}
```
---
## Refresh (REFRESH MATERIALIZED VIEW)
### Verified Accessors (line 16739)
```rust
pub fn path(&self) -> Option<Path>
pub fn with_data(&self) -> Option<WithData>
pub fn with_no_data(&self) -> Option<WithNoData>
pub fn semicolon_token(&self) -> Option<SyntaxToken>
pub fn concurrently_token(&self) -> Option<SyntaxToken>
pub fn materialized_token(&self) -> Option<SyntaxToken>
pub fn refresh_token(&self) -> Option<SyntaxToken>
pub fn view_token(&self) -> Option<SyntaxToken>
```
### Membership
Member of `Stmt` enum (line 41138).
### Key Accessor Notes
**CONCURRENTLY detection:** `concurrently_token().is_some()`
Significant for safe-migrate — concurrent refresh requires a unique index
and cannot run inside certain transaction contexts.
**WITH DATA / WITH NO DATA:**
- `with_data().is_some()` → populate on refresh
- `with_no_data().is_some()` → clear data on refresh
### safe-migrate guidance
```rust
RefreshMaterializedViewFact {
name: QualifiedName, // from path()
concurrently: bool,
with_data: WithDataState,
}
```
---
# CreateViewLike — Synthetic Unification Node
## Definition (src/ast/nodes.rs line 52)
```rust
impl CreateViewLike {
pub fn column_list(&self) -> Option<ast::ColumnList>
pub fn path(&self) -> Option<ast::Path>
pub fn query(&self) -> Option<ast::SelectVariant>
}
```
### Membership
```rust
impl AstNode for CreateViewLike {
fn can_cast(kind: ast::SyntaxKind) -> bool {
matches!(
kind,
ast::SyntaxKind::CREATE_MATERIALIZED_VIEW | ast::SyntaxKind::CREATE_VIEW
)
}
}
```
### Meaning
`CreateViewLike` is a synthetic AST node that can cast from either
`CREATE VIEW` or `CREATE MATERIALIZED VIEW` syntax nodes.
It exposes the minimal common surface:
- `path()` — view name
- `column_list()` — optional column aliases
- `query()` — the defining query
### safe-migrate guidance
Use `CreateViewLike` when writing rules that apply equally to both view types.
Use `CreateView` or `CreateMaterializedView` directly when type-specific
properties are needed (e.g. `with_data`, `or_replace`, `recursive`).
---
# Verified Findings Summary
## Confirmed Complete
- `CreateView`: fully resolved
- `DropView`: fully resolved
- `CreateMaterializedView`: fully resolved
- `DropMaterializedView`: fully resolved
- `Refresh`: fully resolved
- `CreateViewLike`: fully resolved
- `AlterMaterializedViewAction` enum: all members verified
## Confirmed Complete (updated)
- `AlterMaterializedView`: fully resolved, including all 6
`AlterMaterializedViewAction` variant cross-references and the confirmed
intentionality of the `AlterTableAction` wrapping
## Grammar-Confirmed Capabilities
- `AlterView`: confirmed by postgresql.ungram to support multiple action forms
(column defaults, ownership, rename, schema, options) via dedicated accessors —
not an extraction gap, but originally under-documented
## Grammar Cross-Check
This document has been fully cross-checked against postgresql.ungram.
`CreateView`, `DropView`, `CreateMaterializedView`, `DropMaterializedView`,
`Refresh`, `AlterMaterializedView`, `AlterMaterializedViewAction`, and `AlterView`
all match the verified accessor surface exactly. The `AlterView` accessor surface
was updated to reflect the full grammar capabilities.
```
## Symmetry
Both `DropView` and `DropMaterializedView` support multiple names per statement (`paths()`).
---
# Remaining Open Questions
None remaining. The `AlterMaterializedViewAction` variant accessor surfaces
were resolved via cross-reference to existing documentation elsewhere in
this reference set, and the `AlterTableAction` wrapping was confirmed
intentional per direct grammar inspection.