README
¶
go-sql
PostgreSQL SQL parsing, canonical normalization, AST diffing, and formatting for Go — a thin, well-tested layer over pg_query_go.
Packages
| Import | Purpose |
|---|---|
github.com/gomatic/go-sql |
Parse SQL to a PostgreSQL AST, canonically order column lists, deparse back to SQL, and render statements as normalized JSON. |
github.com/gomatic/go-sql/formatter |
Format SQL text into a canonical, indented layout. |
github.com/gomatic/go-sql/compare |
Diff two SQL statements at the AST level, ignoring cosmetic differences. |
github.com/gomatic/go-sql/normalize/sql |
Normalize SQL text (whitespace, comments, column ordering) for canonical comparison. |
github.com/gomatic/go-sql/normalize/plpgsql |
Normalize PL/pgSQL function bodies, token by token. |
Errors
Every error a package can emit is a errs.Const sentinel — match with errors.Is, never by string:
tree, err := sql.Parse("not valid ((")
if errors.Is(err, sql.ErrParse) {
// ...
}
Build configuration is managed upstream
Makefile, .golangci.yaml, .editorconfig, .gitignore, scripts/, and .github/ are distributed and owned by nicerobot/tools.repository (sourced from nicerobot/tools.build/build/go/Makefile). Do not edit them in-tree — they are overwritten on the next push. Per-repo customization goes in a Makefile.local.
make check # vet, lint, staticcheck, govulncheck, 100% coverage gate
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 ¶
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 ErrMarshal errs.Const = "marshal statement"
ErrMarshal means we couldn't marshal a normalized statement to JSON.
Variables ¶
This section is empty.
Functions ¶
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 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.
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. |
|
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. |