sqlserver

package
v1.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 21, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package sqlserver plans and applies dependency-aware scripts on SQL Server through a self-contained plan file: Plan observes the target once and writes what apply will do, and Apply runs exactly that plan, refusing it as stale when the target moved since.

Index

Constants

View Source
const (
	// PlanFileKind identifies a plan file among migration artifacts.
	PlanFileKind = "sqlglot-go/script-plan"
	// PlanFileVersion is the plan file format this package writes and reads.
	PlanFileVersion = 1
)

Variables

This section is empty.

Functions

func Adopt added in v1.3.0

func Adopt(ctx context.Context, db *sql.DB, opts AdoptionOptions, options ...ApplyOption) (returnErr error)

Adopt records independently verified current state without executing script bodies. It re-plans the adoption's plan file like Apply, refusing it as stale when the target moved; no script body runs, so each adopted script records the inputs that re-plan observed.

func Batches

func Batches(name, content string) ([]string, error)

Batches splits plain T-SQL at GO and rejects unsupported sqlcmd directives.

Types

type Adoption

type Adoption struct {
	Plan     PlanFile           `json:"plan"`
	Evidence []AdoptionEvidence `json:"evidence"`
	Hash     string             `json:"hash"`
}

Adoption is a plan file and the evidence that the target already holds the effect of some of its scripts.

func AdoptionPlan

func AdoptionPlan(plan PlanFile, evidence []AdoptionEvidence) (Adoption, error)

AdoptionPlan binds evidence to the scripts of plan it adopts.

type AdoptionEvidence

type AdoptionEvidence struct {
	ID         string `json:"id"`
	SourceHash string `json:"sourceHash"`
	Provenance string `json:"provenance"`
	Query      string `json:"query"`
	Expected   string `json:"expected"`
}

type AdoptionOptions

type AdoptionOptions struct {
	Adoption Adoption
	Verify   func(context.Context, Connection) error
}

type ApplyOption added in v1.3.0

type ApplyOption func(*applyConfig)

ApplyOption configures Apply and Adopt.

func WithAnalysisCache added in v1.3.0

func WithAnalysisCache(store cache.Store, ttl time.Duration) ApplyOption

WithAnalysisCache reuses script and module analyses across Plan and Apply, as Options.Analysis does for Plan.

func WithBarrier added in v1.3.0

func WithBarrier(fn func(context.Context, Connection) error) ApplyOption

WithBarrier runs fn on the locked apply connection after the schema step and before the post scripts, for deployment steps that belong between the phases. Its writes are not part of the plan.

type Connection

type Connection interface {
	// contains filtered or unexported methods
}

Connection is the locked SQL session a barrier runs on.

type ExecutionError

type ExecutionError struct {
	Outcome string
	Err     error
}

func (*ExecutionError) Error

func (e *ExecutionError) Error() string

func (*ExecutionError) Unwrap

func (e *ExecutionError) Unwrap() error

type Function

type Function struct {
	Name          string   `json:"name"`
	Type          string   `json:"type"`
	Nullable      bool     `json:"nullable"`
	Prerequisites []string `json:"prerequisites,omitempty"`
}

type Options

type Options struct {
	DB        *sql.DB
	Scope     string
	Scripts   []scripts.Script
	Functions []Function
	// Schema is the declared-schema reconciliation that runs between the pre
	// and post scripts; nil when the bundle declares no objects.
	Schema *SchemaStep
	// Analysis caches script and module-definition analyses by content
	// (scripts.AnalysisKey); nil analyses every body on every call.
	Analysis cache.Store
	// AnalysisTTL is the expiry of each analysis written to Analysis; zero
	// writes without expiry.
	AnalysisTTL time.Duration
	// contains filtered or unexported fields
}

type PlanBundle added in v1.3.0

type PlanBundle struct {
	Scripts   []scripts.Script `json:"scripts"`
	Functions []Function       `json:"functions,omitempty"`
	Schema    *SchemaStep      `json:"schema,omitempty"`
}

PlanBundle is everything apply needs to run the plan without the sources: the prepared scripts with their SQL and effects, the registered functions and the declared-schema step.

