Documentation
¶
Overview ¶
Package cli defines the pg-sprite command tree (Kong): migrate and status (the optimistic front door), diff and fmt (the declarative front door), and lint and suggest (the offline checker and advisor).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrLintFindings = errors.New("lint found errors")
ErrLintFindings is returned by lint when the script has error-severity findings, so the process exits non-zero; warnings alone pass.
Functions ¶
This section is empty.
Types ¶
type CLI ¶
type CLI struct {
Version kong.VersionFlag `help:"Print version and exit."`
Migrate MigrateCmd `cmd:"" help:"Run a schema change safely."`
Diff DiffCmd `cmd:"" help:"Diff a desired-state schema file against the live schema."`
Fmt FmtCmd `cmd:"" help:"Canonicalize a schema file."`
Lint LintCmd `cmd:"" help:"Lint DDL for unsafe patterns."`
Suggest SuggestCmd `cmd:"" help:"Recommend safer native forms for risky DDL."`
Status StatusCmd `cmd:"" help:"Report the status of a running schema change."`
}
CLI is the root command tree.
type DBFlags ¶
type DBFlags struct {
URL string `help:"PostgreSQL connection URL or key=value DSN." env:"PGSPRITE_URL" required:""`
CACert string `` /* 153-byte string literal not displayed */
LockTimeout time.Duration `help:"Session lock_timeout applied to every statement." default:"3s"`
StatementTimeout time.Duration `help:"Session statement_timeout applied to every statement." default:"30s"`
Debug bool `help:"Log statement-level tracing and lifecycle diagnostics to stderr."`
// contains filtered or unexported fields
}
DBFlags are the connection flags shared by every command that talks to the database, so every entry point carries the same bounded session defaults.
type DiffCmd ¶
type DiffCmd struct {
DBFlags `embed:""`
OutputFlags `embed:""`
Desired string `help:"Path to the desired-state CREATE TABLE .sql file." name:"desired" type:"existingfile" required:""`
Schema string `help:"Schema containing the live table." default:"public"`
JSON bool `help:"Emit the plan as JSON."`
SQL bool `help:"Print the plan as an executable SQL script instead of the diagnostic report."`
}
DiffCmd derives statements from a desired-state schema (declarative front-end): introspect the live table, materialize the desired state on a rolled-back scratch schema, and print the ordered plan without executing anything.
type FmtCmd ¶
type FmtCmd struct {
Path string `arg:"" optional:"" help:"Schema file to format; stdin when omitted." type:"existingfile"`
}
FmtCmd canonicalizes a schema file. It is offline — no database flags.
type LintCmd ¶
type LintCmd struct {
OutputFlags `embed:""`
Path string `arg:"" optional:"" help:"DDL file to lint; stdin when omitted." type:"existingfile"`
JSON bool `help:"Emit the findings report as JSON."`
}
LintCmd checks a DDL script for patterns the engine would refuse, rewrite, or gate. It is offline — no database flags.
type MigrateCmd ¶
type MigrateCmd struct {
DBFlags `embed:""`
OutputFlags `embed:""`
Alter string `help:"Imperative ALTER statement to run." name:"alter" required:""`
MaxTableSize byteSize `` /* 310-byte string literal not displayed */
IndexBuildTimeout time.Duration `` /* 137-byte string literal not displayed */
ValidateTimeout time.Duration `` /* 134-byte string literal not displayed */
Force string `` /* 427-byte string literal not displayed */
LockAttempts int `help:"Maximum bounded attempts when native DDL exceeds lock_timeout; 1 disables retry." default:"3"`
LockBackoff time.Duration `help:"Initial exponential backoff between lock-timeout attempts." default:"100ms"`
LockBackoffMax time.Duration `help:"Maximum exponential backoff between lock-timeout attempts." default:"1s"`
DryRun bool `help:"Classify and route the statement, print the plan, and execute nothing."`
JSON bool `help:"Emit the verdict (or dry-run plan) as JSON."`
}
MigrateCmd runs a schema change (imperative front-end): classify the statement, substitute the planner's safer native sequence by default when the submitted form blocks, and execute every step under bounded budgets. Everything the engine cannot run safely is refused with an explicit verdict.
func (*MigrateCmd) Validate ¶
func (c *MigrateCmd) Validate() error
Validate rejects flag combinations with no coherent meaning. A dry run reports the plan pg-sprite would execute without an override, so --force has nothing to acknowledge there; accepting it would let a forced apply ship with a dry run that reported a refusal it never checked.
type OutputFlags ¶
type OutputFlags struct {
Color string `` /* 196-byte string literal not displayed */
}
OutputFlags are the presentation flags shared by every command that renders a human-facing diagnostic report. Color never touches the machine contracts: the JSON reports and the --sql script stay plain.
type SuggestCmd ¶
type SuggestCmd struct {
OutputFlags `embed:""`
Path string `arg:"" optional:"" help:"DDL file to advise on; stdin when omitted." type:"existingfile"`
JSON bool `help:"Emit the suggestions report as JSON."`
}
SuggestCmd maps risky-as-written DDL to the safer native form the engine would run instead, with typed caveats. It is offline and advisory — no database flags, nothing executes, and it always exits zero.
Source Files