DataStore

DataStore

사용자 가이드  Codelab

API 참조
androidx.datastore

비동기적이고 일관된 트랜잭션 방식으로 데이터를 저장하여 SharedPreferences의 일부 단점을 극복합니다.

최근 업데이트	안정화 버전	출시 후보 버전	베타 버전	알파 버전
2024년 4월 17일	1.1.0	-	-	-

종속 항목 선언

DataStore의 종속 항목을 추가하려면 프로젝트에 Google Maven 저장소를 추가해야 합니다. 자세한 내용은 Google Maven 저장소를 읽어보세요.

DataStore는 Preferences와 Proto 두 가지 방식을 통해 구현이 가능합니다. 둘 중 하나를 선택합니다. 두 구현 중 하나에 Android로부터 독립된 종속 항목을 추가할 수도 있습니다.

다음과 같이 앱 또는 모듈의 build.gradle 파일에 필요한 구현의 종속 항목을 추가합니다.

Preferences DataStore

Groovy

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

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

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

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

Kotlin

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

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

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

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

Proto DataStore

Groovy

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

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

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

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

Kotlin

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

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

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

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

의견

제출하신 의견은 Jetpack을 개선하는 데 도움이 됩니다. 새로운 문제를 발견하거나 라이브러리 개선을 위한 아이디어가 있다면 Google에 알려 주세요. 새 문제를 제출하기 전에 이 라이브러리의 기존 문제를 살펴보시기 바랍니다. 별표 버튼을 클릭하여 기존 문제에 투표할 수 있습니다.

새로운 문제 제출하기

자세한 내용은 Issue Tracker 문서를 참고하세요.

버전 1.1

버전 1.1.0

2024년 4월 17일

androidx.datastore:datastore-*:1.1.0가 출시되었습니다. 버전 1.1.0에 포함된 커밋을 확인하세요.

1.0.0 출시 이후 주요 변경사항

자세한 내용은 1.1.0 알파 및 베타 버전의 출시 노트를 검토하세요. 1.1.0의 주요 업데이트 내용은 다음과 같습니다.

• DataStore는 이제 동일한 파일에 액세스하는 여러 프로세스를 지원하며 프로세스 간 관측 가능성을 지원합니다.
• 새 스토리지 인터페이스를 사용하면 데이터 모델을 저장하거나 직렬화하는 방법을 맞춤설정할 수 있습니다.
• 이제 Kotlin 멀티플랫폼 프로젝트에서 DataStore를 사용할 수 있습니다.

버전 1.1.0-rc01

2024년 4월 3일

androidx.datastore:datastore-*:1.1.0-rc01가 출시되었습니다. 버전 1.1.0-rc01에 포함된 커밋을 확인하세요.

버그 수정

• 새 데이터가 이전 데이터와 동일한 경우 updateData 호출이 디스크 쓰기에서 최적화되지 않는 성능 저하 문제를 해결했습니다. (d64cfb5)
• 초기화 중에 MultiProcess DataStore가 무효화를 놓칠 수 있는 경합 상태가 수정되었습니다. (b/326141553),(094c2dd)

버전 1.1.0-beta02

2024년 3월 6일

androidx.datastore:datastore-*:1.1.0-beta02가 출시되었습니다. 버전 1.1.0-beta02에 포함된 커밋을 확인하세요.

버그 수정

• DataStore의 성능 개선은 관찰된 경우에만 업데이트 알림을 수집합니다. b/267792241을 참조하세요.
  • 코루틴 테스트 라이브러리를 사용하는 경우 이 변경으로 인해 테스트에서 UncompletedCoroutinesError가 트리거될 수 있습니다. 이 문제를 방지하려면 테스트에서 DataStore를 초기화할 때 TestScope.backgroundScope를 통과해야 합니다.
• 동일한 인스턴스에서 중첩된 updateData 호출이 교착 상태에 빠지는 문제를 수정했습니다. b/241760537을 참조하세요.
• 이전 중에 SharedPreferences를 삭제하지 못하면 DataStore에서 더 이상 IOExceptions이 발생하지 않습니다. b/195553816을 참조하세요.
• Android가 아닌 JVM 환경에서 updateData 중에 파일 이름 변경이 실패하는 문제가 수정되었습니다. b/203087070을 참조하세요.
• DataStore 초기화 후 CorruptionException가 처리되지 않는 문제가 해결되었습니다. b/289582516을 참조하세요.

버전 1.1.0-beta01

2024년 1월 10일

