Repository navigation
docs: add database schema management documentation - #224
Conversation
Adds docs/drift-recovery.md explaining: - Current schema-guarded db push approach - How the schema guard prevents data loss - Recovery steps for different drift scenarios - How to baseline a database for migrate deploy if needed This documentation is adapted from the original PR Miracle656#201 work but adjusted to reflect the upstream direction (schemaGuard vs migrate deploy). Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Miracle656
left a comment
There was a problem hiding this comment.
This is the right response to #201, and the doc is better for the split.
I said on #201 that docs/drift-recovery.md was the genuinely good part and the blockers were all underneath it, in prisma/migrations/. Landing it alone gets that work in without waiting on the baseline repair.
Both doc points from that review are fixed:
baselned→baselined.- The resolve loop is
ls -d prisma/migrations/*/, so it matches directories only and no longer feedsmigration_lock.tomltomigrate resolve --applied.
And it now documents what is actually true, which the version on #201 did not. It leads with "Current Approach: Schema-Guarded db push" — which is what src/schemaGuard.ts does today — rather than the migrate deploy world that PR was proposing. Then:
The migration history is incomplete:
- `prisma/migrations` holds 7 migrations covering 5 tables
- The schema defines 15+ tables
- Some tables (TokenTransfer, AccountSummary, IndexerState, OfframpOrder) have no migration
That names OfframpOrder specifically, which is the gap I found on #201 and which no migration creates. Writing down a known deficiency, in the place someone will look when it bites them, is worth more than most code.
Integration tests is red, and it is red on main too — I checked the latest CI run on main and Integration tests is the failing job there. Not caused by a documentation-only change.
Merging. If you come back to the migration baseline, the two things left from #201 are: 0_init and 20250101000000_add_backfill_cursor both CREATE TABLE "wraith"."BackfillCursor" with no IF NOT EXISTS, so the second fails on a fresh database; and OfframpOrder still needs a migration of its own. Neither is urgent while db push is the boot path.
Summary
The Situation:
Your original PR (#201) implements switching from db push --accept-data-loss to prisma migrate deploy
Upstream main has diverged and instead implemented a smart schemaGuard.ts approach that keeps db push but with intelligent guards to prevent data loss
This is a fundamental architectural difference, not just a merge conflict
The Solution:
I created a new branch that:
✅ Rebases onto the latest upstream/main
✅ Adapts the valuable documentation from your PR to reflect the current architecture
✅ Adds drift-recovery.md explaining:
The current schema-guarded db push approach
How the schema guard prevents data loss
Recovery steps for different drift scenarios
How to baseline a database if switching to migrate deploy is ever needed
Closes #192