Breaking Change: supabase-flutter v3 brings type safety to the whole API surface

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#

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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().

Rollout timeline#

Questions or problems with the upgrade? Open an issue on supabase-flutter or contact Supabase support.