Gap Detection¶

Queen automatically detects missing migrations in your sequence.

What are Gaps?¶

Gaps occur when migration versions are not sequential:

001_create_users    Applied
002_add_posts       Missing (GAP)
003_add_comments    Applied
004_add_likes       Applied

Migration 002 is missing but migrations 003 and 004 are already applied.

Why Gaps Occur¶

• Parallel development - Two developers create migrations with the same version, branch merge causes renaming.
• Branch merges - Feature branch deployed before main branch migrations.
• Manual intervention - Migration applied manually but file never committed.

Why Gaps Matter¶

Migration 003 might depend on schema from 002. Missing migrations break the audit trail and can cause deployment failures.

Gap Types¶

Numbering Gaps¶

Missing version numbers in sequence:

Registered: 001, 003, 004, 005
Applied:    001, 003, 004, 005
Gap:        002 (missing from sequence)

Application Gaps¶

Registered migrations not yet applied while later ones are:

Registered: 001, 002, 003, 004
Applied:    001, 004
Gaps:       002, 003 (registered, not applied)

Unregistered Gaps¶

Migrations in database but not in code:

Registered: 001, 002, 004
Applied:    001, 002, 003, 004
Gap:        003 (applied but not registered)

Detection¶

Library¶

gaps, err := q.DetectGaps(ctx)
if err != nil {
    log.Fatal(err)
}

for _, gap := range gaps {
    fmt.Printf("Gap: %s (type: %s)\n", gap.Version, gap.Type)
}

CLI¶

queen gap detect

Output:

Gap Detection Report
Found 1 gap

Version: 002
Name:    add_posts
Status:  Not applied
Impact:  3 migrations applied after this gap

CI/CD Integration¶

queen check --ci

Exit code 4 if gaps detected.

# .github/workflows/migrations.yml
- name: Check for gaps
  run: queen gap detect

Resolving Gaps¶

Fill Gap¶

Apply the missing migration:

queen gap fill 002

Mark as Applied¶

If migration was executed manually:

queen gap fill 002 --mark-applied

Records migration without executing SQL.

Ignore Gap¶

If gap is intentional:

queen gap ignore 002 --reason "Removed migration, superseded by 005"

Creates or updates .queenignore:

002 # Removed migration, superseded by 005

Batch Resolution¶

queen gap fill 002 003 004     # Fill multiple

Resolution Strategy¶

1. Resolve unregistered gaps first (ignore or recreate).
2. Fill numbering gaps (create missing migrations).
3. Apply application gaps.

Safe Resolution¶

# 1. Analyze impact
queen gap analyze

# 2. Backup
pg_dump mydb > backup.sql

# 4. Fill and verify
queen gap fill 003
queen status

Prevention¶

Use Timestamps¶

Avoid version conflicts in parallel development:

config := &queen.Config{
    Naming: &queen.NamingConfig{
        Pattern: queen.NamingPatternSequentialPadded,
        Padding: 3,
        Enforce: true,
    },
}

Sequential padded versions (001, 002, ...) are less prone to conflicts than plain sequential ones. For timestamp-based versions, use sequential-padded with appropriate padding.

CI/CD Validation¶

queen check --ci

Pre-merge Checks¶

queen gap detect
# If gaps found, resolve before merge