type PlanFile added in v1.3.0

type PlanFile struct {
	Kind         string                   `json:"kind"`
	Version      int                      `json:"version"`
	Target       PlanTarget               `json:"target"`
	Bundle       PlanBundle               `json:"bundle"`
	Ledger       map[string]scripts.State `json:"ledger"`
	Observations map[string]string        `json:"observations"`
	Actions      []scripts.Pending        `json:"actions"`
	Warnings     []string                 `json:"warnings,omitempty"`
	Hash         string                   `json:"hash"`
}

PlanFile is a self-contained, terraform-style plan: what the target looked like (its ledger and every observed input) and the ordered actions apply takes. Hash covers every other field; it guards the file's integrity and nothing else.

func Plan added in v1.3.0

func Plan(ctx context.Context, opts Options) (PlanFile, error)

Plan observes the target once, without creating metadata or running anything, and returns the plan file Apply runs: every script of the bundle, pre scripts before post scripts, planned in one pass, and the schema step between them. A script reaching what an earlier selected script, or the schema step, writes is selected as an upstream write.

func (PlanFile) Changed added in v1.3.0

func (p PlanFile) Changed() bool

Changed reports whether applying the plan changes anything beyond running its `runs: always` scripts.

func (PlanFile) Pretty added in v1.3.0

func (p PlanFile) Pretty() api.Text

Pretty renders the plan terraform-style: each phase's scripts as + run (new), ~ re-run with its reasons, ! blocked and ? effects unknown, the schema step between the phases, the warnings and the totals.

func (PlanFile) Selected added in v1.3.0

func (p PlanFile) Selected() []string

Selected lists the scripts the plan runs, in order.

func (PlanFile) Verify added in v1.3.0

func (p PlanFile) Verify() error

Verify checks the file's kind, version and integrity hash.

type PlanTarget added in v1.3.0

type PlanTarget struct {
	Server   string `json:"server"`
	Database string `json:"database"`
	Scope    string `json:"scope"`
}

PlanTarget is the database a plan was made for.

func (PlanTarget) String added in v1.3.0

func (t PlanTarget) String() string

type Result

type Result struct {
	// Outcome is applied, already-applied, stale, failed, or the outcome of the
	// script that failed (partial or commit-unknown).
	Outcome string   `json:"outcome"`
	Applied []string `json:"applied"`
	// Schema is applied when the schema step ran statements.
	Schema string `json:"schema,omitempty"`
	// Blocked lists the scripts the plan left blocked.
	Blocked []string `json:"blocked,omitempty"`
}

func Apply added in v1.3.0

func Apply(ctx context.Context, db *sql.DB, file PlanFile, options ...ApplyOption) (result Result, returnErr error)

Apply runs file on db: it verifies the file's integrity and target, re-plans its bundle against the target and refuses the file with a StalePlanError when the ledger, an observed input or a selection moved since, before anything runs. It then runs the selected pre scripts, the schema step, any WithBarrier step and the selected post scripts, on one locked connection. An input an upstream script in the plan writes is re-observed once after that writer; every other input holds its planned value. A script with unknown effects is followed by a re-plan, and work the file did not plan stops the apply with a StalePlanError: the scripts it already committed stay recorded, and a new plan covers the rest.

type SchemaStatement added in v1.3.0

type SchemaStatement struct {
	SQL         string `json:"sql"`
	Comment     string `json:"comment,omitempty"`
	Destructive bool   `json:"destructive,omitempty"`
}

type SchemaStep added in v1.3.0

type SchemaStep struct {
	// Objects are the declared tables and routines, schema-qualified.
	Objects    []string          `json:"objects"`
	Statements []SchemaStatement `json:"statements"`
}

SchemaStep is the reviewed reconciliation of the bundle's declared tables and routines: the statements apply runs between the pre and post scripts, planned against the declared objects as the plan observed them.

type StalePlanError added in v1.3.0

type StalePlanError struct {
	Moved []string `json:"moved"`
}

StalePlanError refuses a plan whose target moved since it was made.

func (*StalePlanError) Error added in v1.3.0

func (e *StalePlanError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL