Introducing DataStore

A new way to store data on Android.

Overview

• A new and improved data storage solution aimed at replacing SharedPreferences.
• Kotlin coroutines and Flow.
• Data is stored asynchronously, consistently, and transactionally.

SharePreferences vs DataStore

Features

It provides two different implementations:

• Preferences DataStore: stores primitive data key-value pairs.
• Proto DataStore: stores typed objects.

In both implementations, DataStore saves the preferences in a file and performs all data operations on Dispatchers.IO unless specified otherwise.

Pre requirement

• Familiarity with coroutines and Kotlin Flow.

Steps

Setup

Gradle:

// Preferences DataStore 
implementation “androidx.datastore:datastore-preferences:1.0.0-alpha05”
// Proto DataStore 
implementation “androidx.datastore:datastore-core:1.0.0-alpha05”

For Proto DataStore:

• Setup protobuf gradle plugin: https://github.com/google/protobuf-gradle-plugin
• Define your schema in a proto file in the app/src/main/proto/ directory.

Create the DataStore

Preference DataStore:

val dataStore: DataStore<Preferences> = context.createDataStore(name = "settings")

Proto DataStore:

object SettingsSerializer : Serializer<Settings> {
  override fun readFrom(input: InputStream): Settings {
    try {
      return Settings.parseFrom(input)
    } catch (exception: InvalidProtocolBufferException) {
      throw CorruptionException("Cannot read proto.", exception)
    }
  }

  override fun writeTo(
    t: Settings,
    output: OutputStream) = t.writeTo(output)
}

val settingsDataStore: DataStore<Settings> = context.createDataStore(
  fileName = "settings.pb",
  serializer = SettingsSerializer
)

Read data

Preference DataStore:

val MY_COUNTER = preferencesKey<Int>("my_counter")
val myCounterFlow: Flow<Int> = dataStore.data
     .map { currentPreferences ->
        // Unlike Proto DataStore, there's no type safety here.
        currentPreferences[MY_COUNTER] ?: 0   
   }

Proto DataStore:

val myCounterFlow: Flow<Int> = settingsDataStore.data
    .map { settings ->
        // The myCounter property is generated for you from your proto schema!
        settings.myCounter 
    }

Write data

Preference DataStore:

suspend fun incrementCounter() {
    dataStore.edit { settings ->
        // We can safely increment our counter without losing data due to races!
        val currentCounterValue = settings[MY_COUNTER] ?: 0
        settings[MY_COUNTER] = currentCounterValue + 1
    }
}

Proto DataStore:

suspend fun incrementCounter() {
    settingsDataStore.updateData { currentSettings ->
        // We can safely increment our counter without losing data due to races!
        currentSettings.toBuilder()
            .setMyCounter(currentSettings.myCounter + 1)
            .build()
    }
}

Migrate from SharedPreferences

Preference DataStore:

val dataStore: DataStore<Preferences> = context.createDataStore(
    name = "settings",
    migrations = listOf(SharedPreferencesMigration(context, "settings_preferences"))
)

Proto DataStore:

val settingsDataStore: DataStore<Settings> = context.createDataStore(
    produceFile = { File(context.filesDir, "settings.preferences_pb") },
    serializer = SettingsSerializer,
    migrations = listOf(
        SharedPreferencesMigration(
            context,
            "settings_preferences"            
        ) { sharedPrefs: SharedPreferencesView, currentData: Settings ->
            // Map your sharedPrefs to your type here
          }
    )
)

Conclusion

Jetpack DataStore is a replacement for SharedPreferences that address some problems such as a synchronous API that can appear to be safe to call on UI thread, no mechanism for signaling errors, lack of transactional and more. DataStore is fully asynchronous API using Kotlin Coroutines and Flow, consistent, handle data migration and data corruption.