Real-world patterns for common BenchBox scenarios

This directory contains complete, production-ready examples demonstrating how to solve specific real-world problems with BenchBox.

• Problem-focused: Each example solves a specific real-world problem
• Production-ready: Copy-paste into your workflows
• Best practices: Demonstrates recommended patterns
• Complete solutions: End-to-end workflows, not fragments

Problem: Automatically detect performance regressions in pull requests

Solution: Lightweight benchmark with baseline comparison

Key Features:

• Fast execution (< 30 seconds)
• Clear pass/fail criteria
• GitHub Actions integration
• Baseline management

Usage:

# Generate baseline (run once on main branch)
python use_cases/ci_regression_test.py --save-baseline baseline.json

# Test for regressions (run in CI)
python use_cases/ci_regression_test.py --baseline baseline.json

See also: ci_regression_test_github.yml for GitHub Actions workflow

Problem: Choose the right database platform for your workload

Solution: Systematic comparison across multiple platforms

Key Features:

• Side-by-side performance comparison
• Cost estimation
• Platform-specific notes
• Decision criteria

Usage:

# Evaluate local platforms
python use_cases/platform_evaluation.py --platforms duckdb,sqlite

# Add cloud platforms
python use_cases/platform_evaluation.py --platforms duckdb,databricks,bigquery --dry-run

Problem: Systematically optimize database performance

Solution: Iterative optimization workflow with tracking

Key Features:

• Round-by-round optimization
• Improvement tracking
• Multiple optimization strategies
• Tuning report generation

Usage:

# Run full tuning workflow
python use_cases/incremental_tuning.py

# Custom scale factor
python use_cases/incremental_tuning.py --scale 1.0

Problem: Minimize cloud platform costs

Solution: Cost-saving strategies and estimates

Key Features:

• Dry-run validation
• Query subset selection
• Scale factor optimization
• Cost estimation by platform

Usage:

# Preview costs
python use_cases/cost_optimization.py --platform bigquery --dry-run

# See cost strategies
python use_cases/cost_optimization.py

CI/CD Regression Testing

• Pull request validation
• Nightly performance tests
• Release gate criteria
• SLA monitoring

Platform Evaluation

• Database migration decisions
• New project platform selection
• Cost vs performance trade-offs
• Vendor comparison

Incremental Tuning

• Performance optimization
• Query optimization
• Capacity planning
• Benchmarking tuning changes

Cost Optimization

• Cloud budget management
• Development cost reduction
• Test environment optimization
• POC/demo cost control

# .github/workflows/performance.yml
- name: Performance Test
  run: python use_cases/ci_regression_test.py --baseline baseline.json

# .gitlab-ci.yml
performance_test:
  script:
    - python use_cases/ci_regression_test.py --baseline baseline.json

// Jenkinsfile
stage('Performance Test') {
    sh 'python use_cases/ci_regression_test.py --baseline baseline.json'
}

1. Start Simple: Begin with ci_regression_test.py for quick wins
2. Measure First: Run platform_evaluation before migrations
3. Iterate: Use incremental_tuning for systematic optimization
4. Watch Costs: Use cost_optimization for cloud platforms
5. Customize: These are templates - adapt to your needs

• Feature Examples: See features/ for individual capabilities
• Programmatic API: See programmatic/ for library usage
• Patterns: See PATTERNS.md for workflow combinations

Remember: These examples are production-ready templates. Copy and modify them for your specific needs.