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.

Before escalating, gather this evidence. It greatly reduces back-and-forth.

• Project and environment (Dev/Staging/Prod).
• Time of the error (with timezone).
• Steps to reproduce (short and deterministic).
• Full error message (no cropped screenshots).
• Screenshot of the screen (if applicable).
• Browser console (relevant errors and warnings).
• Tab Network (request that failed + status + payload, if there is no sensitive data).

If there is a requestId, traceId or execution link, include it as well.