Skip to main content
Version: v4

Adding Local Data Persistence

Adding Local Data Persistence


Most messaging apps need to work regardless of whether the app is currently connected to the internet. Local data persistence stores the fetched data from the backend on a local SQLite database using the moor package in Flutter. All packages in the SDK can use local data persistence to store messages across multiple platforms.


To add data persistence you can extend the class ChatPersistenceClient and pass an instance to the StreamChatClient.

class CustomChatPersistentClient extends ChatPersistenceClient {

final client = StreamChatClient(
apiKey ?? kDefaultStreamApiKey,
logLevel: Level.INFO,
)..chatPersistenceClient = CustomChatPersistentClient();

We provide an official persistent client in the stream_chat_persistence package that works using the library moor, an SQLite ORM.

Add this to your package's pubspec.yaml file, using the latest version.

stream_chat_persistence: ^latest_version

You should then run flutter packages get

The usage is pretty simple.

  1. Create a new instance of StreamChatPersistenceClient providing logLevel and connectionMode
final chatPersistentClient = StreamChatPersistenceClient(
logLevel: Level.INFO,
connectionMode: ConnectionMode.background,
  1. Pass the instance to the official StreamChatClient
  final client = StreamChatClient(
apiKey ?? kDefaultStreamApiKey,
logLevel: Level.INFO,
)..chatPersistenceClient = chatPersistentClient;

And you are ready to go...

Note that passing ConnectionMode.background the database uses a background isolate to unblock the main thread. The StreamChatClient uses the chatPersistentClient to synchronize the database with the newest information every time it receives new data about channels/messages/users.


The DB file is named after the userId, so if you instantiate a client using a different userId you will use a different database. Calling client.disconnectUser(flushChatPersistence: true) flushes all current database data.

Updating/deleting/sending a message while offline

The information about the action is saved in offline storage. When the client returns online, everything is retried.

Did you find this page helpful?