androidx.datastore:datastore-*:1.1.0-beta01이 1.1.0-alpha07 이후 변경사항 없이 출시되었습니다. 버전 1.1.0-beta01에 포함된 커밋을 확인하세요.

버전 1.1.0-alpha07

2023년 11월 29일

androidx.datastore:datastore-*:1.1.0-alpha07가 출시되었습니다. 버전 1.1.0-alpha07에 포함된 커밋을 확인하세요.

API 변경사항

• MultiProcessDataStoreFactory 메서드는 더 이상 실험용이 아닙니다.@ExperimentalMultiProcessDataStore 주석이 완전히 삭제되었습니다. 추가했습니다. (Ieee54, I8e607)

버그 수정

• 삭제된 @ExperimentalMultiProcessDataStore 주석을 1.1.0-alpha07에 출시합니다. 추가했습니다. (I8e607)

버전 1.1.0-alpha06

2023년 11월 1일

androidx.datastore:datastore-*:1.1.0-alpha06가 출시되었습니다. 버전 1.1.0-alpha06에 포함된 커밋을 확인하세요.

API 변경사항

• createSingleProcessCoordinator 팩토리 메서드는 이제 createMultiProcessCoordinator와 일관되도록 파일 경로 (String, java.io.File, okio.Path)를 수신합니다. 추가했습니다. (I211c8, b/305755935)

버전 1.1.0-alpha05

2023년 9월 6일

androidx.datastore:datastore-*:1.1.0-alpha05가 출시되었습니다. 버전 1.1.0-alpha05에 포함된 커밋을 확인하세요.

API 변경사항

• Datastore FileStorage이 이제 공개적으로 사용 가능하므로 클라이언트가 커스텀 매개변수를 제공할 수 있습니다. 추가했습니다. (Icb985)
• InterProcessCoordinator를 허용하도록 OkioStorage 생성자가 변경되어 Android에서 MultiProcessCoordinator로 사용할 수 있습니다. 추가했습니다. (Iecea3)

버그 수정

• MultiProcessCoordinator가 동일한 디렉터리에서 여러 파일을 모니터링할 수 없는 문제를 수정했습니다.
• 파일 경로가 정규화되지 않으면 중복 파일을 감지할 수 없는 문제를 수정했습니다.
• RxDataStore#isDisposed에서 반환된 잘못된 값을 수정합니다.
• datstore-preferences-core 아티팩트의 누락된 proguard 구성이 수정되었습니다.

버전 1.1.0-alpha04

2023년 4월 5일

androidx.datastore:datastore-*:1.1.0-alpha04가 출시되었습니다. 버전 1.1.0-alpha04에 포함된 커밋을 확인하세요.

버그 수정

• 내부 구현을 개선하여 업데이트 후 DataStore의 데이터 흐름이 이전 값을 내보낼 수 있는 경합 상태를 방지합니다.

버전 1.1.0-alpha03

2023년 3월 24일

androidx.datastore:datastore-*:1.1.0-alpha03가 출시되었습니다.

버그 수정

• Kotlin 네이티브 타겟의 빌드 문제를 해결하기 위해 Maven 아티팩트에서 종속 항목 제약 조건을 삭제했습니다. (b/274786186, KT-57531)

버전 1.1.0-alpha02

2023년 3월 22일

androidx.datastore:datastore-*:1.1.0-alpha02가 출시되었습니다. 버전 1.1.0-alpha02에 포함된 커밋을 확인하세요.

참고

이 버전에는 단일 프로세스 및 다중 프로세스 DataStore 구현의 구현을 병합하는 중요한 내부 리팩터링이 포함되어 있습니다. 의도치 않은 동작 변경 (예: 업데이트 알림 시간)에 주의해 주세요. Issue Tracker 구성요소를 사용하여 이러한 변경사항을 보고할 수 있습니다.

새로운 기능

• 이제 KMM 프로젝트에서 DataStore를 사용할 수 있습니다. DataStore의 Android가 아닌 대상은 아직 실험 단계이지만 개발자가 더 쉽게 사용해 볼 수 있도록 버전을 병합하기로 결정했습니다.
• 멀티 프로세스 기능이 androidx.datastore.multiprocess에서 androidx.datastore.core로 이동했습니다.
• androidx.datastore.core.MultiProcessDataStoreFactory에 새 팩토리 메서드를 추가하여 파일 작업을 위한 Storage 객체로 Datastore 인스턴스를 만듭니다.
• 여러 DataStore 인스턴스가 프로세스 간에 통신할 수 있도록 도와주는 새 인터페이스 InterProcessCoordinator를 추가합니다. InterProcessCoordinator의 다중 프로세스 구현은 Android에서만 사용할 수 있습니다.

