Diagnostics Commands¶

Validate migrations, run health checks, and preview execution plans.

queen doctor¶

Full health check of migration state.

queen doctor [flags]

Flag	Type	Default	Description
`--deep`	bool	false	Deep schema validation (slower)
`--gaps`	bool	false	Only check for gaps
`--fix`	bool	false	Attempt to auto-fix issues

Examples¶

queen doctor

Migration Health Check
  Migrations registered: 15
  Migrations applied: 12
  Pending: 3
  Gaps: 0
  Checksum mismatches: 0
  Status: Healthy

queen doctor --deep --gaps

Includes: database connection, migration table integrity, checksums, gaps, registration sync, schema consistency.

queen doctor --fix

Attempts automatic fixes for detected issues.

queen check¶

Quick CI/CD validation.

queen check [flags]

Flag	Type	Default	Description
`--ci`	bool	false	CI mode (strict validation, fails on warnings)
`--no-pending`	bool	false	Fail if pending migrations exist
`--no-gaps`	bool	false	Fail if gaps are detected

Examples¶

queen check --ci

Exit codes:

0 -- All checks passed
2 -- Configuration error
3 -- Validation failed
4 -- Gaps detected
5 -- Pending migrations

queen check --ci --no-pending --no-gaps

Fails if any pending migrations or gaps exist.

queen validate¶

Validate migration definitions.

queen validate

Checks:

No duplicate versions.
No checksum mismatches.
All migrations have valid format.
Version and name constraints met.

queen validate

Validating migrations...
  001_create_users: OK
  002_add_posts: OK
  003_add_index: WARNING - no rollback defined

Validation complete: 3 migrations, 0 errors, 1 warning

queen plan¶

Preview migration execution without applying.

queen plan [flags]

Flag	Type	Default	Description
`--direction`	string	up	Direction: `up` or `down`
`--limit`	int	0	Limit number of migrations to show (0 = all)

Examples¶

queen plan

Execution Plan (up):
  1. Apply 004_add_comments (SQL)
  2. Apply 005_add_indexes (SQL)
  3. Apply 006_normalize_data (Go)

3 migrations will be applied

queen plan --direction down --limit 2

Shows what would be rolled back.

queen explain¶

Show detailed information about a specific migration.

queen explain VERSION

Uses the global --json flag for JSON output.

Examples¶

queen explain 003

Migration: 003
Name: add_index
Type: SQL
Status: Pending
Checksum: abc123def456

Up SQL:
  CREATE INDEX idx_users_email ON users(email);

Down SQL:
  DROP INDEX idx_users_email;

Destructive: No
Has Rollback: Yes

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