scripts

package
v1.3.1 Latest Latest
Warning

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

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

Documentation

Overview

Package scripts owns migration source identity, dependencies and consumed fingerprints.

Index

Constants

View Source
const AnalysisVersion = "2"

AnalysisVersion versions every cached analysis. Bump it whenever the analyser, the batch splitter or canonicalisation changes what it produces.

View Source
const SchemaWriter = "(schema)"

SchemaWriter is the writer the schema step is planned as.

Variables

This section is empty.

Functions

func AnalysisKey added in v1.3.0

func AnalysisKey(sql string, invokedModule bool) string

AnalysisKey is the content-addressed cache key of a body's analysis.

func Digest

func Digest(fields ...string) string

func InputHash

func InputHash(inputs map[string]string) string

func QuoteName

func QuoteName(name string) (string, error)

func SourceHash

func SourceHash(content string) string

func StateHash added in v1.3.0

func StateHash(s State) string

StateHash is the ledger hash of a state: its source, policy and inputs.

Types

type AfterApplyInput added in v1.3.0

type AfterApplyInput struct {
	Key     string   `json:"key"`
	Writers []string `json:"writers"`
}

AfterApplyInput is an input whose value is known only after Writers, the earlier selected scripts writing what it observes, have run: apply re-observes it after them instead of holding it to its planned value.

type Analysis

type Analysis struct {
	Calls              []string                  `json:"calls"`
	Builtins           []sqlglot.BuiltinFunction `json:"builtins,omitempty"`
	Blocked            []string                  `json:"blocked,omitempty"`
	Unresolved         []string                  `json:"unresolved,omitempty"`
	TransactionControl bool                      `json:"transactionControl,omitempty"`
	// Effects is what running the body does (see analyzeEffects); Defines
	// holds the body effects of each routine a script creates or alters.
	Effects Effects                `json:"effects"`
	Defines map[ObjectName]Effects `json:"defines,omitempty"`
}

func Analyze

func Analyze(opts AnalysisOptions) Analysis

Analyze visits executable expressions, leaving stored module bodies for catalog analysis, and reads the body's effects.

type AnalysisOptions

type AnalysisOptions struct {
	SQL           string
	InvokedModule bool
}

type CachedAnalysis added in v1.3.0

type CachedAnalysis struct {
	Analysis   Analysis `json:"analysis"`
	Canonical  string   `json:"canonical,omitempty"`
	BatchError string   `json:"batchError,omitempty"`
}

CachedAnalysis is what a backend stores for one body: its analysis, the canonical text of a module definition, and the batch error of a script body that does not split.

type Dependency

type Dependency struct {
	Kind string `json:"kind"`
	Name string `json:"name"`
}

type Effects added in v1.3.0

type Effects struct {
	Reads   []ObjectName `json:"reads,omitempty"`
	Writes  []ObjectName `json:"writes,omitempty"`
	Calls   []ObjectName `json:"calls,omitempty"`
	Unknown []string     `json:"unknown,omitempty"`
}

Effects is what a script, or a routine it reaches, does to the database: the objects it reads, writes (including routines it creates or alters) and calls. Unknown lists the statements whose effects could not be determined, as "line N: reason". Analyze reads them from a body with the sqlglot access package. A nil Effects means no inferred dependencies.

func (Effects) Normalized added in v1.3.0

func (e Effects) Normalized() Effects

Normalized returns e with each list sorted and de-duplicated, so equal effects encode, and hash, identically.

type LoadOptions

type LoadOptions struct {
	FS   fs.FS
	Dir  string
	Skip []string
}

type ObjectName added in v1.3.0

type ObjectName string

ObjectName is a schema-qualified database object a script reads, writes or calls: lower-cased "schema.name", with no kind, so a table, view, function or procedure of the same name is one object.

func NewObjectName added in v1.3.0

func NewObjectName(schema, name string) ObjectName

NewObjectName builds the canonical name of schema.name.

type Observation

type Observation struct {
	Kind  string `json:"kind"`
	Hash  string `json:"hash"`
	Error string `json:"error,omitempty"`
}

type Pending

type Pending struct {
	Script     Script            `json:"script"`
	State      State             `json:"state"`
	Selected   bool              `json:"selected"`
	Reasons    []string          `json:"reasons,omitempty"`
	Blocked    []string          `json:"blocked,omitempty"`
	Upstream   []UpstreamWrite   `json:"upstream,omitempty"`
	AfterApply []AfterApplyInput `json:"afterApply,omitempty"`
	// SelfWritten lists the input keys whose observed objects the script's
	// own writes reach: apply observes exactly these again after the script
	// runs, since a script must not change its own inputs.
	SelfWritten []string `json:"selfWritten,omitempty"`
	// EffectsUnknown lists the statements of the script, or of a routine it
	// reaches, whose effects could not be determined. Apply re-inspects the
	// plan after such a script runs.
	EffectsUnknown []string `json:"effectsUnknown,omitempty"`
}

