Android中Realm数据库迁移指南：新增属性后迁移报错的解决方法

你遇到的这个RealmMigrationNeededException是因为Realm检测到你的数据模型（User类）和现有数据库的schema不匹配了——你新增了testRealm属性，但旧版本的数据库里没有这个字段，所以必须执行schema迁移才能兼容旧数据。

针对生产环境的需求，我们可以通过自定义Realm迁移类来实现平滑升级，不需要删除用户的现有数据。下面是具体的实现步骤，结合你的代码来修改：

步骤1：创建Realm迁移类 #

首先新建一个类实现RealmMigration接口，在migrate方法中处理schema的变更逻辑。对于新增字符串属性的场景，Realm可以自动帮我们添加这个字段，我们只需要在迁移方法中声明版本升级的处理：

public class MyRealmMigration implements RealmMigration {
    @Override
    public void migrate(DynamicRealm realm, long oldVersion, long newVersion) {
        // 获取User类的schema对象
        RealmSchema schema = realm.getSchema();
        
        // 版本从0升级到1（假设你之前没设置过schema版本，初始版本默认是0）
        if (oldVersion == 0 && newVersion == 1) {
            // 给User表新增testRealm字段，类型为字符串
            schema.get("User")
                  .addField("testRealm", String.class);
            oldVersion++;
        }
        
        // 如果以后还有其他schema变更，继续在这里添加版本分支，比如从1到2的处理
    }
}

步骤2：修改Application中的Realm初始化代码 #

你之前的初始化只有Realm.init(this);，现在需要配置RealmConfiguration，指定schema版本和迁移类，替换原来的初始化逻辑：

Realm.init(this);
RealmConfiguration config = new RealmConfiguration.Builder()
        // 设置schema版本，每次模型变更都要递增这个数字
        .schemaVersion(1)
        // 设置自定义的迁移类
        .migration(new MyRealmMigration())
        // 生产环境绝对不要设置deleteRealmIfMigrationNeeded()，这会直接删除用户旧数据！
        .build();
// 将这个配置设置为默认配置
Realm.setDefaultConfiguration(config);

步骤3：确认User模型的属性配置 #

你已经在User类中添加了testRealm属性，记得补充对应的getter/setter方法，确保数据能正常读写：

@SerializedName("test")
@Expose
private String testRealm;

public String getTestRealm() {
    return testRealm;
}

public void setTestRealm(String testRealm) {
    this.testRealm = testRealm;
}

生产环境注意事项 #

• 每次修改数据模型（新增/删除属性、修改属性类型等），都要递增schema版本号，并在迁移类中添加对应的版本处理逻辑。
• 绝对不要在生产环境使用deleteRealmIfMigrationNeeded()，这个方法仅适用于开发阶段调试，会直接清空用户的现有数据库。
• 如果有多个版本的schema变更，迁移类中要按版本顺序依次处理，比如从0→1、1→2、2→3这样的分支逻辑，确保每个版本的用户都能平滑升级。

这样修改后，用户更新应用时，Realm会自动执行迁移逻辑，保留原有数据的同时添加新字段，不会再出现迁移报错。

内容的提问来源于stack exchange，提问作者S.P.