What changed
Supabase announced on November 6, 2026 that supabase-flutter v3 would go stable on November 11, 2026. As of November 14 it has not shipped: pub.dev still lists supabase_flutter 2.18.3 and supabase 2.16.5 as the latest stable versions, Supabase published the prerelease 3.0.0-dev.17 on November 11 instead, and the migration guide still says v3 has not been released yet.
anonKey on Supabase.initialize becomes publishableKey. A legacy anon key is still a valid value under the new name.
order() sorted descending by default in v2, the opposite of SQL. v3 follows SQL.
order() no longer sends a null placement by default: v2 always put NULLs last, v3 lets PostgreSQL decide (first on a descending sort).
gotrue, realtime_client, storage_client and functions_client are renamed to supabase_auth, supabase_realtime, supabase_storage and supabase_functions. The old packages are discontinued when v3 ships.
- Timestamps and URLs that were strings become typed values, and realtime callbacks become streams.
- Realtime broadcast messages change shape, and the compiler won't flag it: a v2 app finds nothing at the top level of a broadcast from a v3 app.
- v2 keeps security and critical fixes for 6 months after 3.0.0.
Prerequisites
- A Flutter or Dart app on
supabase_flutter or supabase v2
- Your project's publishable key in
SUPABASE_PUBLISHABLE_KEY
Steps
- Before upgrading, add
ascending: false to every order() call that relies on newest-first sorting, and nullsFirst: false to descending sorts on nullable columns where NULLs must stay last. Both already work on v2.
- Once 3.0.0 is on pub.dev, bump
supabase_flutter or supabase to ^3.0.0 in pubspec.yaml. Until then ^3.0.0 does not resolve; to try v3 now, pin the prerelease exactly, for example supabase_flutter: 3.0.0-dev.17.
- Rename
anonKey to publishableKey in Supabase.initialize.
- Swap any direct dependency on the four old packages for their new names.
- Fix the compile errors for typed dates, URLs and realtime streams, following the migration guide.
- While installed v2 apps still listen on a broadcast channel, turn on
v2BroadcastCompatibility for it, or release every app that shares the channel at the same time:
final channel = supabase.channel(
'room',
options: const RealtimeChannelConfig(v2BroadcastCompatibility: true),
);
Test it
Run your app against your project, check that lists still come back in the order you expect (including where NULLs land), and test realtime between a v2 and a v3 device on the same channel.
Not confirmed
- Supabase has not posted a new date for the stable 3.0.0 release.
- The env variable name is ours; Supabase's Flutter samples pass the key as a string.