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
- func Adopt(ctx context.Context, db *sql.DB, opts AdoptionOptions, options ...ApplyOption) (returnErr error)
- func Batches(name, content string) ([]string, error)
- type Adoption
- type AdoptionEvidence
- type AdoptionOptions
- type ApplyOption
- type Connection
- type ExecutionError
- type Function
- type Options
- type PlanBundle
- type PlanFile
- type PlanTarget
- type Result
- type SchemaStatement
- type SchemaStep
- type StalePlanError
Constants ¶
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.
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 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 ¶
func (*ExecutionError) Error ¶
func (e *ExecutionError) Error() string
func (*ExecutionError) Unwrap ¶
func (e *ExecutionError) Unwrap() error
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
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
Changed reports whether applying the plan changes anything beyond running its `runs: always` scripts.
func (PlanFile) Pretty ¶ added in v1.3.0
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.
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 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