객체 모델 변경 - React Native SDK

이 페이지의 내용

스키마 버전

마이그레이션
속성 추가
속성 삭제
속성 이름 바꾸기
속성 유형 수정

Atlas Device SDK는 더 이상 사용되지 않습니다. 자세한 내용은 지원 중단 페이지 를 참조하세요.

참고

동기화된 Realm의 스키마 속성 수정

다음 페이지에서는 로컬 영역 의 스키마 속성을 수정하는 방법을 설명합니다. 동기화된 영역 의 스키마 속성을 수정하는 방법을 알아보세요.

객체 스키마를 업데이트할 때 스키마의 버전을 높이고 마이그레이션을 수행해야 합니다.

스키마 업데이트가 선택적 속성을 추가하거나 제거하면 Realm은 자동으로 마이그레이션을 수행할 수 있습니다. schemaVersion만 증분하면 됩니다.

좀 더 복잡한 스키마 업데이트는 migration 함수에서 마이그레이션 논리를 수동으로 지정해야 합니다. 여기에는 다음과 같은 변경 사항이 포함될 수 있습니다.

기본값으로 채워야 하는 필수 속성 추가
필드 결합
필드 이름 바꾸기
필드 유형 변경
객체에서 내장된 객체로 변환

팁

개발 중 마이그레이션 우회

애플리케이션을 개발하거나 디버깅할 때 Realm을 마이그레이션하는 대신 삭제하는 것이 나을 수 있습니다. BaseConfiguration.deleteRealmIfMigrationNeeded 속성을 사용하여 스키마 불일치가 마이그레이션을 수행해야 할 때 데이터베이스를 자동으로 삭제합니다.

이 속성을 true으로 설정한 상태에서는 앱을 프로덕션 환경에 릴리즈하지 마세요.

스키마 버전

스키마 버전은 특정 시점의 영역 스키마 상태를 식별합니다. Realm은 각 영역의 스키마 버전을 추적하고 이를 사용하여 각 영역의 객체를 올바른 스키마에 매핑합니다.

스키마 버전은 영역 구성에 포함할 수 있는 오름차순 정수입니다. 클라이언트 애플리케이션에 버전 번호를 지정하지 않으면 영역의 버전은 0가 기본값입니다.

중요

단조적 버전 증가

마이그레이션 영역을 상위 스키마 버전으로 업데이트해야 합니다. 클라이언트 애플리케이션이 영역의 현재 버전보다 낮은 스키마 버전을 사용하거나 지정된 스키마 버전이 영역의 현재 버전과 동일하지만 다른 스키마를 포함하는 경우 영역에서 오류가 발생합니다.

마이그레이션

마이그레이션 은 Realm과 Realm에 포함된 모든 객체를 한 스키마 버전 에서 최신 버전으로 업데이트하는 기능입니다. 마이그레이션을 사용하면 시간이 지남에 따라 객체 스키마를 변경하여 새로운 기능과 리팩터링을 수용할 수 있습니다.

영역의 현재 버전보다 큰 스키마 버전으로 구성을 생성하면 Realm은 사용자가 정의한 마이그레이션 기능을 실행합니다. 함수는 영역의 버전 번호에 액세스할 수 있으며 새 스키마에 맞게 영역의 객체를 점진적으로 업데이트합니다.

Realm은 새 속성 및 삭제된 속성과 같은 특정 변경 사항을 자동으로 마이그레이션하지만 업데이트된 객체 스키마에서 기본값을 지정하지 않는 한 새 속성에 대한 값을 자동으로 설정하지 않습니다. 마이그레이션 기능에서 추가 논리를 정의하여 속성 값을 추가로 사용자 정의할 수 있습니다.

속성 추가

스키마에 속성을 추가하려면 객체의 클래스에 새 속성을 추가하고 Configuration 객체의 schemaVersion를 설정합니다.

예시

스키마 버전 0(기본값)을 사용하는 Realm에는 firstName 및 lastName 속성이 있는 Person 객체 유형이 있습니다. Person 클래스에 age 속성을 추가하기로 결정했습니다.

