package sqlcheck

import "ariga.io/atlas/sql/sqlcheck"

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) ForeignKeySpan(t *schema.Table, fk *schema.ForeignKey) 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

	// From, To holds the representation of schema
	// before and after the file was executed.
	From, To *schema.Realm

	// 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) ForeignKeySpan ¶

func (f *File) ForeignKeySpan(t *schema.Table, fk *schema.ForeignKey) ResourceSpan

ForeignKeySpan returns the span information for the foreign-key constraint.

func (*File) IndexSpan ¶

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

IndexSpan returns the span information for the index.

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 Analyzer.Analyze function that applies a specific analyzer to an SQL file.

type Report ¶

type Report struct {
	Text           string         `json:"Text"`                     // Report text.
	Desc           string         `json:"Desc,omitempty"`           // Optional description (secondary 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.

Source Files ¶

sqlcheck.go

Directories ¶