# Flutter InstantDB — Full Documentation
> Flutter SDK for InstantDB — a real-time, offline-first, local-first database with reactive bindings. Type-safe InstaQL queries, optimistic InstaML transactions, WebSocket sync, auth, presence/rooms, file storage, and reactive widgets for iOS, Android, Web, macOS, Windows, and Linux.
---
# Flutter InstantDB
> Real-time, offline-first database for Flutter with reactive bindings, type-safe queries and code generation.
Source: https://flutter-instantdb.vercel.app/docs
A Flutter/Dart port of [InstantDB](https://instantdb.com) — a real-time,
offline-first database with reactive bindings, a type-safe query DSL, code
generation, and live multiplayer collaboration.
Add the package and initialize the client.
Reactive queries, transactions, and your first live widget.
Compile-time-safe queries and writes generated from your models.
Annotate a model, run the generator, get typed tables.
## A taste
```dart
final db = await InstantDB.init(
appId: 'your-app-id',
config: const InstantConfig(syncEnabled: true),
);
final todos = await TodoTable()
.query()
.where((t) => t.done.eq(false))
.order((t) => t.createdAt.desc())
.getAll(db);
await db.transact(
TodoTable().tx(db).createModel(
Todo(id: db.id(), title: 'Ship it', done: false),
),
);
```
---
# Migration Strategies
> Upgrading Flutter InstantDB and handling data migrations
Source: https://flutter-instantdb.vercel.app/docs/advanced/migration
Handle Flutter InstantDB package updates, data migrations, and schema changes with confidence using proven migration strategies and tools.
## Package Updates
### Semantic Versioning
Flutter InstantDB follows semantic versioning (semver):
- **Patch releases** (0.1.1 → 0.1.2): Bug fixes, no breaking changes
- **Minor releases** (0.1.0 → 0.2.0): New features, backward compatible
- **Major releases** (0.1.0 → 1.0.0): Breaking changes, requires migration
### Safe Update Process
Follow this process for safe updates:
```dart
// 1. Check current version
void checkCurrentVersion() {
// Add to pubspec.yaml temporarily to see current version
print('Current InstantDB version: check pubspec.yaml');
}
// 2. Read changelog before updating
// Always check CHANGELOG.md on GitHub or pub.dev
// 3. Update in development first
// Test thoroughly in development before production
// 4. Create backup of critical data if needed
Future backupCriticalData(InstantDB db) async {
final criticalEntities = ['users', 'payments', 'orders'];
final backup = >>{};
for (final entityType in criticalEntities) {
final result = await db.queryOnce({entityType: {}});
backup[entityType] = (result.data?[entityType] as List? ?? [])
.cast>();
}
// Save backup to file or external storage
await _saveBackup(backup);
}
Future _saveBackup(Map backup) async {
// Implementation depends on your backup strategy
// Could be local file, cloud storage, etc.
}
```
### Breaking Changes Migration
Handle breaking changes systematically:
```dart
class MigrationManager {
final String fromVersion;
final String toVersion;
MigrationManager({
required this.fromVersion,
required this.toVersion,
});
Future migrate(InstantDB db) async {
print('Migrating from $fromVersion to $toVersion');
// Apply migrations based on version ranges
if (_shouldApply('0.1.0', '0.2.0')) {
await _migrateFrom01To02(db);
}
if (_shouldApply('0.2.0', '1.0.0')) {
await _migrateFrom02To10(db);
}
// Update stored version
await _setMigrationVersion(toVersion);
}
bool _shouldApply(String minVersion, String maxVersion) {
// Implement version comparison logic
return _isVersionInRange(fromVersion, minVersion, maxVersion);
}
bool _isVersionInRange(String version, String min, String max) {
// Simple version comparison - you might want a more robust implementation
final versionParts = version.split('.').map(int.parse).toList();
final minParts = min.split('.').map(int.parse).toList();
final maxParts = max.split('.').map(int.parse).toList();
return _compareVersions(versionParts, minParts) >= 0 &&
_compareVersions(versionParts, maxParts) < 0;
}
int _compareVersions(List v1, List v2) {
for (int i = 0; i < 3; i++) {
final diff = v1[i] - v2[i];
if (diff != 0) return diff;
}
return 0;
}
// Example migration from 0.1.0 to 0.2.0
Future _migrateFrom01To02(InstantDB db) async {
print('Applying 0.1.0 → 0.2.0 migration');
// Example: API change in transaction methods
// Old: db.transactChunk() → New: db.transact()
// This would be handled automatically by the package,
// but you might need to update your code
// Example: Schema changes
await _updateUserSchema(db);
}
Future _migrateFrom02To10(InstantDB db) async {
print('Applying 0.2.0 → 1.0.0 migration');
// Major version might have significant changes
await _updateAuthSystem(db);
await _migratePresenceSystem(db);
}
Future _updateUserSchema(InstantDB db) async {
// Example: Add new required fields to existing users
final users = await db.queryOnce({'users': {}});
final userList = (users.data?['users'] as List? ?? [])
.cast>();
final operations = [];
for (final user in userList) {
if (!user.containsKey('profileVersion')) {
operations.add(
db.update(user['id'], {
'profileVersion': 2,
'preferences': {
'notifications': true,
'theme': 'auto',
},
}),
);
}
}
if (operations.isNotEmpty) {
await db.transact(operations);
print('Updated ${operations.length} user profiles');
}
}
Future _updateAuthSystem(InstantDB db) async {
// Example: Migration for auth system changes
print('Updating auth system...');
// Handle auth token format changes, session migration, etc.
final currentUser = db.auth.currentUser.value;
if (currentUser != null) {
// Refresh user data with new format
await db.auth.refreshUser();
}
}
Future _migratePresenceSystem(InstantDB db) async {
// Example: Presence API changes
print('Migrating presence system...');
// Clean up old presence data that might be incompatible
// This is conceptual - actual implementation depends on changes
}
Future _setMigrationVersion(String version) async {
// Store migration version in local storage
final prefs = await SharedPreferences.getInstance();
await prefs.setString('instantdb_migration_version', version);
}
}
```
### Automated Migration Runner
Create an automated migration system:
```dart
class AutoMigrationRunner {
static const String _versionKey = 'instantdb_migration_version';
static const String _currentVersion = '1.0.0'; // Your current package version
static Future runMigrationsIfNeeded(InstantDB db) async {
final prefs = await SharedPreferences.getInstance();
final storedVersion = prefs.getString(_versionKey);
if (storedVersion == null) {
// First install - no migration needed
await prefs.setString(_versionKey, _currentVersion);
return;
}
if (storedVersion != _currentVersion) {
print('Migration needed: $storedVersion → $_currentVersion');
await _runMigrations(db, storedVersion, _currentVersion);
}
}
static Future _runMigrations(
InstantDB db,
String fromVersion,
String toVersion,
) async {
try {
final migrationManager = MigrationManager(
fromVersion: fromVersion,
toVersion: toVersion,
);
await migrationManager.migrate(db);
// Update stored version
final prefs = await SharedPreferences.getInstance();
await prefs.setString(_versionKey, toVersion);
print('Migration completed successfully');
} catch (e) {
print('Migration failed: $e');
// Handle migration failure - might need manual intervention
rethrow;
}
}
}
// Usage in your app initialization
Future initializeApp() async {
final db = await InstantDB.init(
appId: 'your-app-id',
config: const InstantConfig(syncEnabled: true),
);
// Run migrations before using the database
await AutoMigrationRunner.runMigrationsIfNeeded(db);
runApp(MyApp(db: db));
}
```
## Schema Migrations
### Adding New Fields
Safely add new fields to existing entities:
```dart
class SchemaMigration {
final InstantDB db;
SchemaMigration(this.db);
Future addFieldToEntity({
required String entityType,
required String fieldName,
required dynamic defaultValue,
}) async {
print('Adding field $fieldName to $entityType entities');
// Query entities that don't have the new field
final result = await db.queryOnce({entityType: {}});
final entities = (result.data?[entityType] as List? ?? [])
.cast>();
final operations = [];
for (final entity in entities) {
if (!entity.containsKey(fieldName)) {
operations.add(
db.update(entity['id'], {fieldName: defaultValue}),
);
}
}
if (operations.isNotEmpty) {
// Process in batches to avoid overwhelming the system
await _processBatches(operations, batchSize: 50);
print('Added $fieldName to ${operations.length} entities');
} else {
print('All $entityType entities already have $fieldName field');
}
}
Future _processBatches(
List operations, {
int batchSize = 50,
}) async {
for (int i = 0; i < operations.length; i += batchSize) {
final batch = operations.skip(i).take(batchSize).toList();
await db.transact(batch);
// Small delay between batches to avoid overwhelming the system
await Future.delayed(const Duration(milliseconds: 100));
print('Processed batch ${(i / batchSize).ceil() + 1}/${(operations.length / batchSize).ceil()}');
}
}
Future removeFieldFromEntity({
required String entityType,
required String fieldName,
}) async {
print('Removing field $fieldName from $entityType entities');
final result = await db.queryOnce({entityType: {}});
final entities = (result.data?[entityType] as List? ?? [])
.cast>();
final operations = [];
for (final entity in entities) {
if (entity.containsKey(fieldName)) {
final updatedEntity = Map.from(entity);
updatedEntity.remove(fieldName);
operations.add(
db.update(entity['id'], updatedEntity),
);
}
}
if (operations.isNotEmpty) {
await _processBatches(operations);
print('Removed $fieldName from ${operations.length} entities');
}
}
Future renameField({
required String entityType,
required String oldFieldName,
required String newFieldName,
}) async {
print('Renaming field $oldFieldName to $newFieldName in $entityType');
final result = await db.queryOnce({entityType: {}});
final entities = (result.data?[entityType] as List? ?? [])
.cast>();
final operations = [];
for (final entity in entities) {
if (entity.containsKey(oldFieldName) && !entity.containsKey(newFieldName)) {
final value = entity[oldFieldName];
operations.add(
db.update(entity['id'], {
newFieldName: value,
// Remove old field by setting it to null or omitting it
}),
);
}
}
if (operations.isNotEmpty) {
await _processBatches(operations);
print('Renamed field in ${operations.length} entities');
}
}
Future transformFieldValues({
required String entityType,
required String fieldName,
required dynamic Function(dynamic oldValue) transformer,
}) async {
print('Transforming $fieldName values in $entityType');
final result = await db.queryOnce({entityType: {}});
final entities = (result.data?[entityType] as List? ?? [])
.cast>();
final operations = [];
for (final entity in entities) {
if (entity.containsKey(fieldName)) {
final oldValue = entity[fieldName];
final newValue = transformer(oldValue);
if (oldValue != newValue) {
operations.add(
db.update(entity['id'], {fieldName: newValue}),
);
}
}
}
if (operations.isNotEmpty) {
await _processBatches(operations);
print('Transformed $fieldName in ${operations.length} entities');
}
}
}
// Usage examples
Future runSchemaMigrations(InstantDB db) async {
final migration = SchemaMigration(db);
// Add new field with default value
await migration.addFieldToEntity(
entityType: 'users',
fieldName: 'lastLoginAt',
defaultValue: 0,
);
// Transform existing data
await migration.transformFieldValues(
entityType: 'posts',
fieldName: 'createdAt',
transformer: (oldValue) {
// Convert string dates to timestamps
if (oldValue is String) {
return DateTime.parse(oldValue).millisecondsSinceEpoch;
}
return oldValue;
},
);
// Rename field
await migration.renameField(
entityType: 'todos',
oldFieldName: 'done',
newFieldName: 'completed',
);
}
```
## Data Migrations
### Complex Data Transformations
Handle complex data structure changes:
```dart
class DataMigrationRunner {
final InstantDB db;
DataMigrationRunner(this.db);
Future migrateUserProfiles() async {
// Example: Migrate from flat user structure to nested profile
print('Migrating user profiles to new structure');
final users = await db.queryOnce({'users': {}});
final userList = (users.data?['users'] as List? ?? [])
.cast>();
final operations = [];
for (final user in userList) {
// Check if migration is needed
if (user.containsKey('firstName') && !user.containsKey('profile')) {
final newProfile = {
'personal': {
'firstName': user['firstName'],
'lastName': user['lastName'],
'dateOfBirth': user['dateOfBirth'],
},
'contact': {
'email': user['email'],
'phone': user['phone'],
},
'preferences': {
'notifications': user['notifications'] ?? true,
'theme': user['theme'] ?? 'auto',
'language': user['language'] ?? 'en',
},
};
// Create new structure and remove old fields
final updatedUser = {
'profile': newProfile,
'updatedAt': DateTime.now().millisecondsSinceEpoch,
};
operations.add(db.update(user['id'], updatedUser));
}
}
if (operations.isNotEmpty) {
await _processBatchOperations(operations);
print('Migrated ${operations.length} user profiles');
}
}
Future migratePostsWithTags() async {
// Example: Migrate from tag strings to tag objects
print('Migrating posts with tags');
final posts = await db.queryOnce({'posts': {}});
final postList = (posts.data?['posts'] as List? ?? [])
.cast>();
final operations = [];
final tagMap = {}; // tagName -> tagId
for (final post in postList) {
final tags = post['tags'] as List?;
if (tags != null && tags.isNotEmpty && tags.first is String) {
// Convert string tags to tag objects
final newTags = >[];
for (final tagName in tags.cast()) {
// Get or create tag ID
if (!tagMap.containsKey(tagName)) {
tagMap[tagName] = db.id();
// Create tag entity
operations.add(
...db.create('tags', {
'id': tagMap[tagName]!,
'name': tagName,
'createdAt': DateTime.now().millisecondsSinceEpoch,
}),
);
}
newTags.add({
'id': tagMap[tagName]!,
'name': tagName,
});
}
// Update post with new tag structure
operations.add(
db.update(post['id'], {
'tags': newTags,
'updatedAt': DateTime.now().millisecondsSinceEpoch,
}),
);
}
}
if (operations.isNotEmpty) {
await _processBatchOperations(operations);
print('Migrated ${postList.length} posts and created ${tagMap.length} tags');
}
}
Future _processBatchOperations(
List operations, {
int batchSize = 25,
}) async {
for (int i = 0; i < operations.length; i += batchSize) {
final batch = operations.skip(i).take(batchSize).toList();
try {
await db.transact(batch);
print('Processed batch ${(i / batchSize).floor() + 1}');
} catch (e) {
print('Batch failed: $e');
// Decide whether to continue or abort
rethrow;
}
// Small delay to avoid overwhelming the system
await Future.delayed(const Duration(milliseconds: 200));
}
}
}
```
## Rollback Strategies
### Safe Migration with Rollback
Implement rollback capabilities for failed migrations:
```dart
class SafeMigrationRunner {
final InstantDB db;
final List _steps = [];
SafeMigrationRunner(this.db);
void addStep(MigrationStep step) {
_steps.add(step);
}
Future runWithRollback() async {
final completedSteps = [];
try {
for (final step in _steps) {
print('Running migration step: ${step.name}');
await step.execute(db);
completedSteps.add(step);
print('Completed: ${step.name}');
}
} catch (e) {
print('Migration failed at step: ${completedSteps.length + 1}');
print('Rolling back...');
// Rollback completed steps in reverse order
for (final step in completedSteps.reversed) {
try {
print('Rolling back: ${step.name}');
await step.rollback(db);
} catch (rollbackError) {
print('Rollback failed for ${step.name}: $rollbackError');
// Continue with other rollbacks
}
}
rethrow;
}
}
}
abstract class MigrationStep {
String get name;
Future execute(InstantDB db);
Future rollback(InstantDB db);
}
class AddFieldMigrationStep implements MigrationStep {
final String entityType;
final String fieldName;
final dynamic defaultValue;
AddFieldMigrationStep({
required this.entityType,
required this.fieldName,
required this.defaultValue,
});
@override
String get name => 'Add $fieldName to $entityType';
@override
Future execute(InstantDB db) async {
final migration = SchemaMigration(db);
await migration.addFieldToEntity(
entityType: entityType,
fieldName: fieldName,
defaultValue: defaultValue,
);
}
@override
Future rollback(InstantDB db) async {
final migration = SchemaMigration(db);
await migration.removeFieldFromEntity(
entityType: entityType,
fieldName: fieldName,
);
}
}
// Usage
Future runSafeMigration(InstantDB db) async {
final runner = SafeMigrationRunner(db);
runner.addStep(AddFieldMigrationStep(
entityType: 'users',
fieldName: 'profileVersion',
defaultValue: 2,
));
runner.addStep(CustomMigrationStep(
name: 'Update user preferences',
executeAction: (db) => _updateUserPreferences(db),
rollbackAction: (db) => _revertUserPreferences(db),
));
await runner.runWithRollback();
}
```
## Testing Migrations
### Migration Testing Framework
Create comprehensive tests for your migrations:
```dart
class MigrationTestSuite {
late InstantDB testDb;
Future setUp() async {
// Create test database instance
testDb = await InstantDB.init(
appId: 'test-app-id',
config: const InstantConfig(syncEnabled: false), // Offline for testing
);
}
Future tearDown() async {
// Clean up test data
await testDb.dispose();
}
Future testUserProfileMigration() async {
// 1. Create test data in old format
await _createOldFormatUsers();
// 2. Run migration
final migration = DataMigrationRunner(testDb);
await migration.migrateUserProfiles();
// 3. Verify migration results
await _verifyUserProfileMigration();
}
Future _createOldFormatUsers() async {
final operations = [
...testDb.create('users', {
'id': testDb.id(),
'firstName': 'John',
'lastName': 'Doe',
'email': 'john@example.com',
'phone': '+1234567890',
'notifications': true,
'theme': 'dark',
}),
...testDb.create('users', {
'id': testDb.id(),
'firstName': 'Jane',
'lastName': 'Smith',
'email': 'jane@example.com',
'phone': '+0987654321',
'notifications': false,
'theme': 'light',
}),
];
await testDb.transact(operations);
}
Future _verifyUserProfileMigration() async {
final result = await testDb.queryOnce({'users': {}});
final users = (result.data?['users'] as List? ?? [])
.cast>();
for (final user in users) {
// Verify new structure exists
expect(user['profile'], isNotNull);
expect(user['profile']['personal'], isNotNull);
expect(user['profile']['contact'], isNotNull);
expect(user['profile']['preferences'], isNotNull);
// Verify data was migrated correctly
final profile = user['profile'] as Map;
expect(profile['personal']['firstName'], isNotEmpty);
expect(profile['contact']['email'], contains('@'));
// Verify old fields are removed
expect(user.containsKey('firstName'), isFalse);
expect(user.containsKey('lastName'), isFalse);
}
}
Future testMigrationRollback() async {
// Test that rollback works correctly
await _createOldFormatUsers();
final runner = SafeMigrationRunner(testDb);
runner.addStep(AddFieldMigrationStep(
entityType: 'users',
fieldName: 'testField',
defaultValue: 'test',
));
// Force a failure in the second step to test rollback
runner.addStep(FailingMigrationStep());
try {
await runner.runWithRollback();
fail('Migration should have failed');
} catch (e) {
// Verify rollback occurred
final result = await testDb.queryOnce({'users': {}});
final users = (result.data?['users'] as List? ?? [])
.cast>();
for (final user in users) {
expect(user.containsKey('testField'), isFalse);
}
}
}
}
class FailingMigrationStep implements MigrationStep {
@override
String get name => 'Failing step';
@override
Future execute(InstantDB db) async {
throw Exception('Intentional failure for testing');
}
@override
Future rollback(InstantDB db) async {
// Nothing to rollback
}
}
```
## Best Practices
### 1. Version Your Migrations
```dart
class VersionedMigration {
final String version;
final String description;
final Future Function(InstantDB) migration;
VersionedMigration({
required this.version,
required this.description,
required this.migration,
});
}
final migrations = [
VersionedMigration(
version: '1.1.0',
description: 'Add user preferences',
migration: (db) => _addUserPreferences(db),
),
VersionedMigration(
version: '1.2.0',
description: 'Migrate posts to new format',
migration: (db) => _migratePostFormat(db),
),
];
```
### 2. Make Migrations Idempotent
```dart
Future idempotentMigration(InstantDB db) async {
// Check if migration already applied
final users = await db.queryOnce({'users': {'limit': 1}});
final userList = (users.data?['users'] as List? ?? []);
if (userList.isNotEmpty) {
final firstUser = userList.first as Map;
if (firstUser.containsKey('profileVersion')) {
print('Migration already applied');
return;
}
}
// Run migration
await _actualMigration(db);
}
```
### 3. Monitor Migration Performance
```dart
Future monitoredMigration(InstantDB db) async {
final stopwatch = Stopwatch()..start();
try {
await _runMigration(db);
print('Migration completed in ${stopwatch.elapsedMilliseconds}ms');
} catch (e) {
print('Migration failed after ${stopwatch.elapsedMilliseconds}ms: $e');
rethrow;
}
}
```
### 4. Document Migration Impact
```dart
/// Migration: Add user preferences
/// Impact: All existing users will get default preferences
/// Rollback: Remove preferences field from all users
/// Estimated time: ~30 seconds for 10k users
/// Dependencies: None
Future documentedMigration(InstantDB db) async {
// Implementation
}
```
## Next Steps
Learn more about maintaining robust InstantDB applications:
- [Troubleshooting](/docs/advanced/troubleshooting) - Debug migration issues
- [Performance Optimization](/docs/advanced/performance) - Optimize migration performance
- [Offline Functionality](/docs/advanced/offline) - Handle migrations while offline
- [API Reference](/docs/api) - Complete API documentation for migrations
---
# Offline Functionality
> Building offline-first applications with Flutter InstantDB
Source: https://flutter-instantdb.vercel.app/docs/advanced/offline
Flutter InstantDB is designed with offline-first principles. Your app continues to work seamlessly when the network is unavailable, with automatic synchronization when connectivity is restored.
## Offline-First Architecture
### How It Works
InstantDB's offline-first approach ensures your app remains functional regardless of network conditions:
1. **Local SQLite Storage**: All data is stored locally in SQLite
2. **Optimistic Updates**: Changes are applied immediately to the local database
3. **Sync Queue**: Mutations are queued for transmission when online
4. **Automatic Sync**: Changes sync automatically when connection is restored
5. **Conflict Resolution**: Server conflicts are resolved automatically
### Benefits
- ✅ **Instant Responsiveness**: UI updates immediately, no waiting for server
- ✅ **Reliable Offline Work**: Full functionality when disconnected
- ✅ **Automatic Recovery**: Seamless sync when connection returns
- ✅ **Conflict Resolution**: Handles concurrent edits gracefully
- ✅ **Data Persistence**: Local data survives app restarts
## Handling Offline States
### Connection Status Monitoring
Monitor and display connection status to users:
```dart
class ConnectionAwareApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
final db = InstantProvider.of(context);
return Watch((context) {
final isOnline = db.syncEngine?.connectionStatus.value ?? false;
return Scaffold(
body: Column(
children: [
// Connection status banner
if (!isOnline)
Container(
width: double.infinity,
padding: const EdgeInsets.symmetric(vertical: 8, horizontal: 16),
color: Colors.orange,
child: Row(
children: [
const Icon(Icons.cloud_off, color: Colors.white, size: 16),
const SizedBox(width: 8),
const Text(
'Offline - Changes will sync when connected',
style: TextStyle(color: Colors.white),
),
const Spacer(),
Text(
'Offline',
style: TextStyle(
color: Colors.white,
fontWeight: FontWeight.bold,
),
),
],
),
),
// Your app content
Expanded(child: YourAppContent()),
],
),
);
});
}
}
```
### Advanced Connection Status Widget
Create a more sophisticated connection indicator:
```dart
class AdvancedConnectionStatus extends StatelessWidget {
@override
Widget build(BuildContext context) {
final db = InstantProvider.of(context);
return Watch((context) {
final isOnline = db.syncEngine?.connectionStatus.value ?? false;
final pendingCount = _getPendingChangesCount(db);
return AnimatedContainer(
duration: const Duration(milliseconds: 300),
padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 6),
decoration: BoxDecoration(
color: _getStatusColor(isOnline, pendingCount),
borderRadius: BorderRadius.circular(16),
),
child: Row(
mainAxisSize: MainAxisSize.min,
children: [
Icon(
_getStatusIcon(isOnline, pendingCount),
size: 16,
color: Colors.white,
),
const SizedBox(width: 6),
Text(
_getStatusText(isOnline, pendingCount),
style: const TextStyle(
color: Colors.white,
fontSize: 12,
fontWeight: FontWeight.w500,
),
),
if (pendingCount > 0) ...[
const SizedBox(width: 4),
Container(
padding: const EdgeInsets.symmetric(horizontal: 6, vertical: 2),
decoration: BoxDecoration(
color: Colors.white.withOpacity(0.3),
borderRadius: BorderRadius.circular(8),
),
child: Text(
'$pendingCount',
style: const TextStyle(
color: Colors.white,
fontSize: 10,
fontWeight: FontWeight.bold,
),
),
),
],
],
),
);
});
}
Color _getStatusColor(bool isOnline, int pendingCount) {
if (!isOnline && pendingCount > 0) return Colors.orange;
if (!isOnline) return Colors.red;
if (pendingCount > 0) return Colors.blue;
return Colors.green;
}
IconData _getStatusIcon(bool isOnline, int pendingCount) {
if (!isOnline) return Icons.cloud_off;
if (pendingCount > 0) return Icons.sync;
return Icons.cloud_done;
}
String _getStatusText(bool isOnline, int pendingCount) {
if (!isOnline && pendingCount > 0) return 'Offline - $pendingCount pending';
if (!isOnline) return 'Offline';
if (pendingCount > 0) return 'Syncing';
return 'Online';
}
int _getPendingChangesCount(InstantDB db) {
// This would need to be implemented in the sync engine
// For now, return a placeholder
return 0;
}
}
```
## Offline Data Patterns
### Optimistic Updates
All mutations in InstantDB are optimistic by default:
```dart
class OptimisticTodoList extends StatelessWidget {
@override
Widget build(BuildContext context) {
final db = InstantProvider.of(context);
return InstantBuilder(
query: {'todos': {'orderBy': {'createdAt': 'desc'}}},
builder: (context, result) {
final todos = (result.data?['todos'] as List? ?? [])
.cast>();
return ListView.builder(
itemCount: todos.length,
itemBuilder: (context, index) {
final todo = todos[index];
return TodoItem(
todo: todo,
onToggle: () => _toggleTodo(db, todo),
onDelete: () => _deleteTodo(db, todo['id']),
);
},
);
},
);
}
Future _toggleTodo(InstantDB db, Map todo) async {
// This update happens immediately in the UI
// Sync happens automatically in the background
await db.transact([
db.update(todo['id'], {
'completed': !todo['completed'],
'updatedAt': DateTime.now().millisecondsSinceEpoch,
}),
]);
}
Future _deleteTodo(InstantDB db, String todoId) async {
// Deletion also happens immediately
await db.transact([
db.delete(todoId),
]);
}
}
```
### Offline-Aware CRUD Operations
Create operations that provide feedback for offline states:
```dart
class OfflineAwareCRUD {
final InstantDB db;
OfflineAwareCRUD(this.db);
Future createTodo({
required String text,
bool showOfflineMessage = true,
}) async {
try {
final todoId = db.id();
await db.transact([
...db.create('todos', {
'id': todoId,
'text': text,
'completed': false,
'createdAt': DateTime.now().millisecondsSinceEpoch,
}),
]);
final isOnline = db.syncEngine?.connectionStatus.value ?? false;
return OperationResult.success(
message: isOnline
? 'Todo created and synced'
: 'Todo created - will sync when online',
data: {'id': todoId},
);
} catch (e) {
return OperationResult.error('Failed to create todo: $e');
}
}
Future updateTodo({
required String id,
required Map updates,
}) async {
try {
await db.transact([
db.update(id, {
...updates,
'updatedAt': DateTime.now().millisecondsSinceEpoch,
}),
]);
final isOnline = db.syncEngine?.connectionStatus.value ?? false;
return OperationResult.success(
message: isOnline
? 'Todo updated and synced'
: 'Todo updated - will sync when online',
);
} catch (e) {
return OperationResult.error('Failed to update todo: $e');
}
}
Future deleteTodo(String id) async {
try {
await db.transact([db.delete(id)]);
final isOnline = db.syncEngine?.connectionStatus.value ?? false;
return OperationResult.success(
message: isOnline
? 'Todo deleted and synced'
: 'Todo deleted - will sync when online',
);
} catch (e) {
return OperationResult.error('Failed to delete todo: $e');
}
}
}
class OperationResult {
final bool success;
final String message;
final Map? data;
OperationResult._({
required this.success,
required this.message,
this.data,
});
factory OperationResult.success(String message, {Map? data}) {
return OperationResult._(success: true, message: message, data: data);
}
factory OperationResult.error(String message) {
return OperationResult._(success: false, message: message);
}
}
```
## Conflict Resolution
### Understanding Conflicts
Conflicts occur when the same data is modified by multiple clients while offline:
```dart
class ConflictResolutionExample extends StatefulWidget {
@override
State createState() => _ConflictResolutionExampleState();
}
class _ConflictResolutionExampleState extends State {
String? _conflictMessage;
@override
void initState() {
super.initState();
_monitorConflicts();
}
void _monitorConflicts() {
final db = InstantProvider.of(context);
// Listen for sync events (this is conceptual - actual API may vary)
db.syncEngine?.onSyncEvent.listen((event) {
if (event.type == 'conflict_resolved') {
setState(() {
_conflictMessage = 'Conflict resolved: ${event.description}';
});
// Clear message after 5 seconds
Timer(const Duration(seconds: 5), () {
if (mounted) {
setState(() {
_conflictMessage = null;
});
}
});
}
});
}
@override
Widget build(BuildContext context) {
return Column(
children: [
if (_conflictMessage != null)
Container(
width: double.infinity,
padding: const EdgeInsets.all(12),
decoration: BoxDecoration(
color: Colors.blue.shade100,
borderRadius: BorderRadius.circular(8),
),
child: Row(
children: [
Icon(Icons.info, color: Colors.blue.shade700),
const SizedBox(width: 8),
Expanded(
child: Text(
_conflictMessage!,
style: TextStyle(color: Colors.blue.shade700),
),
),
],
),
),
// Your main content
Expanded(child: YourContent()),
],
);
}
}
```
### Custom Conflict Resolution
Implement custom logic for handling specific conflict scenarios:
```dart
class CustomConflictResolver {
static Map resolveDocumentConflict({
required Map localVersion,
required Map serverVersion,
required String userId,
}) {
// Last-write-wins with user preference
final localTimestamp = localVersion['updatedAt'] as int? ?? 0;
final serverTimestamp = serverVersion['updatedAt'] as int? ?? 0;
// If local is newer, keep local
if (localTimestamp > serverTimestamp) {
return localVersion;
}
// If server is newer, merge intelligently
final resolved = Map.from(serverVersion);
// Keep local changes for specific fields if user is the author
if (localVersion['authorId'] == userId) {
final preserveFields = ['title', 'content', 'tags'];
for (final field in preserveFields) {
if (localVersion.containsKey(field)) {
resolved[field] = localVersion[field];
}
}
}
// Add conflict resolution metadata
resolved['_conflictResolved'] = true;
resolved['_conflictResolvedAt'] = DateTime.now().millisecondsSinceEpoch;
resolved['_conflictResolvedBy'] = 'user_preference';
return resolved;
}
static List mergeArrayConflict({
required List localArray,
required List serverArray,
}) {
// Merge arrays preserving unique items
final merged = [];
final seen = {};
// Add all server items first
for (final item in serverArray) {
if (!seen.contains(item)) {
merged.add(item);
seen.add(item);
}
}
// Add local items that aren't in server
for (final item in localArray) {
if (!seen.contains(item)) {
merged.add(item);
seen.add(item);
}
}
return merged;
}
}
```
## Offline Authentication
### Cached Authentication
Handle authentication when offline:
```dart
class OfflineAuthManager {
final InstantDB db;
OfflineAuthManager(this.db);
Future getCachedUser() async {
try {
// Try to get current user (may use cached data)
final user = db.auth.currentUser.value;
if (user != null) return user;
// If no current user, try to restore from secure storage
final token = await SecureStorage.getAuthToken();
if (token != null) {
try {
return await db.auth.signInWithToken(token);
} catch (e) {
// Token might be expired, handle gracefully
print('Failed to restore auth with cached token: $e');
}
}
return null;
} catch (e) {
print('Error getting cached user: $e');
return null;
}
}
bool canPerformOfflineAuth() {
// Check if user has valid cached credentials
return db.auth.isAuthenticated;
}
Future scheduleAuthRefresh() async {
// Schedule auth refresh for when connection is restored
final isOnline = db.syncEngine?.connectionStatus.value ?? false;
if (!isOnline) {
// Listen for connection restoration
db.syncEngine?.connectionStatus.stream.listen((connected) {
if (connected) {
_refreshAuthWhenOnline();
}
});
} else {
await _refreshAuthWhenOnline();
}
}
Future _refreshAuthWhenOnline() async {
try {
await db.auth.refreshUser();
} catch (e) {
print('Auth refresh failed: $e');
// Handle auth refresh failure (e.g., redirect to login)
}
}
}
class SecureStorage {
static Future getAuthToken() async {
// Implementation depends on your secure storage solution
// e.g., flutter_secure_storage
return null;
}
}
```
## Offline UI Patterns
### Offline-First Form Handling
Create forms that work seamlessly offline:
```dart
class OfflineForm extends StatefulWidget {
final Map? initialData;
final String entityType;
const OfflineForm({
super.key,
this.initialData,
required this.entityType,
});
@override
State createState() => _OfflineFormState();
}
class _OfflineFormState extends State {
final _formKey = GlobalKey();
late final Map _formData;
bool _isSaving = false;
String? _saveMessage;
@override
void initState() {
super.initState();
_formData = Map.from(widget.initialData ?? {});
}
@override
Widget build(BuildContext context) {
final db = InstantProvider.of(context);
return Watch((context) {
final isOnline = db.syncEngine?.connectionStatus.value ?? false;
return Form(
key: _formKey,
child: Column(
children: [
// Offline indicator in form
if (!isOnline)
Container(
width: double.infinity,
padding: const EdgeInsets.all(12),
decoration: BoxDecoration(
color: Colors.amber.shade100,
borderRadius: BorderRadius.circular(8),
border: Border.all(color: Colors.amber.shade300),
),
child: Row(
children: [
Icon(Icons.info, color: Colors.amber.shade700, size: 20),
const SizedBox(width: 8),
Expanded(
child: Text(
'You\'re offline. Changes will be saved locally and synced when connected.',
style: TextStyle(color: Colors.amber.shade700),
),
),
],
),
),
const SizedBox(height: 16),
// Form fields
...buildFormFields(),
const SizedBox(height: 24),
// Save message
if (_saveMessage != null)
Container(
width: double.infinity,
padding: const EdgeInsets.all(12),
decoration: BoxDecoration(
color: Colors.green.shade100,
borderRadius: BorderRadius.circular(8),
),
child: Text(
_saveMessage!,
style: TextStyle(color: Colors.green.shade700),
),
),
const SizedBox(height: 16),
// Save button
SizedBox(
width: double.infinity,
child: ElevatedButton(
onPressed: _isSaving ? null : _saveForm,
child: Row(
mainAxisAlignment: MainAxisAlignment.center,
children: [
if (_isSaving) ...[
const SizedBox(
width: 16,
height: 16,
child: CircularProgressIndicator(strokeWidth: 2),
),
const SizedBox(width: 8),
],
Text(_isSaving ? 'Saving...' : 'Save'),
if (!isOnline && !_isSaving) ...[
const SizedBox(width: 8),
Icon(Icons.offline_pin, size: 16),
],
],
),
),
),
],
),
);
});
}
List buildFormFields() {
// Build your form fields based on entity type
return [
TextFormField(
initialValue: _formData['title']?.toString(),
decoration: const InputDecoration(labelText: 'Title'),
onSaved: (value) => _formData['title'] = value,
validator: (value) => value?.isEmpty ?? true ? 'Title is required' : null,
),
const SizedBox(height: 16),
TextFormField(
initialValue: _formData['description']?.toString(),
decoration: const InputDecoration(labelText: 'Description'),
maxLines: 3,
onSaved: (value) => _formData['description'] = value,
),
];
}
Future _saveForm() async {
if (!_formKey.currentState!.validate()) return;
_formKey.currentState!.save();
setState(() {
_isSaving = true;
_saveMessage = null;
});
try {
final db = InstantProvider.of(context);
final isOnline = db.syncEngine?.connectionStatus.value ?? false;
final isUpdate = _formData.containsKey('id');
if (isUpdate) {
await db.transact([
db.update(_formData['id'], {
..._formData,
'updatedAt': DateTime.now().millisecondsSinceEpoch,
}),
]);
} else {
await db.transact([
...db.create(widget.entityType, {
'id': db.id(),
..._formData,
'createdAt': DateTime.now().millisecondsSinceEpoch,
}),
]);
}
setState(() {
_saveMessage = isOnline
? '${isUpdate ? 'Updated' : 'Created'} successfully and synced'
: '${isUpdate ? 'Updated' : 'Created'} successfully - will sync when online';
});
// Clear message after 3 seconds
Timer(const Duration(seconds: 3), () {
if (mounted) {
setState(() {
_saveMessage = null;
});
}
});
} catch (e) {
setState(() {
_saveMessage = 'Error: $e';
});
} finally {
setState(() {
_isSaving = false;
});
}
}
}
```
## Best Practices
### 1. Embrace Optimistic Updates
Trust InstantDB's optimistic update system:
```dart
// Good: Let InstantDB handle optimistic updates
await db.transact([db.update(itemId, newData)]);
// Avoid: Manual optimistic updates
setState(() {
localData = newData; // Don't do this - let InstantDB handle it
});
await db.transact([db.update(itemId, newData)]);
```
### 2. Provide Clear Offline Feedback
Always inform users about offline status:
```dart
class OfflineFeedback extends StatelessWidget {
final Widget child;
const OfflineFeedback({super.key, required this.child});
@override
Widget build(BuildContext context) {
return Column(
children: [
ConnectionStatusBar(),
Expanded(child: child),
],
);
}
}
```
### 3. Handle Large Offline Datasets
Consider data size when working offline:
```dart
class OfflineDataManager {
static const int MAX_OFFLINE_ITEMS = 1000;
static Future preloadOfflineData(InstantDB db) async {
// Load essential data for offline use
final recentPosts = await db.queryOnce({
'posts': {
'where': {'createdAt': {'\$gte': _getLastWeekTimestamp()}},
'limit': MAX_OFFLINE_ITEMS,
'orderBy': {'createdAt': 'desc'},
}
});
// Data is now cached locally
}
static int _getLastWeekTimestamp() {
return DateTime.now()
.subtract(const Duration(days: 7))
.millisecondsSinceEpoch;
}
}
```
### 4. Test Offline Scenarios
Thoroughly test offline functionality:
```dart
void testOfflineScenarios() {
group('Offline functionality', () {
late InstantDB db;
setUp(() async {
db = await InstantDB.init(
appId: 'test-app',
config: const InstantConfig(syncEnabled: true),
);
});
test('should create items when offline', () async {
// Simulate offline mode
await db.syncEngine?.disconnect();
// Create item
await db.transact([
...db.create('items', {
'id': db.id(),
'name': 'Offline Item',
}),
]);
// Verify item exists locally
final result = await db.queryOnce({'items': {}});
expect(result.data?['items'], hasLength(1));
});
test('should sync when coming back online', () async {
// Test sync recovery
await db.syncEngine?.connect();
// Wait for sync
await Future.delayed(const Duration(seconds: 1));
// Verify sync occurred
// Implementation depends on sync monitoring capabilities
});
});
}
```
## Next Steps
Learn more about advanced InstantDB features:
- [Performance Optimization](/docs/advanced/performance) - Optimizing offline performance
- [Troubleshooting](/docs/advanced/troubleshooting) - Debugging offline issues
- [Migration Strategies](/docs/advanced/migration) - Upgrading offline-enabled apps
- [Real-time Sync](/docs/realtime/sync) - Understanding sync mechanisms
---
# Performance Optimization
> Optimizing Flutter InstantDB applications for best performance
Source: https://flutter-instantdb.vercel.app/docs/advanced/performance
Optimize your Flutter InstantDB applications for maximum performance with efficient queries, smart caching strategies, and optimized UI patterns.
## Query Optimization
### Efficient Query Patterns
Write queries that minimize data transfer and processing:
```dart
// ✅ Good: Specific queries with filters
final recentPosts = db.subscribeQuery({
'posts': {
'where': {
'published': true,
'createdAt': {'\$gte': DateTime.now().subtract(Duration(days: 7)).millisecondsSinceEpoch}
},
'orderBy': {'createdAt': 'desc'},
'limit': 20,
}
});
// ❌ Avoid: Broad queries without filters
final allPosts = db.subscribeQuery({'posts': {}});
```
### Pagination for Large Datasets
Implement efficient pagination to handle large amounts of data:
```dart
class PaginatedList extends StatefulWidget {
final String entityType;
final Map? whereClause;
final int pageSize;
const PaginatedList({
super.key,
required this.entityType,
this.whereClause,
this.pageSize = 20,
});
@override
State createState() => _PaginatedListState();
}
class _PaginatedListState extends State {
int _currentPage = 0;
final List> _allItems = [];
bool _isLoading = false;
bool _hasMore = true;
@override
void initState() {
super.initState();
_loadPage(0);
}
Future _loadPage(int page) async {
if (_isLoading || !_hasMore) return;
setState(() {
_isLoading = true;
});
try {
final db = InstantProvider.of(context);
final result = await db.queryOnce({
widget.entityType: {
if (widget.whereClause != null) 'where': widget.whereClause,
'orderBy': {'createdAt': 'desc'},
'limit': widget.pageSize,
'offset': page * widget.pageSize,
}
});
final newItems = (result.data?[widget.entityType] as List? ?? [])
.cast>();
setState(() {
if (page == 0) {
_allItems.clear();
}
_allItems.addAll(newItems);
_hasMore = newItems.length == widget.pageSize;
_currentPage = page;
});
} finally {
setState(() {
_isLoading = false;
});
}
}
@override
Widget build(BuildContext context) {
return ListView.builder(
itemCount: _allItems.length + (_hasMore ? 1 : 0),
itemBuilder: (context, index) {
if (index == _allItems.length) {
// Load more indicator
if (!_isLoading && _hasMore) {
// Trigger load more
WidgetsBinding.instance.addPostFrameCallback((_) {
_loadPage(_currentPage + 1);
});
}
return const Center(
child: Padding(
padding: EdgeInsets.all(16),
child: CircularProgressIndicator(),
),
);
}
final item = _allItems[index];
return ListTile(
title: Text(item['title'] ?? ''),
subtitle: Text(item['description'] ?? ''),
);
},
);
}
}
```
### Query Result Caching
Implement smart caching for frequently accessed data:
```dart
class QueryCache {
static final Map _cache = {};
static const Duration _defaultTTL = Duration(minutes: 5);
static Signal? getCached(
String queryKey,
Map query,
) {
final cached = _cache[queryKey];
if (cached != null && !cached.isExpired) {
return cached.signal;
}
return null;
}
static void setCached(
String queryKey,
Signal signal, {
Duration? ttl,
}) {
_cache[queryKey] = CachedQuery(
signal: signal,
expiresAt: DateTime.now().add(ttl ?? _defaultTTL),
);
}
static void clearExpired() {
_cache.removeWhere((_, cached) => cached.isExpired);
}
static void clear() {
_cache.clear();
}
}
class CachedQuery {
final Signal signal;
final DateTime expiresAt;
CachedQuery({required this.signal, required this.expiresAt});
bool get isExpired => DateTime.now().isAfter(expiresAt);
}
// Cached query widget
class CachedInstantBuilder extends StatelessWidget {
final Map query;
final String? cacheKey;
final Duration? cacheTTL;
final Widget Function(BuildContext, Map?) builder;
const CachedInstantBuilder({
super.key,
required this.query,
this.cacheKey,
this.cacheTTL,
required this.builder,
});
@override
Widget build(BuildContext context) {
final db = InstantProvider.of(context);
final key = cacheKey ?? query.toString();
// Try to get from cache first
var querySignal = QueryCache.getCached(key, query);
if (querySignal == null) {
// Create new query and cache it
querySignal = db.subscribeQuery(query);
QueryCache.setCached(key, querySignal, ttl: cacheTTL);
}
return Watch((context) {
final result = querySignal!.value;
return builder(context, result.data);
});
}
}
```
## Memory Management
### Efficient Widget Patterns
Optimize widget rebuilds and memory usage:
```dart
// ✅ Good: Specific data extraction
class OptimizedPostList extends StatelessWidget {
@override
Widget build(BuildContext context) {
return InstantBuilderTyped>(
query: {
'posts': {
'where': {'published': true},
'limit': 50,
}
},
transformer: (data) => (data['posts'] as List)
.map((json) => Post.fromJson(json))
.toList(),
builder: (context, posts) {
return ListView.builder(
itemCount: posts.length,
itemBuilder: (context, index) => PostCard(post: posts[index]),
);
},
);
}
}
// ❌ Avoid: Processing data in build method
class UnoptimizedPostList extends StatelessWidget {
@override
Widget build(BuildContext context) {
return InstantBuilder(
query: {'posts': {}},
builder: (context, data) {
// Expensive operations in build method
final posts = (data['posts'] as List)
.where((p) => p['published'] == true)
.map((json) => Post.fromJson(json))
.toList()
..sort((a, b) => b.createdAt.compareTo(a.createdAt));
return ListView.builder(
itemCount: posts.length,
itemBuilder: (context, index) => PostCard(post: posts[index]),
);
},
);
}
}
```
### Memory-Efficient List Rendering
Use ListView.builder for large datasets:
```dart
class LargeDataList extends StatelessWidget {
@override
Widget build(BuildContext context) {
return InstantBuilder(
query: {
'items': {
'orderBy': {'createdAt': 'desc'},
'limit': 1000, // Large dataset
}
},
builder: (context, result) {
final items = (result.data?['items'] as List? ?? [])
.cast>();
return ListView.builder(
// Only builds visible items
itemCount: items.length,
itemBuilder: (context, index) {
final item = items[index];
return ListTile(
key: Key(item['id']), // Important for performance
title: Text(item['title']),
subtitle: Text(item['description']),
);
},
);
},
);
}
}
```
### Dispose Resources Properly
Always clean up resources to prevent memory leaks:
```dart
class ResourceAwareWidget extends StatefulWidget {
@override
State createState() => _ResourceAwareWidgetState();
}
class _ResourceAwareWidgetState extends State {
late final Signal _querySignal;
StreamSubscription? _subscription;
Timer? _refreshTimer;
@override
void initState() {
super.initState();
final db = InstantProvider.of(context);
_querySignal = db.subscribeQuery({'items': {}});
// Listen to query changes
_subscription = _querySignal.toStream().listen((result) {
// Handle query updates
});
// Periodic refresh
_refreshTimer = Timer.periodic(
const Duration(minutes: 5),
(_) => _refreshData(),
);
}
@override
void dispose() {
// Clean up all resources
_subscription?.cancel();
_refreshTimer?.cancel();
super.dispose();
}
void _refreshData() {
// Refresh implementation
}
@override
Widget build(BuildContext context) {
return Watch((context) {
final result = _querySignal.value;
return YourWidget(data: result.data);
});
}
}
```
## Sync Performance
### Batch Operations Efficiently
Group related operations for better sync performance:
```dart
class BatchOperationManager {
final InstantDB db;
final List _pendingOperations = [];
Timer? _batchTimer;
static const Duration _batchDelay = Duration(milliseconds: 500);
static const int _maxBatchSize = 50;
BatchOperationManager(this.db);
void addOperation(Operation operation) {
_pendingOperations.add(operation);
if (_pendingOperations.length >= _maxBatchSize) {
_flushBatch();
} else {
_scheduleBatch();
}
}
void _scheduleBatch() {
_batchTimer?.cancel();
_batchTimer = Timer(_batchDelay, _flushBatch);
}
Future _flushBatch() async {
if (_pendingOperations.isEmpty) return;
final batch = List.from(_pendingOperations);
_pendingOperations.clear();
_batchTimer?.cancel();
try {
await db.transact(batch);
} catch (e) {
// Handle batch error - could retry or log
print('Batch operation failed: $e');
}
}
void dispose() {
_batchTimer?.cancel();
if (_pendingOperations.isNotEmpty) {
_flushBatch();
}
}
}
// Usage
class BatchedCRUD {
final BatchOperationManager _batchManager;
BatchedCRUD(InstantDB db) : _batchManager = BatchOperationManager(db);
void createMultipleItems(List> items) {
for (final item in items) {
_batchManager.addOperation(
db.create('items', {
'id': db.id(),
...item,
}).first,
);
}
}
void updateMultipleItems(List>> updates) {
for (final update in updates) {
_batchManager.addOperation(
db.update(update.key, update.value),
);
}
}
}
```
### Connection Pool Management
Optimize WebSocket connections:
```dart
class ConnectionManager {
static const Duration _reconnectDelay = Duration(seconds: 2);
static const Duration _heartbeatInterval = Duration(seconds: 30);
static const int _maxReconnectAttempts = 5;
final InstantDB db;
int _reconnectAttempts = 0;
Timer? _heartbeatTimer;
ConnectionManager(this.db) {
_startHeartbeat();
_monitorConnection();
}
void _startHeartbeat() {
_heartbeatTimer?.cancel();
_heartbeatTimer = Timer.periodic(_heartbeatInterval, (_) {
_sendHeartbeat();
});
}
void _sendHeartbeat() {
// Implementation depends on sync engine capabilities
// This is conceptual
try {
db.syncEngine?.ping();
_reconnectAttempts = 0; // Reset on successful ping
} catch (e) {
print('Heartbeat failed: $e');
_handleConnectionLoss();
}
}
void _monitorConnection() {
db.syncEngine?.connectionStatus.stream.listen((isConnected) {
if (!isConnected) {
_handleConnectionLoss();
} else {
_handleConnectionRestored();
}
});
}
void _handleConnectionLoss() {
if (_reconnectAttempts < _maxReconnectAttempts) {
Timer(_reconnectDelay * (_reconnectAttempts + 1), () {
_attemptReconnect();
});
} else {
print('Max reconnect attempts reached');
}
}
void _handleConnectionRestored() {
_reconnectAttempts = 0;
_startHeartbeat();
}
void _attemptReconnect() {
_reconnectAttempts++;
try {
db.syncEngine?.connect();
} catch (e) {
print('Reconnect attempt $_reconnectAttempts failed: $e');
}
}
void dispose() {
_heartbeatTimer?.cancel();
}
}
```
## UI Performance
### Optimized Presence Updates
Throttle presence updates to avoid excessive network traffic:
```dart
class ThrottledPresenceManager {
final InstantRoom room;
Timer? _cursorTimer;
Timer? _typingTimer;
static const Duration _cursorThrottle = Duration(milliseconds: 100);
static const Duration _typingDebounce = Duration(milliseconds: 300);
ThrottledPresenceManager(this.room);
void updateCursor(double x, double y) {
_cursorTimer?.cancel();
_cursorTimer = Timer(_cursorThrottle, () {
room.updateCursor(x: x, y: y);
});
}
void setTyping(bool isTyping) {
_typingTimer?.cancel();
if (isTyping) {
room.setTyping(true);
_typingTimer = Timer(_typingDebounce, () {
room.setTyping(false);
});
} else {
room.setTyping(false);
}
}
void dispose() {
_cursorTimer?.cancel();
_typingTimer?.cancel();
}
}
```
### Efficient Cursor Rendering
Optimize cursor rendering for many users:
```dart
class OptimizedCursorLayer extends StatelessWidget {
final InstantRoom room;
final Widget child;
static const int _maxVisibleCursors = 10;
const OptimizedCursorLayer({
super.key,
required this.room,
required this.child,
});
@override
Widget build(BuildContext context) {
return Stack(
children: [
child,
Watch((context) {
final cursors = room.getCursors().value;
// Limit visible cursors for performance
final visibleCursors = _getLimitedCursors(cursors);
return RepaintBoundary(
child: Stack(
children: visibleCursors.map((entry) {
return Positioned(
left: entry.value.x,
top: entry.value.y,
child: CursorWidget(
key: Key(entry.key),
cursor: entry.value,
),
);
}).toList(),
),
);
}),
],
);
}
List> _getLimitedCursors(
Map allCursors,
) {
final entries = allCursors.entries.toList();
// Sort by last update time
entries.sort((a, b) {
final aTime = a.value.data['lastUpdate'] ?? 0;
final bTime = b.value.data['lastUpdate'] ?? 0;
return bTime.compareTo(aTime);
});
return entries.take(_maxVisibleCursors).toList();
}
}
class CursorWidget extends StatelessWidget {
final dynamic cursor;
const CursorWidget({super.key, required this.cursor});
@override
Widget build(BuildContext context) {
// Wrap in RepaintBoundary for better performance
return RepaintBoundary(
child: Container(
width: 20,
height: 20,
decoration: BoxDecoration(
color: cursor.data['color'] ?? Colors.blue,
shape: BoxShape.circle,
),
),
);
}
}
```
## Monitoring and Analytics
### Performance Monitoring
Track performance metrics:
```dart
class PerformanceMonitor {
static final Map _metrics = {};
static void startTimer(String operation) {
_metrics[operation] = PerformanceMetric(
operation: operation,
startTime: DateTime.now(),
);
}
static void endTimer(String operation) {
final metric = _metrics[operation];
if (metric != null) {
metric.endTime = DateTime.now();
_logMetric(metric);
}
}
static void _logMetric(PerformanceMetric metric) {
final duration = metric.duration;
print('Performance: ${metric.operation} took ${duration.inMilliseconds}ms');
// Send to analytics service
_sendToAnalytics(metric);
}
static void _sendToAnalytics(PerformanceMetric metric) {
// Implementation for your analytics service
// e.g., Firebase Performance, custom analytics
}
static Future measureAsync(
String operation,
Future Function() action,
) async {
startTimer(operation);
try {
return await action();
} finally {
endTimer(operation);
}
}
static T measure(
String operation,
T Function() action,
) {
startTimer(operation);
try {
return action();
} finally {
endTimer(operation);
}
}
}
class PerformanceMetric {
final String operation;
final DateTime startTime;
DateTime? endTime;
PerformanceMetric({
required this.operation,
required this.startTime,
});
Duration get duration => endTime!.difference(startTime);
}
// Usage
class PerformanceAwareService {
Future performExpensiveOperation() async {
await PerformanceMonitor.measureAsync('expensive_operation', () async {
// Your expensive operation here
await Future.delayed(const Duration(seconds: 2));
});
}
}
```
### Memory Usage Tracking
Monitor memory consumption:
```dart
class MemoryMonitor {
static void logMemoryUsage(String context) {
// Get current memory usage (implementation varies by platform)
final rss = _getCurrentMemoryUsage();
print('Memory usage at $context: ${rss}MB');
if (rss > _getMemoryThreshold()) {
print('WARNING: High memory usage detected');
_handleHighMemoryUsage();
}
}
static double _getCurrentMemoryUsage() {
// Implementation depends on platform
// This is a placeholder
return 0.0;
}
static double _getMemoryThreshold() {
// Define your memory threshold (e.g., 200MB)
return 200.0;
}
static void _handleHighMemoryUsage() {
// Clear caches, dispose unused resources, etc.
QueryCache.clear();
_forceGarbageCollection();
}
static void _forceGarbageCollection() {
// Force garbage collection if supported
// Implementation varies by platform
}
}
```
## Best Practices
### 1. Use Specific Queries
Always filter data at the query level:
```dart
// ✅ Good: Filter in query
final activeUsers = db.subscribeQuery({
'users': {
'where': {'status': 'active'},
'limit': 100,
}
});
// ❌ Avoid: Filter in UI
final allUsers = db.subscribeQuery({'users': {}});
// Then filtering in build method
```
### 2. Implement Proper Pagination
Don't load all data at once:
```dart
// ✅ Good: Paginated loading
void loadNextPage() {
final offset = currentPage * pageSize;
final query = {
'items': {
'limit': pageSize,
'offset': offset,
}
};
}
```
### 3. Batch Related Operations
Group operations for efficiency:
```dart
// ✅ Good: Batch operations
await db.transact([
...db.create('post', postData),
db.update(authorId, {'postCount': {'\$increment': 1}}),
...db.create('notification', notificationData),
]);
// ❌ Avoid: Separate transactions
await db.transact([...db.create('post', postData)]);
await db.transact([db.update(authorId, {'postCount': {'\$increment': 1}})]);
await db.transact([...db.create('notification', notificationData)]);
```
### 4. Use Keys for List Items
Always provide keys for dynamic lists:
```dart
ListView.builder(
itemCount: items.length,
itemBuilder: (context, index) {
final item = items[index];
return ListTile(
key: Key(item['id']), // Important for performance
title: Text(item['title']),
);
},
)
```
### 5. Profile and Measure
Regularly profile your app:
```dart
void main() {
// Enable performance overlay in debug mode
if (kDebugMode) {
debugProfileBuildsEnabled = true;
}
runApp(MyApp());
}
```
## Performance Checklist
Use this checklist to ensure optimal performance:
- [ ] Queries use specific filters and limits
- [ ] Large lists use ListView.builder with keys
- [ ] Resources are properly disposed
- [ ] Batch operations are used where possible
- [ ] Presence updates are throttled
- [ ] Memory usage is monitored
- [ ] Performance metrics are tracked
- [ ] Caching is implemented appropriately
- [ ] UI rebuilds are minimized
- [ ] Network requests are optimized
## Next Steps
Learn more about optimizing your Flutter InstantDB app:
- [Troubleshooting](/docs/advanced/troubleshooting) - Debugging performance issues
- [Migration Strategies](/docs/advanced/migration) - Upgrading performant apps
- [Offline Functionality](/docs/advanced/offline) - Optimizing offline performance
- [Real-time Sync](/docs/realtime/sync) - Sync performance optimization
---
# Schema CLI (TS ⇆ Dart)
> Convert instant.schema.ts to and from Dart @InstantModel classes
Source: https://flutter-instantdb.vercel.app/docs/advanced/schema-cli
The `schema` CLI (`bin/schema.dart`) converts between InstantDB's
`instant.schema.ts` and Dart `@InstantModel` classes — the input to the code
generator. It is pure Dart (no analyzer, no extra dependencies).
## Commands
```bash
# Cloud round-trips (wrap instant-cli)
dart run instantdb_flutter:schema pull # instant-cli pull → convert TS to Dart
dart run instantdb_flutter:schema push # convert Dart to TS → instant-cli push
# Offline conversion (no cloud / npx)
dart run instantdb_flutter:schema to-dart instant.schema.ts -s lib/schema/app_schema.dart
dart run instantdb_flutter:schema to-ts -s lib/schema/app_schema.dart
# Best-effort normalized diff of the Dart schema vs instant.schema.ts
dart run instantdb_flutter:schema diff -s lib/schema/app_schema.dart
```
After `pull`/`to-dart`, run `dart run build_runner build` to regenerate the
typed tables.
## Type mapping
| `instant.schema.ts` | Dart | Notes |
|---------------------|-------------------------|-------|
| `i.string()` | `String` | |
| `i.number()` | `num` | `int`/`double`/`num` all collapse to `i.number()` on export |
| `i.boolean()` | `bool` | |
| `i.json()` | `Map?` | always nullable + optional ctor param |
| `i.date()` | `DateTime?` | always nullable + optional ctor param |
- `.optional()` → nullable Dart type + optional constructor parameter.
- Every entity gets a required `final String id`.
- `$`-prefixed system entities (`$users`, `$files`) are not emitted as Dart
classes; they only resolve as link targets.
## Modifiers and constraints
`@InstantField` carries `unique` / `indexed` so constraints survive the round
trip:
```dart
@InstantModel('users')
class User {
final String id;
@InstantField('email', unique: true, indexed: true)
final String email;
const User({required this.id, required this.email});
}
```
emits `email: i.string().unique().indexed()`. The code generator ignores these
flags.
## Links
TS `links` (forward/reverse) map to paired `@InstantLink` fields:
- `has: 'one'` → `T?`
- `has: 'many'` → `List`
The side of a link that lands on a system entity is skipped. On export,
reciprocal links are deduped and a `has: 'many'` reverse is synthesized when only
one side is declared — so hand-tuned link names may change.
---
# Files & Storage
> Upload, download, and delete files with db.storage and the $files namespace
Source: https://flutter-instantdb.vercel.app/docs/advanced/storage
InstantDB includes a storage API for uploading and serving files, plus a queryable
`$files` namespace for file metadata.
## The storage client
`db.storage` is an `InstantStorage` instance exposing three methods.
### `uploadFile`
Upload bytes to a path. Returns the created `InstantFile` record.
```dart
import 'dart:typed_data';
final bytes = Uint8List.fromList(/* ... */);
final file = await db.storage.uploadFile(
'avatars/ada.png',
bytes,
contentType: 'image/png', // optional
contentDisposition: 'inline', // optional
);
print(file.path); // 'avatars/ada.png'
```
### `getDownloadUrl`
Get a signed download URL for the file at a path.
```dart
final url = await db.storage.getDownloadUrl('avatars/ada.png');
// Use `url` in an Image.network(...) or share it
```
### `delete`
Delete the file at a path.
```dart
await db.storage.delete('avatars/ada.png');
```
### `list`
List uploaded files by reading the `$files` namespace through the query
pipeline. Pass `where`, `order`, `limit`, and `offset` to filter and page.
Requires sync to be enabled so the `$files` namespace is populated.
```dart
Future> list({
Map? where,
Map? order,
int? limit,
int? offset,
});
```
```dart
final files = await db.storage.list(
order: {'serverCreatedAt': 'desc'},
limit: 50,
);
for (final f in files) {
print('${f.path} (${f.size} bytes)');
}
```
## The `InstantFile` model
`uploadFile` returns an `InstantFile` describing the stored file:
```dart
class InstantFile {
final String id;
final String path;
final String? url;
final int? size;
final String? contentType;
}
```
## Querying `$files`
The `$files` namespace is queryable like any other namespace:
```dart
final result = await db.queryOnce({r'$files': {}});
final files = result.data![r'$files'] as List;
```
A local file reference can be removed via a transaction on the `$files` namespace:
```dart
await db.transact(db.tx[r'$files'][fileId].delete());
```
---
# Troubleshooting
> Common issues and debugging techniques for Flutter InstantDB
Source: https://flutter-instantdb.vercel.app/docs/advanced/troubleshooting
Debug and resolve common issues with Flutter InstantDB applications using systematic troubleshooting techniques and diagnostic tools.
## Common Issues
### Connection and Sync Problems
#### 1. "Failed to connect to InstantDB server"
**Symptoms:** App shows offline status, sync doesn't work
**Causes & Solutions:**
```dart
// Check your app ID and configuration
final db = await InstantDB.init(
appId: 'your-correct-app-id', // Verify this is correct
config: const InstantConfig(
syncEnabled: true,
// Use custom endpoint if needed
baseUrl: 'https://api.instantdb.com', // Default
websocketUrl: 'wss://api.instantdb.com/ws', // Default
),
);
// Enable verbose logging to see connection details
final db = await InstantDB.init(
appId: 'your-app-id',
config: const InstantConfig(
syncEnabled: true,
verboseLogging: true, // Enable detailed logs
),
);
```
**Debugging steps:**
1. Check your internet connection
2. Verify app ID is correct
3. Check firewall/proxy settings
4. Enable verbose logging to see detailed error messages
#### 2. "Data not syncing between devices"
**Symptoms:** Changes on one device don't appear on others
**Common causes:**
```dart
// ❌ Problem: Different app IDs
Device1: InstantDB.init(appId: 'app-123')
Device2: InstantDB.init(appId: 'app-456') // Wrong!
// ✅ Solution: Same app ID everywhere
Device1: InstantDB.init(appId: 'your-app-id')
Device2: InstantDB.init(appId: 'your-app-id')
// ❌ Problem: Sync disabled
InstantDB.init(
appId: 'your-app-id',
config: const InstantConfig(
syncEnabled: false, // This disables sync!
),
)
// ✅ Solution: Enable sync
InstantDB.init(
appId: 'your-app-id',
config: const InstantConfig(
syncEnabled: true, // Enable sync
),
)
```
#### 3. "Sync is slow or inconsistent"
**Diagnostic widget:**
```dart
class SyncDiagnostics extends StatefulWidget {
@override
State createState() => _SyncDiagnosticsState();
}
class _SyncDiagnosticsState extends State {
final List _syncEvents = [];
StreamSubscription? _connectionSubscription;
@override
void initState() {
super.initState();
_monitorSync();
}
void _monitorSync() {
final db = InstantProvider.of(context);
// Monitor connection status changes
_connectionSubscription = db.syncEngine?.connectionStatus.stream.listen((isConnected) {
final event = '${DateTime.now()}: Connection ${isConnected ? 'restored' : 'lost'}';
setState(() {
_syncEvents.add(event);
if (_syncEvents.length > 50) {
_syncEvents.removeRange(0, _syncEvents.length - 50);
}
});
});
}
@override
Widget build(BuildContext context) {
final db = InstantProvider.of(context);
return Scaffold(
appBar: AppBar(title: const Text('Sync Diagnostics')),
body: Column(
children: [
// Current status
Watch((context) {
final isConnected = db.syncEngine?.connectionStatus.value ?? false;
return Container(
width: double.infinity,
padding: const EdgeInsets.all(16),
color: isConnected ? Colors.green : Colors.red,
child: Text(
'Status: ${isConnected ? 'Connected' : 'Disconnected'}',
style: const TextStyle(color: Colors.white, fontSize: 18),
),
);
}),
// Test sync button
Padding(
padding: const EdgeInsets.all(16),
child: ElevatedButton(
onPressed: _testSync,
child: const Text('Test Sync'),
),
),
// Event log
Expanded(
child: ListView.builder(
itemCount: _syncEvents.length,
itemBuilder: (context, index) {
return ListTile(
dense: true,
title: Text(
_syncEvents[index],
style: const TextStyle(fontSize: 12, fontFamily: 'monospace'),
),
);
},
),
),
],
),
);
}
Future _testSync() async {
final db = InstantProvider.of(context);
final testId = db.id();
setState(() {
_syncEvents.add('${DateTime.now()}: Testing sync with item $testId');
});
try {
await db.transact([
...db.create('sync_test', {
'id': testId,
'timestamp': DateTime.now().millisecondsSinceEpoch,
'test': true,
}),
]);
setState(() {
_syncEvents.add('${DateTime.now()}: Sync test transaction completed');
});
} catch (e) {
setState(() {
_syncEvents.add('${DateTime.now()}: Sync test failed: $e');
});
}
}
@override
void dispose() {
_connectionSubscription?.cancel();
super.dispose();
}
}
```
### Authentication Issues
#### 1. "Invalid email format" error
**Problem:** Email validation is too strict or has issues
```dart
// Debug email validation
void debugEmailValidation(String email) {
final isValid = RegExp(r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$').hasMatch(email);
print('Email: $email');
print('Valid: $isValid');
print('Length: ${email.length}');
if (!isValid) {
if (email.contains(' ')) print('Contains spaces');
if (!email.contains('@')) print('Missing @ symbol');
if (!email.contains('.')) print('Missing domain extension');
}
}
```
#### 2. Magic code/link not working
**Debugging authentication flow:**
```dart
class AuthDebugScreen extends StatefulWidget {
@override
State createState() => _AuthDebugScreenState();
}
class _AuthDebugScreenState extends State {
final _emailController = TextEditingController();
final _codeController = TextEditingController();
final List _debugLog = [];
void _log(String message) {
setState(() {
_debugLog.add('${DateTime.now()}: $message');
});
print(message);
}
Future _testMagicCode() async {
final email = _emailController.text.trim();
_log('Testing magic code for: $email');
try {
final db = InstantProvider.of(context);
// Step 1: Send magic code
_log('Sending magic code...');
await db.auth.sendMagicCode(email);
_log('Magic code sent successfully');
} catch (e) {
_log('Failed to send magic code: $e');
if (e is InstantException) {
_log('Error code: ${e.code}');
_log('Error message: ${e.message}');
// Specific debugging for common errors
if (e.code == 'invalid_email') {
_log('Email validation failed - check email format');
} else if (e.code == 'endpoint_not_found') {
_log('Auth endpoint not found - check app configuration');
}
}
}
}
Future _testVerifyCode() async {
final email = _emailController.text.trim();
final code = _codeController.text.trim();
_log('Verifying code: $code for email: $email');
try {
final db = InstantProvider.of(context);
final user = await db.auth.verifyMagicCode(
email: email,
code: code,
);
_log('Verification successful!');
_log('User ID: ${user.id}');
_log('User email: ${user.email}');
} catch (e) {
_log('Verification failed: $e');
if (e is InstantException) {
_log('Error code: ${e.code}');
if (e.code == 'invalid_code') {
_log('Code is invalid or expired');
}
}
}
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Auth Debug')),
body: Padding(
padding: const EdgeInsets.all(16),
child: Column(
children: [
TextField(
controller: _emailController,
decoration: const InputDecoration(labelText: 'Email'),
),
const SizedBox(height: 16),
ElevatedButton(
onPressed: _testMagicCode,
child: const Text('Test Send Magic Code'),
),
const SizedBox(height: 16),
TextField(
controller: _codeController,
decoration: const InputDecoration(labelText: 'Magic Code'),
),
const SizedBox(height: 16),
ElevatedButton(
onPressed: _testVerifyCode,
child: const Text('Test Verify Code'),
),
const SizedBox(height: 24),
// Debug log
Expanded(
child: Container(
width: double.infinity,
padding: const EdgeInsets.all(12),
decoration: BoxDecoration(
color: Colors.grey[100],
border: Border.all(color: Colors.grey),
borderRadius: BorderRadius.circular(8),
),
child: ListView.builder(
itemCount: _debugLog.length,
itemBuilder: (context, index) {
return Padding(
padding: const EdgeInsets.symmetric(vertical: 2),
child: Text(
_debugLog[index],
style: const TextStyle(fontSize: 12, fontFamily: 'monospace'),
),
);
},
),
),
),
],
),
),
);
}
}
```
### Query Issues
#### 1. "Query returns no results"
**Debug query structure:**
```dart
class QueryDebugger {
static void debugQuery(InstantDB db, Map query) {
print('=== Query Debug ===');
print('Query: ${jsonEncode(query)}');
// Test the query
db.queryOnce(query).then((result) {
print('Result: ${result.data}');
print('Error: ${result.error}');
if (result.data != null) {
result.data!.forEach((entityType, entities) {
final count = (entities as List).length;
print('$entityType: $count items');
});
}
}).catchError((error) {
print('Query failed: $error');
});
}
static void debugEntityStructure(InstantDB db, String entityType) {
print('=== Entity Structure Debug ===');
// Get a sample of entities to see structure
db.queryOnce({
entityType: {'limit': 5}
}).then((result) {
final entities = result.data?[entityType] as List? ?? [];
if (entities.isEmpty) {
print('No $entityType entities found');
return;
}
print('Sample $entityType entities:');
for (int i = 0; i < entities.length; i++) {
final entity = entities[i] as Map;
print('Entity $i: ${entity.keys.join(', ')}');
if (i == 0) {
// Show full structure of first entity
entity.forEach((key, value) {
print(' $key: ${value.runtimeType} = $value');
});
}
}
});
}
}
// Usage
void testQuery() {
final query = {
'todos': {
'where': {'completed': false},
'orderBy': {'createdAt': 'desc'},
}
};
QueryDebugger.debugQuery(db, query);
QueryDebugger.debugEntityStructure(db, 'todos');
}
```
#### 2. "Widget not updating when data changes"
**Debug reactive updates:**
```dart
class ReactivityDebugger extends StatefulWidget {
final Map query;
const ReactivityDebugger({super.key, required this.query});
@override
State createState() => _ReactivityDebuggerState();
}
class _ReactivityDebuggerState extends State {
final List _updateLog = [];
late Signal _querySignal;
@override
void initState() {
super.initState();
final db = InstantProvider.of(context);
_querySignal = db.subscribeQuery(widget.query);
// Monitor signal changes
_querySignal.toStream().listen((result) {
final timestamp = DateTime.now().toString();
setState(() {
_updateLog.add('$timestamp: Query updated');
if (_updateLog.length > 20) {
_updateLog.removeRange(0, _updateLog.length - 20);
}
});
});
}
@override
Widget build(BuildContext context) {
return Column(
children: [
// Current data
Watch((context) {
final result = _querySignal.value;
final hasData = result.data != null;
final hasError = result.error != null;
return Container(
padding: const EdgeInsets.all(12),
decoration: BoxDecoration(
color: hasError ? Colors.red[100] :
hasData ? Colors.green[100] : Colors.grey[100],
border: Border.all(color: Colors.grey),
borderRadius: BorderRadius.circular(8),
),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text('Status: ${hasError ? 'Error' : hasData ? 'Data' : 'Loading'}'),
if (hasError) Text('Error: ${result.error}'),
if (hasData)
Text('Data keys: ${result.data!.keys.join(', ')}'),
],
),
);
}),
const SizedBox(height: 16),
// Update log
Text('Update Log (${_updateLog.length}):'),
Expanded(
child: ListView.builder(
itemCount: _updateLog.length,
itemBuilder: (context, index) {
return Text(
_updateLog[index],
style: const TextStyle(fontSize: 12, fontFamily: 'monospace'),
);
},
),
),
],
);
}
}
```
## Diagnostic Tools
### Logging Configuration
Set up comprehensive logging:
```dart
import 'package:logging/logging.dart';
void setupLogging() {
// Set up hierarchical logging
Logger.root.level = Level.ALL;
Logger.root.onRecord.listen((record) {
final timestamp = record.time.toString().substring(11, 23);
final level = record.level.name.padRight(7);
final logger = record.loggerName.padRight(20);
print('$timestamp $level $logger ${record.message}');
if (record.error != null) {
print(' Error: ${record.error}');
}
if (record.stackTrace != null) {
print(' Stack: ${record.stackTrace}');
}
});
}
// Custom logger for InstantDB components
class InstantDBLogger {
static final _logger = Logger('InstantDB');
static void debug(String message) => _logger.fine(message);
static void info(String message) => _logger.info(message);
static void warning(String message) => _logger.warning(message);
static void error(String message, [Object? error, StackTrace? stackTrace]) {
_logger.severe(message, error, stackTrace);
}
}
```
### Database Inspector
Create a database inspection tool:
```dart
class DatabaseInspector extends StatefulWidget {
@override
State createState() => _DatabaseInspectorState();
}
class _DatabaseInspectorState extends State {
String? _selectedEntity;
Map? _entityData;
@override
Widget build(BuildContext context) {
final db = InstantProvider.of(context);
return Scaffold(
appBar: AppBar(
title: const Text('Database Inspector'),
actions: [
IconButton(
onPressed: _exportData,
icon: const Icon(Icons.download),
),
],
),
body: Row(
children: [
// Entity list
SizedBox(
width: 200,
child: _buildEntityList(db),
),
const VerticalDivider(),
// Entity data
Expanded(
child: _selectedEntity != null
? _buildEntityData(db, _selectedEntity!)
: const Center(child: Text('Select an entity')),
),
],
),
);
}
Widget _buildEntityList(InstantDB db) {
// List of known entity types - you might want to make this configurable
final entityTypes = ['users', 'posts', 'comments', 'todos', 'sync_test'];
return ListView.builder(
itemCount: entityTypes.length,
itemBuilder: (context, index) {
final entityType = entityTypes[index];
return ListTile(
title: Text(entityType),
selected: _selectedEntity == entityType,
onTap: () => _selectEntity(entityType),
);
},
);
}
Widget _buildEntityData(InstantDB db, String entityType) {
return InstantBuilder(
query: {entityType: {'limit': 100}},
builder: (context, result) {
if (result.error != null) {
return Center(child: Text('Error: ${result.error}'));
}
final entities = (result.data?[entityType] as List? ?? [])
.cast>();
return Column(
children: [
// Header
Container(
padding: const EdgeInsets.all(16),
child: Row(
children: [
Text(
'$entityType (${entities.length} items)',
style: Theme.of(context).textTheme.headlineSmall,
),
const Spacer(),
ElevatedButton(
onPressed: () => _addTestEntity(db, entityType),
child: const Text('Add Test Item'),
),
],
),
),
// Data table
Expanded(
child: SingleChildScrollView(
scrollDirection: Axis.horizontal,
child: SingleChildScrollView(
child: _buildDataTable(entities),
),
),
),
],
);
},
);
}
Widget _buildDataTable(List> entities) {
if (entities.isEmpty) {
return const Center(child: Text('No data'));
}
// Get all unique keys
final Set allKeys = {};
for (final entity in entities) {
allKeys.addAll(entity.keys);
}
final keys = allKeys.toList()..sort();
return DataTable(
columns: keys.map((key) => DataColumn(label: Text(key))).toList(),
rows: entities.map((entity) {
return DataRow(
cells: keys.map((key) {
final value = entity[key];
return DataCell(
Text(
value?.toString() ?? '',
maxLines: 1,
overflow: TextOverflow.ellipsis,
),
);
}).toList(),
);
}).toList(),
);
}
void _selectEntity(String entityType) {
setState(() {
_selectedEntity = entityType;
});
}
Future _addTestEntity(InstantDB db, String entityType) async {
final testData = {
'id': db.id(),
'test': true,
'createdAt': DateTime.now().millisecondsSinceEpoch,
'name': 'Test ${entityType.substring(0, entityType.length - 1)}',
};
try {
await db.transact([
...db.create(entityType, testData),
]);
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text('Test $entityType created')),
);
} catch (e) {
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text('Failed to create test $entityType: $e')),
);
}
}
void _exportData() {
// Export database data for debugging
print('Database export requested');
// Implementation depends on your export requirements
}
}
```
## Performance Issues
### Memory Leaks
Detect and fix memory leaks:
```dart
class MemoryLeakDetector {
static final Map _widgetCounts = {};
static void registerWidget(String widgetName) {
_widgetCounts[widgetName] = (_widgetCounts[widgetName] ?? 0) + 1;
}
static void unregisterWidget(String widgetName) {
_widgetCounts[widgetName] = (_widgetCounts[widgetName] ?? 1) - 1;
if (_widgetCounts[widgetName]! <= 0) {
_widgetCounts.remove(widgetName);
}
}
static void printReport() {
print('=== Widget Memory Report ===');
_widgetCounts.forEach((widget, count) {
if (count > 10) { // Threshold for potential leaks
print('WARNING: $widget has $count instances (potential leak)');
} else {
print('$widget: $count instances');
}
});
}
}
// Use in your widgets
class LeakAwareWidget extends StatefulWidget {
@override
State createState() => _LeakAwareWidgetState();
}
class _LeakAwareWidgetState extends State {
@override
void initState() {
super.initState();
MemoryLeakDetector.registerWidget('LeakAwareWidget');
}
@override
void dispose() {
MemoryLeakDetector.unregisterWidget('LeakAwareWidget');
super.dispose();
}
@override
Widget build(BuildContext context) {
return Container();
}
}
```
## Error Recovery
### Automatic Error Recovery
Implement robust error recovery:
```dart
class ErrorRecoveryService {
final InstantDB db;
int _retryCount = 0;
static const int _maxRetries = 3;
static const Duration _retryDelay = Duration(seconds: 2);
ErrorRecoveryService(this.db);
Future withRetry(
String operation,
Future Function() action,
) async {
_retryCount = 0;
while (_retryCount < _maxRetries) {
try {
final result = await action();
_retryCount = 0; // Reset on success
return result;
} catch (e) {
_retryCount++;
print('$operation failed (attempt $_retryCount/$_maxRetries): $e');
if (_retryCount >= _maxRetries) {
print('$operation failed permanently after $_maxRetries attempts');
rethrow;
}
// Wait before retry
await Future.delayed(_retryDelay * _retryCount);
// Try to recover based on error type
await _attemptRecovery(e);
}
}
throw Exception('Maximum retries exceeded for $operation');
}
Future _attemptRecovery(dynamic error) async {
if (error is InstantException) {
switch (error.code) {
case 'network_error':
// Try to reconnect
try {
await db.syncEngine?.connect();
} catch (_) {}
break;
case 'auth_error':
// Try to refresh auth
try {
await db.auth.refreshUser();
} catch (_) {}
break;
}
}
}
}
```
## Best Practices for Debugging
### 1. Enable Verbose Logging in Development
```dart
InstantDB.init(
appId: 'your-app-id',
config: InstantConfig(
syncEnabled: true,
verboseLogging: kDebugMode, // Only in debug mode
),
);
```
### 2. Use Structured Error Handling
```dart
Future handleOperation(Future Function() operation) async {
try {
await operation();
} on InstantException catch (e) {
// Handle InstantDB specific errors
print('InstantDB Error: ${e.code} - ${e.message}');
_showUserFriendlyError(e);
} catch (e, stackTrace) {
// Handle other errors
print('Unexpected error: $e');
print('Stack trace: $stackTrace');
_reportError(e, stackTrace);
}
}
```
### 3. Create Debug Screens
```dart
class DebugScreen extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Debug Tools')),
body: ListView(
children: [
ListTile(
title: const Text('Sync Diagnostics'),
onTap: () => Navigator.push(
context,
MaterialPageRoute(builder: (_) => SyncDiagnostics()),
),
),
ListTile(
title: const Text('Database Inspector'),
onTap: () => Navigator.push(
context,
MaterialPageRoute(builder: (_) => DatabaseInspector()),
),
),
ListTile(
title: const Text('Auth Debug'),
onTap: () => Navigator.push(
context,
MaterialPageRoute(builder: (_) => AuthDebugScreen()),
),
),
],
),
);
}
}
```
### 4. Monitor App State
```dart
class AppStateMonitor extends StatefulWidget {
final Widget child;
const AppStateMonitor({super.key, required this.child});
@override
State createState() => _AppStateMonitorState();
}
class _AppStateMonitorState extends State
with WidgetsBindingObserver {
@override
void initState() {
super.initState();
WidgetsBinding.instance.addObserver(this);
}
@override
void dispose() {
WidgetsBinding.instance.removeObserver(this);
super.dispose();
}
@override
void didChangeAppLifecycleState(AppLifecycleState state) {
print('App lifecycle state changed: $state');
final db = InstantProvider.of(context);
switch (state) {
case AppLifecycleState.paused:
// App is paused - might want to pause sync
break;
case AppLifecycleState.resumed:
// App is resumed - ensure connection is active
db.syncEngine?.connect();
break;
case AppLifecycleState.detached:
// App is being terminated
break;
default:
break;
}
}
@override
Widget build(BuildContext context) {
return widget.child;
}
}
```
## Getting Help
### 1. Collect Debug Information
Before asking for help, collect this information:
```dart
void collectDebugInfo() {
print('=== InstantDB Debug Info ===');
print('App ID: ${db.appId}');
print('Sync enabled: ${db.config.syncEnabled}');
print('Is authenticated: ${db.auth.isAuthenticated}');
print('Current user: ${db.auth.currentUser.value?.email}');
print('Connection status: ${db.syncEngine?.connectionStatus.value}');
print('Flutter version: ${Platform.version}');
print('Platform: ${Platform.operatingSystem}');
}
```
### 2. Reproduce Issues
Create minimal reproduction cases:
```dart
Future reproduceIssue() async {
// Minimal code that reproduces the problem
final db = await InstantDB.init(appId: 'your-app-id');
try {
// Steps to reproduce
await db.transact([...db.create('test', {'id': db.id()})]);
} catch (e) {
print('Issue reproduced: $e');
}
}
```
### 3. Report Bugs
Include this information when reporting bugs:
- Flutter InstantDB version
- Flutter/Dart version
- Platform (iOS/Android/Web)
- Complete error messages and stack traces
- Steps to reproduce
- Expected vs actual behavior
## Next Steps
Learn more about maintaining robust InstantDB applications:
- [Migration Strategies](/docs/advanced/migration) - Handling app updates and migrations
- [Performance Optimization](/docs/advanced/performance) - Preventing performance issues
- [Offline Functionality](/docs/advanced/offline) - Debugging offline scenarios
- [API Reference](/docs/api) - Complete API documentation
---
# InstantDB API
> Complete API reference for the core InstantDB class
Source: https://flutter-instantdb.vercel.app/docs/api/instantdb
The `InstantDB` class is the main entry point for interacting with your InstantDB database. It provides methods for initialization, queries, transactions, authentication, and real-time synchronization.
## Initialization
### `InstantDB.init()`
Initialize a new InstantDB instance.
```dart
static Future init({
required String appId,
InstantConfig config = const InstantConfig(),
})
```
**Parameters:**
- `appId` (`String`): Your InstantDB application ID
- `config` (`InstantConfig`, optional): Configuration options
**Returns:** `Future` - The initialized database instance
**Example:**
```dart
final db = await InstantDB.init(
appId: 'your-app-id',
config: const InstantConfig(
syncEnabled: true,
verboseLogging: false,
),
);
```
### `InstantConfig`
Configuration options for InstantDB initialization.
```dart
class InstantConfig {
const InstantConfig({
this.persistenceDir,
this.syncEnabled = true,
this.baseUrl = 'https://api.instantdb.com',
this.maxCacheSize = 50 * 1024 * 1024, // 50MB
this.reconnectDelay = const Duration(seconds: 1),
this.verboseLogging = false,
});
final String? persistenceDir;
final bool syncEnabled;
final String baseUrl;
final int maxCacheSize;
final Duration reconnectDelay;
final bool verboseLogging;
}
```
**Properties:**
- `persistenceDir` (`String?`): Custom directory for SQLite database storage
- `syncEnabled` (`bool`): Enable real-time synchronization (default: `true`)
- `baseUrl` (`String`): Custom API endpoint URL (default: `https://api.instantdb.com`)
- `maxCacheSize` (`int`): Maximum size of the local database cache in bytes (default: 50MB)
- `reconnectDelay` (`Duration`): Delay between reconnection attempts (default: 1 second)
- `verboseLogging` (`bool`): Enable detailed debug logging (default: `false`)
## Core Properties
### `isReady`
A reactive signal indicating if the database is initialized and ready for use.
```dart
ReadonlySignal get isReady
```
**Example:**
```dart
if (db.isReady.value) {
print('Database is ready');
}
```
### `isOnline`
A reactive signal indicating if the database is currently connected to the sync server.
```dart
ReadonlySignal get isOnline
```
**Example:**
```dart
Watch((context) {
final online = db.isOnline.value;
return Text(online ? 'Connected' : 'Disconnected');
});
```
### `appId`
Get the application ID for this database instance.
```dart
String get appId
```
**Returns:** `String` - The application ID
**Example:**
```dart
print('Database app ID: ${db.appId}');
```
### `auth`
Access the authentication manager.
```dart
AuthManager get auth
```
**Returns:** `AuthManager` - The authentication manager instance
**Example:**
```dart
final currentUser = db.auth.currentUser.value;
if (currentUser != null) {
print('User: ${currentUser.email}');
}
```
### `presence`
Access the presence manager for real-time collaboration.
```dart
PresenceManager get presence
```
**Returns:** `PresenceManager` - The presence manager instance
**Example:**
```dart
final room = db.presence.joinRoom('chat-room');
await room.setPresence({'status': 'online'});
```
### `syncEngine`
Access the internal synchronization engine. Note that most synchronization logic is handled automatically through `db.query` and `db.transact`.
```dart
SyncEngine get syncEngine
```
**Returns:** `SyncEngine` - The sync engine instance
## Query Methods
### `query()`
Create a reactive query that updates automatically when data changes. This is the preferred method for getting data.
```dart
Signal query(Map query, {bool syncedOnly = false})
```
**Parameters:**
- `query` (`Map`): The InstaQL query object
- `syncedOnly` (`bool`, optional): If true, only returns entities that sync to cloud (excludes local-only entities)
**Returns:** `Signal` - A reactive signal containing query results
**Example:**
```dart
final todosSignal = db.query({
'todos': {
'where': {'completed': false},
'orderBy': {'createdAt': 'desc'},
'limit': 20,
},
});
```
### `subscribeQuery()`
Alias for `query()`, kept for API compatibility.
```dart
Signal subscribeQuery(Map query)
```
**Example:**
```dart
final todosSignal = db.subscribeQuery({
'todos': {
'where': {'completed': false},
'orderBy': {'createdAt': 'desc'},
'limit': 20,
},
});
// Use in reactive widgets
Watch((context) {
final result = todosSignal.value;
final todos = result.data?['todos'] ?? [];
return TodoList(todos: todos);
});
```
### `queryOnce()`
Execute a one-time query without creating a subscription.
```dart
Future queryOnce(Map query, {bool syncedOnly = false})
```
**Parameters:**
- `query` (`Map`): The InstaQL query object
- `syncedOnly` (`bool`, optional): If true, only returns entities that sync to cloud
**Returns:** `Future` - The query result
**Example:**
```dart
final result = await db.queryOnce({
'users': {
'where': {'role': 'admin'},
'limit': 5,
},
});
final adminUsers = result.data?['users'] ?? [];
print('Found ${adminUsers.length} admin users');
```
## Transaction Methods
### `transact()`
Execute a transaction with a list of operations or transaction chunk.
```dart
Future transact(dynamic transaction)
```
**Parameters:**
- `transaction` (`List` or `TransactionChunk`): The operations to execute
**Returns:** `Future` - The transaction result
**Example:**
```dart
// With list of operations
await db.transact([
...db.create('todos', {
'id': db.id(),
'text': 'Learn InstantDB',
'completed': false,
}),
]);
// With transaction chunk (new tx API)
await db.transact(
db.tx['todos'][todoId].update({'completed': true})
);
```
### `transactChunk()` (Deprecated)
Execute a transaction chunk. Use `transact()` instead.
```dart
@Deprecated('Use transact() instead')
Future transactChunk(TransactionChunk chunk)
```
### `create()`
Create a new entity operation.
```dart
List create(String entityType, Map data)
```
**Parameters:**
- `entityType` (`String`): The type of entity to create
- `data` (`Map`): The entity data
**Returns:** `List` - List containing the create operation
**Example:**
```dart
final operations = db.create('posts', {
'id': db.id(),
'title': 'Hello World',
'content': 'This is my first post',
'authorId': userId,
'createdAt': DateTime.now().millisecondsSinceEpoch,
});
await db.transact(operations);
```
### `update()`
Create an update entity operation.
```dart
Operation update(String entityId, Map data)
```
**Parameters:**
- `entityId` (`String`): The ID of the entity to update
- `data` (`Map`): The data to update
**Returns:** `Operation` - The update operation
**Example:**
```dart
await db.transact([
db.update(postId, {
'title': 'Updated Title',
'updatedAt': DateTime.now().millisecondsSinceEpoch,
}),
]);
```
### `delete()`
Create a delete entity operation.
```dart
Operation delete(String entityId)
```
**Parameters:**
- `entityId` (`String`): The ID of the entity to delete
**Returns:** `Operation` - The delete operation
**Example:**
```dart
await db.transact([
db.delete(postId),
]);
```
### `merge()`
Create a deep merge operation.
```dart
Operation merge(String entityId, Map data)
```
**Parameters:**
- `entityId` (`String`): The ID of the entity to merge
- `data` (`Map`): The data to deep merge
**Returns:** `Operation` - The merge operation
**Example:**
```dart
await db.transact([
db.merge(userId, {
'preferences': {
'theme': 'dark',
'notifications': {'email': false},
},
}),
]);
```
### `link()`
Create a link operation between entities.
```dart
Operation link(String fromId, String linkName, String toId)
```
**Parameters:**
- `fromId` (`String`): The source entity ID
- `linkName` (`String`): The name of the link relationship
- `toId` (`String`): The target entity ID
**Returns:** `Operation` - The link operation
**Example:**
```dart
await db.transact([
db.link(userId, 'posts', postId),
]);
```
### `unlink()`
Create an unlink operation between entities.
```dart
Operation unlink(String fromId, String linkName, String toId)
```
**Parameters:**
- `fromId` (`String`): The source entity ID
- `linkName` (`String`): The name of the link relationship
- `toId` (`String`): The target entity ID
**Returns:** `Operation` - The unlink operation
**Example:**
```dart
await db.transact([
db.unlink(userId, 'posts', postId),
]);
```
## Transaction API (tx namespace)
### `tx`
Access the new transaction API namespace for fluent operations.
```dart
TransactionNamespace get tx
```
**Returns:** `TransactionNamespace` - The transaction namespace
**Example:**
```dart
// Fluent API for complex operations
await db.transact(
db.tx['users'][userId]
.update({'name': 'New Name'})
.link({'posts': [postId]})
.merge({
'preferences': {'theme': 'dark'},
})
);
```
## Utility Methods
### `id()`
Generate a new UUID for entity IDs.
```dart
String id()
```
**Returns:** `String` - A new UUID string
**Example:**
```dart
final newId = db.id();
print('Generated ID: $newId'); // e.g., "123e4567-e89b-12d3-a456-426614174000"
await db.transact([
...db.create('items', {
'id': newId,
'name': 'New Item',
}),
]);
```
### `lookup()`
Create a lookup reference for referencing entities by attribute instead of ID.
```dart
LookupRef lookup(String entityType, String attribute, dynamic value)
```
**Parameters:**
- `entityType` (`String`): The type of entity to lookup
- `attribute` (`String`): The attribute to match against
- `value` (`dynamic`): The value to match
**Returns:** `LookupRef` - A lookup reference object
**Example:**
```dart
// Reference user by email instead of ID
await db.transact([
...db.create('posts', {
'id': db.id(),
'title': 'Hello World',
'authorId': lookup('users', 'email', 'john@example.com'),
}),
]);
// Use in queries
final posts = db.subscribeQuery({
'posts': {
'where': {
'author': lookup('users', 'email', 'john@example.com'),
},
},
});
```
## Authentication Helpers
### `getAuth()`
Get the current authentication state (one-time check).
```dart
AuthUser? getAuth()
```
**Returns:** `AuthUser?` - The current user, or null if not authenticated
**Example:**
```dart
final currentUser = db.getAuth();
if (currentUser != null) {
print('Logged in as: ${currentUser.email}');
} else {
print('Not logged in');
}
```
### `subscribeAuth()`
Get a stream of authentication state changes.
```dart
Stream subscribeAuth()
```
**Returns:** `Stream` - A stream of auth user state
**Example:**
```dart
db.subscribeAuth().listen((user) {
if (user != null) {
print('User signed in: ${user.email}');
} else {
print('User signed out');
}
});
```
### `getAnonymousUserId()`
Get or generate an anonymous user ID for presence and collaboration.
```dart
String getAnonymousUserId()
```
**Returns:** `String` - An anonymous user ID
**Example:**
```dart
final anonymousId = db.getAnonymousUserId();
final room = db.presence.joinRoom('public-room', initialPresence: {
'userId': anonymousId,
'userName': 'Guest ${anonymousId.substring(0, 4)}',
});
```
## Lifecycle Methods
### `dispose()`
Clean up database resources and connections.
```dart
Future dispose()
```
**Returns:** `Future`
**Example:**
```dart
@override
void dispose() {
super.dispose();
// Clean up database when app is disposed
db.dispose();
}
```
## Error Handling
All InstantDB methods can throw `InstantException` for database-related errors:
```dart
try {
await db.transact([
...db.create('invalid', {}), // Missing required fields
]);
} on InstantException catch (e) {
print('InstantDB Error: ${e.code}');
print('Message: ${e.message}');
// Handle specific error types
switch (e.code) {
case 'validation_error':
// Handle validation errors
break;
case 'network_error':
// Handle network issues
break;
case 'auth_error':
// Handle authentication errors
break;
}
} catch (e) {
print('Unexpected error: $e');
}
```
## Complete Example
Here's a complete example showing common InstantDB operations:
```dart
class TodoService {
final InstantDB db;
TodoService(this.db);
// Get reactive todos
Signal getTodos({bool? completed}) {
return db.subscribeQuery({
'todos': {
if (completed != null) 'where': {'completed': completed},
'orderBy': {'createdAt': 'desc'},
},
});
}
// Create a new todo
Future createTodo({
required String text,
bool completed = false,
}) async {
await db.transact([
...db.create('todos', {
'id': db.id(),
'text': text,
'completed': completed,
'createdAt': DateTime.now().millisecondsSinceEpoch,
'userId': db.auth.currentUser.value?.id,
}),
]);
}
// Update todo using new tx API
Future updateTodo(String todoId, {String? text, bool? completed}) async {
final updates = {};
if (text != null) updates['text'] = text;
if (completed != null) updates['completed'] = completed;
updates['updatedAt'] = DateTime.now().millisecondsSinceEpoch;
await db.transact(
db.tx['todos'][todoId].update(updates)
);
}
// Delete todo
Future deleteTodo(String todoId) async {
await db.transact([db.delete(todoId)]);
}
// Get todos by user email (using lookup)
Signal getTodosByUser(String email) {
return db.subscribeQuery({
'todos': {
'where': {
'user': lookup('users', 'email', email),
},
},
});
}
// Bulk operations
Future markAllCompleted() async {
final result = await db.queryOnce({
'todos': {'where': {'completed': false}},
});
final todos = (result.data?['todos'] as List? ?? [])
.cast>();
final operations = todos.map((todo) =>
db.update(todo['id'], {'completed': true})
).toList();
if (operations.isNotEmpty) {
await db.transact(operations);
}
}
}
```
## Next Steps
Explore specific API areas:
- [Transactions API](/docs/api/transactions) - Detailed transaction and operation methods
- [Queries API](/docs/api/queries) - Advanced querying and InstaQL syntax
- [Presence API](/docs/api/presence-api) - Real-time collaboration methods
- [Flutter Widgets](/docs/api/widgets) - Reactive UI components
- [Types Reference](/docs/api/types) - Complete type definitions
---
# Presence API
> Complete API reference for InstantDB presence and real-time collaboration
Source: https://flutter-instantdb.vercel.app/docs/api/presence-api
The Presence API enables real-time collaboration features like cursors, typing indicators, reactions, and user awareness. It provides both room-based and direct APIs for building collaborative applications.
## PresenceManager
The main entry point for presence functionality, accessed via `db.presence`.
### `joinRoom()`
Join a presence room and get a scoped API for room operations.
```dart
InstantRoom joinRoom(
String roomId, {
Map? initialPresence,
})
```
**Parameters:**
- `roomId` (`String`): Unique identifier for the room
- `initialPresence` (`Map?`): Initial presence data
**Returns:** `InstantRoom` - Room instance with scoped operations
**Example:**
```dart
final room = db.presence.joinRoom('editor-room', initialPresence: {
'userName': 'Alice',
'status': 'online',
'color': '#ff6b6b',
});
```
### `leaveRoom()`
Leave a presence room and clean up resources.
```dart
Future leaveRoom(String roomId)
```
**Parameters:**
- `roomId` (`String`): Room ID to leave
**Example:**
```dart
await db.presence.leaveRoom('editor-room');
```
### Direct Presence Methods
For simple use cases, you can use direct methods without joining a room:
#### `setPresence()`
```dart
Future setPresence(String roomId, Map presence)
```
#### `updateCursor()`
```dart
Future updateCursor(String roomId, {required double x, required double y})
```
#### `setTyping()`
```dart
Future setTyping(String roomId, bool isTyping)
```
#### `sendReaction()`
```dart
Future sendReaction(String roomId, String reaction, {Map? metadata})
```
## InstantRoom
Room-scoped presence API providing isolated operations for a specific collaboration space.
### Presence Operations
#### `setPresence()`
Update user presence data in the room.
```dart
Future setPresence(Map presence)
```
**Parameters:**
- `presence` (`Map`): Presence data to set
**Example:**
```dart
await room.setPresence({
'status': 'editing',
'currentDocument': documentId,
'mood': '😊',
'tool': 'text-editor',
});
```
#### `getPresence()`
Get a reactive signal of all user presence data in the room.
```dart
Signal> getPresence()
```
**Returns:** `Signal>` - Map of user ID to presence data
**Example:**
```dart
Watch((context) {
final presence = room.getPresence().value;
final onlineCount = presence.values.length;
return Text('$onlineCount users in room');
});
```
### Cursor Operations
#### `updateCursor()`
Update cursor position in the room.
```dart
Future updateCursor({required double x, required double y})
```
**Parameters:**
- `x` (`double`): X coordinate
- `y` (`double`): Y coordinate
**Example:**
```dart
void _onMouseMove(PointerEvent event) {
room.updateCursor(
x: event.localPosition.dx,
y: event.localPosition.dy,
);
}
```
#### `getCursors()`
Get a reactive signal of all cursor positions in the room.
```dart
Signal> getCursors()
```
**Returns:** `Signal>` - Map of user ID to cursor data
**Example:**
```dart
Watch((context) {
final cursors = room.getCursors().value;
return Stack(
children: cursors.entries.map((entry) {
final cursor = entry.value;
return Positioned(
left: cursor.x,
top: cursor.y,
child: CursorWidget(
userName: cursor.userName ?? 'Unknown',
userColor: cursor.userColor != null
? Color(int.parse(cursor.userColor!.replaceAll('#', '0xFF')))
: Colors.blue,
),
);
}).toList(),
);
});
```
### Typing Operations
#### `setTyping()`
Set typing indicator status.
```dart
Future setTyping(bool isTyping)
```
**Parameters:**
- `isTyping` (`bool`): Whether user is currently typing
**Example:**
```dart
final _textController = TextEditingController();
Timer? _typingTimer;
void _onTextChanged(String text) {
// Set typing to true
room.setTyping(true);
// Clear typing after delay
_typingTimer?.cancel();
_typingTimer = Timer(const Duration(seconds: 2), () {
room.setTyping(false);
});
}
```
#### `getTyping()`
Get a reactive signal of users currently typing. Returns a map of user IDs to the timestamp they were last seen typing.
```dart
Signal> getTyping()
```
**Returns:** `Signal>` - Map of user IDs to typing timestamps
**Example:**
```dart
Watch((context) {
final typing = room.getTyping().value;
if (typing.isEmpty) {
return const SizedBox.shrink();
}
return Text('${typing.length} people are typing...');
});
```
### Reaction Operations
#### `sendReaction()`
Send a reaction to the room.
```dart
Future sendReaction(
String reaction, {
Map? metadata,
})
```
**Parameters:**
- `reaction` (`String`): Reaction emoji or identifier
- `metadata` (`Map?`): Additional reaction data
**Example:**
```dart
void _onDoubleTap(TapDownDetails details) {
room.sendReaction('❤️', metadata: {
'x': details.localPosition.dx,
'y': details.localPosition.dy,
'message': 'Great idea!',
'timestamp': DateTime.now().millisecondsSinceEpoch,
});
}
```
#### `getReactions()`
Get a reactive signal of recent reactions.
```dart
Signal> getReactions()
```
**Returns:** `Signal>` - List of recent reactions
**Example:**
```dart
Watch((context) {
final reactions = room.getReactions().value;
return Stack(
children: reactions.map((reaction) {
final metadata = reaction.metadata;
final x = metadata?['x']?.toDouble() ?? 0.0;
final y = metadata?['y']?.toDouble() ?? 0.0;
return Positioned(
left: x,
top: y,
child: AnimatedReaction(
emoji: reaction.emoji,
onComplete: () {
// Reaction animation completed
},
),
);
}).toList(),
);
});
```
## Topic-Based Messaging
Rooms support topic-based messaging for structured communication.
### `publishTopic()`
Publish a message to a specific topic within the room.
```dart
Future publishTopic(String topic, Map data)
```
**Parameters:**
- `topic` (`String`): Topic name
- `data` (`Map`): Message data
**Example:**
```dart
await room.publishTopic('chat', {
'message': 'Hello everyone!',
'userName': 'Alice',
'timestamp': DateTime.now().millisecondsSinceEpoch,
});
await room.publishTopic('document-changes', {
'type': 'text-insert',
'position': 42,
'text': 'Hello',
'userId': currentUserId,
});
```
### `subscribeTopic()`
Subscribe to messages on a specific topic.
```dart
Stream> subscribeTopic(String topic)
```
**Parameters:**
- `topic` (`String`): Topic name to subscribe to
**Returns:** `Stream>` - Stream of messages
**Example:**
```dart
class ChatRoomWidget extends StatefulWidget {
final InstantRoom room;
const ChatRoomWidget({super.key, required this.room});
@override
State createState() => _ChatRoomWidgetState();
}
class _ChatRoomWidgetState extends State {
final List _messages = [];
StreamSubscription? _chatSubscription;
@override
void initState() {
super.initState();
// Subscribe to chat messages
_chatSubscription = widget.room.subscribeTopic('chat').listen((data) {
final message = ChatMessage.fromJson(data);
setState(() {
_messages.add(message);
});
});
}
@override
void dispose() {
_chatSubscription?.cancel();
super.dispose();
}
void _sendMessage(String text) {
widget.room.publishTopic('chat', {
'message': text,
'userName': 'Current User',
'timestamp': DateTime.now().millisecondsSinceEpoch,
});
}
@override
Widget build(BuildContext context) {
return Column(
children: [
Expanded(
child: ListView.builder(
itemCount: _messages.length,
itemBuilder: (context, index) {
return MessageBubble(message: _messages[index]);
},
),
),
MessageInput(onSend: _sendMessage),
],
);
}
}
```
## Data Types
### `PresenceData`
Represents a user's presence data.
```dart
class PresenceData {
final String userId;
final Map data;
final DateTime lastSeen;
const PresenceData({
required this.userId,
required this.data,
required this.lastSeen,
});
}
```
**Properties:**
- `userId` (`String`): Unique user identifier
- `data` (`Map`): Custom presence data
- `lastSeen` (`DateTime`): When user was last seen in the room
### `CursorData`
Represents cursor position and metadata.
```dart
class CursorData {
final String userId;
final String? userName;
final String? userColor;
final double x;
final double y;
final Map? metadata;
final DateTime lastUpdated;
const CursorData({
required this.userId,
this.userName,
this.userColor,
required this.x,
required this.y,
this.metadata,
required this.lastUpdated,
});
}
```
**Properties:**
- `userId` (`String`): User who owns the cursor
- `userName` (`String?`): Optional display name for the user
- `userColor` (`String?`): Optional hex color string for the cursor
- `x` (`double`): X coordinate
- `y` (`double`): Y coordinate
- `metadata` (`Map?`): Additional custom cursor metadata
- `lastUpdated` (`DateTime`): When cursor was last updated
### `ReactionData`
Represents a reaction sent to the room.
```dart
class ReactionData {
final String id;
final String userId;
final String emoji;
final String? messageId;
final Map? metadata;
final DateTime timestamp;
const ReactionData({
required this.id,
required this.userId,
required this.emoji,
this.messageId,
this.metadata,
required this.timestamp,
});
}
```
**Properties:**
- `id` (`String`): Unique reaction identifier
- `userId` (`String`): User who sent the reaction
- `emoji` (`String`): Reaction emoji
- `messageId` (`String?`): Optional ID of a message this reaction refers to
- `metadata` (`Map