
## 🦫 CAPYSQUASH Analysis

☑ **Migrations analyzed successfully!**

### <ChartBar size={20} weight="bold" /> RESULTS

- **Changed files:** 3 migrations
- **Current total:** 156 migrations
- **Total migrations:** 287 files
- **Consolidation opportunity:** Squashes to 1 optimized file (99% reduction)
- **Warnings:** 2 minor issues
- **Estimated deployment time:** +15 seconds

### <WarningCircle size={20} weight="bold" /> WARNINGS

1. **Migration 20240115_add_column.sql**
   - Adding non-nullable column without default
   - Risk: May fail if table has existing rows
   - Suggestion: Add DEFAULT value or make nullable

2. **Migration 20240116_drop_table.sql**
   - Dropping table `old_data`
   - Risk: Permanent data loss
   - Suggestion: Backup data first or use soft delete

### <Lightbulb size={20} weight="bold" /> RECOMMENDATIONS

- ☑ Migrations follow naming convention
- ☑ No syntax errors detected
- ⚠️ Consider consolidating after merge (92% reduction available)
- ⚠️ Review data loss warnings before merging

### <ChartLineUp size={20} weight="bold" /> IMPACT

**Current state:**

- 156 migrations
- ~2.5 minutes deployment time
- 12 MB total size

**After consolidation:**

- 12 migrations (92% reduction)
- ~10 seconds deployment time
- 1.2 MB total size
- ☑ Same end result, guaranteed

### <Target size={20} weight="bold" /> NEXT STEPS

1. Review warnings above
2. Fix non-nullable column issue
3. Consider backup strategy for dropped table
4. After merge, run consolidation: `pgsquash squash`

