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
July 21, 2021 - 1.0.0-rc02 - -

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:

Datastore Typed

Groovy

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation "androidx.datastore:datastore:1.0.0-rc02"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.0.0-rc02"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-rxjava3:1.0.0-rc02"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-core:1.0.0-rc02"
    }
    

Kotlin

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation("androidx.datastore:datastore:1.0.0-rc02")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.0.0-rc02")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-rxjava3:1.0.0-rc02")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-core:1.0.0-rc02")
    }
    

Datastore Preferences

Groovy

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation "androidx.datastore:datastore-preferences:1.0.0-rc02"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.0.0-rc02"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-preferences-rxjava3:1.0.0-rc02"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-preferences-core:1.0.0-rc02"
    }
    

Kotlin

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation("androidx.datastore:datastore-preferences:1.0.0-rc02")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.0.0-rc02")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-preferences-rxjava3:1.0.0-rc02")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-preferences-core:1.0.0-rc02")
    }
    

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-rc02

July 21, 2021

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

Bug Fixes

  • Clarify that SharedPreferencesMigration does not run if there are no keys. (Icfa32, b/192824325)
  • Fix bug where SharedPreferencesMigration constructed with MIGRATE_ALL_KEYS would throw an exception if the key requested does not yet exist. (Ie318a, b/192824325)

Version 1.0.0-rc01

June 30, 2021

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

Bug Fixes

  • Fixes bug where .java file was inadvertently added into final jar (I65d96, b/188985637)

Version 1.0.0-beta02

June 16, 2021

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

Bug Fixes

Version 1.0.0-beta01

April 21, 2021

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

API Changes

  • Remove JVM overloads for kotlin only methods (I2adc7)

Bug Fixes

  • Fixed a bug where datastore delegates could result in leaking contexts (Ie96fc, b/184415662)

Version 1.0.0-alpha08

March 10, 2021

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

API Changes

  • You can now add a migration that depends on context to your dataStore and preferencesDataStore property delegate. (I4ef69, b/173726702)
  • Adds helper functions to get the name of the file if you are no longer using datastore delegate or context.createDataStore (I60f9a)
  • Serializer writeTo and readFrom are now suspending. If you have implemented a Serializer, you will need to update your functions to be suspend functions. (I1e58e)
  • Added property delegates for RxDataStore users. (Ied768, b/173726702)

Bug Fixes

Version 1.0.0-alpha07

February 24, 2021

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

API Changes

  • The Context.createDataStore extension function has been removed and replaced with globalDataStore property delegate. Call globalDataStore once at the top level in your kotlin file. For example:

    val Context.myDataStore by dataStore(...)
    

    Put this at the top level of your kotlin file so there is only one instance of it. (I57215, b/173726702)

  • The RxDataStore functions are now on an RxDataStore class instead of extension functions on DataStore. (Idccdb, b/177691248)

  • If you want to migrate EncryptedSharedPreferences (or direct boot SharedPreferences) to DataStore you can now do that with the new SharedPreferencesMigration constructor that allows you to inject the SharedPreferences. (I8e04e, b/177278510)

Bug Fixes

  • DataStore will now throw an exception if there are multiple active DataStores for the same file. If you were not managing your DataStore as a Singleton or were not ensuring that no two instances of DataStore are simultaneously active for a file then you may now see exceptions when reading or writing to DataStore. These can be fixed by managing your DataStore as a Singleton. (Ib43f4, b/177691248)
  • Fix cancellation behavior when caller scope is cancelled. (I2c7b3)

Version 1.0.0-alpha06

January 13, 2021

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

New Features

  • Added RxJava wrappers for DataStore. The datastore-rxjava2/3 artifacts contain the wrappers for the core DataStore APIs (RxDataStore, RxDataStoreBuilder, and RxDataMigration). The datastore-preferences-rxjava2/3 artifacts contain a builder to construct a Preferences DataStore.

API Changes

  • Hide the CorruptionHandler interface. There was no reason for it to be public because the DataStore factory only accepts a ReplaceFileCorruptionHandler. (I0b3b3, b/176032264)
  • The preferencesKey<T>(name: String): Key<T> method has been removed and replaced with methods specific to each supported type, for example preferencesKey<Int>("int") is now intPreferencesKey("int") (Ibcfac, b/170311106)

Bug Fixes

  • Fixes documentation on DataStoreFactory which left out the fact that the datastore file is created in the “datastore/” subdirectory. (Ica222)

Version 1.0.0-alpha05

December 2, 2020

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

Bug Fixes

  • Add better documentation and exceptions around concurrent writes from datastores. (Ia98a2, b/173522155, b/173726702)
  • We now allow (but don't require) the OutputStream passed to Serializer.writeTo() to be closed. (I5c9bf, b/173037611)

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.