Sqitch "deploy failed" / Revert and Dependency Errors in CI

By Daniel Zoghalchali·Latchkey

Sqitch deploys change scripts in dependency order and reverts the failing change on error. A failed deploy means a change’s SQL errored, or a declared dependency/tag was not satisfied. This is about the change definition, not connectivity.

What this error means

sqitch deploy fails on a specific change, reports it reverted that change, or complains a required dependency is missing. It is deterministic - the same change fails until the SQL or dependency is fixed.

sqitch output

Deploying changes to db:pg://app@db/app
  + add_orders_status .. psql:deploy/add_orders_status.sql:3: ERROR:
    column "status" of relation "orders" already exists
"add_orders_status" failed
Reverting all changes from this deploy

Common causes

A change script errored

The deploy SQL for a change failed (duplicate column, missing object, constraint). Sqitch reverts that change and stops, so the deploy fails deterministically.

Missing or unsatisfied dependency

A change requires another change/tag that has not been deployed, so Sqitch refuses to deploy it out of order.

Running against a non-clean database

Deploying against a database that already has the change’s objects makes the create fail, often after a partial earlier run.

How to fix it

Fix the failing change script and redeploy

Correct the SQL so it matches the real schema state, then deploy again (Sqitch resumes from the last good change).

Terminal

# edit deploy/add_orders_status.sql to match reality, then:
sqitch deploy db:pg://app@db/app

Declare and order dependencies

Add the required dependency so Sqitch deploys changes in the correct order.

Terminal

sqitch add add_orders_status --requires add_orders -n "Add status to orders"

Deploy against a clean database in CI

Start each CI run from an empty database so each change deploys exactly once.
Run sqitch deploy then optionally sqitch verify to confirm state.
Use sqitch status to see what is deployed vs pending.

How to prevent it

Declare every change’s requires so deploy order is enforced.
Deploy against ephemeral databases in CI so each change runs once.
Use sqitch verify to validate deployed changes.

Frequently asked questions

What causes ""Deploy failed" (Sqitch)"?