Google is committed to advancing racial equity for Black communities. See how.

DataStore

interface DataStore<T>
androidx.datastore.DataStore

DataStore provides a safe and durable way to store small amounts of data, such as preferences and application state. It does not support partial updates: if any field is modified, the whole object will be serialized and persisted to disk. If you want partial updates, consider the Room API (SQLite).

DataStore provides ACID guarantees. It is thread-safe, and non-blocking. In particular, it addresses these design shortcomings of the SharedPreferences API:

  1. Synchronous API encourages StrictMode violations
  2. apply() and commit() have no mechanism of signalling errors
  3. apply() will block the UI thread on fsync()
  4. Not durable – it can returns state that is not yet persisted
  5. No consistency or transactional semantics
  6. Throws runtime exception on parsing errors
  7. Exposes mutable references to its internal state

Summary

Public methods
abstract suspend T
updateData(transform: suspend (t: T) -> T)

Updates the data transactionally in an atomic read-modify-write operation.

Extension functions
From androidx.datastore.preferences
suspend Preferences
DataStore<Preferences>.edit(transform: suspend (MutablePreferences) -> Unit)

Edit the value in DataStore transactionally in an atomic read-modify-write operation.

Properties
abstract Flow<T>

Provides efficient, cached (when possible) access to the latest durably persisted state.

Public methods

updateData

abstract suspend fun updateData(transform: suspend (t: T) -> T): T

Updates the data transactionally in an atomic read-modify-write operation. All operations are serialized, and the transform itself is a coroutine so it can perform heavy work such as RPCs.

The coroutine completes when the data has been persisted durably to disk (after which data will reflect the update). If the transform or write to disk fails, the transaction is aborted and an exception is thrown.

Return
the snapshot returned by the transform
Exceptions
IOException when an exception is encountered when writing data to disk
Exception when thrown by the transform function

Properties

data

abstract val data: Flow<T>

Provides efficient, cached (when possible) access to the latest durably persisted state. The flow will always either emit a value or throw an exception encountered when attempting to read from disk. If an exception is encountered, collecting again will attempt to read the data again.

Do not layer a cache on top of this API: it will be be impossible to guarantee consistency. Instead, use data.first() to access a single snapshot.

Return
a flow representing the current state of the data
Exceptions
IOException when an exception is encountered when reading data