supabase/supabase-flutter/supabase-migrate-v3

Migrate supabase from v2 to v3

The full migration guide is in references/migration-v2-v3.md. Its section headings name the symbol that changed, so search it for the symbol in a compiler error or in the code you are changing. Every "Before" and "After" snippet there is authoritative. This file is the order to apply it in and the checks that make the migration complete.

Rules

• Follow the steps in order. Do not skip the Supabase CLI check.
• Never write the table definitions by hand. They come from

supabase gen types --lang dart, and the generated file is never edited.

• Every query ends up on the typed table() API unless it matches one of the

exceptions in step 8. Report every exception to the user.

• Keep the behavior of the app. Where v3 changed a default, pin the v2

behavior explicitly unless the user asks for the new one.

• Do not suppress analyzer errors or warnings to get a clean run. Fix them.
• Ask the user before a choice that changes runtime behavior and is not

covered here.

1. Preflight

1. Read pubspec.yaml. Note which of these are dependencies and their

versions: supabase_flutter, supabase, gotrue, postgrest, realtime_client, storage_client, functions_client.

1. Run git status. If the tree is dirty, ask the user to commit or stash

first so the migration is one reviewable diff.

1. Run dart analyze and save the output. Issues that exist before the

migration are the baseline, and step 9 is measured against it.

1. Check for a supabase/ folder with config.toml and migrations/. It

decides the source of the generated types in step 4.

2. Supabase CLI 2.122.0 or newer

Dart generation requires Supabase CLI 2.122.0 or newer.

supabase --version

If the project runs the CLI through npm (a supabase entry in package.json), check npx supabase --version instead.

If the command is missing or prints a version below 2.122.0, stop and give the user the command for their platform, then wait until the version check passes:

Do not continue on an older CLI and do not fall back to hand-written types.

3. Pin the changed order() defaults while still on v2

v3 changed two defaults of order() without a compile error. Both pins below already mean the same thing on v2, so add them before upgrading:

grep -rnE '\.order\(' lib test bin

• A call without ascending: sorted descending on v2 and sorts ascending on

v3. Add ascending: false.

• A query that sorts descending (including the ones you just changed) put

NULLs last on v2 and puts them first on v3. When the column is nullable, add nullsFirst: false. This does not apply to stream().order(), which takes no null placement.

The direction pin applies to stream().order() too. The result is that every order() call states its direction and, on a descending query of a nullable column, its null placement.

4. Dependencies and the typed schema

Once supabase_typegen is added, its supabase-typegen-generate skill has the details of the generator, its options and its errors.

1. Update the dependencies. Use the newest 3.x version of each package;

dart pub outdated lists it, prereleases included.

• supabase to 3.x.
• Replace any direct dependency on a renamed package, and its imports:

A direct dependency that only duplicates what supabase already re-exports can be removed instead.

1. Add the generator: dart pub add dev:supabase_typegen.
2. Run dart pub get.
3. Generate the schema. Pick the source:

• A supabase/ folder with migrations: run supabase start (needs Docker),

then supabase gen types --lang dart --local.

• A project linked with supabase link: --linked.
• Otherwise ask the user for the project ref and use

--project-id <ref>.

Ask which schemas the app queries. Pass --schema for each schema other than public that the app uses. Write to lib/supabase_schema.g.dart unless the project already has a generated-code convention:

``sh supabase gen types --lang dart --local > lib/supabase_schema.g.dart ``

1. Run dart analyze lib/supabase_schema.g.dart. It must be clean. If it is

not, report the error to the user rather than editing the file.

5. Mechanical renames

Apply these across the project before reading compiler errors, since they remove most of them. The tables are in the reference:

• "The client packages are renamed": imports and the GoTrue* type names,

such as GoTrueClient to AuthClient.

• "Abbreviations in the public API are spelled out": for example

queryParams: to queryParameters: and opts: to options:.

• "Plural enum names singularized" and "One shared SortDirection for every

sort direction".

• "Every deprecated API is gone": for example User.confirmedAt to

User.emailConfirmedAt and AuthUser to User.

6. Compiler-driven pass

1. Run dart analyze.
2. For each new error, search the reference for the symbol it names and apply

the "After" form of that section.

1. Repeat until the only issues left are the baseline from step 1.

The sections that most often apply:

• "Sign-in methods that always issue a session return the Session":

signInWithPassword() and others return the Session directly.

• "AuthState is a sealed class" and

"User.appMetadata is an AppMetadata and userMetadata is never null".

• "Realtime listener callbacks are now streams": onPostgresChanges,

onBroadcast and the connection callbacks.

• "The auth client persists the session itself": localStorage: and

LocalStorage subclasses become an AuthAsyncStorage.

• "Service exceptions share one base" and "FunctionsException is sealed".
• "Every client takes one SupabaseRetryOptions".
• "Timestamps are DateTime instead of String or int".
• "rpc is a getter", "insert() and upsert() no longer take filters" and

"The rest client and its builders are stateless".

7. Changes the compiler will not catch

Go through every item. For each one, search with the given pattern, read every match, and fix or confirm it. Keep a list of the sites you could not decide for the summary in step 9.