DataStore Preferences

SharedPreferences Limitations

SharedPreferences has served Android well but has real problems:

1. Synchronous API on main thread — getSharedPreferences() does disk I/O. Calling commit() on the main thread causes ANRs.
2. No error handling — getString() returns null on failure with no exception.
3. Not thread-safe by default — apply() can lose writes during process death.
4. No type safety — keys are raw strings, values have no compile-time checking.
5. Blocking I/O — even apply() writes to disk synchronously under the hood, then posts to memory.

DataStore Advantages

• Fully asynchronous via Kotlin coroutines and Flow
• Type-safe with compile-time key definitions
• Transactional — writes are atomic
• Consistent — no partial writes during process death
• Two flavors — Preferences DataStore and Proto DataStore

Choosing Between Preferences and Proto

Setup

// build.gradle.kts
implementation("androidx.datastore:datastore-preferences:1.1.1")

// Creating the DataStore instance
val Context.dataStore by preferencesDataStore(name = "settings")

Defining Keys

object PreferenceKeys {
    val DARK_MODE = booleanPreferencesKey("dark_mode")
    val USERNAME = stringPreferencesKey("username")
    val FONT_SIZE = intPreferencesKey("font_size")
    val LANGUAGE = stringPreferencesKey("language")
}

Keys are compile-time constants — no more typo bugs with raw strings.

Writing Preferences

// In a ViewModel or repository
viewModelScope.launch {
    context.dataStore.edit { prefs ->
        prefs[PreferenceKeys.DARK_MODE] = true
        prefs[PreferenceKeys.USERNAME] = "amazon_developer"
        prefs[PreferenceKeys.FONT_SIZE] = 14
    }
}

edit is atomic. The lambda runs inside a transaction — either all changes apply or none do.

Reading as Flow

val darkModeFlow: Flow<Boolean> = context.dataStore.data
    .catch { exception ->
        if (exception is IOException) emit(emptyPreferences())
        else throw exception
    }
    .map { prefs ->
        prefs[PreferenceKeys.DARK_MODE] ?: false
    }

// Collect in Composable
@Composable
fun SettingsScreen(viewModel: SettingsViewModel) {
    val isDarkMode by viewModel.darkModeFlow.collectAsState(initial = false)
    
    Switch(
        checked = isDarkMode,
        onCheckedChange = { viewModel.toggleDarkMode(it) }
    )
}

The catch operator handles disk I/O errors gracefully. Without it, an IOException kills the Flow.

Reading Once (Non-Flow)

suspend fun getUsername(): String {
    return context.dataStore.data.first()[PreferenceKeys.USERNAME] ?: "Guest"
}

first() collects the latest value and cancels. Use this for one-shot reads, not ongoing observation.

Clearing Preferences

context.dataStore.edit { it.clear() }

This removes all keys in a single transaction.

Migration Strategy

Android provides SharedPreferencesMigration to automatically move data during the first DataStore read.

val Context.dataStore by preferencesDataStore(
    name = "settings",
    produceMigrations = { context ->
        listOf(SharedPreferencesMigration(context, "old_prefs_name"))
    }
)

When the DataStore is first accessed, it reads all keys from the old SharedPreferences file and writes them into the new DataStore. After migration, the old file is not deleted — handle that yourself after verifying the migration worked.

Manual Migration

For complex scenarios where key names changed or values need transformation:

suspend fun migratePreferences(dataStore: DataStore<Preferences>) {
    val oldPrefs = context.getSharedPreferences("old_prefs", Context.MODE_PRIVATE)
    
    dataStore.edit { newPrefs ->
        // Map old key to new key
        oldPrefs.getString("theme", null)?.let {
            newPrefs[PreferenceKeys.DARK_MODE] = (it == "dark")
        }
        
        // Transform value
        oldPrefs.getInt("text_size", 12).let {
            newPrefs[PreferenceKeys.FONT_SIZE] = it + 2
        }
    }
    
    // Delete old file after successful migration
    File(oldPrefs.fileParent, oldPrefs.file.name).delete()
}

Best Practices

• Never access DataStore before ViewModel init — use by lazy or dependency injection
• Handle IOException in the catch operator of every Flow read
• Use first() for one-shot reads, not first().value which can block
• Test migration by verifying all expected keys transfer with correct values
• Don't use DataStore on the main thread for direct reads — always use coroutines