> For the complete documentation index, see [llms.txt](https://docs.madrix.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.madrix.dev/troubleshooting/database-migrations-and-schema.md).

# 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).

{% hint style="info" %}
If there is a `requestId`, `traceId` or execution link, include it as well.
{% endhint %}