README
Documentation
¶
Overview ¶
Package sql parses SQL text into PostgreSQL's syntax tree, puts it in a canonical order, and deparses it back to SQL. It's a thin, allocation-light layer over pg_query that adds sentinel-error wrapping (ErrParse, ErrDeparse) plus the column-ordering normalization we use for canonical comparison.
The JSON normalization (ToJSON) lives right here too; SQL formatting, AST diffing, and text normalization live over in the formatter, compare, and normalize subpackages.
Index ¶
- Constants
- func Comments(sql SQL) ([]string, error)
- func Fingerprint(sql SQL) (string, error)
- func Parse(sql SQL) (*pg_query.ParseResult, error)
- func Scan(sql SQL) (*pg_query.ScanResult, error)
- func SortColumnLists(tree *pg_query.ParseResult)
- func ToJSON(result *pg_query.ParseResult) ([]json.RawMessage, error)
- type SQL
Constants ¶
const ( // ErrParse means we couldn't parse the SQL text into an AST. ErrParse errs.Const = "parse SQL" // ErrDeparse means we couldn't turn an AST back into SQL. ErrDeparse errs.Const = "deparse SQL" )
Sentinel errors this package can return. Match them with errors.Is, not by string.
const ErrFingerprint errs.Const = "fingerprint SQL"
ErrFingerprint means we couldn't fingerprint the SQL text. Match it with errors.Is, not by string.
const ErrMarshal errs.Const = "marshal statement"
ErrMarshal means we couldn't marshal a normalized statement to JSON.
const ErrScan errs.Const = "scan SQL"
ErrScan means we couldn't scan the SQL text into tokens. Match it with errors.Is, not by string.
Variables ¶
This section is empty.
Functions ¶
func Comments ¶ added in v0.0.2
Comments returns the text of every comment in sql, both line (`-- …`) and block (`/* … */`), in source order. It's the basis for checking that a reformat preserved every comment. A lexical error comes back wrapped in ErrScan.
func Fingerprint ¶ added in v0.0.2
Fingerprint returns PostgreSQL's structural fingerprint of sql: two statements that mean the same thing modulo formatting, literal values, and case share a fingerprint. A parse failure comes back wrapped in ErrFingerprint.
func Parse ¶
func Parse(sql SQL) (*pg_query.ParseResult, error)
Parse turns SQL text into PostgreSQL's parse-result AST. If parsing fails, you get back an error wrapped in ErrParse.
func Scan ¶ added in v0.0.2
func Scan(sql SQL) (*pg_query.ScanResult, error)
Scan tokenizes SQL text into PostgreSQL's lexical tokens, each with its source offsets and keyword classification. Unlike Parse it doesn't require a well-formed statement, but a lexical error (an unterminated string, say) comes back wrapped in ErrScan.
func SortColumnLists ¶
func SortColumnLists(tree *pg_query.ParseResult)
SortColumnLists puts the column lists of INSERT … SELECT and simple SELECT target lists into a canonical order, in place, so two trees that mean the same thing compare equal.
It edits tree in place, so it's not safe to run concurrently on the same *pg_query.ParseResult — serialize the calls, or work on separate trees.
func ToJSON ¶
func ToJSON(result *pg_query.ParseResult) ([]json.RawMessage, error)
ToJSON converts a parse result to normalized JSON, one statement per entry. Within each statement the field order is canonical (keys sorted, zero values dropped) so two equivalent statements come out as identical JSON. A nil result gives you back a nil slice.
Types ¶
type SQL ¶
type SQL string
SQL is raw SQL text.
func Deparse ¶
func Deparse(tree *pg_query.ParseResult) (SQL, error)
Deparse turns an AST back into SQL text. If it fails, you get back an error wrapped in ErrDeparse.
func LowerKeywords ¶ added in v0.0.2
LowerKeywords lowercases every SQL keyword in text and leaves everything else — string literals, quoted identifiers, dollar-quoted bodies, numbers, operators — exactly as written. A lexical error comes back wrapped in ErrScan.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package compare tells you what changed between two SQL scripts, at the AST level.
|
Package compare tells you what changed between two SQL scripts, at the AST level. |
|
Package formatter renders PostgreSQL statements as canonically-styled SQL text.
|
Package formatter renders PostgreSQL statements as canonically-styled SQL text. |
|
doc
Package doc is a small Wadler/Prettier-style document algebra: you build an immutable layout tree out of Text, Concat, Group, Indent, and the line primitives, then Render it at a target width.
|
Package doc is a small Wadler/Prettier-style document algebra: you build an immutable layout tree out of Text, Concat, Group, Indent, and the line primitives, then Render it at a target width. |
|
normalize
|
|
|
plpgsql
Package plpgsql canonicalizes PL/pgSQL code so you can compare it for meaning rather than formatting.
|
Package plpgsql canonicalizes PL/pgSQL code so you can compare it for meaning rather than formatting. |
|
sql
Package sqlnorm canonicalizes SQL text so you can compare it for meaning rather than formatting.
|
Package sqlnorm canonicalizes SQL text so you can compare it for meaning rather than formatting. |