pg

README

pg -- PostgreSQL Parser

Recursive descent parser for PostgreSQL 17, producing a full AST with position tracking.

Public API

import "github.com/bytebase/omni/pg"

stmts, err := pg.Parse(sql)

Parse(sql string) ([]Statement, error)

Splits and parses a SQL string into individual statements.

Statement

type Statement struct {
    Text      string       // SQL text including trailing semicolon
    AST       ast.Node     // Inner statement node (e.g. *ast.SelectStmt)
    ByteStart int          // Inclusive start byte offset
    ByteEnd   int          // Exclusive end byte offset
    Start     Position     // Start line:column (1-based)
    End       Position     // End line:column (1-based)
}

Packages

Package	Description
pg/ast	210+ AST node types matching PostgreSQL internals
pg/parser	Recursive descent parser (~29,000 lines, 39 files)
pg/catalog	In-memory catalog simulation, DDL semantic analysis, type resolution
pg/parsertest	746 test cases organized by SQL feature
pg/pgregress	PostgreSQL official regression test compatibility

Documentation

Index

• Constants
• type CompletionContext
  • func CollectCompletion(sql string, cursorOffset int) *CompletionContext
• type Position
• type RangeReference
• type RangeReferenceKind
• type ScopeSnapshot
• type Segment
  • func Split(sql string) []Segment
  • func (s Segment) Empty() bool
• type Statement
  • func Parse(sql string) ([]Statement, error)
  • func (s *Statement) Empty() bool

Constants

const (
	RangeReferenceRelation  = parser.RangeReferenceRelation
	RangeReferenceSubquery  = parser.RangeReferenceSubquery
	RangeReferenceFunction  = parser.RangeReferenceFunction
	RangeReferenceJoinAlias = parser.RangeReferenceJoinAlias
	RangeReferenceCTE       = parser.RangeReferenceCTE
)

Types

type CompletionContext

type CompletionContext = parser.CompletionContext

CompletionContext is the parser-native context for SQL completion.

func CollectCompletion

func CollectCompletion(sql string, cursorOffset int) *CompletionContext

CollectCompletion returns completion candidates plus a best-effort visible relation scope at cursorOffset. Ordinary Parse remains strict.

type Position

type Position struct {
	// Line is 1-based line number.
	Line int
	// Column is 1-based column in bytes.
	Column int
}

Position represents a location in source text.

type RangeReference

type RangeReference = parser.RangeReference

RangeReference is a syntax-level FROM/JOIN reference.

type RangeReferenceKind

type RangeReferenceKind = parser.RangeReferenceKind

RangeReferenceKind classifies a range-table entry visible to completion.

type ScopeSnapshot

type ScopeSnapshot = parser.ScopeSnapshot

ScopeSnapshot describes the SELECT-level relation scope visible at a cursor.

type Segment

type Segment struct {
	Text      string // the raw text of this segment
	ByteStart int    // byte offset of start in original sql
	ByteEnd   int    // byte offset of end (exclusive) in original sql
}

Segment represents a portion of SQL text delimited by top-level semicolons.

func Split

func Split(sql string) []Segment

Split splits SQL text into segments at top-level semicolons. It is a pure lexical scanner that does not parse SQL, so it works on both valid and invalid SQL. Each returned segment includes the terminating semicolon (if present). Segments are returned with their byte offsets in the original string.

func (Segment) Empty

func (s Segment) Empty() bool

Empty returns true if the segment contains only whitespace, comments, and semicolons.

type Statement

type Statement struct {
	// Text is the SQL text including trailing semicolon if present.
	Text string
	// AST is the inner statement node (e.g. *ast.SelectStmt). Nil for empty statements.
	AST ast.Node

	// ByteStart is the inclusive start byte offset in the original SQL.
	ByteStart int
	// ByteEnd is the exclusive end byte offset in the original SQL.
	ByteEnd int

	// Start is the start position (line:column) in the original SQL.
	Start Position
	// End is the exclusive end position (line:column) in the original SQL.
	End Position
}

Statement is the result of parsing a single SQL statement.

func Parse

func Parse(sql string) ([]Statement, error)

Parse splits and parses a SQL string into statements. Each statement includes the text, AST, and byte/line positions. Text boundaries are derived from RawStmt.Loc: each statement's text spans from the end of the previous statement to just past the semicolon (or end of input) following the current statement.

func (*Statement) Empty

func (s *Statement) Empty() bool

Empty returns true if this statement has no meaningful content.