For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Last updated

Was this helpful?