sqlcheck

Documentation

Overview

Package sqlcheck provides interfaces for analyzing the contents of SQL files to generate insights on the safety of many kinds of changes to database schemas. With this package developers may define an Analyzer that can be used to diagnose the impact of SQL statements on the target database. For instance, The `destructive` package exposes an Analyzer that detects destructive changes to the database schema, such as the dropping of tables or columns.

Index

• func Code(code string) string
• func Register(name string, f func(*schemahcl.Resource) ([]Analyzer, error))
• type Analyzer
  • func AnalyzerFor(name string, r *schemahcl.Resource) ([]Analyzer, error)
• type AnalyzerFunc
  • func (f AnalyzerFunc) Analyze(ctx context.Context, p *Pass) error
• type Analyzers
  • func (a Analyzers) Analyze(ctx context.Context, p *Pass) error
• type Change
• type Diagnostic
  • func (d *Diagnostic) SuggestFix(m string, e *TextEdit)
• type File
  • func (f *File) ColumnSpan(t *schema.Table, c *schema.Column) ResourceSpan
  • func (f *File) IndexSpan(t *schema.Table, i *schema.Index) ResourceSpan
  • func (f *File) SchemaSpan(s *schema.Schema) ResourceSpan
  • func (f *File) TableSpan(t *schema.Table) ResourceSpan
• type NamedAnalyzer
• type Options
• type Pass
• type Report
• type ReportWriter
• type ReportWriterFunc
  • func (f ReportWriterFunc) WriteReport(r Report)
• type ResourceSpan
• type SuggestedFix
• type TextEdit

Functions

func Code

func Code(code string) string

Code stores the given code in the registry. It protects from duplicate analyzers' codes.

func Register

func Register(name string, f func(*schemahcl.Resource) ([]Analyzer, error))

Register allows drivers to register a constructor function for creating analyzers from the given HCL resource.

Types

type Analyzer

type Analyzer interface {
	// Analyze executes the analysis function.
	Analyze(context.Context, *Pass) error
}

An Analyzer describes a migration file analyzer.

func AnalyzerFor

func AnalyzerFor(name string, r *schemahcl.Resource) ([]Analyzer, error)

AnalyzerFor instantiates a new Analyzer from the given HCL resource based on the registered constructor function.

type AnalyzerFunc

type AnalyzerFunc func(ctx context.Context, p *Pass) error

AnalyzerFunc allows using ordinary functions as analyzers.

func (AnalyzerFunc) Analyze

func (f AnalyzerFunc) Analyze(ctx context.Context, p *Pass) error

Analyze calls f.

type Analyzers

type Analyzers []Analyzer

Analyzers implements Analyzer.

func (Analyzers) Analyze

func (a Analyzers) Analyze(ctx context.Context, p *Pass) error

Analyze implements Analyzer.

type Change

type Change struct {
	schema.Changes               // The actual changes.
	Stmt           *migrate.Stmt // The SQL statement generated this change.
}

A Change in a migration file.

type Diagnostic

type Diagnostic struct {
	Pos            int            `json:"Pos"`                      // Diagnostic position.
	Text           string         `json:"Text"`                     // Diagnostic text.
	Code           string         `json:"Code"`                     // Code describes the check. For example, DS101
	SuggestedFixes []SuggestedFix `json:"SuggestedFixes,omitempty"` // Fixes to this specific diagnostics (statement-level).
}

A Diagnostic is a text associated with a specific position of a statement in a file.

func (*Diagnostic) SuggestFix

func (d *Diagnostic) SuggestFix(m string, e *TextEdit)

SuggestFix appends a suggested fix to the diagnostic.

type File

type File struct {
	migrate.File

	// Changes represents the list of changes this file represents.
	Changes []*Change

	// Sum represents a summary of changes this file represents. For example,
	// in case of a file that contains exactly two statements, and the first
	// statement is reverted by the one after it, the Sum is nil.
	Sum schema.Changes

	// A Parser that may be used for parsing this file. It sets to any as the contract
	// between checks and their parsers can vary. For example, in case of running checks
	// from CLI, the injected parser can be found in cmd/atlas/internal/sqlparse.Parser.
	Parser any
	// contains filtered or unexported fields
}

File represents a parsed version of a migration file.

func (*File) ColumnSpan

func (f *File) ColumnSpan(t *schema.Table, c *schema.Column) ResourceSpan

ColumnSpan returns the span information for the column.

func (*File) IndexSpan

func (f *File) IndexSpan(t *schema.Table, i *schema.Index) ResourceSpan

IndexSpan returns the span information for the span.

func (*File) SchemaSpan

func (f *File) SchemaSpan(s *schema.Schema) ResourceSpan

SchemaSpan returns the span information for the schema.

func (*File) TableSpan

func (f *File) TableSpan(t *schema.Table) ResourceSpan

TableSpan returns the span information for the table.

type NamedAnalyzer

type NamedAnalyzer interface {
	Analyzer
	// Name of the analyzer. Identifies the analyzer
	// in configuration and linting passes.
	Name() string
}

A NamedAnalyzer describes an Analyzer that has a name.

type Options

type Options struct {
	// Error indicates if an analyzer should
	// error in case a Diagnostic was found.
	Error *bool `spec:"error"`

	// Allow drivers to extend the configuration.
	schemahcl.DefaultExtension
}

Options defines a generic configuration options for analyzers.

type Pass

type Pass struct {
	// A migration file and the changes it describes.
	File *File

	// Dev is a driver-specific environment used to execute analysis work.
	Dev *sqlclient.Client

	// Report reports analysis reports.
	Reporter ReportWriter
}

A Pass provides information to the Run function that applies a specific analyzer to an SQL file.

type Report

type Report struct {
	Text           string         `json:"Text"`                     // Report text.
	Diagnostics    []Diagnostic   `json:"Diagnostics,omitempty"`    // Report diagnostics.
	SuggestedFixes []SuggestedFix `json:"SuggestedFixes,omitempty"` // Report-level suggested fixes.
}

A Report describes an analysis report with an optional specific diagnostic.

type ReportWriter

type ReportWriter interface {
	WriteReport(Report)
}

ReportWriter represents a writer for analysis reports.

type ReportWriterFunc

type ReportWriterFunc func(Report)

ReportWriterFunc is a function that implements Reporter.

func (ReportWriterFunc) WriteReport

func (f ReportWriterFunc) WriteReport(r Report)

WriteReport calls f(r).

type ResourceSpan

type ResourceSpan uint

ResourceSpan describes the lifespan of a resource in perspective to the migration file.

const (
	// SpanUnknown describes unknown lifespan.
	// e.g. resource may exist before this file.
	SpanUnknown ResourceSpan = iota

	// SpanAdded describes that a span of
	// a resource was started in this file.
	SpanAdded

	// SpanDropped describes that a span of
	// a resource was ended in this file.
	SpanDropped

	// SpanTemporary indicates that a resource lifetime
	// was started and ended in this file (CREATE and DROP).
	SpanTemporary = SpanAdded | SpanDropped
)

type SuggestedFix

type SuggestedFix struct {
	Message  string    `json:"Message"`
	TextEdit *TextEdit `json:"TextEdit,omitempty"`
}

A SuggestedFix is a change associated with a diagnostic that can be applied to fix the issue. Both the message and the text edit are optional.

type TextEdit

type TextEdit struct {
	Line    int    `json:"Line"`    // Start line to edit.
	End     int    `json:"End"`     // End line to edit.
	NewText string `json:"NewText"` // New text to replace.
}

A TextEdit represents a code changes in a file. The suggested edits are line-based starting from 1.