func (Pending) AfterApplyKey added in v1.3.0

func (p Pending) AfterApplyKey(key string) bool

AfterApplyKey reports whether key is known only after apply.

type Phase

type Phase string
const (
	Pre  Phase = "pre"
	Post Phase = "post"
	// Version is the ledger state version this package records. Version 2
	// states (no EffectsHash) read as current; version 1 is the legacy
	// content-only ledger.
	Version = 3
)

type Plan

type Plan struct {
	Target   string    `json:"target"`
	Phase    Phase     `json:"phase"`
	Hash     string    `json:"hash"`
	Scripts  []Pending `json:"scripts"`
	Warnings []string  `json:"warnings,omitempty"`
}

func Build

func Build(opts PlanOptions) (Plan, error)

Build plans the bundle in Ordered order. With an empty phase it plans both phases in one pass; a phase filters the plan to that phase while still propagating every earlier script's writes.

type PlanOptions

type PlanOptions struct {
	Target string
	// Phase filters the plan to one phase; empty plans the whole bundle in
	// one pass, pre scripts first.
	Phase        Phase
	Scripts      []Script
	Recorded     map[string]State
	Observations map[string]map[string]Observation
	// Modules holds the effects of catalog routines, by name, so a call into
	// the catalog reaches what that routine reads and calls.
	Modules map[ObjectName]Effects
	// SchemaWrites are the declared objects the schema step between the pre
	// and post scripts changes; a post script reaching one is selected as an
	// upstream write of SchemaWriter.
	SchemaWrites []ObjectName
}

type Scalar

type Scalar struct {
	Type      string `json:"type"`
	Length    int64  `json:"length"`
	Precision int64  `json:"precision"`
	Scale     int64  `json:"scale"`
	Null      bool   `json:"null"`
	Value     string `json:"value"`
}

func (Scalar) Fingerprint

func (s Scalar) Fingerprint(invocation string) (string, error)

type Script

type Script struct {
	ID                   string       `json:"id"`
	Path                 string       `json:"path"`
	Name                 string       `json:"name"`
	SQL                  string       `json:"sql"`
	Phase                Phase        `json:"phase"`
	HeaderPhase          Phase        `json:"-"`
	Always               bool         `json:"always,omitempty"`
	NonTransactional     bool         `json:"nonTransactional,omitempty"`
	DependsOn            []string     `json:"dependsOn,omitempty"`
	Dependencies         []Dependency `json:"dependencies,omitempty"`
	ExplicitDependencies bool         `json:"explicitDependencies,omitempty"`
	ContextPolicy        string       `json:"contextPolicy,omitempty"`
	Effects              *Effects     `json:"effects,omitempty"`
	// Defines holds the body effects of each routine the script creates or
	// alters (each also listed in Effects.Writes). A script calling one of
	// them later in the bundle reaches these effects instead of the catalog's.
	Defines map[ObjectName]Effects `json:"defines,omitempty"`
}

func Load

func Load(opts LoadOptions) ([]Script, error)

func Ordered

func Ordered(items []Script) ([]Script, error)

func Parse

func Parse(name, content string) (Script, error)

type State

type State struct {
	Version    int    `json:"version"`
	SourceHash string `json:"sourceHash"`
	PolicyHash string `json:"policyHash"`
	// EffectsHash identifies the effects the script was planned with. It is
	// audit evidence only: Hash excludes it, so a changed analysis never
	// selects a script by itself.
	EffectsHash  string            `json:"effectsHash,omitempty"`
	Hash         string            `json:"hash"`
	Inputs       map[string]string `json:"inputs"`
	Outcome      string            `json:"outcome,omitempty"`
	EvidenceHash string            `json:"evidenceHash,omitempty"`
	Provenance   string            `json:"provenance,omitempty"`
	LastSuccess  *State            `json:"lastSuccess,omitempty"`
}

type UpstreamWrite added in v1.3.0

type UpstreamWrite struct {
	Object ObjectName `json:"object"`
	Script string     `json:"script"`
}

UpstreamWrite is an object a script's dependency closure reaches that an earlier selected script in the same plan writes.

Directories

Path Synopsis
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.
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.

Jump to

Keyboard shortcuts

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