Realm 객체 스키마 업데이트 - Flutter SDK
Realm 객체를 처음 만든 후에 해당 객체의 스키마를 변경할 수 있습니다. 스키마 변경 유형에 따라 변경 사항이 자동으로 적용되거나 새 스키마를 수동으로 업데이트해야 할 수 있습니다. 수동 스키마 업데이트는 Realm에서 마이그레이션이라고 합니다.
Realm 객체 모델에서 속성 을 추가하거나 삭제 때 Realm 객체 스키마 를 자동으로 업데이트 할 수 있습니다. 자세한 내용은 스키마 자동 업데이트 섹션을 참조하세요.
다른 모든 스키마 변경 사항에 대해서는 수동 마이그레이션을 수행해야 합니다. 자세한 내용은 스키마 수동 마이그레이션 섹션을 참조하세요.
팁
개발 중 마이그레이션 우회
애플리케이션 을 개발하거나 디버깅할 때 영역 을 마이그레이션하는 대신 삭제 하는 것이 나을 수 있습니다.LocalConfiguration.shouldDeleteIfMigrationNeeded 스키마 불일치로 인해 마이그레이션 이 필요한 경우 데이터베이스 를 자동으로 삭제 하는 속성 입니다.
중요
동기화된 Realm의 스키마 속성 수정
이 페이지의 내용은 로컬 영역에만 적용 됩니다. 스키마 마이그레이션 은 Atlas Device Sync 를 사용하여 데이터를 MongoDB Atlas 와 동기화하는 Realm 에서 다르게 작동합니다. 동기화된 Realm 의 스키마 업데이트하기 섹션을 참조하세요.
스키마 버전
스키마 버전은 특정 시점의 영역 스키마 상태를 식별합니다. Realm은 각 영역의 스키마 버전을 추적하고 이를 사용하여 각 영역의 객체를 올바른 스키마에 매핑합니다.
스키마 버전은 영역을 열 때 영역 구성에 선택적으로 포함할 수 있는 오름차순 정수입니다. 클라이언트 애플리케이션이 영역을 열 때 버전 번호를 지정하지 않으면 영역은 버전에 기본값인 0을 사용합니다.
수동 마이그레이션의 경우, 영역을 상위 스키마 버전으로 업데이트해야 합니다. 클라이언트 애플리케이션이 영역의 현재 버전보다 낮은 스키마 버전의 영역을 열거나 지정된 스키마 버전이 영역의 현재 버전과 동일하지만 다른 객체 스키마를 포함하는 경우 영역에서 오류가 발생합니다.
스키마 자동 업데이트
Realm은 추가 및 삭제된 속성을 자동으로 마이그레이션할 수 있습니다. 이러한 변경을 수행할 때 스키마 버전을 업데이트해야 합니다.
속성 추가
스키마에 속성을 추가하려면 다음과 같이 하세요:
객체의
RealmModel클래스에 새 속성을 추가합니다.
예시
스키마 버전 1을 사용하는 영역에는 firstName 및 lastName 속성을 가진 Person 객체 유형이 있습니다. 개발자가 age 속성을 _Person RealmModel 클래스에 추가합니다.
업데이트된 Person 스키마 를 준수하도록 영역 을 변경하려면 개발자 는 Realm의 스키마 버전 을 2 로 설정합니다.
() class _Person { late String firstName; late String lastName; late int age; }
final config = Configuration.local([Person.schema], schemaVersion: 2); final realm = Realm(config);
속성 삭제
스키마에서 속성을 삭제하려면 다음과 같이 하세요:
객체의
RealmModel클래스에서 속성을 제거합니다.영역 구성에 다시 생성된
RealmObject.schema를 포함하고schemaVersion을 상향합니다.
속성을 삭제해도 기존 객체에는 영향을 미치지 않습니다.
예시
스키마 버전 1을 사용하는 영역에 weight 속성을 가진 Person 객체 유형이 있습니다. 개발자는 스키마에서 속성을 제거하기로 결정합니다.
업데이트된 Person 스키마를 준수하도록 Realm을 마이그레이션하려면 개발자는 Realm의 스키마 버전 을 2 로 설정합니다.
final config = Configuration.local([Person.schema], schemaVersion: 2); final realm = Realm(config);
스키마 수동 마이그레이션
더 복잡한 스키마 업데이트의 경우, Realm에서는 지정된 객체의 이전 인스턴스를 새 스키마로 수동으로 마이그레이션해야 합니다.
업데이트된 스키마로 영역을 열 때 영역의 Configuration에서 다음을 수행해야 합니다.
schemaVersion속성을 상향합니다.migrationCallback에서 마이그레이션 로직을 정의합니다. Realm 구성 의 속성 . 마이그레이션 콜백에는 다음과 같은 매개 변수가 있습니다.
migration: 현재 영역, 마이그레이션하려는 영역 및 마이그레이션 작업에 도움이 되는 메서드에 액세스할 수 있는 마이그레이션 인스턴스입니다.oldSchemaVersion: 기기 내 영역의 이전 스키마 버전 번호입니다.
다음 섹션에서는 다양한 마이그레이션 작업을 수행하는 방법에 대해 설명합니다.
객체 유형 삭제
영역에서 특정 유형의 모든 객체를 삭제하려면 string 객체 스키마 이름의 표현을 Migration.deleteType()에 전달합니다.
이전 버전의 스키마에는 Realm 객체 유형이 있지만 새 버전의 스키마에는 없는 경우에 유용합니다.
final configWithoutPerson = Configuration.local([Car.schema], schemaVersion: 2, migrationCallback: ((migration, oldSchemaVersion) { // Between v1 and v2 we removed the Person type migration.deleteType('Person'); })); final realmWithoutPerson = Realm(configWithoutPerson);
속성 이름 바꾸기
Migration.renameProperty()를 사용하여 스키마속성의 이름을 변경합니다.
final configWithRenamedAge = Configuration.local([Person.schema, Car.schema], schemaVersion: 2, migrationCallback: ((migration, oldSchemaVersion) { // Between v1 and v2 we renamed the Person 'age' property to 'yearsSinceBirth' migration.renameProperty('Person', 'age', 'yearsSinceBirth'); })); final realmWithRenamedAge = Realm(configWithRenamedAge);
기타 마이그레이션 작업
다른 영역 스키마 마이그레이션을 수행하려면 마이그레이션 콜백 함수에서 Migration 객체의 다음 속성을 사용합니다.
Migration.oldRealm: 이전 스키마 버전으로 마이그레이션하기 직전에 존재했던 영역입니다. 표준 유형 기반 쿼리를 사용할 수 없으므로 해당 객체에 액세스하려면
oldRealm의 동적 API를 사용해야 합니다. 동적 사용하면 클래스 API Realm string 이름의 표현으로 객체를 찾을 수 있습니다.Migration.newRealm: 마이그레이션 후에도 존재하는 영역입니다. 마이그레이션 콜백이 끝날 무렵에는 스키마 업데이트의 영향을 받는 모든 데이터를
oldRealm에서newRealm로 마이그레이션해야 합니다. 스키마 업데이트의 영향을 받지만 마이그레이션되지 않은 모든 데이터는 손실됩니다.
새 영역에서 이전 영역에 있는 객체의 인스턴스를 찾으려면 Migration.findInNewRealm()을 사용합니다. 이전 스키마에서 객체의 속성에 액세스하려면 RealmObjectBase.dynamic API를 사용합니다.
final configWithChanges = Configuration.local([Person.schema, Car.schema], schemaVersion: 2, migrationCallback: ((migration, oldSchemaVersion) { // Dynamic query for all Persons in previous schema final oldPeople = migration.oldRealm.all('Person'); for (final oldPerson in oldPeople) { // Find Person instance in the updated realm final newPerson = migration.findInNewRealm<Person>(oldPerson); if (newPerson == null) { // That person must have been deleted, so nothing to do. continue; } // Use dynamic API to get properties from old schema and use in the // new schema newPerson.fullName = "${oldPerson.dynamic.get<String>("firstName")} ${oldPerson.dynamic.get<String>("lastName")}"; // convert `id` from ObjectId to String final oldId = oldPerson.dynamic.get<ObjectId>("id"); newPerson.id = oldId.toString(); } })); final realmWithChanges = Realm(configWithChanges);
동기화된 Realm의 스키마 업데이트
동기화된 영역의 스키마 업데이트는 로컬 전용 영역의 스키마 업데이트와 별도의 프로세스로 진행됩니다.
동기화된 영역에는 스키마 버전이 없으며 객체를 최신 스키마로 자동으로 마이그레이션합니다. 동기화된 영역은 깨지지 않는 스키마 변경만 지원합니다.