Skip to content

docs: add database schema management documentation - #224

Merged
Miracle656 merged 1 commit into
Miracle656:mainfrom
funds0033-cmyk:fix/migration-baseline-and-docs
Oct 5, 2026
Merged

Miracle656 merged 1 commit into
Miracle656:mainfrom
funds0033-cmyk:fix/migration-baseline-and-docs

Conversation

@funds0033-cmyk

@funds0033-cmyk funds0033-cmyk commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

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

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 Miracle656 left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 feeds migration_lock.toml to migrate 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.

@Miracle656
Miracle656 merged commit e45b700 into Miracle656:main Oct 5, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Apply committed migrations on boot instead of db push --accept-data-loss

2 participants