Skip to main content

Troubleshooting

Checksum mismatch​

Queen detected that an applied SQL migration changed after it was recorded.

What to do:

  • restore the original migration if the change was accidental;
  • create a new migration for the intended change;
  • only update recorded state manually if you have audited the database and understand the drift.

No rollback defined​

Down and Reset require DownSQL or DownFunc.

For irreversible migrations, document the reason in code and avoid workflows that depend on automatic rollback.

Gap detected​

Run:

go run ./cmd/migrate gap detect --driver postgres --dsn "$DATABASE_URL"
go run ./cmd/migrate gap analyze --driver postgres --dsn "$DATABASE_URL"

If a numbering gap is intentional, ignore it:

go run ./cmd/migrate gap ignore 003 --reason "removed before release"

If an application gap exists, inspect carefully before using gap fill.

The file format is documented in Config Files.

Production prompt blocks deploy​

Production environments can require:

--unlock-production

Use --yes only in trusted CI/CD contexts where the environment and DSN are already controlled.