API 변경사항

• datastore-core 인터페이스의 StorageConnection에 InterProcessCoordinator를 추가했습니다. (I555bb)
• 저장소를 사용하도록 datastore-core MultiProcessDataStoreFactory의 API를 변경합니다. (Iac02f)
• datastore-multiprocess의 공개 API를 datastore-core로 이동했습니다. (I76d7c)
• datastore-preferences-core에서 PreferencesSerializer를 노출했습니다. (I4b788)
• @JvmDefaultWithCompatibility 주석을 추가합니다. (I8f206)

버전 1.1.0-alpha01

2022년 11월 9일

androidx.datastore:datastore-*:1.1.0-alpha01가 출시되었습니다. 버전 1.1.0-alpha01에 포함된 커밋을 확인하세요.

새로운 기능

• 프로세스 전반에서 DataStore 인스턴스 간에 데이터 일관성이 보장되는 다중 프로세스 사용 사례를 지원합니다. MultiProcessDataStoreFactory#create를 추가하여 이러한 DataStore 인스턴스를 만듭니다.
• Datastore의 기본 저장소 메커니즘을 전환할 수 있는 새로운 저장소 인터페이스입니다. java.io 및 okio의 구현이 제공됩니다. DataStore 팩토리에는 이 저장소 객체를 허용하는 새로운 메서드가 있습니다.

API 변경사항

• 저장소를 사용하도록 datastore-core MultiProcessDataStoreFactory의 API를 변경합니다. (Iac02f)
• datastore-multiprocess의 공개 API를 datastore-core로 이동했습니다. (I76d7c)
• datastore-preferences-core에서 PreferencesSerializer를 노출했습니다. (I4b788)

버전 1.0.0

버전 1.0.0

2021년 8월 4일

androidx.datastore:datastore-*:1.0.0가 출시되었습니다. 버전 1.0.0에 포함된 커밋을 확인하세요.

1.0.0의 주요 기능

Jetpack Datastore는 프로토콜 버퍼를 사용하여 키-값 쌍 또는 유형이 지정된 객체를 저장할 수 있는 데이터 저장소 솔루션입니다. Datastore는 Kotlin 코루틴 및 Flow를 사용하여 비동기적이고 일관된 트랜잭션 방식으로 데이터를 저장합니다.

버전 1.0.0-rc02

2021년 7월 21일

androidx.datastore:datastore-*:1.0.0-rc02가 출시되었습니다. 버전 1.0.0-rc02에 포함된 커밋을 확인하세요.

버그 수정

• 키가 없으면 SharedPreferencesMigration이 실행되지 않음을 명확히 했습니다. (Icfa32, b/192824325)
• 요청된 키가 아직 존재하지 않는 경우 MIGRATE_ALL_KEYS로 구성된 SharedPreferencesMigration에서 예외가 발생하는 버그를 수정했습니다. (Ie318a, b/192824325)

버전 1.0.0-rc01

2021년 6월 30일

androidx.datastore:datastore-*:1.0.0-rc01가 출시되었습니다. 버전 1.0.0-rc01에 포함된 커밋을 확인하세요.

버그 수정

• .java 파일이 실수로 최종 jar에 추가되는 버그를 수정했습니다. (I65d96, b/188985637)

버전 1.0.0-beta02

2021년 6월 16일

androidx.datastore:datastore-*:1.0.0-beta02가 출시되었습니다. 버전 1.0.0-beta02에 포함된 커밋을 확인하세요.

버그 수정

• ClassVerificationFailure를 수정했습니다. (b/187450483)

버전 1.0.0-beta01

2021년 4월 21일

androidx.datastore:datastore-*:1.0.0-beta01가 출시되었습니다. 버전 1.0.0-beta01에 포함된 커밋을 확인하세요.

API 변경사항

• kotlin 전용 메서드의 JVM 오버로드를 삭제합니다. (I2adc7)

버그 수정

• Datastore 위임으로 인해 컨텍스트가 누출될 수 있는 버그가 수정되었습니다. (Ie96fc, b/184415662)

버전 1.0.0-alpha08

2021년 3월 10일

androidx.datastore:datastore-*:1.0.0-alpha08가 출시되었습니다. 버전 1.0.0-alpha08에 포함된 커밋을 확인하세요.

API 변경사항

