docs: simplify the v2 to v3 migration guide

[spydon]

Rewrites MIGRATION.md so it reads as a list of things to change rather than an account of why they changed. 1893 lines down to 1566.

What changed

Design rationale removed. Every "why we did this" passage is gone: why realtime_client was a poor package name, why the socket state was exposed twice, why the broadcast REST fallback was a problem, why PostgrestClient had to become stateless, why one status stream beats four callbacks. What remains per section is the change, a before/after table or snippet, and any follow-up action.

Everything stated from a v2 baseline. A few entries described renames relative to intermediary states that only ever existed on main:

• The abbreviations table had TableSnapshotScope.value → TableSnapshotScope.name, but TableSnapshotScope does not exist in v2. It now reads LoadTableSnapshots.value → TableSnapshotScope.name.
• The per-package sub-headings in the abbreviations section still said realtime_client: and storage_client:; they now use the v3 package names.
• The LoadTableSnapshots row in the singularization table is attributed to iceberg rather than supabase_storage, which is where the type lives in v3.

I checked every "Before" symbol in the guide against the last v2 tag of its package (gotrue-v2.27.2, storage_client-v2.8.0, realtime_client-v2.13.0, functions_client-v2.7.1, postgrest-v2.9.1, supabase-v2.16.1, supabase_flutter-v2.17.2) to confirm it actually exists there.

Sections merged. The four package-rename sections collapse into one "The client packages are renamed" with three tables: dependency, import, and the auth type renames. The standalone "conn abbreviations on RealtimeClient spelled out" section folds into the existing abbreviations table.

One section added. "Changes the compiler will not catch" at the top of the v3 section links the six changes that compile silently but behave differently: order() defaulting to ascending, the connectionState type change, the HttpMethod index shift, userUpdated on email and phone confirmation, the PostgREST backoff defaults, and writes without a select() resolving to void.

Drive-by fix. A snippet in the realtime codec section still passed anonKey: to Supabase.initialize, contradicting the section that makes publishableKey required.

Coverage

All 45 original sections are accounted for in the 42 that remain (four merged away, one added). No migration instruction was dropped.

[coderabbitai]

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

💤 Files selected but had no reviewable changes (1)

• MIGRATION.md

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 5d5523d1-5560-41e1-94e1-d081efd0c7f2

📥 Commits

Reviewing files that changed from the base of the PR and between 185d6bc and 8622693.

📒 Files selected for processing (1)

• MIGRATION.md

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}