Offline Support

How it works

The SDK uses a local Drift database on the device to cache query results and queue writes. No configuration needed — offline support is enabled automatically when you initialize the SDK.

Cache-first reads

Every query automatically checks local cache first. If data exists, it returns immediately and triggers a background network refresh. Use isFromCache to know the data source.

final result = await Koolbase.db
  .collection('posts')
  .get();

if (result.isFromCache) {
  // Data loaded from local storage — network refresh in progress
  print('Showing cached data');
} else {
  // Fresh data from server
  print('Showing live data');
}

for (final post in result.records) {
  print(post.data['title']);
}

@override
void initState() {
  super.initState();

  // Listen for fresh data after background refresh
  Koolbase.db.collection('posts').stream.listen((result) {
    setState(() => _posts = result.records);
  });
}

Offline writes

Inserts work the same way whether you're online or offline. If the network is unavailable, the write is queued locally and synced automatically when connectivity is restored.

// Works online and offline — no change to your code
final post = await Koolbase.db.insert(
  collection: 'posts',
  data: {
    'title': 'Written offline',
    'body': 'This will sync when back online',
  },
);

// If offline, returns an optimistic record immediately
print(post.id); // temporary local ID until synced

Syncing pending writes

The SDK auto-syncs when network connectivity is restored. You can also trigger a sync manually at any point — for example, on app resume or after a user action.

// Manual sync — call at any point
await Koolbase.db.syncPendingWrites();

// Sync on app resume
@override
void didChangeAppLifecycleState(AppLifecycleState state) {
  if (state == AppLifecycleState.resumed) {
    Koolbase.db.syncPendingWrites();
  }
}

Retry behavior

Failed writes are retried automatically. After 3 failed attempts, the write is dropped and logged. This prevents the queue from growing indefinitely on persistent errors.

Local storage

Offline data is stored in a local SQLite database using Drift. The database persists across app restarts and is stored in the app's private storage directory — not accessible to other apps.

Current limitations