Database, migrations and schema

Migrations failing, divergent schema, or connection errors.

When to use

• Migration fails on deploy.

• App starts, but gives error of non-existent table/column.

• Database connection errors.

Quick checklist (2 min)

1. Confirm in which environment the error occurs.

2. Check the most recently applied migration.

3. See if there is a mismatch between expected schema and actual schema.

Diagnosis

1) Connection

• Correct credentials/URL?

• Network/VPC open (if applicable)?

2) Order and idempotence of migrations

• Does a migration depend on another that didn't run?

• Does a migration run twice and break?

3) Existing data

• Altering a column with old data often breaks.

• Constraints (NOT NULL / FK) require backfill.

How to resolve (patterns)

• Column/table error: review the last migration and the schema.

• Constraint failed: perform backfill before applying constraint.

• Connection: validate secrets and network permissions.

When to escalate

• Migration repeatedly breaks in the pipeline.

• Corruption/inconsistent data.

• Error only in Prod and not reproducible in Staging.