オブジェクトモデルの変更 - Node.js SDK

項目一覧

スキーマバージョン

移行
プロパティを追加する
プロパティを削除する
プロパティの名前を変更する
プロパティタイプの変更

Atlas Device SDK は非推奨です。詳細については、の廃止ページを参照してください。

スキーマバージョン

スキーマバージョンは、ある時点におけるRealm スキーマの状態を識別します。 Realm は各 Realm のスキーマバージョンを追跡し、それを使用して各 Realm 内のオブジェクトを正しいスキーマにマッピングします。

スキーマバージョンは昇順の整数であり、Realm を開くときに Realm 構成に任意で含めることができます。クライアントアプリケーションが Realm を開くときにバージョン番号を指定しない場合、Realm はデフォルトでバージョン 0になります。

重要

バージョンを単調に増加させる

移行によって、Realm をより高いスキーマバージョンに更新する必要があります。 Realm は、Realm の現在のバージョンよりも低いスキーマバージョンでクライアントアプリケーションが Realm を開き、または指定されたスキーマバージョンが Realm の現在のバージョンと同じであるが、異なるオブジェクトスキーマを含む場合にエラーをスローします。

移行

移行は、Realm とそれに含まれるすべてのオブジェクトを、あるスキーマバージョンから新しいバージョンに更新する関数です。移行により、新しい機能やリファクターに対応するために、オブジェクトスキーマを経時的に変更する柔軟性が付与されます。

Tip

開発中のバイパス移行

アプリケーションを開発またはデバッグする際には、Realm を移行するのではなく、Realm を削除することをお勧めします。スキーマの不一致により移行が必要になる場合に、 deleteRealmIfMigrationNeededフラグを使用してデータベースを自動的に削除します。

このフラグをtrueに設定して本番環境にアプリをリリースしないでください。

Realm の現在のバージョンよりも大きいスキーマバージョンで既存の Realm を開くたびに、Realm は定義した移行関数を実行します。この関数は Realm のバージョン番号にアクセスし、新しいスキーマに準拠するように Realm 内のオブジェクトを段階的に更新します。

Realm は、新しいプロパティや削除されたプロパティなど、特定の変更を自動的に移行しますが、更新されたオブジェクトスキーマでデフォルト値が指定されていない限り、新しいプロパティの値が自動的に設定されることはありません。移行関数で追加のロジックを定義して、プロパティ値をさらにカスタマイズできます。

注意

同期された Realm のスキーマプロパティの変更

次のページでは、ローカル Realm のスキーマプロパティを変更する方法を示します。同期された Realm のスキーマプロパティを変更する方法を学びます。

プロパティを追加する

スキーマにプロパティを追加するには、新しいプロパティをオブジェクトのクラスに追加し、 Realm の構成オブジェクトのschemaVersionを設定します。

例

スキーマバージョン1を使用する Realm には、 firstNameとlastNameプロパティを持つPersonオブジェクトタイプがあります。開発者は、 Personクラスにageプロパティを追加することを決定します。

更新されたPersonスキーマに準拠するように Realm を移行するには、開発者は Realm のスキーマバージョンを2に設定します。

const Person = {
  name: 'Person',
  properties: {
    firstName: 'string',
    lastName: 'string',
    age: 'int'
  }
}

const realm = await Realm.open({
    schema: [Person],
    schemaVersion: 2
  });

プロパティを削除する

スキーマからプロパティを削除するには、オブジェクトのクラスからプロパティを削除し、 Realm の構成オブジェクトのschemaVersionを設定します。プロパティを削除しても、既存のオブジェクトには影響しません。

例

スキーマバージョン1を使用する Realm には、 weightプロパティを持つDogオブジェクトタイプがあります。開発者は、スキーマからプロパティを削除することを決定します。

更新されたDogスキーマに準拠するように Realm を移行するには、開発者は Realm のスキーマバージョンを2に設定します。

const realm = await Realm.open({
    schema: [Dog],
    schemaVersion: 2
  });

プロパティの名前を変更する

オブジェクトプロパティの名前を変更するには、オブジェクトスキーマでプロパティ名を変更し、増加したスキーマバージョンと、新しいプロパティ名を使用するように既存のオブジェクトをアップデートする移行関数を使用してRealmを開きます。

移行では、プロパティの名前を直接変更することはできません。代わりに、更新された名前で新しいプロパティを作成し、古いプロパティから値をコピーして、古いプロパティを削除できます。

例

スキーマバージョン1を使用する Realm のオブジェクトタイプはPersonです。元のスキーマにはfirstName lastNameフィールドとフィールドがありました。開発者は後で、 Personクラスが結合されたfullNameフィールドを使用する必要があると判断し、個別のfirstNameフィールドとlastNameフィールドを削除します。

更新されたPerson スキーマに準拠するように Realm を移行するには、開発者は Realm の2 スキーマバージョンをfullName に設定し、既存のfirstName プロパティとlastName プロパティに基づいての値を設定するための移行関数を定義します。。

Realm.open({
  schema: [Person],
  schemaVersion: 2,
  onMigration: (oldRealm, newRealm) => {
    // only apply this change if upgrading to schemaVersion 2
    if (oldRealm.schemaVersion < 2) {
      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}`;
      }
    }
  }
});

重要

同期された Realm

同期されたRealmは、古いクライアントが新しいクライアントと同期できるようにするために、重大じゃない変更（追加と呼ばれる）のみをサポートします。名前を完全に変更するには古いプロパティを削除する必要があるため、クライアントのリセットが必要な同期プロパティの名前を変更することはできません。代わりに、古いプロパティを削除せずに、名前が変更されたプロパティを追加することを検討してください。あるいは、 mapToを使用して、既存の内部名を使用してデータを保存し、コードでは別の名前を使用できるようにします。

プロパティタイプの変更

プロパティのタイプを変更するには、変更するフィールドのプロパティタイプを新しいデータ型に設定します。次に、 Realm の構成オブジェクトのschemaVersionとmigrationコールバック関数を設定します。

注意

同期された Realmは、古いクライアントが新しいクライアントと同期できるようにするために、重大でない変更のみをサポートします。つまり、同期された Realm では、スキーマのプロパティのタイプの変更はサポートされていません。

例

スキーマバージョン1を使用する Realm のオブジェクトタイプはDogです。元のスキーマには、プロパティタイプがObject IDである_idがありました。開発者は後で、 Dogクラスの_idフィールドがstring型である必要があると判断し、スキーマを更新します。

更新されたDogスキーマに準拠するように Realm を移行するには、開発者は Realm のスキーマバージョンを2に設定し、 Object ID型をstring型に変換する移行関数を定義します。

const realm = await Realm.open({
    schema: [Dog],
    schemaVersion: 2,
    onMigration: (oldRealm, newRealm) => {
        if(oldRealm.schemaVersion < 2){
            const oldObjects = oldRealm.objects('Dog');
            const newObjects = newRealm.objects('Dog');
            // 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 = oldObject._id.toHexString();
            }
        }
    },
  });

戻る

関係と埋め込みオブジェクト

データ型

スキーマ バージョン

重要