Brick is an all-in-one data manager for Flutter that handles querying and uploading between Supabase and local caches like SQLite. Using Brick, developers can focus on implementing the application without worrying about translating or storing their data.
Most significantly, Brick focuses on offline-first data parity: an app should function the same with or without connectivity.
Why Offline?#
The worst version of your app is always the unusable one. People use their phones on subways, airplanes, and on sub-3G connections. Building for offline-first provides the best user experience when you can’t guarantee steady bandwidth.
Even if you’re online-only, Brick’s round trip time is drastically shorter because all data from Supabase is stored in a local cache. When you query the same data again, your app retrieves the local copy, reducing the time and expense of a round trip. And, if SQLite isn’t performant enough, Brick also offers a third cache in memory. When requests are made while the app is offline, they’ll be continually retried until the app comes online, ensuring that your local state syncs up to your remote state.
Of course, you can always opt-out of the cache on a request-by-request basis for sensitive or must-be-fresh data.
Getting Started#
Create a Flutter app:
Add the Brick dependencies to your pubspec.yaml:
_10
dependencies:
_10
brick_offline_first_with_supabase: ^1.0.0
_10
sqflite: ^2.3.0
_10
brick_sqlite: ^3.1.0
_10
uuid: ^3.0.4
_10
_10
dev_dependencies:
_10
brick_offline_first_with_supabase_build: ^1.0.0
_10
build_runner: ^2.4.0
Set up directories for Brick’s generated code:
_10
mkdir -p lib/brick/adapters lib/brick/db;
Brick synthesizes your remote data to your local data through code generation. From a Supabase table, create Dart fields that match the table’s columns:
_26
// Your model definition can live anywhere in lib/**/* as long as it has the .model.dart suffix
_26
// Assume this file is saved at my_app/lib/src/users/user.model.dart
_26
_26
import 'package:brick_offline_first_with_supabase/brick_offline_first_with_supabase.dart';
_26
import 'package:brick_sqlite/brick_sqlite.dart';
_26
import 'package:brick_supabase/brick_supabase.dart';
_26
import 'package:uuid/uuid.dart';
_26
_26
@ConnectOfflineFirstWithSupabase(
_26
supabaseConfig: SupabaseSerializable(tableName: 'users'),
_26
)
_26
class User extends OfflineFirstWithSupabaseModel {
_26
final String name;
_26
_26
// Be sure to specify an index that **is not** auto incremented in your table.
_26
// An offline-first strategy requires distributed clients to create
_26
// indexes without fear of collision.
_26
@Supabase(unique: true)
_26
@Sqlite(index: true, unique: true)
_26
final String id;
_26
_26
User({
_26
String? id,
_26
required this.name,
_26
}) : this.id = id ?? const Uuid().v4();
_26
}
When some (or all) of your models have been defined, generate the code:
_10
dart run build_runner build
This will generate adapters to serialize/deserialize to and from Supabase. Migrations for SQLite are also generated for any new, dropped, or changed columns. Check these migrations after they are generated - Brick is smart, but not as smart as you.
The Repository#
Your application does not need to touch SQLite or Supabase directly. By interacting with this single entrypoint, Brick makes the hard choices under the hood about where to fetch and when to cache while the application code remains consistent in online or offline modes.
Finally, run your app:
_54
// Saved in my_app/lib/src/brick/repository.dart
_54
import 'package:brick_offline_first_with_supabase/brick_offline_first_with_supabase.dart';
_54
import 'package:brick_sqlite/brick_sqlite.dart';
_54
// This hide is for Brick's @Supabase annotation; in most cases,
_54
// supabase_flutter **will not** be imported in application code.
_54
import 'package:brick_supabase/brick_supabase.dart' hide Supabase;
_54
import 'package:sqflite_common/sqlite_api.dart';
_54
import 'package:supabase_flutter/supabase_flutter.dart';
_54
_54
import 'brick.g.dart';
_54
_54
class Repository extends OfflineFirstWithSupabaseRepository {
_54
static late Repository? _instance;
_54
_54
Repository._({
_54
required super.supabaseProvider,
_54
required super.sqliteProvider,
_54
required super.migrations,
_54
required super.offlineRequestQueue,
_54
super.memoryCacheProvider,
_54
});
_54
_54
factory Repository() => _instance!;
_54
_54
static Future<void> configure(DatabaseFactory databaseFactory) async {
_54
final (client, queue) = OfflineFirstWithSupabaseRepository.clientQueue(
_54
databaseFactory: databaseFactory,
_54
);
_54
_54
await Supabase.initialize(
_54
url: supabaseUrl,
_54
anonKey: supabaseAnonKey,
_54
httpClient: client,
_54
);
_54
_54
final provider = SupabaseProvider(
_54
Supabase.instance.client,
_54
modelDictionary: supabaseModelDictionary,
_54
);
_54
_54
_instance = Repository._(
_54
supabaseProvider: provider,
_54
sqliteProvider: SqliteProvider(
_54
'my_repository.sqlite',
_54
databaseFactory: databaseFactory,
_54
modelDictionary: sqliteModelDictionary,
_54
),
_54
migrations: migrations,
_54
offlineRequestQueue: queue,
_54
// Specify class types that should be cached in memory
_54
memoryCacheProvider: MemoryCacheProvider(),
_54
);
_54
}
_54
}
_11
import 'package:my_app/brick/repository.dart';
_11
import 'package:sqflite/sqflite.dart' show databaseFactory;
_11
_11
Future<void> main() async {
_11
await Repository.configure(databaseFactory);
_11
// .initialize() does not need to be invoked within main()
_11
// It can be invoked from within a state manager or within
_11
// an initState()
_11
await Repository().initialize();
_11
runApp(MyApp());
_11
}
The fun part. Brick’s DSL queries are written once and transformed for local and remote integration. For example, to retrieve all users with the name “Thomas”:
_10
await Repository().get<User>(query: Query.where('name', 'Thomas'));
Or query by association:
_10
// Assuming we had a model `Order` with a `user` association
_10
await Repository().get<Order>(query: Query.where('user', Where.exact('name', 'Thomas'));
Queries can be much more advanced, leveraging contains, not, like operators as well as sub clauses. Please note that, as of writing, not all Supabase operators are supported.
Reactivity
Beyond async requests, you can subscribe to a stream of updated local data from anywhere in your app (for example, if you pull-to-refresh a list of users, all listeners will be notified of the new data):
_10
final Stream<List<User>> usersStream = Repository().subscribe<User>(query: Query.where('name', 'Thomas'));
This does not leverage Supabase’s channels by default; if Supabase updates, your app will not be notified. This opt-in feature is currently under active development.
Upserting
After a model has been created, it can uploaded to Supabase without serializing it to JSON first:
_10
await Repository().upsert<User>(User(name: 'Thomas'));
All attached associations will be upserted too.
Foreign Keys/Associations#
Easily connect related models/tables:
_25
import 'package:brick_offline_first_with_supabase/brick_offline_first_with_supabase.dart';
_25
import 'package:brick_sqlite/brick_sqlite.dart';
_25
import 'package:brick_supabase/brick_supabase.dart';
_25
import 'package:my_app/lib/src/users/user.model.dart';
_25
import 'package:uuid/uuid.dart';
_25
_25
@ConnectOfflineFirstWithSupabase(
_25
supabaseConfig: SupabaseSerializable(tableName: 'orders'),
_25
)
_25
class Order extends OfflineFirstWithSupabaseModel {
_25
// Like Supabase's client, specifying a foreign_key
_25
// is possible but only necessary if there are joins
_25
// with multiple foreign keys
_25
// @Supabase(foreignKey: 'user_id')
_25
final User user;
_25
_25
@Supabase(unique: true)
_25
@Sqlite(index: true, unique: true)
_25
final String id;
_25
_25
Order({
_25
String? id,
_25
required this.user,
_25
}) : this.id = id ?? const Uuid().v4();
_25
}
Brick allows very granular model configuration - you can specify specific tables, individual columns, and more.
Testing#
Quickly mock your Supabase endpoints to add uncluttered unit testing:
_33
import 'package:brick_supabase/testing.dart';
_33
import 'package:test/test.dart'
_33
_33
void main() {
_33
// Pass an instance of your model dictionary to the mock server.
_33
// This permits quick generation of fields and generated responses
_33
final mock = SupabaseMockServer(modelDictionary: supabaseModelDictionary);
_33
_33
group('MyClass', () {
_33
setUp(mock.setUp);
_33
_33
tearDown(mock.tearDown);
_33
_33
test('#myMethod', () async {
_33
// If your request won't exactly match the columns of MyModel, provide
_33
// the query list to the `fields:` parameter
_33
final req = SupabaseRequest<MyModel>();
_33
final resp = SupabaseResponse([
_33
// mock.serialize converts models to expected Supabase payloads
_33
// but you don't need to use it - any jsonEncode-able object
_33
// can be passed to SupabaseRepsonse
_33
await mock.serialize(MyModel(name: 'Demo 1', id: '1')),
_33
await mock.serialize(MyModel(name: 'Demo 2', id: '2')),
_33
]);
_33
// This method stubs the server based on the described requests
_33
// and their matched responses
_33
mock.handle({req: resp});
_33
final provider = SupabaseProvider(mock.client, modelDictionary: supabaseModelDictionary);
_33
final retrieved = await provider.get<MyModel>();
_33
expect(retrieved, hasLength(2));
_33
});
_33
});
_33
}
Brick manages a lot. It can be overwhelming at times. But it’s been used in production across thousands of devices for more than five years, so it’s got a sturdy CV. There’s likely an existing solution to a seemingly novel problem. Please reach out to the community or package maintainers with any questions.
- Example: Brick with Supabase
- Video: Brick Architecture. An explanation of Brick parlance with a supplemental analogy.
- Video: Brick Basics. An overview of essential Brick mechanics.
- Build a User Management App with Flutter