compare

Documentation

Overview

Package compare tells you what changed between two SQL scripts, at the AST level. It parses both inputs with the root sql package, normalizes each statement to a canonical JSON form (with positional metadata stripped), pairs statements up by a type-specific identity, and reports which statements were added, removed, and changed going from source to target.

Identity is what makes two statements "the same object" across the two scripts: a CREATE TABLE is keyed by its qualified name, an ALTER TABLE by its table plus the column or constraint it touches, a GRANT by object and grantee, and so on. If a statement's type has no handler, or we can't derive its identity, we skip it.

sql: github.com/gomatic/go-sql

Index

• Constants
• type Diff
• type Result
  • func Compare(source, target sql.SQL) (Result, error)
  • func (r Result) HasChanges() bool
• type StatementResult

Constants

const (
	// ErrConvert means we couldn't render a parsed AST to JSON.
	ErrConvert errs.Const = "convert AST"
	// ErrDecode means we couldn't decode a normalized statement.
	ErrDecode errs.Const = "decode statement"
)

Sentinel errors this package can return. Match them with errors.Is, not by string. A parse failure comes straight through as the root package's sql.ErrParse, unwrapped.

Types

type Diff

type Diff struct {
	Source any    `json:"source"`
	Target any    `json:"target"`
	Field  string `json:"field"`
}

Diff is one field-level difference between two statements. Source or Target is nil when the field only exists on one side.

type Result

type Result struct {
	Added   []StatementResult `json:"added"`
	Changed []StatementResult `json:"changed"`
	Removed []StatementResult `json:"removed"`
}

Result is what you get back from comparing a source script against a target script. Its JSON shape is stable: three statement lists, each under its own lowercase key. A statement that shows up only in the target is Added, one only in the source is Removed, and one in both with different content is Changed.

func Compare

func Compare(source, target sql.SQL) (Result, error)

Compare parses source and target SQL and tells you what changed at the statement level: which statements were added, removed, or changed going from source to target. A parse failure comes back as sql.ErrParse. Finding differences isn't an error — look at the returned Result.

func (Result) HasChanges

func (r Result) HasChanges() bool

HasChanges tells you whether the comparison found any difference at all.

type StatementResult

type StatementResult struct {
	Statement map[string]any `json:"statement,omitempty"`
	Identity  string         `json:"identity"`
	Type      string         `json:"type"`
	Diffs     []Diff         `json:"diffs,omitempty"`
}

StatementResult describes one statement in a Result. For added and removed statements, Statement carries the whole decoded statement; for changed ones, Diffs carries the field-level differences and Statement is empty.