업데이트된 Person 스키마를 준수하도록 영역을 마이그레이션하려면 Configuration에서 영역의 스키마 버전을 1로 설정하세요. 마지막으로 구성 객체를 createRealmContext() 메서드에 전달합니다.

class Person extends Realm.Object {
  static schema = {
    name: 'Person',
    properties: {
      _id: 'string',
      firstName: 'string',
      lastName: 'string',
      // add a new property, 'age' to the schema
      age: 'int',
    },
  };
}
const config = {
  schema: [Person],
  // Increment the 'schemaVersion', since 'age' has been added to the schema.
  // The initial schemaVersion is 0.
  schemaVersion: 2,
};
// pass the configuration object with the updated 'schemaVersion' to
// createRealmContext()
const {RealmProvider} = createRealmContext(config);

class Person extends Realm.Object<Person> {
  _id!: string;
  firstName!: string;
  lastName!: string;
  age!: number;
  static schema: ObjectSchema = {
    name: 'Person',
    properties: {
      _id: 'string',
      firstName: 'string',
      lastName: 'string',
      // add a new property, 'age' to the schema
      age: 'int',
    },
  };
}
const config: Realm.Configuration = {
  schema: [Person],
  // Increment the 'schemaVersion', since 'age' has been added to the schema.
  // The initial schemaVersion is 0.
  schemaVersion: 2,
};
// pass the configuration object with the updated 'schemaVersion' to
// createRealmContext()
const {RealmProvider} = createRealmContext(config);

속성 삭제

스키마에서 속성을 삭제하려면 객체의 클래스에서 속성을 제거하고 구성 객체의 schemaVersion을 설정합니다. 속성을 삭제해도 기존 객체에는 영향을 미치지 않습니다.

예시

스키마 버전 0( 기본값 )을 사용하는 영역 에는 lastName 속성 을 가진 Person 객체 유형이 있습니다. 스키마 에서 속성 을 제거 하기로 결정합니다.

업데이트된 Person 스키마를 준수하도록 영역을 마이그레이션하려면 Configuration 객체에서 영역의 스키마 버전을 1로 설정하세요. 마지막으로 구성 객체를 createRealmContext() 메서드에 전달합니다.

class Person extends Realm.Object {
  static schema = {
    name: 'Person',
    properties: {
      _id: 'string',
      firstName: 'string',
      age: 'int',
    },
  };
}
const config = {
  schema: [Person],
  // Increment the 'schemaVersion', since 'lastName' has been removed from the schema.
  // The initial schemaVersion is 0.
  schemaVersion: 1,
};
// pass the configuration object with the updated 'schemaVersion' to createRealmContext()
const {RealmProvider} = createRealmContext(config);

class Person extends Realm.Object<Person> {
  _id!: string;
  firstName!: string;
  age!: number;
  static schema: ObjectSchema = {
    name: 'Person',
    properties: {
      _id: 'string',
      firstName: 'string',
      age: 'int',
    },
  };
}
const config: Realm.Configuration = {
  schema: [Person],
  // Increment the 'schemaVersion', since 'lastName' has been removed from the schema.
  // The initial schemaVersion is 0.
  schemaVersion: 1,
};
// pass the configuration object with the updated 'schemaVersion' to createRealmContext()
const {RealmProvider} = createRealmContext(config);

속성 이름 바꾸기

객체 속성의 이름을 변경하려면 객체 스키마에서 속성 이름을 변경한 다음 증가된 스키마 버전과 기존 객체가 새 속성 이름을 사용하도록 업데이트하는 마이그레이션 함수를 사용하여 영역 구성을 만드세요.

마이그레이션을 통해서는 속성의 이름을 직접 변경할 수 없습니다. 대신 업데이트된 이름으로 새 속성을 생성하고 이전 속성의 값을 복사한 다음 이전 속성을 삭제할 수 있습니다.

예시

스키마 버전 0(기본값)을 사용하는 Realm의 객체 유형은 Person 입니다. 원래 스키마에는 firstName 및 lastName 필드가 있었습니다. 나중에 Person 클래스가 결합된 fullName 필드를 사용해야 한다고 결정하고 별도의 firstName 및 lastName 필드를 제거합니다.

