Query tables with table() and the generated schema, never with from() and Map<String, dynamic>, unless the table is missing from the generated file.
Generate the schema with the Supabase CLI (3.0.0 or newer) and never edit it by hand. Regenerate it after every change to the database schema, whether it came from a migration or the dashboard, and after upgrading supabase_typegen or the Supabase CLI. For a project that keeps its schema in supabase/migrations, apply new migrations to the local stack with supabase migration up first, then run supabase gen types --lang dart > lib/supabase_schema.g.dart. migration up skips migrations that are already applied, so after editing one, rebuild the stack with supabase db reset, which drops local data, so ask the user first. Add --remote for the linked project, or --remote=<ref> for another one, to read a hosted project instead, such as after a change in the dashboard. The supabase-typegen-generate skill, installed with the supabase_typegen dev dependency, covers the setup and the options.
Pass publishableKey. anonKey does not exist in v3.
Listen to realtime with streams. v3 has no callback: parameters.
Catch the SupabaseException hierarchy, never ClientException, TimeoutException or String.
A typed update() or delete() does nothing until .where(…) or .all() is called on it. The analyzer reports a missing one as an unused_result warning.
Create one SupabaseClient per process and reuse it. Call dispose() on it before a script exits.

Client setup

import 'package:supabase/supabase.dart';

final supabase = SupabaseClient(
  'https://your-project.supabase.co',
  'your-publishable-key',
);

A client without an asyncStorage keeps the code verifiers of the default pkce flow in memory, so pass a storage that writes to disk when the flow completes in another process, such as from an email link. Pass persistSession: true and such a storage to keep the session across runs, then await supabase.auth.initialized before reading currentSession.

Reading rows

The generated file has, per table, a row type (BooksRow), insert and update types (BooksInsert, BooksUpdate) and a class (Books) with the table definition and one constant per column and relation. A table in another schema carries the schema as a prefix, InventoryBooks.

final List<BooksRow> books = await supabase
    .table(Books.table)
    .select()
    .where(Books.inPrint.isTrue() & Books.price.lt(10))
    .order(Books.createdAt.desc())
    .limit(20);
final String title = books.first.title;

final BooksRow book = await supabase
    .table(Books.table)
    .select()
    .where(Books.id.eq(1))
    .single();

Filters are methods on the column constants, combined with &, | and not(). Values must match the column type, and isNull() only exists on nullable columns. order() sorts ascending unless the ordering says .desc().

Read some columns only, or embed related rows, with selectOnly, and read the values back through the same constants:

final books = await supabase.table(Books.table).selectOnly([
  Books.title,
  Books.authors(Authors.name),
]);
final String title = books.first.read(Books.title);
final String? authorName = books.first.read(Books.authors)?.read(Authors.name);

Writing rows

await supabase
    .table(Books.table)
    .insert(BooksInsert(authorId: 2, title: 'Dune'));

final BooksRow inserted = await supabase
    .table(Books.table)
    .insert(BooksInsert(authorId: 2, title: 'Emma'))
    .select()
    .single();

await supabase
    .table(Books.table)
    .update(BooksUpdate(inPrint: false).setPriceToNull())
    .where(Books.id.eq(1));

await supabase.table(Books.table).delete().where(Books.id.eq(1));

Several rows go through insertAll() and upsertAll().
A null argument to BooksInsert or BooksUpdate leaves the column out. Write SQL NULL with the generated set…ToNull() methods.
Writes resolve to void. Add .select() to get the written rows back.
upsert() takes onConflict as a list of columns, onConflict: [Authors.name].

Calling database functions

Every function PostgREST exposes gets a typed method on rpc:

final BooksRow? book = await supabase.rpc.bookById(bookId: 1);

supabase.rpc('fn', params: {...}) is the untyped fallback for functions the generator gives no method, which it explains in a comment in the generated file.

Auth

Sign-in methods that always produce a session return the Session:

final session = await supabase.auth.signInWithPassword(
  email: 'user@example.com',
  password: 'a-strong-password',
);
final user = session.user;

signUp() and verifyOTP() still return an AuthResponse, since they can complete without a session.

AuthState is sealed, with one subtype per event. Every new listener first receives AuthInitialSession with the current session or null. A failed token refresh, for example while offline, is an error of the stream, so every listener passes onError:

final subscription = supabase.auth.onAuthStateChange.listen(
  (state) {
    switch (state) {
      case AuthInitialSession(:final session):
        // The session when this listener attached, or null.
        print(session?.user.id);
      case AuthSignedIn(:final session):
        print('Signed in as ${session.user.email}');
      case AuthSignedOut():
        print('Signed out');
      case _:
    }
  },
  onError: (Object error) => print('Auth error: $error'),
);

user.userMetadata is never null, and user.appMetadata is an AppMetadata with typed provider and providers.

Realtime

Keep a list of rows up to date with stream():

final Stream<List<BooksRow>> books = supabase
    .table(Books.table)
    .stream(primaryKey: [Books.id])
    .filter(Books.authorId.eq(2))
    .order(Books.title);

The supabase-realtime skill covers broadcast, presence and channel status in more depth.

React to individual changes with onTableChanges. Create the stream before subscribe(), and remove the channel when done:

final channel = supabase.channel('books');
final subscription = channel
    .onTableChanges(Books.table, filters: [Books.authorId.eq(2)])
    .listen((change) {
      switch (change) {
        case TypedPostgresInsert(:final newRow):
          print('Added ${newRow.title}');
        case TypedPostgresUpdate(:final newRow):
          print('Changed ${newRow.title}');
        case TypedPostgresDelete(:final oldRow):
          print('Removed ${oldRow.read(Books.id)}');
      }
    });
channel.subscribe();

await subscription.cancel();
await supabase.removeChannel(channel);

Broadcast and connection status are streams too:

final channel = supabase.channel('room');
channel
    .onBroadcast(event: 'cursor')
    .listen((message) => print(message['payload']));
channel.onStatusChange.listen((change) async {
  if (change.status == RealtimeSubscribeStatus.subscribed) {
    await channel.sendBroadcastMessage(event: 'cursor', payload: {'x': 1});
  }
});
channel.subscribe();

The table must be added to the supabase_realtime publication in the database, or no changes arrive.

Errors

Every exception the SDK throws for a failed request extends SupabaseException. SupabaseApiException means the server answered with an error, and SupabaseTransportException means no response arrived, including a timeout:

try {
  await supabase.table(Books.table).select();
} on SupabaseApiException catch (error) {
  print('${error.statusCode} ${error.errorCode}: ${error.message}');
} on SupabaseTransportException catch (error) {
  print('No response: ${error.cause}');
}

Each service also has its own base, such as PostgrestException, AuthException or StorageException, to catch the errors of one service only. AuthApiException and PostgrestApiException carry the server's errorCode.

Logging

The SDK never prints. It logs through package:logging under the supabase logger, so listen to it to see the records:

import 'package:logging/logging.dart';

void enableSupabaseLogs() {
  Logger.root.onRecord.listen((record) {
    if (record.loggerName.startsWith('supabase.')) {
      print('${record.loggerName}: ${record.level.name}: ${record.message}');
    }
  });
}

Tests

Use the supabase_test package as a dev dependency instead of mocking the HTTP client by hand. Its MockSupabaseHttpClient, testSupabaseClient and signInTestUser answer requests and put a client in a signed-in state. The supabase-test-testing skill, installed with the supabase_test dev dependency, covers stubbing, assertions, auth and realtime in tests.

supabase-idioms

Writing supabase v3 code

Rules