You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
supabase-flutter v3 types queries, functions, realtime, and auth, and changes v2 behavior. Nothing changes until you upgrade. Follow the migration guide and check the changes the compiler misses.
supabase-flutter v3 is the next major version of the Supabase client libraries for Flutter and Dart. You can try it today through the 3.0.0-dev prereleases on pub.dev. The stable 3.0.0 release is planned for November 11, 2026.
What you get
Types across the whole client. supabase gen types --lang dart turns your database schema into a Dart file with a row, insert, and update type for every table. The new supabase.table(Books.table) API uses them end to end: selects return List<BooksRow> instead of List<Map<String, dynamic>>, a filter such as Books.price.lt(20) only accepts a value of the column's type, writes take generated insert and update types, embedded selects follow foreign keys, and stream() emits typed rows. Postgres functions get typed methods on supabase.rpc. Beyond the database, the connection state of the realtime client, channel results, AuthState, and every service exception are typed too. A renamed column breaks your build, not your users' sessions.
An API that reads like Dart. Timestamps are DateTime, URLs are Uri, durations are Duration, realtime listeners are Streams, AuthState is a sealed class you can switch over exhaustively, and every service exception extends one SupabaseException base.
Skills for coding agents. The supabase, supabase_flutter, supabase_typegen, and supabase_test packages ship package skills for Claude Code, Cursor, Gemini, and Copilot. They teach your agent the v3 API instead of the v2 code it was trained on, and include a skill that carries a v2 project through the upgrade.
The typed API is additive. from() keeps working on the same client, so you can move one table at a time. It is marked @experimental while its shape settles.
Why v3 breaks v2 code
Large parts of v2 were ported directly from supabase-js. Timestamps and URLs were strings, realtime used callbacks, and order() sorted descending by default, the opposite of SQL, with nothing in the analyzer or the results to reveal it. A major version is the only moment these shapes and defaults can change, so v3 changes all of them at once. You upgrade once instead of absorbing a series of smaller breaks.
Who is affected
Every Dart and Flutter project on supabase_flutter or supabase v2 that upgrades to v3.
Projects that depend directly on gotrue, realtime_client, storage_client, or functions_client. These are renamed to supabase_auth, supabase_realtime, supabase_storage, and supabase_functions, and the old packages are marked discontinued on pub.dev when v3 ships. If you only depend on supabase_flutter or supabase, your dependencies and imports stay the same.
Projects that use a third-party package built on supabase_flutter v2. You can upgrade once that package releases a v3-compatible version.
Self-hosted projects running a GoTrue older than API version 2024-01-01. v3 only reads the newer error codes.
What happens if you take no action
Nothing changes. A ^2.x version constraint never resolves 3.0.0, and pub never picks a prerelease unless you ask for one. v2 keeps receiving security and critical fixes for 6 months after the stable 3.0.0 release. New features only land in v3.
Changes the compiler will not catch
Most of the upgrade shows up as compile errors. Some changes do not, such as the default sort direction of order() and how apps on v2 and v3 exchange realtime broadcasts, so check the full list of changes the compiler will not catch in the migration guide before you ship.
Migration steps
Read the changes the compiler will not catch. Add ascending: false to every order() call that relies on descending order, while you are still on v2.
Bump supabase_flutter or supabase to ^3.0.0 in pubspec.yaml. Replace direct dependencies on gotrue, realtime_client, storage_client, and functions_client with their renamed packages.
Install the package skills, for example with dart run skills@ get -p supabase_flutter, then ask your coding agent to run the migration skill if you work with one.
Fix the compile errors with the migration guide. For example, anonKey on Supabase.initialize becomes publishableKey. Your existing anon key is still a valid value.
Go through the changes the compiler will not catch one by one, and release every app that shares a realtime broadcast channel at the same time.
Optionally, add supabase_typegen as a dev dependency, generate your types with Supabase CLI 2.122.0 or newer, and move your queries from from() to table().
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
supabase-flutter v3 types queries, functions, realtime, and auth, and changes v2 behavior. Nothing changes until you upgrade. Follow the migration guide and check the changes the compiler misses.
supabase-flutter v3 is the next major version of the Supabase client libraries for Flutter and Dart. You can try it today through the
3.0.0-devprereleases on pub.dev. The stable 3.0.0 release is planned for November 11, 2026.What you get
supabase gen types --lang dartturns your database schema into a Dart file with a row, insert, and update type for every table. The newsupabase.table(Books.table)API uses them end to end: selects returnList<BooksRow>instead ofList<Map<String, dynamic>>, a filter such asBooks.price.lt(20)only accepts a value of the column's type, writes take generated insert and update types, embedded selects follow foreign keys, andstream()emits typed rows. Postgres functions get typed methods onsupabase.rpc. Beyond the database, the connection state of the realtime client, channel results,AuthState, and every service exception are typed too. A renamed column breaks your build, not your users' sessions.DateTime, URLs areUri, durations areDuration, realtime listeners areStreams,AuthStateis a sealed class you canswitchover exhaustively, and every service exception extends oneSupabaseExceptionbase.supabase,supabase_flutter,supabase_typegen, andsupabase_testpackages ship package skills for Claude Code, Cursor, Gemini, and Copilot. They teach your agent the v3 API instead of the v2 code it was trained on, and include a skill that carries a v2 project through the upgrade.The typed API is additive.
from()keeps working on the same client, so you can move one table at a time. It is marked@experimentalwhile its shape settles.Why v3 breaks v2 code
Large parts of v2 were ported directly from
supabase-js. Timestamps and URLs were strings, realtime used callbacks, andorder()sorted descending by default, the opposite of SQL, with nothing in the analyzer or the results to reveal it. A major version is the only moment these shapes and defaults can change, so v3 changes all of them at once. You upgrade once instead of absorbing a series of smaller breaks.Who is affected
supabase_flutterorsupabasev2 that upgrades to v3.gotrue,realtime_client,storage_client, orfunctions_client. These are renamed tosupabase_auth,supabase_realtime,supabase_storage, andsupabase_functions, and the old packages are marked discontinued on pub.dev when v3 ships. If you only depend onsupabase_flutterorsupabase, your dependencies and imports stay the same.supabase_flutterv2. You can upgrade once that package releases a v3-compatible version.2024-01-01. v3 only reads the newer error codes.What happens if you take no action
Nothing changes. A
^2.xversion constraint never resolves 3.0.0, and pub never picks a prerelease unless you ask for one. v2 keeps receiving security and critical fixes for 6 months after the stable 3.0.0 release. New features only land in v3.Changes the compiler will not catch
Most of the upgrade shows up as compile errors. Some changes do not, such as the default sort direction of
order()and how apps on v2 and v3 exchange realtime broadcasts, so check the full list of changes the compiler will not catch in the migration guide before you ship.Migration steps
ascending: falseto everyorder()call that relies on descending order, while you are still on v2.supabase_flutterorsupabaseto^3.0.0inpubspec.yaml. Replace direct dependencies ongotrue,realtime_client,storage_client, andfunctions_clientwith their renamed packages.dart run skills@ get -p supabase_flutter, then ask your coding agent to run the migration skill if you work with one.anonKeyonSupabase.initializebecomespublishableKey. Your existing anon key is still a valid value.supabase_typegenas a dev dependency, generate your types with Supabase CLI 2.122.0 or newer, and move your queries fromfrom()totable().Rollout timeline
3.0.0-devprereleases on pub.devgotrue,realtime_client,storage_client, andfunctions_clientare marked discontinued on pub.devQuestions or problems with the upgrade? Open an issue on supabase-flutter or contact Supabase support.
Affected products: supabase-flutter
All reactions