업데이트된 Person 스키마를 준수하도록 Realm을 마이그레이션하려면 구성 객체를 만들고 Realm의 스키마 버전을 1 로 설정한 다음 기존 firstName 를 기반으로 fullName 값을 설정하는 마이그레이션 함수를 정의하고 lastName 속성. 마지막으로 구성 객체를 createRealmContext() 메서드에 전달합니다.

class Person extends Realm.Object {
  static schema = {
    name: 'Person',
    properties: {
      _id: 'string',
      // rename the 'firstName' and 'lastName' property, to 'fullName'
      // in the schema
      fullName: 'string',
      age: 'int',
    },
  };
}
const config = {
  schema: [Person],
  // Increment the 'schemaVersion', since 'fullName' has replaced
  // 'firstName' and 'lastName' in the schema.
  // The initial schemaVersion is 0.
  schemaVersion: 1,
  onMigration: (oldRealm, newRealm) => {
    // only apply this change if upgrading schemaVersion
    if (oldRealm.schemaVersion < 1) {
      const oldObjects = oldRealm.objects(Person);
      const newObjects = newRealm.objects(Person);
      // loop through all objects and set the fullName property in the
      // new schema
      for (const objectIndex in oldObjects) {
        const oldObject = oldObjects[objectIndex];
        const newObject = newObjects[objectIndex];
        newObject.fullName = `${oldObject.firstName} ${oldObject.lastName}`;
      }
    }
  },
};
// pass the configuration object with the updated 'schemaVersion' and
// 'migration' function to createRealmContext()
const {RealmProvider} = createRealmContext(config);

class Person extends Realm.Object<Person> {
  _id!: string;
  fullName!: string;
  age!: number;
  static schema: ObjectSchema = {
    name: 'Person',
    properties: {
      _id: 'string',
      // rename the 'firstName' and 'lastName' property, to 'fullName'
      // in the schema
      fullName: 'string',
      age: 'int',
    },
  };
}
class OldObjectModel extends Realm.Object<OldObjectModel> {
  _id!: string;
  firstName!: string;
  lastName!: string;
  age!: number;
  static schema: ObjectSchema = {
    name: 'Person',
    properties: {
      _id: 'string',
      firstName: 'string',
      lastName: 'string',
    },
  };
}
const config: Realm.Configuration = {
  schema: [Person],
  // Increment the 'schemaVersion', since 'fullName' has replaced
  // 'firstName' and 'lastName' in the schema.
  // The initial schemaVersion is 0.
  schemaVersion: 1,
  onMigration: (oldRealm: Realm, newRealm: Realm) => {
    // only apply this change if upgrading schemaVersion
    if (oldRealm.schemaVersion < 1) {
      const oldObjects: Realm.Results<OldObjectModel> =
        oldRealm.objects(OldObjectModel);
      const newObjects: Realm.Results<Person> = newRealm.objects(Person);
      // loop through all objects and set the fullName property in the
      // new schema
      for (const objectIndex in oldObjects) {
        const oldObject = oldObjects[objectIndex];
        const newObject = newObjects[objectIndex];
        newObject.fullName = `${oldObject.firstName} ${oldObject.lastName}`;
      }
    }
  },
};
// pass the configuration object with the updated 'schemaVersion' and
// 'migration' function to createRealmContext()
const {RealmProvider} = createRealmContext(config);

중요

동기화된 Realms

동기화된 영역은 이전 클라이언트가 최신 클라이언트와 동기화할 수 있도록 호환성을 깨뜨리지 않는(non-breaking) 변경 사항(추가 변경 고도 사항이라고)만 지원합니다. 전체 이름을 바꾸려면 이전 속성을 삭제해야 하므로 클라이언트 재설정 없이는 동기화된 속성의 이름을 바꿀 수 없습니다. 이전 속성을 삭제하지 않고 이름을 바꾼 속성을 추가하는 것이 좋습니다. 아니면 mapTo를 사용하면 기존의 내부 이름을 사용하여 데이터를 저장하되 코드에서 다른 이름을 사용하도록 할 수 있습니다.

