Prisma Migration Drift Detected After Manual Schema Change on Managed Postgres
Prisma migrate drift detected shows up at the worst possible time: you're trying to add a new migration for an unrelated feature, and Prisma refuses to move forward at all, insisting your migration history doesn't match your actual database. Nine times out of ten, the explanation is boring and a little uncomfortable — someone ran a manual ALTER TABLE directly against the managed Postgres dashboard during an incident, or a hotfix went in without a matching migration file, and Prisma is the first thing to actually notice.
Short answer: your real database no longer matches what Prisma's migration history says it should look like, and the fix is prisma migrate resolve --applied, which updates Prisma's internal tracking table to reflect reality without running any SQL against your data. The manual change already happened. This just tells Prisma the truth about it.
Why Prisma Reports Migration Drift Detected
Drift detection is a side effect of the same shadow database mechanism behind Prisma's shadow database permission errors — but where that error happens when Prisma can't create the shadow database, drift is what Prisma finds after successfully using one. prisma migrate dev replays your entire recorded migration history against a fresh temporary database, then compares the result to your actual database. If they don't match, something changed your real schema outside of a Prisma migration file — a manual dashboard ALTER TABLE, a hotfix applied directly under time pressure, a teammate's one-off CREATE INDEX that never got backfilled into a migration. Prisma has no way to know about changes it didn't make, and it refuses to proceed rather than silently generating a migration against an assumption that's already wrong.
(If you're the one who ran that manual change during an incident — no judgment here. "Fix it now, write the proper migration later" is a completely reasonable call at 2am. This is just what "later" looks like when it finally arrives.)
Reconciling Drift Without Losing Data
The fix is a two-step process: make your schema file match reality, then tell Prisma the corresponding migration already happened.
1# Step 1: update schema.prisma to match what actually exists in the database,
2# then generate a migration file describing that change
3npx prisma migrate dev --name retroactively-add-index1# Step 2: tell Prisma this migration already ran in production —
2# this only updates the tracking table, it runs no SQL against your data
3npx prisma migrate resolve --applied "20260115120000_retroactively_add_index"Prisma's own documentation on patching and hotfixing confirms exactly what --applied does: it adds an entry to the _prisma_migrations table without executing the migration's SQL — because that SQL already ran, manually, and running it again would either fail outright or duplicate a change that's already in place. If the manual fix was also applied to staging or any other environment, repeat the same migrate resolve --applied command there too before committing the migration file and letting your normal CI/CD pipeline deploy it to any environment that was never patched.
Diagnosing Exactly What Changed First
Before writing the reconciling migration, confirm precisely what drifted rather than guessing:
1# Reports which migrations are applied, pending, or in a failed state
2npx prisma migrate statusFor a full picture of the live schema, prisma db pull introspects the actual database and writes what it finds into schema.prisma — running it against a copy of your schema file (not your real one, until you're ready) gives you a clean diff to review before deciding exactly what the reconciling migration needs to contain. Prisma's CLI reference documents every flag both commands accept if you need more than the basic invocation shown here. Skipping this diagnostic step and guessing at the change is how a drift fix accidentally introduces a second, smaller drift of its own.
Preventing Drift Going Forward
The fix above resolves one instance. Preventing the next one is a process question more than a tooling one: treat direct SQL execution against a managed Postgres dashboard as an emergency-only action, and build a habit — not just a good intention — of backfilling a matching Prisma migration the same day, while the change is still fresh. Restricting which roles have direct write access to production schema at all, where your managed provider allows it, removes the temptation entirely for anyone other than whoever's actually handling the incident.
The Opinion Part
Here's the position worth stating plainly: drift isn't really a Prisma problem, it's the migration-history equivalent of a codebase where someone can push directly to main without review, and the tool just happens to be the thing that finally notices when reality and the record disagree. The three biggest predictors of project success that Standish's CHAOS research keeps coming back to — user involvement, executive support, and a clear statement of requirements — all share a theme: they're process disciplines, not technology choices. A migration history that stays trustworthy isn't a Prisma feature you configure once; it's a team habit you maintain, and drift detection is just the moment that habit's absence becomes visible instead of quietly accumulating.
Conclusion
If Prisma is reporting migration drift, don't fight the shadow database or second-guess your schema file — something changed the real database outside of a migration, and Prisma correctly refuses to proceed on a false assumption. Run migrate status and db pull to see exactly what changed, write the migration that should have existed all along, and use migrate resolve --applied to tell Prisma the truth without touching your data. Then close the loop on why the manual change happened in the first place, because the same gap produces the same drift again otherwise.
If shadow database permissions themselves are also giving you trouble on the same project, our dedicated guide on that error covers the earlier-stage version of this exact mechanism, and if the manual change in question was itself a production incident response, our zero-downtime deployment guide covers safer patterns for the next one.
Reconcile the history, write down what actually happened, and get back to shipping migrations that describe reality instead of arguing with it.
Frequently Asked Questions
It means Prisma replayed your entire recorded migration history against a temporary shadow database and got a different result than what your actual development or production database currently looks like. That mismatch — drift — almost always means someone changed the schema directly, outside of a Prisma migration file, so the migration history Prisma knows about no longer describes reality.
No, when used correctly. migrate resolve --applied only updates Prisma's internal _prisma_migrations tracking table to say a specific migration has already run — it doesn't execute any SQL against your actual tables or touch your data at all. It's a bookkeeping fix that brings Prisma's records back in line with what already happened, not a destructive operation.
Run prisma migrate status first — it explicitly reports which migrations are applied, pending, or in a failed state, and often points directly at the mismatch. For a full diff between your schema.prisma and the live database, prisma db pull temporarily overwrites a copy of your schema with the database's actual current structure, which you can diff against your real schema file to see precisely what changed.
The most reliable fix is process, not tooling: treat direct dashboard SQL execution as an emergency-only action that always gets backfilled with a matching Prisma migration within the same day, and where possible, restrict which team members and service roles have direct write access to production schema at all. Some teams also run prisma migrate status as a scheduled check specifically to catch drift within hours instead of discovering it the next time someone runs migrate dev.
Yes — both bugs involve the same shadow database, just failing at different stages. The permission error happens when Prisma can't create the shadow database at all. Drift detection happens after the shadow database is successfully created and used, when replaying your migration history against it produces a schema that doesn't match your real database. Fixing the permission issue doesn't prevent drift, and fixing drift doesn't require fixing shadow database permissions if they were never a problem to begin with.
