formatter

Documentation

Overview

Package formatter provides human-readable formatting for schema differences and comparison reports.

Overview

The formatter package takes schema differences and produces formatted output in various styles suitable for different use cases:

• Text: Plain text for console output
• Markdown: For documentation and pull requests
• JSON: For programmatic consumption
• HTML: For web interfaces (future)

Usage

Format differences as text:

diffs, _ := comparer.CompareSchemas(old, new, nil)
report := formatter.FormatText(diffs, &formatter.Options{
    ShowContext: true,
    Colorize:    true,
})
fmt.Println(report)

Format as markdown:

mdReport := formatter.FormatMarkdown(diffs, &formatter.Options{
    GroupByCategory: true,
    IncludeSummary:  true,
})
os.WriteFile("schema-changes.md", []byte(mdReport), 0644)

Format as JSON:

jsonReport := formatter.FormatJSON(diffs, &formatter.Options{
    PrettyPrint: true,
})

Text Output Features

• Color-coded severity (red for critical, yellow for warning)
• Grouped by category (tables, columns, indexes)
• Summary statistics (X tables added, Y columns modified)
• Optional context (schema names, object details)

Markdown Output Features

• Proper heading hierarchy
• Tables for structured data
• Code blocks for SQL snippets
• Emoji indicators for severity
• Collapsible sections for large reports

Formatting Options

Options control output format:

• ShowContext: Include schema and table context
• Colorize: Use ANSI color codes (text only)
• GroupByCategory: Group by object type vs chronological
• IncludeSummary: Add summary section
• Verbose: Include all details vs high-level overview

Use Cases

• Console output for developers
• Pull request descriptions
• Migration documentation
• Audit reports
• Automated notifications (Slack, email)

Index

• func FormatDiffAsJSON(mdiff *diff.MetadataDiff, pretty bool) (string, error)
• func FormatDiffAsMarkdown(mdiff *diff.MetadataDiff) string
• func FormatDiffAsSummaryJSON(mdiff *diff.MetadataDiff, pretty bool) (string, error)
• func FormatDiffAsText(mdiff *diff.MetadataDiff) string
• func FormatStrategyAsJSON(strategy *planner.MigrationStrategy, pretty bool) (string, error)
• func FormatStrategyAsMarkdown(strategy *planner.MigrationStrategy) string
• func FormatStrategyAsSummaryJSON(strategy *planner.MigrationStrategy, pretty bool) (string, error)
• func FormatStrategyAsText(strategy *planner.MigrationStrategy) string
• type DiffSummary
• type OperationSummary
• type StrategySummary

Functions

func FormatDiffAsJSON

func FormatDiffAsJSON(mdiff *diff.MetadataDiff, pretty bool) (string, error)

FormatDiffAsJSON formats a MetadataDiff as JSON.

func FormatDiffAsMarkdown

func FormatDiffAsMarkdown(mdiff *diff.MetadataDiff) string

FormatDiffAsMarkdown formats a MetadataDiff as Markdown.

func FormatDiffAsSummaryJSON

func FormatDiffAsSummaryJSON(mdiff *diff.MetadataDiff, pretty bool) (string, error)

FormatDiffAsSummaryJSON formats a MetadataDiff as a simplified JSON summary.

func FormatDiffAsText

func FormatDiffAsText(mdiff *diff.MetadataDiff) string

FormatDiffAsText formats a MetadataDiff as human-readable text.

func FormatStrategyAsJSON

func FormatStrategyAsJSON(strategy *planner.MigrationStrategy, pretty bool) (string, error)

FormatStrategyAsJSON formats a MigrationStrategy as JSON.

func FormatStrategyAsMarkdown

func FormatStrategyAsMarkdown(strategy *planner.MigrationStrategy) string

FormatStrategyAsMarkdown formats a MigrationStrategy as Markdown.

func FormatStrategyAsSummaryJSON

func FormatStrategyAsSummaryJSON(strategy *planner.MigrationStrategy, pretty bool) (string, error)

FormatStrategyAsSummaryJSON formats a MigrationStrategy as a simplified JSON summary.

func FormatStrategyAsText

func FormatStrategyAsText(strategy *planner.MigrationStrategy) string

FormatStrategyAsText formats a MigrationStrategy as human-readable text.

Types

type DiffSummary

type DiffSummary struct {
	Database     string                 `json:"database"`
	TotalChanges int                    `json:"totalChanges"`
	Summary      map[string]int         `json:"summary"`
	Changes      map[string]interface{} `json:"changes"`
}

DiffSummary is a simplified view of a MetadataDiff for JSON export.

type OperationSummary

type OperationSummary struct {
	ID           string   `json:"id"`
	Type         string   `json:"type"`
	Action       string   `json:"action"`
	Description  string   `json:"description"`
	Risk         string   `json:"risk"`
	Reversible   bool     `json:"reversible"`
	Warnings     []string `json:"warnings,omitempty"`
	Dependencies []string `json:"dependencies,omitempty"`
}

OperationSummary is a simplified operation for JSON export.

type StrategySummary

type StrategySummary struct {
	Engine             string             `json:"engine"`
	TotalOperations    int                `json:"totalOperations"`
	HighRiskCount      int                `json:"highRiskCount"`
	DataLossCount      int                `json:"dataLossCount"`
	RiskDistribution   map[string]int     `json:"riskDistribution"`
	OperationTypes     map[string]int     `json:"operationTypes"`
	Warnings           []string           `json:"warnings,omitempty"`
	HighRiskOperations []OperationSummary `json:"highRiskOperations,omitempty"`
	ExecutionOrder     []OperationSummary `json:"executionOrder"`
}

StrategySummary is a simplified view of a MigrationStrategy for JSON export.