속성 유형 수정

속성 유형을 수정하려면 수정하려는 필드의 속성 유형을 새 데이터 유형으로 설정하세요. 그런 다음 구성 객체의 schemaVersion 및 migration 콜백 함수를 설정합니다.

참고

동기화된 영역은 이전 클라이언트가 최신 클라이언트와 동기화할 수 있도록 호환성이 손상되지 않는 변경 사항만 지원합니다. 동기화된 영역은 스키마 속성 유형 수정을 지원하지 않는다는 의미입니다.

예시

스키마 버전 0(기본값)을 사용하는 Realm의 객체 유형은 Person 입니다. 원래 스키마에는 속성 유형이 int 인 _id 이(가) 있었습니다. 나중에 Person 클래스의 _id 필드가 ObjectId 유형이어야 한다고 결정하고 스키마를 업데이트합니다.

업데이트된 Person 스키마를 준수하도록 영역을 마이그레이션하려면 Configuration 객체를 만들고 영역의 스키마 버전을 1로 설정한 다음 정수 유형을 Object ID 유형으로 변환하는 마이그레이션 함수를 정의하세요. 마지막으로 구성 객체를 createRealmContext() 메서드에 전달합니다.

class Person extends Realm.Object {
  static schema = {
    name: 'Person',
    properties: {
      // update the data type of '_id' to be 'objectId' within the schema
      _id: 'objectId',
      firstName: 'string',
      lastName: 'string',
    },
  };
}
const config = {
  schema: [Person],
  // Increment the 'schemaVersion', since the property type of '_id'
  // has been modified.
  // The initial schemaVersion is 0.
  schemaVersion: 1,
  onMigration: (oldRealm, newRealm) => {
    if (oldRealm.schemaVersion < 1) {
      const oldObjects = oldRealm.objects(Person);
      const newObjects = newRealm.objects(Person);
      // loop through all objects and set the _id property
      // in the new schema
      for (const objectIndex in oldObjects) {
        const oldObject = oldObjects[objectIndex];
        const newObject = newObjects[objectIndex];
        newObject._id = new Realm.BSON.ObjectId(oldObject._id);
      }
    }
  },
};
// Pass the configuration object with the updated
// 'schemaVersion' and 'migration' function to createRealmContext()
const {RealmProvider} = createRealmContext(config);

class Person extends Realm.Object<Person> {
  _id!: Realm.BSON.ObjectId;
  firstName!: string;
  lastName!: string;
  age!: number;
  static schema: ObjectSchema = {
    name: 'Person',
    properties: {
      // Update the data type of '_id' to be 'objectId' within the schema.
      _id: 'objectId',
      firstName: 'string',
      lastName: 'string',
    },
  };
}
// `OldObjectModel` is only used for type injection for `oldRealm`. It is
// not related to the `Person` object model.
interface OldObjectModel {
  _id: Realm.BSON.ObjectId;
  firstName: string;
  lastName: string;
  age: number;
}
const config: Realm.Configuration = {
  schema: [Person],
  // Increment the 'schemaVersion', since the property type of '_id'
  // has been modified.
  // The initial schemaVersion is 0.
  schemaVersion: 1,
  onMigration: (oldRealm: Realm, newRealm: Realm) => {
    if (oldRealm.schemaVersion < 1) {
      const oldObjects: Realm.Results<OldObjectModel> =
        oldRealm.objects(Person);
      const newObjects: Realm.Results<Person> = newRealm.objects(Person);
      // Loop through all objects and set the _id property
      // in the new schema.
      for (const objectIndex in oldObjects) {
        const oldObject = oldObjects[objectIndex];
        const newObject = newObjects[objectIndex];
        newObject._id = new Realm.BSON.ObjectId(oldObject._id);
      }
    }
  },
};
// Pass the configuration object with the updated
// 'schemaVersion' and 'migration' function to createRealmContext().
const {RealmProvider} = createRealmContext(config);

돌아가기

관계 & 내장된 객체

데이터 유형