Upgrade guide

Make sure you are using v2 of the client library in your pubspec.yaml file.

Optionally passing custom configuration to Supabase.initialize() is now organized into separate objects:

Renaming Provider to OAuthProvider#

Provider enum is renamed to OAuthProvider. Previously the Provider symbol often collided with classes in the provider package and developers needed to add import prefixes to avoid collisions. With the new update, developers can use Supabase and Provider in the same codebase without any import prefixes.

Sign in with Apple method deprecated#

We have removed the sign_in_with_apple dependency in v2. This is because not every developer needs to sign in with Apple, and we want to reduce the number of dependencies in the library.

With v2, you can import sign_in_with_apple as a separate dependency if you need to sign in with Apple. We have also added auth.generateRawNonce() method to easily generate a secure nonce.

Initialization does not await for session refresh#

In v1, Supabase.initialize() would await for the session to be refreshed before returning. This caused delays in the app's launch time, especially when the app is opened in a poor network environment.

In v2, Supabase.initialize() returns immediately after obtaining the session from the local storage, which makes the app launch faster. Because of this, there is no guarantee that the session is valid when the app starts.

If you need to make sure the session is valid, you can access the isExpired getter to check if the session is valid. If the session is expired, you can listen to the onAuthStateChange event and wait for a new tokenRefreshed event to be fired.

Removing Flutter Webview dependency for OAuth sign in#

In v1, on iOS you could pass a BuildContext to the signInWithOAuth() method to launch the OAuth flow in a Flutter Webview.

In v2, we have dropped the webview_flutter dependency in v2 to allow you to have full control over the UI of the OAuth flow. We now have native support for Google and Apple sign in, so opening an external browser is no longer needed on iOS.

Because of this update, we no longer need the context parameter, so we have removed the context parameter from the signInWithOAuth() method.

PKCE is the default auth flow type#

PKCE flow, which is a more secure method for obtaining sessions from deep links, is now the default auth flow for any authentication involving deep links.

Auth callback host name parameter removed#

Supabase.initialize() no longer has the authCallbackUrlHostname parameter. The supabase_flutter SDK will automatically detect auth callback URLs and handle them internally.

SupabaseAuth class removed#

The SupabaseAuth had an initialSession member, which was used to obtain the initial session upon app start. This is now removed, and currentSession should be used to access the session at any time.

Insert and return data#

We made the query builder immutable, which means you can reuse the same query object to chain multiple filters and get the expected outcome.

Renaming is and in filter#

Because is and in are reserved keywords in Dart, v1 used is_ and in_ as query filter names. Users found the underscore confusing, so the query filters are now renamed to isFilter and inFilter.

Deprecate FetchOption in favor of count() and head() methods#

FetchOption() on .select() is now deprecated, and new .count() and head() methods are added to the query builder.

count() on .select() performs the select while also getting the count value, and .count() directly on .from() performs a head request resulting in only fetching the count value.

PostgREST error codes#

The PostgrestException instance thrown by the API methods has a code property. In v1, the code property contained the http status code.

In v2, the code property contains the PostgREST error code, which is more useful for debugging.

Postgres Changes#

Use the new .onPostgresChanges() method to listen to realtime changes in the database.

In v1, filters were not strongly typed because they took a String type. In v2, filter takes an object. Its properties are strictly typed to catch type errors.

The payload of the callback is now typed as well. In v1, the payload was returned as dynamic. It is now returned as a PostgresChangePayload object. The object contains the oldRecord and newRecord properties for accessing the data before and after the change.

Broadcast#

Broadcast now uses the dedicated .onBroadcast() method, rather than the generic .on() method. Because the method is specific to broadcast, it takes fewer properties.

Presence#

Realtime Presence gets three different methods for listening to three different presence events: sync, join, and leave. This allows the callback to be strictly typed.