docs: add migration history notes and pre-launch squash plan - #21
Conversation
|
CodeAnt AI is reviewing your PR. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Review limit reached
More reviews will be available in 33 minutes and 52 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughA new documentation file records the migration history divergence between local development and Supabase (Dev/Staging) encountered on 2026-06-03. The notes detail the reconciliation steps executed to repair migration tracking, the resulting database state, verification steps confirming zero pending migrations, and the planned pre-launch consolidation strategy. ChangesMigration History Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
codeant-ai
Bot
added
the
size:S
|
CodeAnt AI finished reviewing your PR. |
Greptile SummaryThis PR adds a single documentation file recording the Dev/Staging migration tracking divergence from PRs #19/#20, the four reconciliation steps executed to re-sync
Confidence Score: 5/5Documentation-only change with no migration files, schema files, or application code modified; safe to merge. The PR touches only a new markdown file. No migration SQL, application logic, or ADR files are changed. The previously raised concerns about ADR-0004 alignment have been acknowledged and a Deviation section was added. The one remaining gap is a minor numerical inconsistency in the incident record (16+ vs 24) that does not affect any runnable code. docs/migration-history-notes.md — the count discrepancy between "16+ reverted" and "24 recent re-applied" is worth clarifying before this becomes the canonical incident reference. Important Files Changed
Sequence DiagramsequenceDiagram
participant Dev as Developer
participant CLI as Supabase CLI
participant DevDB as Dev DB schema_migrations
Note over Dev,DevDB: Incident - caused the divergence
Dev->>CLI: repair --status reverted on 16+ migrations
CLI->>DevDB: DELETE rows for 16+ timestamps
Dev->>CLI: db push --include-all
CLI->>DevDB: Apply schema SQL - objects already existed
Note over Dev,DevDB: Reconciliation Steps documented in this PR
Dev->>DevDB: SQL verify schema objects are present
loop 30 timestamps - 6 early plus 24 recent
Dev->>CLI: migration repair --status applied timestamp --linked
CLI->>DevDB: INSERT row for timestamp
end
Dev->>CLI: migration list and db push dry-run
CLI-->>Dev: 0 pending migrations confirmed
Reviews (3): Last reviewed commit: "docs: clarify SQL execution scope during..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
docs/migration-history-notes.md (1)
1-23: Architecture concern: document records systematic ADR violations without remediation plan.This document presents a "reconciliation" process that systematically violates the migration discipline defined in ADR 0004-migration-discipline.md at every step:
- Line 6: Uses
repair --status reverted(explicitly rejected by ADR, lines 118-121)- Line 18: Uses
repair --status appliedto fabricate history (violates ADR core invariant + Rule 5)- Line 23: Plans to squash/rename applied migrations (violates Rule 1 forward-only principle)
Missing from this document:
- Acknowledgment that these actions violate the established ADR
- Risk assessment of the permanent git ↔
schema_migrationsmismatch- Remediation plan to restore ADR compliance, OR
- Proposal to amend ADR 0004 if the strict discipline is unworkable
Current state: The Dev environment now has falsified migration tracking where
schema_migrationsclaims migrations were applied when they were not executed through the canonical path. The planned squash will make this unfixable.Recommendation: Before merging this PR, either:
- Restore compliance: Roll back the Dev database to a clean snapshot, remove never-truly-applied migrations from git, then reapply the real migration sequence via the canonical MCP path
- Amend the ADR: If the strict discipline is impractical for the team's workflow, formally amend ADR 0004 with the new rules and explicitly accept the risks documented in the original ADR's rationale
- Document exception: If this is a one-time cleanup of early development chaos, add a section explaining this is a pre-launch exception and commit to strict ADR compliance going forward
As per coding guidelines, ADR 0004 Context states the core invariant: "The history of schema changes in git matches the history of supabase_migrations.schema_migrations in prod, with the one explicit exception described in the Emergency rollback procedure."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/migration-history-notes.md` around lines 1 - 23, The migration notes document violates ADR 0004 by advocating use of `pnpm supabase migration repair --status reverted` and `--status applied` and proposing to squash/rename migrations; update docs/migration-history-notes.md to explicitly acknowledge the ADR 0004-migration-discipline.md conflict, add a short risk assessment about git ↔ schema_migrations divergence and irreversible effects of squashing, and include one concrete remediation path (pick one of: restore from snapshot and reapply canonical migrations; formally amend ADR 0004 with the new rules; or document this as a one-time pre-launch exception with controls), plus a required approval step referencing ADR 0004 and the `schema_migrations` table before any squash or repair commands are run.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/migration-history-notes.md`:
- Around line 5-11: The documented use of "pnpm supabase migration repair
--status reverted" contradicts ADR 0004-migration-discipline and must be removed
and replaced: delete or rewrite the paragraph that endorses using that command
and instead state that ADR 0004 forbids manipulating applied history, reference
"ADR 0004-migration-discipline" and "schema_migrations", and explicitly instruct
readers to follow the ADR's Emergency rollback procedure (execute rollback SQL,
delete the schema_migrations row only as part of that procedure, commit a
forward migration documenting the reversion, and apply via MCP) as the correct
remediation for wrongly applied migrations; mention that using migration repair
is disallowed and should not be documented as a reconciliation technique.
- Around line 22-23: The "Future Action (Pre-Launch Squash)" plan must be
removed because it conflicts with ADR 0004's forward-only rule: do not
edit/rename/delete migrations that are recorded as applied in schema_migrations
(and especially after using repair --status applied). Replace that paragraph
with an explicit statement that existing migrations are immutable per ADR 0004
and update the migration strategy to: stop any squash/rename plans, do not touch
files already marked applied, and instead create new append-only migrations
(e.g., a new "Phase 1 Schema" migration file) for any consolidation or
corrective work; also reference ADR 0004 and the schema_migrations table so
reviewers can locate the related rules.
- Around line 13-20: You marked 30 migrations as applied using "pnpm supabase
migration repair --status applied", which falsifies
supabase_migrations.schema_migrations and violates ADR 0004/Rule 5; undo the
repair rows and instead restore ADR-compliant history by either (A) making the
superseded files (202601010000–202601010005) idempotent and applying them
through the canonical MCP apply path (use apply_migration) so the DB and git
history match, or (B) if those files were never applied, remove them from git
before any apply, then apply the legit migrations (e.g., 202604260001) via
apply_migration; update docs to remove the repair workflow and reference ADR
0004 and supabase_migrations.schema_migrations to ensure future changes follow
the canonical apply path.
- Line 9: The migration range in the sentence uses inconsistent timestamp
formats: change the 12-digit timestamp `202604300001` to the 14-digit
`YYYYMMDDHHmmss` format so it matches `20260603100000` (e.g., update
`202604300001` to `20260430000100` or the correct 14-digit timestamp for that
migration) so both timestamps follow the 14-digit convention.
---
Nitpick comments:
In `@docs/migration-history-notes.md`:
- Around line 1-23: The migration notes document violates ADR 0004 by advocating
use of `pnpm supabase migration repair --status reverted` and `--status applied`
and proposing to squash/rename migrations; update
docs/migration-history-notes.md to explicitly acknowledge the ADR
0004-migration-discipline.md conflict, add a short risk assessment about git ↔
schema_migrations divergence and irreversible effects of squashing, and include
one concrete remediation path (pick one of: restore from snapshot and reapply
canonical migrations; formally amend ADR 0004 with the new rules; or document
this as a one-time pre-launch exception with controls), plus a required approval
step referencing ADR 0004 and the `schema_migrations` table before any squash or
repair commands are run.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: e4b84b91-e82c-4339-b58a-6c97ae44971f
📒 Files selected for processing (1)
docs/migration-history-notes.md
| ### Pre-prod Reconciliation Steps Executed | ||
| To safely re-sync the history without breaking the functional dev schema, we executed the following steps: | ||
|
|
||
| 1. **Safety First**: Verified the linked ref was `hibfpvmxynoonzxxdllu` (Dev). | ||
| 2. **SQL Verification**: Checked directly via SQL that the schema effects for the unapplied migrations were physically present in the database (e.g. `idempotency_keys` table, `withdraw_wallet` function, `dispute_milestone` new auth logic). | ||
| 3. **Tracking Repair**: Looped through all 30 unapplied timestamps (the 6 early ones + the 24 recent ones) and ran `pnpm supabase migration repair --status applied <timestamp> --linked`. | ||
| - **Why the 6 early ones?**: If left unapplied, `pnpm supabase db push --dry-run` would attempt to apply them and fail since their objects (e.g., `profiles`) were already created by `202604260001`. Marking them as applied bypasses execution and ensures a 100% clean pending queue. | ||
| 4. **Clean Verification**: Ran `pnpm supabase migration list` and `db push --dry-run` to confirm exactly zero pending migrations. |
There was a problem hiding this comment.
Critical issue: fabricating migration history with repair --status applied violates ADR invariant.
Line 18 documents using pnpm supabase migration repair --status applied to mark 30 migrations as applied without actually executing them through the canonical apply path. This violates ADR 0004's core requirement that "the history of schema changes in git matches the history of supabase_migrations.schema_migrations."
While the rationale in line 19 is pragmatically sound (avoiding duplicate object errors from superseded migrations), the solution creates falsified migration tracking where schema_migrations claims migrations were applied when they were not executed via the canonical MCP apply_migration path (ADR Rule 5).
Root cause analysis: The problem originated because:
- Superseded migrations (
202601010000through202601010005) were committed to git but never properly applied - A later migration (
202604260001) recreated the same objects non-idempotently - The repair command was used to retroactively falsify history
Correct approach per ADR 0004:
- Migrations should be idempotent so re-running is safe
- If old migrations are truly superseded, they should be removed from git BEFORE being applied anywhere (Rule 1 allows deletion of never-applied migrations)
- Once applied, history cannot be rewritten
The documented approach leaves the repository in a state where schema_migrations does not reflect the actual sequence of SQL operations executed against the database.
As per coding guidelines, ADR 0004 Rule 5 states: "The canonical apply path is the Supabase MCP apply_migration tool... The author is responsible for confirming the applied row matches the file on disk."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/migration-history-notes.md` around lines 13 - 20, You marked 30
migrations as applied using "pnpm supabase migration repair --status applied",
which falsifies supabase_migrations.schema_migrations and violates ADR 0004/Rule
5; undo the repair rows and instead restore ADR-compliant history by either (A)
making the superseded files (202601010000–202601010005) idempotent and applying
them through the canonical MCP apply path (use apply_migration) so the DB and
git history match, or (B) if those files were never applied, remove them from
git before any apply, then apply the legit migrations (e.g., 202604260001) via
apply_migration; update docs to remove the repair workflow and reference ADR
0004 and supabase_migrations.schema_migrations to ensure future changes follow
the canonical apply path.
There was a problem hiding this comment.
Acknowledged. This process absolutely deviated from the strict forward-only rules mandated by ADR-0004. I've added a new 'Deviation from ADR-0004' section to the document to explicitly clarify this. This was a one-time, dev/staging-only recovery to fix the schema_migrations tracking table after an earlier wipe broke db push. We are not reverting the repair because that would re-break db push on dev. No migration files were edited, no schema objects were altered, and production was never touched. ADR-0004 remains fully in force for all future migrations.
There was a problem hiding this comment.
@shaiksohelll, thanks for the thorough context and for adding the explicit Deviation from ADR-0004 section — that's exactly the right mitigation when a clean-room undo isn't viable. Documenting the why, the scope (dev/staging only), and the guardrails (production untouched, no files edited) preserves institutional memory and makes the deviation auditable for anyone reviewing the repo later.
A couple of small suggestions to make the deviation section as airtight as possible:
- Explicitly state the trigger: note that this deviation was necessitated by an earlier
repair --status revertedwipe ofschema_migrationsrows (the root cause), so it's clear this wasn't an elective shortcut. - Add a "never-repeat" note: something like "This repair approach MUST NOT be used on the production database or for any future migrations; ADR-0004 Rule 5 (canonical
apply_migrationpath) applies unconditionally going forward." Even though it's implied, making it explicit closes any ambiguity.
With those additions the document serves as a complete post-mortem. The concern is considered addressed given the explicit deviation documentation and the dev-only scope.
🐇 📋
| ### Future Action (Pre-Launch Squash) | ||
| Before launching to production, we must squash and rename the local migrations to consolidate the numerous patches into a clean baseline sequence. This squash will cleanly combine the `202601010000` mock schemas and the fragmented PR #1/19/20 fixes into coherent numbered releases (e.g., Phase 1 Schema, Phase 2 Escrow). |
There was a problem hiding this comment.
Critical issue: planned squash/rename violates ADR 0004 forward-only principle.
The proposed pre-launch squash to "consolidate the numerous patches into a clean baseline sequence" directly violates ADR 0004 Rule 1: "Never edit, rename, or delete an existing migration file after it has been applied to any environment."
According to the reconciliation steps documented in line 18, all 30 migrations were marked as applied in the Dev database's schema_migrations table. Therefore, they are considered "applied to an environment" and cannot be squashed, renamed, or deleted per the ADR.
Impact: If these migrations are squashed:
- The Dev database
schema_migrationstable will reference timestamps that no longer exist in git - Any attempt to apply migrations to a fresh environment will fail to reproduce the Dev schema
- The permanent git ↔ applied history mismatch becomes unfixable
Correct approach: Once migrations are marked as applied (even via repair), they become immutable per ADR 0004. If consolidation is desired:
- It should have been done BEFORE any
repair --status appliedcommands were executed - OR accept the fragmented history and move forward with properly disciplined migrations from this point
The combination of using repair --status applied (line 18) followed by planned squash (line 23) creates an irreconcilable state where the repository can never satisfy the ADR's core invariant.
As per coding guidelines, ADR 0004 Rule 1 states: "Migrations are append-only... Never edit, rename, or delete an existing migration file after it has been applied to any environment."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/migration-history-notes.md` around lines 22 - 23, The "Future Action
(Pre-Launch Squash)" plan must be removed because it conflicts with ADR 0004's
forward-only rule: do not edit/rename/delete migrations that are recorded as
applied in schema_migrations (and especially after using repair --status
applied). Replace that paragraph with an explicit statement that existing
migrations are immutable per ADR 0004 and update the migration strategy to: stop
any squash/rename plans, do not touch files already marked applied, and instead
create new append-only migrations (e.g., a new "Phase 1 Schema" migration file)
for any consolidation or corrective work; also reference ADR 0004 and the
schema_migrations table so reviewers can locate the related rules.
There was a problem hiding this comment.
Acknowledged. This process absolutely deviated from the strict forward-only rules mandated by ADR-0004. I've added a new 'Deviation from ADR-0004' section to the document to explicitly clarify this. This was a one-time, dev/staging-only recovery to fix the schema_migrations tracking table after an earlier wipe broke db push. We are not reverting the repair because that would re-break db push on dev. No migration files were edited, no schema objects were altered, and production was never touched. ADR-0004 remains fully in force for all future migrations.
There was a problem hiding this comment.
@shaiksohelll, thanks for the detailed explanation and for adding the explicit "Deviation from ADR-0004" section — that kind of transparency in the documentation is exactly the right approach for a one-time emergency recovery.
A couple of notes:
-
The deviation documentation approach is correct. Since this was a dev/staging-only recovery to unbreak
db push(and no migration files or schema objects were mutated), documenting it as a named exception is far better than pretending it didn't happen. Future reviewers and operators will understand the state of theschema_migrationstable and won't be surprised. -
The squash plan text at line 23 still warrants a small update. Since you're committing to ADR-0004 going forward, the "Future Action (Pre-Launch Squash)" paragraph should either be removed or replaced with a note explicitly stating that no squash/rename will occur (referencing ADR-0004), and that any consolidation work will instead take the form of new, append-only migration files (e.g., a
20260603_phase1_baseline.sqlthat is additive and idempotent). This prevents any future developer from reading that paragraph in isolation and concluding a squash is still planned. -
The constraint going forward is clear: the 30 timestamps now recorded as
appliedinschema_migrationsare immutable. New corrective or consolidation work must come as new migrations.
If you update line 23 to reflect the no-squash commitment, this comment can be resolved. Would you also like to open a follow-up issue to track the "clean baseline migration" work as an append-only alternative to the squash?
🐇 (⌒‿⌒) — well documented recovery!
1 participant
User description
Documenting the divergence between local migration history and the dev database tracking table, and outlining the pre-launch squashing plan to consolidate the early mock schemas.
CodeAnt-AI Description
Document the migration history cleanup and pre-launch squash plan
What Changed
Impact
✅ Clearer migration recovery✅ Fewer deployment surprises✅ Easier pre-launch release planning💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.
Summary by CodeRabbit