Realm Java升降级后触发RealmFileException 不支持的Realm文件格式版本报错

根因说明 #

Realm 5.x和10.x属于跨度极大的版本迭代，高版本生成的Realm数据库文件格式向下不兼容。你遇到的「全新安装仍存在旧数据库文件」现象，是Android 6.0及以上系统的自动备份机制导致的：默认配置下应用卸载时，系统会自动备份App私有目录下的文件到云端，重装同包名应用时会自动恢复备份文件，因此高版本生成的Realm文件会被恢复到低版本应用中，触发格式不兼容报错。

报错信息：

io.realm.exceptions.RealmFileException: Unable to open a realm at path '/data/data/com.my.app/files/fileName.realm': 
Unsupported Realm file format version. (Unsupported Realm file format version) (/data/data/com.my.app/files/fileName.realm) 
in /Users/cm/Realm/realm-java/realm/realm-library/src/main/cpp/io_realm_internal_OsSharedRealm.cpp 
line 101 Kind: ACCESS_ERROR.

解决方案 #

临时测试解决方案 #

重装低版本应用前按以下操作关闭自动恢复即可：

• 打开手机系统设置，找到「备份和恢复」相关设置项（不同厂商路径略有差异，常见路径为：设置→系统→备份）
• 关闭「自动恢复」开关
• 完全卸载已安装的高版本应用
• 重新安装低版本应用即可正常运行

永久规避方案 #

在应用配置中禁用Realm文件的自动备份，有两种实现方式：

1. 直接关闭整个应用的自动备份，在AndroidManifest.xml的application标签添加属性：

<application
    ...
    android:allowBackup="false"
    android:fullBackupContent="false">

2. 仅排除Realm文件不备份，保留其他文件的备份能力：
   首先在res/xml目录下新建backup_rules.xml，内容如下：

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <exclude domain="files" path="fileName.realm"/>
    <!-- 有多个Realm文件就依次添加exclude规则即可 -->
</full-backup-content>

然后在AndroidManifest.xml的application标签引用该规则：

<application
    ...
    android:allowBackup="true"
    android:fullBackupContent="@xml/backup_rules">

异常兼容方案 #

初始化Realm时增加异常捕获逻辑，检测到格式不兼容时直接删除本地损坏的数据库文件再重新初始化：

try {
    Realm realm = Realm.getInstance(config);
} catch (RealmFileException e) {
    if (e.getKind() == RealmFileException.Kind.ACCESS_ERROR 
        && e.getMessage().contains("Unsupported Realm file format version")) {
        // 删除不兼容的数据库文件
        Realm.deleteRealm(config);
        // 重新初始化
        Realm realm = Realm.getInstance(config);
    }
}

内容的提问来源于stack exchange，提问作者zetatlas