feat: exposed the support for EXPLAIN ANALYZE

Author: radim

cmd/baseline.go

@@ -11,20 +11,24 @@ import (
 var (
 	baselineCwd       string
 	baselineRunFilter string
+	baselineAnalyze   bool
 
 	// baselineCmd represents the baseline command
 	baselineCmd = &cobra.Command{
 		Use:   "baseline [flags]",
 		Short: "Creates baseline EXPLAIN analysis for queries",
 		Long: `Creates baseline EXPLAIN analysis for all queries in the suite.
 This command executes EXPLAIN for each query and stores the query plan
-metrics (costs, timing, rows) in JSON files under the baselines directory.`,
+metrics (costs, timing, rows) in JSON files under the baselines directory.
+
+Use --analyze to create baselines with EXPLAIN (ANALYZE, BUFFERS) which
+captures actual buffer I/O counts for deterministic regression detection.`,
 		Run: func(cmd *cobra.Command, args []string) {
 			if err := checkDirectory(baselineCwd); err != nil {
 				fmt.Print(err.Error())
 				os.Exit(1)
 			}
-			regresql.BaselineQueries(baselineCwd, baselineRunFilter)
+			regresql.BaselineQueries(baselineCwd, baselineRunFilter, baselineAnalyze)
 		},
 	}
 )
@@ -34,4 +38,5 @@ func init() {
 
 	baselineCmd.Flags().StringVarP(&baselineCwd, "cwd", "C", ".", "Change to Directory")
 	baselineCmd.Flags().StringVar(&baselineRunFilter, "run", "", "Run only queries matching regexp (matches file names and query names)")
+	baselineCmd.Flags().BoolVar(&baselineAnalyze, "analyze", false, "Use EXPLAIN (ANALYZE, BUFFERS) for baselines")
 }

regresql/baseline.go

@@ -16,13 +16,29 @@ import (
 // for query costs compared to baseline (10% = queries can cost up to 110% of baseline)
 const DefaultCostThresholdPercent = 10.0
 
-// Baseline stores the EXPLAIN analysis results for a query
-type Baseline struct {
-	Query         string          `json:"query"`
-	Timestamp     string          `json:"timestamp"`
-	Plan          map[string]any  `json:"plan"`
-	PlanSignature *PlanSignature  `json:"plan_signature,omitempty"` // Optional for backwards compatibility
-}
+type (
+	Baseline struct {
+		Query         string          `json:"query"`
+		Timestamp     string          `json:"timestamp"`
+		Plan          map[string]any  `json:"plan"`
+		PlanSignature *PlanSignature  `json:"plan_signature,omitempty"`
+		AnalyzeMode   bool            `json:"analyze_mode,omitempty"`
+		Buffers       *BufferBaseline `json:"buffers,omitempty"`
+		Actuals       *ActualBaseline `json:"actuals,omitempty"`
+	}
+
+	BufferBaseline struct {
+		SharedHitBlocks  int64 `json:"shared_hit_blocks"`
+		SharedReadBlocks int64 `json:"shared_read_blocks"`
+		TotalBuffers     int64 `json:"total_buffers"`
+	}
+
+	ActualBaseline struct {
+		ActualRows      float64 `json:"actual_rows"`
+		PlanRows        float64 `json:"plan_rows"`
+		ExecutionTimeMs float64 `json:"execution_time_ms"`
+	}
+)
 
 // GetBaselinePath returns the path where baseline JSON file should be stored
 func getBaselinePath(q *Query, baselineDir string, bindingName string) string {
@@ -91,7 +107,7 @@ func ExecuteExplainWithOptions(q Querier, query string, opts ExplainOptions, arg
 	return &plans[0], nil
 }
 
-func (q *Query) CreateBaseline(baselineDir string, planDir string, db *sql.DB) error {
+func (q *Query) CreateBaseline(baselineDir string, planDir string, db *sql.DB, useAnalyze bool) error {
 	var plan *Plan
 	var err error
 
@@ -108,7 +124,7 @@ func (q *Query) CreateBaseline(baselineDir string, planDir string, db *sql.DB) e
 		}
 	}
 
-	baselines, fullPlans, err := plan.CreateBaselines(db)
+	baselines, fullPlans, err := plan.CreateBaselines(db, useAnalyze)
 	if err != nil {
 		return err
 	}
@@ -119,15 +135,15 @@ func (q *Query) CreateBaseline(baselineDir string, planDir string, db *sql.DB) e
 		if i < len(fullPlans) {
 			fullPlan = fullPlans[i]
 		}
-		if err := writeBaselineFile(baseline.Query, baselinePath, baseline.Plan, fullPlan); err != nil {
+		if err := writeBaselineFile(baseline.Query, baselinePath, baseline.Plan, fullPlan, useAnalyze); err != nil {
 			return err
 		}
 	}
 
 	return nil
 }
 
-func writeBaselineFile(queryName, baselinePath string, filteredPlan map[string]any, fullExplainPlan *ExplainOutput) error {
+func writeBaselineFile(queryName, baselinePath string, filteredPlan map[string]any, fullExplainPlan *ExplainOutput, useAnalyze bool) error {
 	var planSignature *PlanSignature
 	if fullExplainPlan != nil {
 		planSignature = ExtractPlanSignatureFromNode(&fullExplainPlan.Plan)
@@ -140,6 +156,20 @@ func writeBaselineFile(queryName, baselinePath string, filteredPlan map[string]a
 		PlanSignature: planSignature,
 	}
 
+	if useAnalyze && fullExplainPlan != nil {
+		baseline.AnalyzeMode = true
+		baseline.Buffers = &BufferBaseline{
+			SharedHitBlocks:  fullExplainPlan.Plan.SharedHitBlocks,
+			SharedReadBlocks: fullExplainPlan.Plan.SharedReadBlocks,
+			TotalBuffers:     fullExplainPlan.Plan.SharedHitBlocks + fullExplainPlan.Plan.SharedReadBlocks,
+		}
+		baseline.Actuals = &ActualBaseline{
+			ActualRows:      fullExplainPlan.Plan.ActualRows,
+			PlanRows:        fullExplainPlan.Plan.PlanRows,
+			ExecutionTimeMs: fullExplainPlan.ExecutionTime,
+		}
+	}
+
 	jsonBytes, err := json.MarshalIndent(baseline, "", "  ")
 	if err != nil {
 		return fmt.Errorf("failed to marshal baseline to JSON: %w", err)
@@ -149,12 +179,15 @@ func writeBaselineFile(queryName, baselinePath string, filteredPlan map[string]a
 		return fmt.Errorf("failed to write baseline JSON: %w", err)
 	}
 
-	fmt.Printf("  Created baseline: %s\n", filepath.Base(baselinePath))
+	mode := ""
+	if useAnalyze {
+		mode = " [analyze]"
+	}
+	fmt.Printf("  Created baseline: %s%s\n", filepath.Base(baselinePath), mode)
 	return nil
 }
 
-// BaselineQueries creates baselines for all queries in the suite
-func BaselineQueries(root string, runFilter string) {
+func BaselineQueries(root string, runFilter string, analyzeOverride bool) {
 	config, err := ReadConfig(root)
 	ignorePatterns := []string{}
 	if err == nil {
@@ -168,6 +201,8 @@ func BaselineQueries(root string, runFilter string) {
 		fmt.Printf("Error reading config: %s\n", err.Error())
 		os.Exit(3)
 	}
+	SetGlobalConfig(config)
+	useAnalyze := analyzeOverride || IsAnalyzeEnabled()
 
 	if err := TestConnectionString(config.PgUri); err != nil {
 		fmt.Printf("Error connecting to database: %s\n", err.Error())
@@ -189,7 +224,11 @@ func BaselineQueries(root string, runFilter string) {
 		os.Exit(11)
 	}
 
-	fmt.Println("\nCreating baselines for queries:")
+	mode := "cost-based"
+	if useAnalyze {
+		mode = "analyze (buffers)"
+	}
+	fmt.Printf("\nCreating baselines for queries (%s):\n", mode)
 
 	for _, folder := range suite.Dirs {
 		folderBaselineDir := filepath.Join(baselineDir, folder.Dir)
@@ -227,7 +266,7 @@ func BaselineQueries(root string, runFilter string) {
 					continue
 				}
 
-				if err := q.CreateBaseline(folderBaselineDir, folderPlanDir, db); err != nil {
+				if err := q.CreateBaseline(folderBaselineDir, folderPlanDir, db, useAnalyze); err != nil {
 					fmt.Printf("  Error creating baseline for %s: %s\n", q.Name, err.Error())
 				}
 			}
@@ -265,3 +304,14 @@ func CompareCost(actualCost, baselineCost, thresholdPercent float64) (bool, floa
 
 	return isOk, percentageIncrease
 }
+
+func CompareBuffers(actualBuffers, baselineBuffers int64, thresholdPercent float64) (bool, float64) {
+	if baselineBuffers == 0 {
+		return actualBuffers == 0, 0
+	}
+
+	percentageIncrease := (float64(actualBuffers-baselineBuffers) / float64(baselineBuffers)) * 100
+	isOk := percentageIncrease <= thresholdPercent
+
+	return isOk, percentageIncrease
+}

regresql/config.go

@@ -16,6 +16,13 @@ type (
 		PlanQuality    *PlanQualityGlobal    `yaml:"plan_quality,omitempty"`
 		DiffComparison *DiffComparisonGlobal `yaml:"diff_comparison,omitempty"`
 		Snapshot       *SnapshotConfig       `yaml:"snapshot,omitempty"`
+		Analyze        *AnalyzeConfig        `yaml:"analyze,omitempty"`
+	}
+
+	AnalyzeConfig struct {
+		Enabled         bool    `yaml:"enabled"`
+		BufferThreshold float64 `yaml:"buffer_threshold,omitempty"` // default: 2.0
+		CostThreshold   float64 `yaml:"cost_threshold,omitempty"`   // default: 10.0
 	}
 
 	PlanQualityGlobal struct {
@@ -169,3 +176,38 @@ func GetDiffConfig() *DiffConfig {
 	}
 	return cfg
 }
+
+func GetAnalyzeConfig() *AnalyzeConfig {
+	if cachedConfig == nil || cachedConfig.Analyze == nil {
+		return &AnalyzeConfig{
+			Enabled:         false,
+			BufferThreshold: 2.0,
+			CostThreshold:   10.0,
+		}
+	}
+	cfg := cachedConfig.Analyze
+	result := &AnalyzeConfig{
+		Enabled:         cfg.Enabled,
+		BufferThreshold: cfg.BufferThreshold,
+		CostThreshold:   cfg.CostThreshold,
+	}
+	if result.BufferThreshold == 0 {
+		result.BufferThreshold = 2.0
+	}
+	if result.CostThreshold == 0 {
+		result.CostThreshold = 10.0
+	}
+	return result
+}
+
+func IsAnalyzeEnabled() bool {
+	return GetAnalyzeConfig().Enabled
+}
+
+func GetBufferThreshold() float64 {
+	return GetAnalyzeConfig().BufferThreshold
+}
+
+func GetCostThreshold() float64 {
+	return GetAnalyzeConfig().CostThreshold
+}

regresql/formatter_console.go

@@ -92,9 +92,17 @@ func (f *ConsoleFormatter) AddResult(r TestResult, w io.Writer) error {
 }
 
 func (f *ConsoleFormatter) printCostFailure(r TestResult, w io.Writer) {
-	fmt.Fprintf(w, "  Expected cost: %.2f\n", r.ExpectedCost)
-	fmt.Fprintf(w, "  Actual cost:   %.2f (+%.1f%%)\n", r.ActualCost, r.PercentIncrease)
-	fmt.Fprintln(w)
+	if r.AnalyzeMode {
+		fmt.Fprintf(w, "  Expected buffers: %d\n", r.BaselineBuffers)
+		fmt.Fprintf(w, "  Actual buffers:   %d (+%.1f%%)\n", r.ActualBuffers, r.BufferIncrease)
+		fmt.Fprintln(w)
+		fmt.Fprintf(w, "  Cost (info):      %.2f (baseline: %.2f)\n", r.ActualCost, r.ExpectedCost)
+		fmt.Fprintln(w)
+	} else {
+		fmt.Fprintf(w, "  Expected cost: %.2f\n", r.ExpectedCost)
+		fmt.Fprintf(w, "  Actual cost:   %.2f (+%.1f%%)\n", r.ActualCost, r.PercentIncrease)
+		fmt.Fprintln(w)
+	}
 
 	if len(r.PlanRegressions) > 0 {
 		f.printPlanRegressions(r.PlanRegressions, w)

regresql/formatters.go

@@ -24,9 +24,15 @@ type (
 		ActualCost      float64
 		PercentIncrease float64
 		Threshold       float64
-		PlanChanged      bool
-		PlanRegressions  []PlanRegression
-		PlanWarnings     []PlanWarning
+		PlanChanged     bool
+		PlanRegressions []PlanRegression
+		PlanWarnings    []PlanWarning
+
+		// Buffer comparisons (when analyze_mode baseline)
+		AnalyzeMode     bool
+		ActualBuffers   int64
+		BaselineBuffers int64
+		BufferIncrease  float64
 
 		// Diagnostics
 		QueryFile    string

regresql/library.go

@@ -30,8 +30,12 @@ type (
 		PlanRegressions []PlanRegression
 		PlanWarnings    []PlanWarning
 
-		// Metrics from EXPLAIN ANALYZE (nil if ANALYZE not used or on error)
-		Metrics *PlanMetrics
+		Metrics *PlanMetrics // from EXPLAIN ANALYZE
+
+		AnalyzeMode     bool
+		ActualBuffers   int64
+		BaselineBuffers int64
+		BufferIncrease  float64
 	}
 )
 
@@ -156,12 +160,12 @@ func (p *Plan) CompareCostsData(db *sql.DB, baselines []Baseline, thresholdPerce
 	return results
 }
 
-func (p *Plan) CreateBaselines(db *sql.DB) ([]Baseline, []*ExplainOutput, error) {
+func (p *Plan) CreateBaselines(db *sql.DB, useAnalyze bool) ([]Baseline, []*ExplainOutput, error) {
 	baselines := make([]Baseline, len(p.Names))
 	fullPlans := make([]*ExplainOutput, len(p.Names))
 
 	for i := range p.Names {
-		baseline, fullPlan, err := p.createSingleBaseline(db, i)
+		baseline, fullPlan, err := p.createSingleBaseline(db, i, useAnalyze)
 		if err != nil {
 			return nil, nil, err
 		}
@@ -172,15 +176,21 @@ func (p *Plan) CreateBaselines(db *sql.DB) ([]Baseline, []*ExplainOutput, error)
 	return baselines, fullPlans, nil
 }
 
-func (p *Plan) createSingleBaseline(db *sql.DB, index int) (Baseline, *ExplainOutput, error) {
+func (p *Plan) createSingleBaseline(db *sql.DB, index int, useAnalyze bool) (Baseline, *ExplainOutput, error) {
 	var explainPlan *ExplainOutput
 	var err error
 
+	opts := DefaultExplainOptions()
+	if useAnalyze {
+		opts.Analyze = true
+		opts.Buffers = true
+	}
+
 	if len(p.Query.Args) == 0 {
-		explainPlan, err = ExecuteExplain(db, p.Query.OrdinalQuery)
+		explainPlan, err = ExecuteExplainWithOptions(db, p.Query.OrdinalQuery, opts)
 	} else {
 		sql, args := p.Query.Prepare(p.Bindings[index])
-		explainPlan, err = ExecuteExplain(db, sql, args...)
+		explainPlan, err = ExecuteExplainWithOptions(db, sql, opts, args...)
 	}
 	if err != nil {
 		return Baseline{}, nil, fmt.Errorf("failed to create baseline for %s: %w", p.Names[index], err)

regresql/snapshot_build.go

@@ -45,8 +45,8 @@ func BuildSnapshot(basePgUri string, root string, opts SnapshotBuildOptions) (*s
 		}
 	}
 
-	if len(opts.Fixtures) == 0 && opts.SchemaPath == "" {
-		return nil, fmt.Errorf("no schema or fixtures specified for snapshot build")
+	if len(opts.Fixtures) == 0 && opts.SchemaPath == "" && opts.MigrationsDir == "" && opts.MigrationCommand == "" {
+		return nil, fmt.Errorf("no schema, migrations, or fixtures specified for snapshot build")
 	}
 
 	if opts.Verbose {