output

type ConnectionStatus ¶

type ConnectionStatus string

ConnectionStatus reports whether the command reached a live cluster. Commands that never connect (version, parse, format) report ConnectionDisconnected.

const (
	ConnectionDisconnected ConnectionStatus = "disconnected"
	ConnectionConnected    ConnectionStatus = "connected"
)

type Envelope ¶

type Envelope struct {
	Tier             Tier             `json:"tier,omitempty"`
	ParserVersion    string           `json:"parser_version"`
	TargetVersion    string           `json:"target_version,omitempty"`
	ConnectionStatus ConnectionStatus `json:"connection_status"`
	Errors           []Error          `json:"errors,omitempty"`
	Data             json.RawMessage  `json:"data,omitempty"`
}

Envelope is the response contract every crdb-sql subcommand returns under --output=json.

Lifecycle: built fresh by the subcommand's RunE, marshalled once by Renderer.Render, then discarded. No long-lived state.

Field discipline:

• Tier uses omitempty so commands without tier semantics (e.g. version) omit the field rather than emitting a misleading empty string. This relies on TierUnset being the empty-string zero value.
• ParserVersion and ConnectionStatus are always emitted so agents can rely on their presence.
• TargetVersion uses omitempty so the field is absent when the user did not pass --target-version (or the equivalent MCP parameter). This preserves byte-identical output for the unflagged path.
• Errors uses omitempty so a clean run produces no errors key rather than a noisy "errors": null.
• Data is json.RawMessage so each subcommand controls its own payload marshalling and this package never depends on subcommand types.

type Error ¶

type Error struct {
	Code        string         `json:"code"`
	Severity    Severity       `json:"severity"`
	Message     string         `json:"message"`
	Position    *Position      `json:"position,omitempty"`
	Category    string         `json:"category,omitempty"`
	Context     map[string]any `json:"context,omitempty"`
	Suggestions []Suggestion   `json:"suggestions,omitempty"`
}

Error is the per-error schema agents consume; the fields are derived from the JSON example in docs/design_doc.md (search "Error output"). Code, Severity, and Message are required (every error has them); Position, Category, Context, and Suggestions are optional so early subcommands can populate only what they have. Richer enrichment lands with later issues.

func VersionMismatchWarning(parserVersion, targetVersion string) (Error, bool)

type Format ¶

type Format string

Format selects how a subcommand serializes its result.

text — human-readable, subcommand-defined layout (default).
json — Envelope marshalled as indented JSON.

const (
	FormatText Format = "text"
	FormatJSON Format = "json"
)

func ParseFormat(s string) (Format, error)

type Position ¶

type Position struct {
	Line       int `json:"line"`
	Column     int `json:"column"`
	ByteOffset int `json:"byte_offset"`
}

Position is a 1-based line/column with a 0-based byte offset, matching the convention used by the CockroachDB parser.

type Range ¶

type Range struct {
	Start int `json:"start"`
	End   int `json:"end"`
}

Range is a half-open byte range [Start, End) into the original input.

type Renderer ¶

type Renderer struct {
	Format Format
	Out    io.Writer
}

Renderer writes a subcommand's result in the selected format.

For FormatText, textFn owns the output: it receives the configured writer and produces whatever lines the subcommand wants (the envelope is ignored). For FormatJSON, the envelope is marshalled as indented JSON so piped output stays human-readable; agents that want compact form can pipe through `jq -c`. A trailing newline is appended so the output is a well-formed line on terminals.

EPIPE handling: write failures with errno EPIPE are suppressed (return nil) because they are the normal outcome when a downstream consumer closes stdout early (e.g. piping into `head -n1`). Surfacing them as a non-zero exit with a "broken pipe" message is hostile for a tool meant to be piped, and partial output is acceptable. Marshal errors and the unsupported-format error are NOT subject to EPIPE filtering — they are propagated unchanged. On Windows the native broken-pipe error has a different value (ERROR_BROKEN_PIPE), so this check would not fire there; Windows is not a supported target, so we don't add a separate branch.

func (r Renderer) Render(env Envelope, textFn func(io.Writer) error) error

func (r Renderer) RenderError(env Envelope, failure error) error

func (r Renderer) RenderErrorEntry(env Envelope, failure error, entry Error) error

type Severity ¶

type Severity string

Severity is the severity level of a structured Error. Values use the PostgreSQL frontend/backend protocol severity strings (uppercase) so wire output matches what agents see from a live cluster. Defining the set as named constants prevents subcommands from drifting between "ERROR"/"error"/"Error" as more error producers come online.

const (
	SeverityError   Severity = "ERROR"
	SeverityWarning Severity = "WARNING"
	SeverityNotice  Severity = "NOTICE"
	SeverityFatal   Severity = "FATAL"
	SeverityPanic   Severity = "PANIC"
)

type Suggestion ¶

type Suggestion struct {
	Replacement string  `json:"replacement"`
	Range       Range   `json:"range"`
	Confidence  float64 `json:"confidence"`
	Reason      string  `json:"reason"`
}

Suggestion is a structured fix proposal: replace bytes [Range.Start, Range.End) with Replacement. Confidence is in [0, 1]; Reason is a machine-readable label (e.g. "levenshtein_distance_1").

type Tier ¶

type Tier string

Tier identifies which analysis tier produced a response. The names and order match the "Three analysis tiers" section in docs/design_doc.md:

zero_config — Tier 1, expression type checking (zero-config).
schema_file — Tier 2, name resolution (requires schema files).
connected   — Tier 3, connected validation.

TierUnset is the zero value and indicates the command has no tier semantics (e.g. version).

const (
	TierUnset      Tier = ""
	TierZeroConfig Tier = "zero_config"
	TierSchemaFile Tier = "schema_file"
	TierConnected  Tier = "connected"
)