--- slug: supabase-flutter-v3 published: 2026-11-06 change_type: breaking-change affected_products: - supabase-flutter page: https://supabase.com/changelog/supabase-flutter-v3 --- # 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](https://pub.dev/packages/supabase_flutter/versions). 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` instead of `List>`, 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 `Stream`s, `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](https://dart.dev/ai/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](https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md#changes-the-compiler-will-not-catch) in the migration guide before you ship. ## Migration steps 1. Read the [changes the compiler will not catch](https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md#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](https://github.com/supabase/supabase-flutter/blob/main/MIGRATION.md). 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 | Date | Milestone | User action | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Now | v3 available as `3.0.0-dev` prereleases on pub.dev | Optional: try v3 and report issues on [GitHub](https://github.com/supabase/supabase-flutter/issues) | | **2026-11-11** | 3.0.0 stable. `gotrue`, `realtime_client`, `storage_client`, and `functions_client` are marked discontinued on pub.dev | Upgrade by following the migration steps | | 6 months after the stable release | v2 stops receiving security and critical fixes | Finish the upgrade to v3 | Questions or problems with the upgrade? Open an issue on [supabase-flutter](https://github.com/supabase/supabase-flutter/issues) or contact [Supabase support](https://supabase.com/support).