[View full analysis →](https://capysquash.dev/runs/abc123)

---

_CAPYSQUASH Professional · [Configure](https://capysquash.dev/settings/github)_

Comment Sections

WHAT'S INCLUDED

SUMMARY

File counts, consolidation opportunity, deployment impact

WARNINGS
Issues detected with specific files and actionable fixes
RECOMMENDATIONS
Best practices, optimization opportunities, next steps
IMPACT
Before/after metrics showing improvement potential
🔗 LINK
Full detailed report in CAPYSQUASH dashboard

STATUS CHECKS

In addition to the comment, CAPYSQUASH creates a GitHub status check:

Check States

State	Icon	Meaning
Success	☑	No issues or informational mode
Failure	☒	Issues detected (blocking mode only)
Pending	🟡	Analysis in progress
Error	⚠️	Analysis failed (technical error)

Check Details

Click the check for detailed information:

CAPYSQUASH Analysis
☑ Migrations analyzed successfully
Details:
► 3 files changed
► 2 warnings detected
► 92% consolidation opportunity
► 15s deployment impact
View full report →

Branch Protection

Require CAPYSQUASH check to pass before merging:

Go to GitHub repo Settings
Branches → Add rule for your branch (e.g., main)
Require status checks to pass
Search for and select "CAPYSQUASH Analysis"
Save rule

Now PRs must pass CAPYSQUASH analysis to merge.

MANUAL TRIGGERS

Trigger analysis manually via PR comment:

Basic Trigger

@CAPYSQUASH analyze

Runs analysis with default settings.

With Safety Level

@CAPYSQUASH analyze --safety=conservative

Override default safety level for this run.

Specific Files

@CAPYSQUASH analyze migrations/002_*.sql

Analyze only specific migration files.

Force Reanalysis

@CAPYSQUASH analyze --force

Reanalyze even if nothing changed.

With Options

@CAPYSQUASH analyze --safety=paranoid --verbose

Combine multiple options.

Who Can Trigger?

Repository collaborators: Yes
External contributors (forks): Requires approval
Organization members: Yes
Bots: Can be configured

FORK PR WORKFLOW

Pull requests from forked repositories require special handling for security:

Security Restrictions

GitHub limits what apps can do on fork PRs:

☑ Can read PR details
☒ Cannot automatically read repo contents
☒ Cannot post comments automatically

Why: Prevent malicious forks from accessing private data.

Analyzing Fork PRs

FORK PR PROCESS

CONTRIBUTOR OPENS FORK PR
External contributor submits PR from their fork
2
MAINTAINER REVIEWS PR
Check if PR is safe and contains migrations
3
MAINTAINER TRIGGERS ANALYSIS
Comment: @CAPYSQUASH analyze
4
CAPYSQUASH ANALYZES
Runs with maintainer's approval and posts results

Alternative: Wait until PR merged to branch, then automatic analysis on subsequent updates.

HANDLING WARNINGS

When CAPYSQUASH detects warnings:

1. Read Warning Details

Each warning includes:

File: Which migration has the issue
Issue: What's wrong
Risk: Potential impact
Suggestion: How to fix

2. Assess Severity

Critical (🔴 High Risk):

Data loss
Production breaking changes
Security issues

Medium (🟡 Medium Risk):

Performance concerns
Non-nullable without default
Missing indexes

Low (🟢 Low Risk):

Style issues
Optimization opportunities
Best practice suggestions

3. Take Action

Option A: Fix in PR


# Update migration file

git add migrations/fixed.sql
git commit -m "fix: address CAPYSQUASH warnings"
git push

CAPYSQUASH automatically reanalyzes.

Option B: Document Why Ignoring


# Add comment explaining decision

# Migration is intentional, data backed up, etc.

Option C: Override Safety Level

@CAPYSQUASH analyze --safety=aggressive

If warnings are too strict for your use case.

DRAFT PR BEHAVIOR

Configure how CAPYSQUASH handles draft PRs:

Option 1: Analyze Drafts (Default)

Analyze even when PR is draft.

Pros:

Early feedback
Fix issues before ready for review

Use case: Solo developers, early validation

Option 2: Skip Drafts

Don't analyze until PR marked ready:

skip_draft_prs: true

Pros:

Reduce noise
Only analyze when ready
Save analysis quota

Use case: Teams with frequent WIP PRs

Note: Can manually trigger on draft PR: @CAPYSQUASH analyze

UPDATING AFTER ANALYSIS

When you push new commits to an analyzed PR:

Automatic Reanalysis

CAPYSQUASH automatically:

Detects new commits
Reruns analysis
Updates comment (or posts new one)
Updates status check

Comment Updates

Option A: Edit existing comment (default)

Keeps PR clean
Single source of truth
Shows latest results

Option B: Post new comment

update_strategy: new_comment

Keeps history of all analyses
Can compare changes over time

CONSOLIDATION WORKFLOW

When CAPYSQUASH suggests consolidation:

In PR

💡 **Consolidation Opportunity:**
Can reduce 156 migrations → 12 migrations (92% reduction)

After Merge

Don't consolidate in the PR - it conflicts with migration history.

After merge:


# On main branch

git pull origin main

# Run consolidation

pgsquash squash

# Review changes

git diff

# Commit consolidated migrations

git add migrations/
git commit -m "chore: consolidate migrations"
git push origin main

Learn more about consolidation →

PERFORMANCE

Analysis Speed

Typical timing:

Small projects (50-120 migrations): 15-30 seconds
Medium projects (100-300 migrations): 30-60 seconds
Large projects (300-800 migrations): 60-120 seconds

Factors Affecting Speed

Factor	Impact
Number of migrations	High
Migration file size	Medium
Safety level	Medium
AI validation enabled	High
Repository size	Low

Optimization Tips

Consolidate regularly - Fewer migrations = faster analysis
Configure path precisely - Don't scan entire repo
Use aggressive safety - For faster feedback (if acceptable)
Skip draft PRs - Reduce unnecessary analyses

TROUBLESHOOTING

Analysis Not Running

Problem: PR opened but no analysis

Check:

Do migration files actually change?
Are they in configured path?
Is PR targeting enabled branch?
Is PR from fork? (Needs manual trigger)
Does PR have skip labels?

Comment Not Appearing

Problem: Analysis runs but no comment

Check:

GitHub App has write permission for PRs
Not rate limited by GitHub
Check dashboard for analysis results
Repository not archived/locked

Check Not Created

Problem: Comment appears but no status check

Check:

Checks enabled in repository settings?
Check mode set to "blocking" or "warning"?
GitHub App has write permission for checks

Wrong Results

Problem: Analysis doesn't match local pgsquash-engine

Check:

Same safety level used?
PR analyzing correct branch?
Different migration files than local?
Try manual trigger: @CAPYSQUASH analyze - verbose

BEST PRACTICES

For Developers

Run locally first - Use pgsquash-engine before opening PR

pgsquash analyze migrations/*.sql --safety=conservative

Address warnings early - Fix issues before review
Clear commit messages - Help reviewers understand changes

feat(db): add user profile table
New migration adds user_profiles table
Indexed on user_id for performance
CAPYSQUASH validated safe

Regular consolidation - Keep migrations manageable

For Reviewers

Check CAPYSQUASH comment - Review before manual review
Understand warnings - Not all warnings are blockers
Verify fixes - If author fixed warnings, confirm
Consider context - Team's risk tolerance varies

For Teams

Set clear policies - When to block vs warn
Document overrides - When and why to bypass checks
Regular consolidation - Schedule periodic cleanup
Monitor trends - Track migration quality over time

NEXT STEPS

🔒 PERMISSIONS Understand GitHub App security

📁 PROJECTS Configure project settings

---

On this page