• 이제 컨텍스트에 따라 dataStore 및 preferencesDataStore 속성 위임에 이전을 추가할 수 있습니다. (I4ef69, b/173726702)
• 더 이상 Datastore 위임 또는 context.createDataStore를 사용하지 않는 경우 파일 이름을 가져오는 도우미 함수를 추가합니다. (I60f9a)
• 이제 Serializer writeTo 및 readFrom이 정지됩니다. Serializer를 구현한 경우 정지 함수가 되도록 함수를 업데이트해야 합니다. (I1e58e)
• RxDataStore 사용자를 위한 속성 위임을 추가했습니다. (Ied768, b/173726702)

버그 수정

• 실험용 API의 공개 사용에 제한을 적용합니다. (I6aa29, b/174531520)

버전 1.0.0-alpha07

2021년 2월 24일

androidx.datastore:datastore-*:1.0.0-alpha07가 출시되었습니다. 버전 1.0.0-alpha07에 포함된 커밋을 확인하세요.

API 변경사항

• Context.createDataStore 확장 함수를 삭제하고 globalDataStore 속성 위임으로 대체했습니다. kotlin 파일의 최상위 수준에서 globalDataStore를 한 번 호출합니다. 예:

  val Context.myDataStore by dataStore(...)
  

  kotlin 파일의 최상위 수준에 배치하면 이 인스턴스가 하나만 생깁니다. (I57215, b/173726702)

• RxDataStore 함수는 이제 DataStore의 확장 함수 대신 RxDataStore 클래스에 있습니다. (Idccdb, b/177691248)

• EncryptedSharedPreferences를 DataStore로 이전(또는 SharedPreferences를 직접 부팅)하려는 경우 이제 SharedPreferences를 삽입할 수 있는 새로운 SharedPreferencesMigration 생성자를 사용하면 됩니다. (I8e04e, b/177278510)

버그 수정

• 동일한 파일에 활성 DataStore가 여러 개 있는 경우 이제 DataStore에서 예외가 발생합니다. DataStore를 싱글톤으로 관리하지 않았거나 한 파일의 DataStore 인스턴스 두 개가 동시에 활성화되지 않도록 조치하지 않은 경우 이제 DataStore를 읽거나 DataStore에 쓸 때 예외가 발생할 수도 있습니다. DataStore를 싱글톤으로 관리하면 해결할 수 있습니다. (Ib43f4, b/177691248)
• 호출자 범위 취소 시의 취소 동작을 수정합니다. (I2c7b3)

버전 1.0.0-alpha06

2021년 1월 13일

androidx.datastore:datastore-*:1.0.0-alpha06이 출시되었습니다. 버전 1.0.0-alpha06에 포함된 커밋을 확인하세요.

새로운 기능

• DataStore용 RxJava 래퍼를 추가했습니다. datastore-rxjava2/3 아티팩트에는 핵심 DataStore API용 래퍼가 포함됩니다(RxDataStore, RxDataStoreBuilder, RxDataMigration). datastore-preferences-rxjava2/3 아티팩트에는 Preferences DataStore를 생성하는 빌더가 포함됩니다.

API 변경사항

• CorruptionHandler 인터페이스를 숨깁니다. DataStore 팩토리가 ReplaceFileCorruptionHandler만 허용하므로 인터페이스를 공개할 이유가 없기 때문입니다. (I0b3b3, b/176032264)
• preferencesKey<T>(name: String): Key<T> 메서드를 삭제하고 각 지원되는 유형과 관련된 메서드로 대체했습니다. 예를 들어, preferencesKey<Int>("int")는 이제 intPreferencesKey("int")입니다. (Ibcfac, b/170311106)

버그 수정

• 데이터 저장소 파일이 'datastore/' 하위 디렉터리에 생성되었다는 사실이 누락된 DataStoreFactory 관련 문서를 수정했습니다. (Ica222)

버전 1.0.0-alpha05

2020년 12월 2일

androidx.datastore:datastore-*:1.0.0-alpha05가 출시되었습니다. 버전 1.0.0-alpha05에 포함된 커밋을 확인하세요.

버그 수정

• Datastore의 동시 쓰기에 관해 더 적절한 문서 및 예외를 추가했습니다. (Ia98a2, b/173522155, b/173726702)
• 이제 Serializer.writeTo()에 전달된 OutputStream을 종료할 수 있습니다(필수는 아님). (I5c9bf, b/173037611)

버전 1.0.0-alpha04

2020년 11월 17일

androidx.datastore:datastore-*:1.0.0-alpha04가 출시되었습니다. 버전 1.0.0-alpha04에 포함된 커밋을 확인하세요.

버그 수정

