Operations¶

Apply, rollback, and monitor migrations.

Applying Migrations¶

Apply All Pending¶

err := q.Up(ctx)

Applies all pending migrations in natural version order. Each migration runs in a separate transaction. If one fails, execution stops and previously applied migrations remain.

Apply N Steps¶

err := q.UpSteps(ctx, 3)  // Apply next 3 pending migrations

Up is equivalent to UpSteps(ctx, 0).

CLI¶

queen up                    # Apply all pending
queen up --steps 3          # Apply next 3
queen up --yes              # Skip confirmation (CI/CD)

Rolling Back¶

Rollback N Migrations¶

err := q.Down(ctx, 1)   // Rollback last migration
err := q.Down(ctx, 3)   // Rollback last 3 migrations

If n <= 0, rolls back 1 migration. Migrations must have DownSQL or DownFunc defined.

Rollback All¶

err := q.Reset(ctx)

Rolls back all applied migrations in reverse order.

CLI¶

queen down                  # Rollback last migration
queen down --steps 2        # Rollback last 2
queen reset --yes           # Rollback all (skip confirmation)

Checking Status¶

statuses, err := q.Status(ctx)
for _, s := range statuses {
    fmt.Printf("%s %s: %s\n", s.Version, s.Name, s.Status)
}

Each MigrationStatus contains:

Status Values¶

• Pending -- Migration is registered but not applied.
• Applied -- Migration was applied and checksum matches.
• Modified -- Migration was applied but the code has changed since (checksum mismatch).

CLI¶

queen status                # Show all migration statuses
queen status --json         # JSON output

Validation¶

err := q.Validate(ctx)

Checks for:

• Duplicate versions among registered migrations.
• Invalid migration definitions (missing required fields).
• Checksum mismatches between registered and applied migrations.

Returns the first error found. Use in CI/CD to catch problems before deployment.

CLI¶

queen validate              # Validate all migrations
queen check --ci            # Quick check for CI/CD (exit codes)

Dry Run¶

Preview what migrations would be applied or rolled back without executing them:

plans, err := q.DryRun(ctx, queen.DirectionUp, 0)    // All pending
plans, err := q.DryRun(ctx, queen.DirectionDown, 3)   // Last 3 applied

for _, p := range plans {
    fmt.Printf("%s %s [%s] %s\n", p.Version, p.Name, p.Type, p.Direction)
    if len(p.Warnings) > 0 {
        fmt.Printf("  Warnings: %v\n", p.Warnings)
    }
}

Explain¶

Get a detailed plan for a specific migration:

plan, err := q.Explain(ctx, "003")
fmt.Printf("Version: %s\n", plan.Version)
fmt.Printf("Direction: %s\n", plan.Direction)
fmt.Printf("SQL: %s\n", plan.SQL)
fmt.Printf("Warnings: %v\n", plan.Warnings)

If the migration is already applied, Explain shows the rollback plan. If pending, it shows the apply plan.

CLI¶

queen plan                  # Show pending execution plan
queen explain 003           # Detailed plan for version 003

Locking¶

Queen acquires an advisory lock before applying or rolling back migrations. This prevents concurrent migration runs from corrupting the database.

config := &queen.Config{
    LockTimeout: 30 * time.Minute,  // Default
    SkipLock:    false,
}

• LockTimeout -- How long to wait for the lock before returning ErrLockTimeout.
• SkipLock -- Disable locking entirely (single-user development only).

CLI¶

queen up --timeout 60m      # Custom lock timeout

Error Handling¶

All operations return error. Migration-specific errors are wrapped in MigrationError:

err := q.Up(ctx)
if err != nil {
    var migErr *queen.MigrationError
    if errors.As(err, &migErr) {
        log.Printf("Migration %s (%s) failed during %s on %s: %v",
            migErr.Version, migErr.Name, migErr.Operation, migErr.Driver, migErr.Cause)
    }
}

Common errors:

Metadata¶

Queen automatically collects metadata for each migration execution:

• AppliedBy -- System username running the migration.
• Hostname -- Machine hostname.
• Environment -- Value of QUEEN_ENV environment variable.
• DurationMS -- Execution time in milliseconds.
• Action -- apply or rollback.
• Status -- success or failed.

This metadata is stored in the migration table and available through the CLI:

queen log                   # Show migration history with metadata
queen log --with-duration   # Include execution times