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

DataStore

Store data asynchronously, consistently, and transactionally, overcoming some of the drawbacks of SharedPreferences
Latest Update Current Stable Release Next Release Candidate Beta Release Alpha Release
November 17, 2020 - - - 1.0.0-alpha04

Declaring dependencies

To add a dependency on DataStore, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

There are two implementations of DataStore: Preferences and Proto. Choose one or the other. You can also add Android-free dependencies to either implementation.

Add the dependencies for the implementation you need in the build.gradle file for your app or module:

Typed

// Typed DataStore (Typed API surface, such as Proto)
dependencies {
  implementation "androidx.datastore:datastore:1.0.0-alpha04"
}
// Alternatively - use the following artifact without an Android dependency.
dependencies {
  implementation "androidx.datastore:datastore-core:1.0.0-alpha04"
}

Preferences

// Preferences DataStore (SharedPreferences like APIs)
dependencies {
  implementation "androidx.datastore:datastore-preferences:1.0.0-alpha04"
}
// Alternatively - use the following artifact without an Android dependency.
dependencies {
  implementation "androidx.datastore:datastore-preferences-core:1.0.0-alpha04"
}

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.0.0

Version 1.0.0-alpha04

November 17, 2020

androidx.datastore:datastore-*:1.0.0-alpha04 is released. Version 1.0.0-alpha04 contains these commits.

Bug Fixes

  • Fixed a packaging issue that causes the following crash in Preference Datastore 1.0.0-alpha03: java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences

Version 1.0.0-alpha03

November 11, 2020

androidx.datastore:datastore-*:1.0.0-alpha03 is released. Version 1.0.0-alpha03 contains these commits.

New Features

  • Preferences now supports double values (which is useful if you need more precision than floats) (I5be8f, b/169471808)

API Changes

  • Created a pure kotlin dependency for datastore to allow for faster compilation. androidx.datastore:datastore-core contains the core kotlin only APIs and androidx.datastore:datastore contains the APIs that depend on android (including the SharedPreferencesMigration and the Context.createDataStore constructor.)(I42d75, b/168512698)
  • Splitting out targets for preferences data store for faster kotlin compilation (Ia3c19)
  • Serializers now require a new property for the default value that will be used if there is no data on disk. This makes it easier to implement custom serializers so users do not have to special case empty input streams (empty input streams don't parse with json).

    • Also there is now a check to confirm that the output stream provided to writeTo() is not closed, and if it is closed it throws exceptions (I16e29)
  • Making the constructor for SharedPreferencesView internal. It was originally public to allow for testing. Tests should instead construct a SharedPreferencesMigration and test against that. (I93891)

Bug Fixes

  • The produceFile parameter on DataStoreFactory and PreferenceDataStoreFactory is now the last parameter in the list so it lets you use the kotlin trailing lambda syntax. (Ibe7f1, b/169425442)
  • Following the new explicit API requirements for kotlin (I5ae1e)

Known Issues

  • Preference Datastore crashes with java.lang.NoClassDefFoundError. (b/173036843)

Version 1.0.0-alpha02

October 14, 2020

androidx.datastore:datastore-core:1.0.0-alpha02 and androidx.datastore:datastore-preferences:1.0.0-alpha02 are released. Version 1.0.0-alpha02 contains these commits.

Bug Fixes

  • Added a safeguard against mutation in datastore-core. Mutation breaks datastore usage for people using datastore with non-proto/non-preferences types (I6aa84)
  • Added a toString method to Preferences.kt to make current state easy to debug (I96006)
  • Added an exception to safeguard against misuse of DataStore.Preferences (I1134d)
  • Fixed a bug that would cause the app to crash on start up (I69237, b/168580258)

Version 1.0.0-alpha01

September 2, 2020

androidx.datastore:datastore-core:1.0.0-alpha01 and androidx.datastore:datastore-preferences:1.0.0-alpha01 are released. Version 1.0.0-alpha01 contains these commits.

New Features

Jetpack DataStore is a new and improved data storage solution aimed at replacing SharedPreferences. Built on Kotlin coroutines and Flow, DataStore provides two different implementations:

  • Proto DataStore, that lets you store typed objects (backed by protocol buffers)
  • Preferences DataStore, that stores key-value pairs

Data is stored asynchronously, consistently, and transactionally, overcoming most of the drawbacks of SharedPreferences.