Realm 구성 및 열기 - Kotlin SDK
이 페이지의 내용
이 페이지에서는 Realm 파일과 데이터를 로컬에서만 유지하는 Realm을 구성하고 열고 닫는 방법에 대해 설명합니다. Device Sync를 사용하여 Atlas와 데이터를 동기화하는 Realm을 열려면 동기화된 Realm 열기를 참조하세요.
영역 은 Realm 에서 데이터를 구성하는 데 사용되는 핵심 데이터 구조입니다. 각 영역 은 Realm 객체의 컬렉션 으로, 애플리케이션 에서 사용하는 객체와 해당 객체를 설명하는 추가 메타데이터 입니다. 각 Realm 객체 유형 에는 정의된 객체 모델을 기반으로 하는 객체 스키마 가 있습니다.
영역 스키마 는 영역에 포함될 수 있는 유효한 객체 스키마 목록입니다. Realm을 열 때 스키마를 지정합니다. Realm을 열 때 Realm에 이미 데이터가 포함되어 있는 경우 Realm은 각 객체의 유효성을 검사하여 해당 유형에 대한 객체 스키마가 제공되었는지, 스키마에 지정된 모든 제약 조건을 충족하는지 확인합니다.
Realm 파일
Realm은 영역의 모든 객체와 유형의 바이너리 인코딩 버전을 단일 .realm
파일에 저장합니다. Realm을 열 때 .realm
파일이 아직 존재하지 않으면 Realm이 이를 생성합니다. 파일은 영역을 열 때 정의할 수 있는 특정 경로에 있습니다.
.realm
파일 또는 관련 보조 파일을 생성하지 않으려면 인메모리 영역 을 열 수 있습니다. 자세한 내용은 인메모리 Realm 열기 섹션을 참조하세요.
보조 파일
Realm은 각 Realm에 대해 추가 파일을 생성합니다.
'realm' 접미사가 붙은 영역 파일(예:
default.realm
: 객체 데이터를 포함합니다.잠금 파일, "lock" 접미사(예:
default.realm.lock
: Realm에서 활발하게 사용 중인 데이터 버전을 추적합니다. 이렇게 하면 Realm이 클라이언트 애플리케이션에서 아직 사용 중인 저장 공간을 회수할 수 없습니다.메모 파일, 접미사 '메모'(예:
default.realm.note
: 스레드 간 및 프로세스 간 알림을 활성화합니다.관리 파일, 접미사 "관리"(예:
default.realm.management
: 내부 상태 관리입니다.
이러한 파일을 삭제하는 것은 중요한 의미를 갖습니다. .realm
또는 보조 파일 삭제에 대한 자세한 내용은 Realm 삭제를 참조하세요.
Realm 열기
Realm을 열려면 Realm의 세부 정보를 정의하는 RealmConfiguration 객체를 생성하세요. 그런 다음 결과 RealmConfiguration
을 Realm.open()에 전달합니다.
기본 구성 값으로 영역을 열거나 추가 구성 옵션으로 RealmConfiguration
를 빌드할 수 있습니다. 그러나 영역에서 사용하려는 모든 객체 클래스 를 포함하는 스키마 매개 변수를 전달 해야 합니다 .
원하는 구성으로 영역 을 연 후에는 정의된 스키마 를 기반으로 데이터를 읽고 쓰기 (write) 수 있습니다.
이 페이지의 예제는 다음 Realm 객체를 참조합니다.
class Frog : RealmObject { var _id: ObjectId = ObjectId() var name: String = "" } class Person : RealmObject { var _id: ObjectId = ObjectId() var name: String = "" }
기본 Realm 열기
기본값 구성 값으로 Realm을 열려면 영역 () 를 사용합니다. 메서드. 객체 클래스 설정하다 을 영역 스키마 로 정의하기만 하면 됩니다. 그런 다음 RealmConfiguration
을 Realm.open()에 전달합니다.
다음 예시 에서는 Frog
및 Person
클래스를 포함하는 스키마 로 기본값 경로에서 default.realm
파일 을 엽니다.
// Creates a realm with default configuration values val config = RealmConfiguration.create( // Pass object classes for the realm schema schema = setOf(Frog::class, Person::class) ) // Open the realm with the configuration object val realm = Realm.open(config) Log.v("Successfully opened realm: ${realm.configuration.name}") // ... use the open realm ...
기본 파일 위치
영역 파일 에 대한 디렉토리 를 정의하지 않으면 플랫폼의 기본값 앱 저장 위치 가 사용됩니다. 다음에서 플랫폼의 기본값 디렉토리 를 찾을 수 있습니다.
Android:
Context.getFiles()
JVM:
System.getProperty("user.dir")
macOS:
platform.Foundation.NSFileManager.defaultManager.currentDirectoryPath
iOS:
NSFileManager.defaultManager.URLForDirectory( NSDocumentDirectory, NSUserDomainMask, null, true, null )
In-Memory Realm 열기
.realm
파일 이나 관련 보조 파일을 생성하지 않는 메모리에서 영역 을 완전히 열 수 있습니다. 대신 SDK는 영역 이 열려 있는 동안 메모리에 객체를 저장한 다음 모든 인스턴스가 닫히면 데이터를 삭제합니다.
파일에 기록되지 않고 실행되는 Realm을 열려면 RealmConfiguration.Builder 에서 inMemory 속성을 사용하여 RealmConfiguration
를 빌드합니다. 그런 다음 결과 RealmConfiguration
을 Realm.open()에 전달합니다.
// Create the in-memory realm configuration val config = RealmConfiguration.Builder( schema = setOf(Frog::class, Person::class) ) .inMemory() .build() // Open the realm with the configuration object val realm = Realm.open(config) Log.v("Successfully opened an in-memory realm") // ... use the open realm ...
참고
인메모리 Realm이 지속되지 않음
인메모리 Realm은 지속되지 않으므로 데이터에 액세스하려면 Realm의 열린 인스턴스가 하나 이상 있어야 합니다. 인메모리 Realm의 마지막 인스턴스를 닫은 후에는 데이터를 더 이상 사용할 수 없습니다.
Realm 구성 사용자 지정
다음을 포함하여 열려는 영역 의 세부 사항을 제어하기 위해 RealmConfiguration
에 선택적 인수를 추가할 수 있습니다.
사용자 지정 파일 이름 및 파일 경로 정의
Realm 암호화를 위한 암호화 키 전달
영역 을 압축하여 파일 크기 줄이기
스키마 변경시 스키마 버전 또는 마이그레이션 차단 지정
마이그레이션 이 필요한 경우 Realm에서 Realm 영역 파일 삭제 할지 여부에 플래그 지정
특정 구성 구현에 대한 자세한 내용은 Realm 파일 관리 - 코틀린 SDK (Kotlin SDK) 를 참조하세요.
기본값이 아닌 값으로 Realm을 구성하려면 RealmConfiguration
() 설정하려는 속성을 전달합니다. 그런 다음 결과 RealmConfiguration
를 Realm.open()에 전달합니다.
다음 예제에서 RealmConfiguration
는 사용자 지정 이름과 디렉토리("my-directory-path/myRealmName.realm") 및 암호화 키를 지정합니다.
// Create a realm configuration with configuration builder // and pass all optional arguments val config = RealmConfiguration.Builder( schema = setOf(Frog::class, Person::class) ) .name("myRealmName.realm") .directory("my-directory-path") .encryptionKey(myEncryptionKey) .build() // Open the realm with the configuration object val realm = Realm.open(config) Log.v("Successfully opened realm: ${realm.configuration.name}") // ... use the open realm ...
Realm에 초기 데이터 추가
initialDataCallback 을 사용하여 영역 에 초기 데이터를 추가할 수 있습니다. 콜백 은 영역 이 처음 열릴 때 트리거됩니다.
val config = RealmConfiguration.Builder( schema = setOf(Frog::class, Person::class) ) .initialData { copyToRealm(Frog().apply { name = "Kermit" }) copyToRealm(Person().apply { name = "Jim Henson" }) } .build() val realm = Realm.open(config) Log.v("Successfully opened realm: ${realm.configuration.name}") // Opened realm includes the initial data val initialFrog = realm.query<Frog>().find().first() val initialPerson = realm.query<Person>().find().first() Log.v("Realm initialized with: ${initialFrog.name} and ${initialPerson.name}")
Realm 파일 경로 찾기
.realm
파일의 파일 경로를 찾으려면 realm.configuration.path 속성을 사용합니다.
val realmPath = realm.configuration.path Log.v("Realm path: $realmPath")
Realm 닫기
realm.close() 를 사용하여 영역을 닫습니다. 이 메서드는 영역의 모든 쓰기 트랜잭션(write transaction)이 완료될 때까지 차단합니다.
realm.close()
경고
메모리 누수를 방지하기 위해 Realm을 닫습니다.
리소스를 확보하려면 Realm 인스턴스를 종료하는 것이 중요합니다. Realm을 닫지 못하면 OutOfMemoryError
이(가) 발생할 수 있습니다.
새 Realm으로 데이터 복사
기존 Realm에서 다른 구성 옵션이 있는 새 영역 으로 데이터를 복사하려면 새 구성을 Realm .writeCopyTo( ) 메서드. 예를 예시 , 로컬 영역 을 백업 하거나 동기화된 영역 을 로컬 영역 으로 변환하기 위한 방법으로 데이터를 복사할 수 있습니다.
동일한 구성을 사용하는 영역에 데이터를 복사할 수 있습니다.
로컬 Realm에서 로컬 Realm으로
인메모리 영역에서 인메모리 영역으로
동기화된 Realm에서 동기화된 Realm으로
다양한 동기화 구성을 사용하는 영역에 데이터를 복사할 수 있습니다.
로컬 영역 에서 파티션 기반 동기화 영역 으로
영역과 로컬 영역 동기화
다른 사용자의 동기화된 Realm에서 동기화된 Realm으로
경고
로컬 Realm에서 Flexible Sync Realm으로 데이터를 복사 할 수 없습니다 . 파티션 기반 동기화에서 Flexible Sync로 등 서로 다른 동기화 구성 유형 간에는 복사할 수 없습니다.
구성 변경 사항을 결합할 수도 있습니다. 예를 예시 암호화되지 않은 인메모리 동기화 영역 에서 암호화됨 로컬 영역 으로 데이터를 복사할 수 있습니다.
Realm.writeCopyTo()
사용하는 동안 염두에 두어야 할 몇 가지 추가 고려사항은 다음과 같습니다.
대상 파일이 이미 존재할 수 없습니다.
쓰기 트랜잭션(write transaction) 내에서 또는 마이그레이션 중에는 영역 복사가 허용되지 않습니다.
Device Sync 를 사용하는 경우 사본을 쓰기 전에 모든 로컬 변경 사항을 서버 와 동기화 해야 합니다. 이렇게 하면 파일 을 새로 설치된 애플리케이션 의 점 으로 사용할 수 있습니다. 보류 중인 업로드가 있는 경우 Realm 에서 오류가 발생합니다.
uploadAllLocalChanges() 및 downloadAllServerChanges() 를 사용하여 모든 동기화 프로세스가 완료되었는지 확인할 수 있습니다.
예시
Flexible Sync Realm 에서 로컬 Realm 으로 데이터 복사
// Instantiate the synced realm with your App ID val app = App.create(YOUR_APP_ID) runBlocking { val user = app.login(credentials) // Create the synced realm configuration val syncConfig = SyncConfiguration.Builder(user, setOf(Frog::class)) .initialSubscriptions { realm -> add(realm.query<Frog>(),"all-frogs") } .build() // Open the synced realm and add data to it val syncRealm = Realm.open(syncConfig) Log.v("Successfully opened realm: ${syncRealm.configuration.name}") syncRealm.write { this.copyToRealm(Frog().apply { name = "Kermit" }) } // Wait for write to sync syncRealm.syncSession.uploadAllLocalChanges(30.seconds) // Create the local realm val localConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("local.realm") .build() // Copy data from synced realm to the new realm syncRealm.writeCopyTo(localConfig) // Close the synced realm when you're done copying syncRealm.close() // Open the new local realm val localRealm = Realm.open(localConfig) // Copied Frog object is available in the new realm val frog = localRealm.query<Frog>().find().first() Log.v("Copied Frog: ${frog.name}") localRealm.close() }
복사된 영역의 구성에 새 암호화 키를 포함하거나 새 구성에서 암호화 키를 제거할 수도 있습니다.
예시
암호화되지 않은 Realm에서 암호화된 Realm으로 데이터 복사
runBlocking { // Create the unencrypted realm val unencryptedConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("unencrypted.realm") .build() // Open the realm and add data to it val unencryptedRealm = Realm.open(unencryptedConfig) unencryptedRealm.write { this.copyToRealm(Frog().apply { name = "Kermit" }) } // ... Generate encryption key ... // Create the encrypted realm val encryptedConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("encrypted.realm") .encryptionKey(encryptionKey) .build() // Copy data from `unencryptedRealm` to the new realm // Data is encrypted as part of the copy process unencryptedRealm.writeCopyTo(encryptedConfig) // Close the original realm when you're done copying unencryptedRealm.close() // Open the new encrypted realm val encryptedRealm = Realm.open(encryptedConfig) // Copied Frog object is available in the new realm val frog = encryptedRealm.query<Frog>().find().first() Log.v("Copied Frog: ${frog.name}") encryptedRealm.close() }
예시
인메모리에서 로컬 Realm 으로 데이터 복사
runBlocking { // Create the in-memory realm val inMemoryConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("inMemory.realm") .inMemory() .build() // Open the realm and add data to it val inMemoryRealm = Realm.open(inMemoryConfig) inMemoryRealm.write { this.copyToRealm(Frog().apply { name = "Kermit" }) } // Create the local realm val localConfig = RealmConfiguration.Builder(setOf(Frog::class)) .name("local.realm") .build() // Copy data from `inMemoryRealm` to the new realm inMemoryRealm.writeCopyTo(localConfig) // Close the original realm when you're done copying inMemoryRealm.close() // Open the new local realm val localRealm = Realm.open(localConfig) // Copied Frog object is available in the new realm val frog = localRealm.query<Frog>().find().first() Log.v("Copied Frog: ${frog.name}") localRealm.close() }