• Preference Datastore 1.0.0-alpha03에서 다음과 같은 비정상 종료를 일으키는 패키징 문제가 수정되었습니다. java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences
  • 기존 비정상 종료는 여기에 보고했습니다. b/173036843
  • (I4712d, b/173036843)

버전 1.0.0-alpha03

2020년 11월 11일

androidx.datastore:datastore-*:1.0.0-alpha03가 출시되었습니다. 버전 1.0.0-alpha03에 포함된 커밋을 확인하세요.

주의: 대신 1.0.0-alpha04 버전을 사용하세요. 1.0.0-alpha03에서 Preference Datastore가 java.lang.NoClassDefFoundError와 함께 비정상 종료되는 심각한 문제가 발견되었습니다. (b/173036843)

새로운 기능

• 이제 Preferences에서 이중 값을 지원합니다(부동 소수점 수보다 더 높은 정밀도가 필요한 경우 유용함). (I5be8f, b/169471808)

API 변경사항

• 더 빠른 컴파일을 위해 Datastore용 순수 kotlin 종속 항목을 만들었습니다. androidx.datastore:datastore-core에는 Core Kotlin 전용 API가 있고, androidx.datastore:datastore에는 Android에 종속되는 API(SharedPreferencesMigration 및 Context.createDataStore 생성자 포함)가 있습니다. (I42d75, b/168512698)
• 더 빠른 kotlin 컴파일을 위해 Preferences DataStore의 타겟을 분리합니다. (Ia3c19)

• 이제 Serializer에서는 디스크에 데이터가 없는 경우 사용될 기본값의 새 속성이 필요합니다. 이에 따라, 맞춤 Serializer를 더 쉽게 구현할 수 있어 사용자는 빈 입력 스트림을 특별한 사례로 처리할 필요가 없습니다(빈 입력 스트림이 json으로 파싱되지 않음).

  • 이제 writeTo()에 제공된 출력 스트림이 닫히지 않았는지 확인하는 검사도 있습니다. 이 스트림이 닫혀 있는 경우 예외가 발생합니다. (I16e29)

• SharedPreferencesView 내부용 생성자를 만듭니다. 원래는 테스트를 위해 공개되었습니다. 대신 테스트는 SharedPreferencesMigration을 생성해야 하며 이를 테스트해야 합니다. (I93891)

버그 수정

• 이제 DataStoreFactory 및 PreferenceDataStoreFactory의 produceFile 매개변수가 목록의 마지막 매개변수이므로, kotlin 후행 람다 구문을 사용할 수 있습니다. (Ibe7f1, b/169425442)
• kotlin에 관한 새로운 명시적인 API 요구사항을 따릅니다. (I5ae1e)

알려진 문제

• Preference Datastore가 java.lang.NoClassDefFoundError와 충돌합니다. (b/173036843)

버전 1.0.0-alpha02

2020년 10월 14일

androidx.datastore:datastore-core:1.0.0-alpha02 및 androidx.datastore:datastore-preferences:1.0.0-alpha02가 출시되었습니다. 버전 1.0.0-alpha02에 포함된 커밋을 확인하세요.

버그 수정

• Datastore-core의 변형에 대비한 보호 장치를 추가했습니다. 변형은 non-proto/non-preferences 유형을 통해 Datastore를 사용하는 사용자의 Datastore 사용을 중단시킵니다. (I6aa84)
• 현재 상태를 쉽게 디버깅할 수 있도록 Preferences.kt에 toString 메서드를 추가했습니다. (I96006)
• DataStore.Preferences의 오용을 방지하기 위한 예외가 추가되었습니다. (I1134d)
• 시작 시 앱의 비정상 종료를 유발하는 버그를 수정했습니다. (I69237, b/168580258)

버전 1.0.0-alpha01

2020년 9월 2일

androidx.datastore:datastore-core:1.0.0-alpha01 및 androidx.datastore:datastore-preferences:1.0.0-alpha01가 출시되었습니다. 버전 1.0.0-alpha01에 포함된 커밋을 확인하세요.

새로운 기능

Jetpack DataStore는 SharedPreferences를 대체하는 개선된 신규 데이터 저장소 솔루션입니다. Kotlin 코루틴과 Flow를 기반으로 한 DataStore는 다음과 같은 두 가지 구현을 제공합니다.

• Proto DataStore: 유형이 지정된 객체(프로토콜 버퍼로 지원됨)를 저장할 수 있습니다.
• Preferences DataStore: 키-값 쌍을 저장합니다.

비동기적이고 일관된 트랜잭션 방식으로 데이터를 저장하여 SharedPreferences의 단점을 대부분 극복합니다.