# SharedPreferencesMigration

Artifact: [androidx.datastore:datastore](https://developer.android.com/jetpack/androidx/releases/datastore) [View Source](https://cs.android.com/search?q=file:androidx/datastore/migrations/SharedPreferencesMigration.android.kt+class:androidx.datastore.migrations.SharedPreferencesMigration) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.0.0)

*** ** * ** ***


```
class SharedPreferencesMigration<T : Any?> : DataMigration<T>
```

<br />

*** ** * ** ***

DataMigration instance for migrating from SharedPreferences to DataStore.

## Summary

| ### Public constructors |
|---|
| `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesMigration#SharedPreferencesMigration(kotlin.Function0,kotlin.collections.Set,kotlin.coroutines.SuspendFunction1,kotlin.coroutines.SuspendFunction2)( produceSharedPreferences: () -> https://developer.android.com/reference/android/content/SharedPreferences.html, keysToMigrate: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>, shouldRunMigration: suspend (T) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, migrate: suspend (https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesView, T) -> T )` DataMigration from SharedPreferences to DataStore. |
| `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesMigration#SharedPreferencesMigration(android.content.Context,kotlin.String,kotlin.collections.Set,kotlin.coroutines.SuspendFunction1,kotlin.coroutines.SuspendFunction2)( context: https://developer.android.com/reference/android/content/Context.html, sharedPreferencesName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, keysToMigrate: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>, shouldRunMigration: suspend (T) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, migrate: suspend (https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesView, T) -> T )` DataMigration from SharedPreferences to DataStore. |

| ### Public functions |
|---|---|
| `open suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesMigration#cleanUp()()` Clean up any old state/data that was migrated into the DataStore. |
| `open suspend T` | `https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesMigration#migrate(kotlin.Any)(currentData: T)` Perform the migration. |
| `open suspend https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesMigration#shouldMigrate(kotlin.Any)(currentData: T)` Return whether this migration needs to be performed. |

## Public constructors

### SharedPreferencesMigration

```
<T : Any?> SharedPreferencesMigration(
    produceSharedPreferences: () -> SharedPreferences,
    keysToMigrate: Set<String> = MIGRATE_ALL_KEYS,
    shouldRunMigration: suspend (T) -> Boolean = { true },
    migrate: suspend (SharedPreferencesView, T) -> T
)
```

DataMigration from SharedPreferences to DataStore.

Note: This migration only supports the basic SharedPreferences types: boolean, float, int, long, string and string set. If the result of getAll contains other types, they will be ignored.

Example usage:

```kotlin
val sharedPrefsMigration = SharedPreferencesMigration(
  produceSharedPreferences = { EncryptedSharedPreferences.create(...) }
) { prefs: SharedPreferencesView, myData: MyData ->
   myData.toBuilder().setCounter(prefs.getCounter(COUNTER_KEY, default = 0)).build()
}
```

| Parameters |
|---|---|
| `produceSharedPreferences: () -> https://developer.android.com/reference/android/content/SharedPreferences.html` | Should return the instance of SharedPreferences to migrate from. |
| `keysToMigrate: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html> = MIGRATE_ALL_KEYS` | The list of keys to migrate. The keys will be mapped to datastore .Preferences with their same values. If the key is already present in the new Preferences, the key will not be migrated again. If the key is not present in the SharedPreferences it will not be migrated. If keysToMigrate is not set, all keys will be migrated from the existing SharedPreferences. |
| `shouldRunMigration: suspend (T) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = { true }` | A lambda which accepts current data of type `T` and returns whether migration should run. |
| `migrate: suspend (https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesView, T) -> T` | maps SharedPreferences into T. Implementations should be idempotent since this may be called multiple times. See `https://developer.android.com/reference/kotlin/androidx/datastore/core/DataMigration#migrate(kotlin.Any)` for more information. The lambda accepts a SharedPreferencesView which is the view of the SharedPreferences to migrate from (limited to `https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesMigration#(kotlin.Function0,kotlin.collections.Set,kotlin.coroutines.SuspendFunction1,kotlin.coroutines.SuspendFunction2)` and a T which represent the current data. The function must return the migrated data. If SharedPreferences is empty or does not contain any keys which you specified, this callback will not run. |

### SharedPreferencesMigration

```
<T : Any?> SharedPreferencesMigration(
    context: Context,
    sharedPreferencesName: String,
    keysToMigrate: Set<String> = MIGRATE_ALL_KEYS,
    shouldRunMigration: suspend (T) -> Boolean = { true },
    migrate: suspend (SharedPreferencesView, T) -> T
)
```

DataMigration from SharedPreferences to DataStore.

If the SharedPreferences is empty once the migration completes, this migration will attempt to delete it.

Example usage:

```kotlin
val sharedPrefsMigration = SharedPreferencesMigration(
  context,
  mySharedPreferencesName
) { prefs: SharedPreferencesView, myData: MyData ->
   myData.toBuilder().setCounter(prefs.getCounter(COUNTER_KEY, default = 0)).build()
}
```

| Parameters |
|---|---|
| `context: https://developer.android.com/reference/android/content/Context.html` | Context used for getting SharedPreferences. |
| `sharedPreferencesName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the SharedPreferences. |
| `keysToMigrate: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html> = MIGRATE_ALL_KEYS` | The list of keys to migrate. The keys will be mapped to datastore .Preferences with their same values. If the key is already present in the new Preferences, the key will not be migrated again. If the key is not present in the SharedPreferences it will not be migrated. If keysToMigrate is not set, all keys will be migrated from the existing SharedPreferences. |
| `shouldRunMigration: suspend (T) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = { true }` | A lambda which accepts current data of type `T` and returns whether migration should run. |
| `migrate: suspend (https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesView, T) -> T` | maps SharedPreferences into T. Implementations should be idempotent since this may be called multiple times. See `https://developer.android.com/reference/kotlin/androidx/datastore/core/DataMigration#migrate(kotlin.Any)` for more information. The lambda accepts a SharedPreferencesView which is the view of the SharedPreferences to migrate from (limited to `https://developer.android.com/reference/kotlin/androidx/datastore/migrations/SharedPreferencesMigration#(android.content.Context,kotlin.String,kotlin.collections.Set,kotlin.coroutines.SuspendFunction1,kotlin.coroutines.SuspendFunction2)` and a T which represent the current data. The function must return the migrated data. If SharedPreferences is empty or does not contain any keys which you specified, this callback will not run. |

## Public functions

### cleanUp

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/datastore#1.0.0)

```
open suspend fun cleanUp(): Unit
```

Clean up any old state/data that was migrated into the DataStore. This will not be called if the migration fails. If cleanUp throws an exception, the exception will be propagated back to the DataStore call that triggered the migration and future calls to DataStore will result in DataMigrations being attempted again. This method may be run multiple times when any failure is encountered.

This is useful for cleaning up files or data outside of DataStore and accessing any data from DataStore directly from inside this function will result in deadlock, since DataStore doesn't return data until all migrations complete.

### migrate

```
open suspend fun migrate(currentData: T): T
```

Perform the migration. Implementations should be idempotent since this may be called multiple times. If migrate fails, DataStore will not commit any data to disk, cleanUp will not be called, and the exception will be propagated back to the DataStore call that triggered the migration. Future calls to DataStore will result in DataMigrations being attempted again. This method may be run multiple times when any failure is encountered.

Note that this will always be called before a call to `https://developer.android.com/reference/kotlin/androidx/datastore/core/DataMigration#cleanUp()`.

Note that accessing any data from DataStore directly from inside this function will result in deadlock, since DataStore doesn't return data until all migrations complete.

| Parameters |
|---|---|
| `currentData: T` | the current data (it might be populated from other migrations or from manual changes before this migration was added to the app) |

| Returns |
|---|---|
| `T` | The migrated data. |

### shouldMigrate

```
open suspend fun shouldMigrate(currentData: T): Boolean
```

Return whether this migration needs to be performed. If this returns false, no migration or cleanup will occur. Apps should do the cheapest possible check to determine if this migration should run, since this will be called every time the DataStore is initialized. This method may be run multiple times when any failure is encountered.

Note that this will always be called before each call to `https://developer.android.com/reference/kotlin/androidx/datastore/core/DataMigration#migrate(kotlin.Any)`.

Note that accessing any data from DataStore directly from inside this function will result in deadlock, since DataStore doesn't return data until all migrations complete.

| Parameters |
|---|---|
| `currentData: T` | the current data (which might already be populated from previous runs of this or other migrations) |