react-native-nitro-storage 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -6,6 +6,38 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 Breaking changes are always listed first in each release section.
 
+## [0.13.0] - 2026-10-01
+
+### Breaking changes
+
+- **Android no longer deletes a corrupt Disk database.** In 0.12.0, Android replaced a corrupt Disk database with an empty one when it opened. Now the file is kept and every Disk call fails with `storage_corruption`, as on iOS, until the app calls `storage.clear(StorageScope.Disk)` or `storage.clearAll()`. Migration: catch `storage_corruption` on Disk calls and call `storage.clear(StorageScope.Disk)` when the app can continue without the stored data.
+- **iOS reports undecodable Secure data as `storage_corruption`.** Reading a Secure or biometric item whose Keychain data is empty or is not UTF-8 text failed with an untagged `failed with status 0` error. It now fails with the `storage_corruption` code. The item can still be deleted or replaced. Migration: handle `storage_corruption` on Secure reads if you matched the old message.
+
+### Added
+
+- `storage.clear(StorageScope.Disk)` and `storage.clearAll()` recover a corrupt Disk database on iOS and Android: they delete the database and its journal files and create an empty store. `clear` with `except`, namespace clears, and `removeByPrefix` need to read keys and still fail on a corrupt database.
+- `storage.clear(StorageScope.Disk)` works on a full device. When the delete fails with `storage_full`, the database is deleted and created again, which frees its space.
+
+### Changed
+
+- Android Disk uses SQLite WAL. 0.12.0 documented WAL but did not enable it. An existing database converts on first open and keeps its rows. If the conversion cannot run, for example on a full device, the database opens without WAL so reads keep working, and the next launch tries again. With WAL and `synchronous=NORMAL`, a power loss can drop the most recent commits; an app kill cannot. This matches iOS.
+- `getKeysByPrefix` on Disk uses the key index instead of reading every key, on iOS and Android. On iOS, `size(StorageScope.Disk)` no longer builds the full key list. Results are unchanged.
+
+### Fixed
+
+- `storage.clear(StorageScope.Disk)` no longer fails before it reaches native storage when a Disk listener or event observer is registered and the stored values cannot be read, or when pending async Disk writes cannot be flushed. The pending writes are dropped and listeners receive a `clear` batch with no key changes.
+- Android: `setBatch`, `removeBatch`, and the first-launch import report a full Disk database with the `storage_full` code. They used to fail with an untagged `cannot rollback` error.
+- Android: Disk values larger than 2 MiB can be read. They could be written but not read.
+- Android: a Disk I/O error that occurs with less than 1 MiB of free space carries the `storage_full` code. Read errors do not.
+- iOS: Disk I/O errors caused by a full device or an exceeded quota carry the `storage_full` code, including while the database opens.
+- iOS: a Disk read of a legacy value that is not yet migrated no longer fails when the Disk database is full.
+- iOS: `clearSecureBiometric` reports an unavailable Keychain with the `keychain_locked` code.
+- iOS: the Disk WAL file is truncated after checkpoints on every SQLite build.
+- iOS: a Disk key that is not valid UTF-8 is rejected before anything is written or removed.
+- `removeByPrefix("", scope)` rejects an invalid scope.
+- Unknown native failures in `hasSecureBiometric`, `setSecureAccessControl`, `setSecureWritesAsync`, and `setKeychainAccessGroup` surface as a `NitroStorage: … failed (unknown error)` error.
+- The Android library declares its unit-test dependencies only inside the repository, so consumer builds do not resolve them.
+
 ## [0.12.0] - 2026-10-01
 
 ### Breaking changes

package/README.md

@@ -91,7 +91,7 @@ before installing this package, then rebuild the native app so the generated
 Nitro bindings and native runtime use the same major-minor version:
 
 ```sh
-bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.12.0
+bun add react-native-nitro-modules@0.37.1 react-native-nitro-storage@0.13.0
 bunx expo prebuild
 ```
 
@@ -752,17 +752,17 @@ Native and web adapters tag classified failures with stable error codes. Use
 Errors never swallow the underlying cause silently: the original platform
 message is preserved on the error for diagnostics.
 
-| Code                          | Meaning                                                                                                                                               |
-| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `keychain_locked`             | The protected store is locked. Retry after the device unlocks.                                                                                        |
-| `authentication_required`     | The item needs user authentication, or the user cancelled the prompt.                                                                                 |
-| `key_invalidated`             | The protecting key was invalidated, for example by a biometric enrolment change.                                                                      |
-| `biometric_unavailable`       | The requested biometric level is not available on this device or OS version.                                                                          |
-| `storage_corruption`          | Stored secure data could not be decrypted, the Disk database is corrupt, or (Android) the Secure master key or store cannot be created. Do not retry. |
-| `storage_compensation_failed` | A multi-step write failed and restoring the previous state also failed.                                                                               |
-| `unsupported`                 | The operation is not available on this platform or environment.                                                                                       |
-| `storage_full`                | The device or database is out of space, or the web storage quota is exceeded. Free space before retrying.                                             |
-| `invalid_key`                 | The storage key is empty. Keys must be non-empty strings.                                                                                             |
+| Code                          | Meaning                                                                                                                                             |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `keychain_locked`             | The protected store is locked. Retry after the device unlocks.                                                                                      |
+| `authentication_required`     | The item needs user authentication, or the user cancelled the prompt.                                                                               |
+| `key_invalidated`             | The protecting key was invalidated, for example by a biometric enrolment change.                                                                    |
+| `biometric_unavailable`       | The requested biometric level is not available on this device or OS version.                                                                        |
+| `storage_corruption`          | Stored secure data could not be decoded, the Disk database is corrupt, or (Android) the Secure master key or store cannot be created. Do not retry. |
+| `storage_compensation_failed` | A multi-step write failed and restoring the previous state also failed.                                                                             |
+| `unsupported`                 | The operation is not available on this platform or environment.                                                                                     |
+| `storage_full`                | The device or database is out of space, or the web storage quota is exceeded. Free space before retrying.                                           |
+| `invalid_key`                 | The storage key is empty. Keys must be non-empty strings.                                                                                           |
 
 Invalid scopes and non-finite numeric levels are rejected with untagged errors
 before they reach native storage.
@@ -788,6 +788,44 @@ function saveDraft(draft: string): "saved" | "storage_full" {
 }
 ```
 
+A full device does not block cleanup. `storage.clear(StorageScope.Disk)`
+deletes and recreates the Disk database when a normal delete fails with
+`storage_full`, which frees the space the database used. `remove` and
+`removeBatch` can still fail with `storage_full`, because a delete also writes
+to the database log.
+
+A corrupt Disk database is never deleted automatically. Every Disk call fails
+with `storage_corruption` until the app clears Disk storage:
+
+```ts
+import {
+  isStorageError,
+  storage,
+  StorageScope,
+} from "react-native-nitro-storage";
+
+function readDraft(): string | undefined {
+  try {
+    return storage.getString("draft", StorageScope.Disk);
+  } catch (error) {
+    if (!isStorageError(error, "storage_corruption")) throw error;
+    storage.clear(StorageScope.Disk);
+    return undefined;
+  }
+}
+```
+
+`storage.clear(StorageScope.Disk)` and `storage.clearAll()` are the recovery
+calls. `clear` with `except`, namespace clears, and `removeByPrefix` read keys
+first and fail on a corrupt database. A `clear` batch event with an empty
+`changes` array means every key in that scope was removed and the previous
+values could not be read; treat all keys in the scope as deleted.
+
+On Android, Disk values above 512 KiB are read in 512 KiB chunks, and read
+time grows faster than value size (about 30 ms for 5 MiB and 265 ms for 20 MiB
+in a host measurement; devices are slower). Keep single Disk values below about
+5 MiB.
+
 ## Platform Support
 
 | Platform               | Status                                             |

package/SECURITY.md

@@ -6,8 +6,8 @@ Security fixes are shipped for the latest published `0.x` release line.
 
 | Version  | Supported |
 | -------- | --------- |
-| `0.11.x` | Yes       |
-| `< 0.11` | No        |
+| `0.13.x` | Yes       |
+| `< 0.13` | No        |
 
 ## Reporting a Vulnerability
 

package/android/build.gradle

@@ -83,4 +83,9 @@ dependencies {
   implementation "com.facebook.react:react-native:+"
   implementation "androidx.security:security-crypto:1.1.0"
   implementation project(":react-native-nitro-modules")
+
+  if (file("src/test").exists()) {
+    testImplementation "junit:junit:4.13.2"
+    testImplementation "org.robolectric:robolectric:4.13"
+  }
 }

package/android/src/main/cpp/AndroidStorageAdapterCpp.cpp

@@ -1,4 +1,5 @@
 #include "AndroidStorageAdapterCpp.hpp"
+#include "JniSize.hpp"
 
 #include <limits>
 #include <stdexcept>
@@ -13,11 +14,8 @@ namespace {
 local_ref<JString> toJavaString(const std::string& value) {
     // fbjni's std::string overload uses c_str(), which truncates embedded NUL.
     if (value.find('\0') == std::string::npos) return make_jstring(value);
-    if (value.size() > static_cast<size_t>(std::numeric_limits<jsize>::max())) {
-        throw std::length_error("Storage string exceeds the Java array limit");
-    }
-    const auto size = static_cast<jsize>(value.size());
-    auto bytes = JArrayByte::newArray(size);
+    const jsize size = toJniSize(value.size(), "Storage string exceeds the Java array limit");
+    auto bytes = JArrayByte::newArray(value.size());
     bytes->setRegion(0, size, reinterpret_cast<const jbyte*>(value.data()));
     static auto constructor = JString::javaClassStatic()->getConstructor<
         jstring(jbyteArray, jstring)>();
@@ -26,10 +24,11 @@ local_ref<JString> toJavaString(const std::string& value) {
 }
 
 local_ref<JavaStringArray> toJavaStringArray(const std::vector<std::string>& values) {
-    auto javaArray = JavaStringArray::newArray(static_cast<jsize>(values.size()));
+    toJniSize(values.size(), "Storage batch exceeds the Java array limit");
+    auto javaArray = JavaStringArray::newArray(values.size());
     for (size_t i = 0; i < values.size(); ++i) {
         auto javaValue = toJavaString(values[i]);
-        javaArray->setElement(static_cast<jsize>(i), javaValue.get());
+        javaArray->setElement(i, javaValue.get());
     }
     return javaArray;
 }
@@ -38,9 +37,9 @@ std::vector<std::optional<std::string>> fromNullableJavaStringArray(alias_ref<Ja
     std::vector<std::optional<std::string>> parsedValues;
     if (!values) return parsedValues;
 
-    const jsize size = static_cast<jsize>(values->size());
+    const size_t size = values->size();
     parsedValues.reserve(size);
-    for (jsize i = 0; i < size; ++i) {
+    for (size_t i = 0; i < size; ++i) {
         auto currentValue = values->getElement(i);
         if (!currentValue) {
             parsedValues.push_back(std::nullopt);
@@ -53,10 +52,10 @@ std::vector<std::optional<std::string>> fromNullableJavaStringArray(alias_ref<Ja
 
 std::vector<std::string> fromJavaStringArray(alias_ref<JavaStringArray> values) {
     if (!values) return {};
-    const jsize size = values->size();
+    const size_t size = values->size();
     std::vector<std::string> result;
     result.reserve(size);
-    for (jsize i = 0; i < size; ++i) {
+    for (size_t i = 0; i < size; ++i) {
         auto currentValue = values->getElement(i);
         // Null entries are dropped so a missing key can never surface as the
         // empty-string clear sentinel used by change listeners.
@@ -115,7 +114,7 @@ std::vector<std::string> AndroidStorageAdapterCpp::getKeysByPrefixDisk(const std
 
 size_t AndroidStorageAdapterCpp::sizeDisk() {
     static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jint()>("sizeDisk");
-    return static_cast<size_t>(method(AndroidStorageAdapterJava::javaClassStatic()));
+    return fromJniSize(method(AndroidStorageAdapterJava::javaClassStatic()));
 }
 
 void AndroidStorageAdapterCpp::setDiskBatch(
@@ -199,7 +198,7 @@ std::vector<std::string> AndroidStorageAdapterCpp::getKeysByPrefixSecure(const s
 
 size_t AndroidStorageAdapterCpp::sizeSecure() {
     static auto method = AndroidStorageAdapterJava::javaClassStatic()->getStaticMethod<jint()>("sizeSecure");
-    return static_cast<size_t>(method(AndroidStorageAdapterJava::javaClassStatic()));
+    return fromJniSize(method(AndroidStorageAdapterJava::javaClassStatic()));
 }
 
 void AndroidStorageAdapterCpp::setSecureBatch(

package/android/src/main/cpp/JniSize.hpp

@@ -0,0 +1,21 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <limits>
+#include <stdexcept>
+
+namespace NitroStorage {
+
+inline int32_t toJniSize(size_t size, const char* what) {
+    if (size > static_cast<size_t>(std::numeric_limits<int32_t>::max())) {
+        throw std::length_error(what);
+    }
+    return static_cast<int32_t>(size);
+}
+
+inline size_t fromJniSize(int32_t size) {
+    return size > 0 ? static_cast<size_t>(size) : 0;
+}
+
+} // namespace NitroStorage

package/android/src/main/java/com/nitrostorage/AndroidStorageAdapter.kt

@@ -4,9 +4,11 @@ package com.nitrostorage
 
 import android.content.Context
 import android.database.sqlite.SQLiteDatabaseCorruptException
+import android.database.sqlite.SQLiteDiskIOException
 import android.database.sqlite.SQLiteException
 import android.database.sqlite.SQLiteFullException
 import android.os.Build
+import android.os.StatFs
 import android.security.keystore.KeyGenParameterSpec
 import android.security.keystore.KeyPermanentlyInvalidatedException
 import android.security.keystore.KeyProperties
@@ -20,7 +22,7 @@ import java.security.KeyStore
 import java.security.KeyStoreException
 import javax.crypto.AEADBadTagException
 
-private fun Throwable.hasCause(type: Class<*>): Boolean {
+internal fun Throwable.hasCause(type: Class<*>): Boolean {
     var current: Throwable? = this
     while (current != null) {
         if (type.isInstance(current)) return true
@@ -29,7 +31,7 @@ private fun Throwable.hasCause(type: Class<*>): Boolean {
     return false
 }
 
-private fun Throwable.storageErrorCode(): String? {
+internal fun Throwable.storageErrorCode(): String? {
     val taggedCode = message
         ?.let { Regex("\\[nitro-error:([a-z_]+)]").find(it)?.groupValues?.get(1) }
     if (taggedCode == "storage_compensation_failed") {
@@ -47,7 +49,34 @@ private fun Throwable.storageErrorCode(): String? {
     }
 }
 
-private fun Throwable.wrapStorageException(
+internal const val OUT_OF_SPACE_USABLE_BYTES = 1L shl 20
+
+private val sqliteExtendedCodePattern = Regex("\\(code (\\d+)")
+private const val SQLITE_IOERR_READ = 266
+private const val SQLITE_IOERR_SHORT_READ = 522
+
+internal fun isOutOfSpaceFailure(error: Throwable, usableBytes: Long): Boolean {
+    var current: Throwable? = error
+    while (current != null && current !is SQLiteDiskIOException) {
+        current = current.cause
+    }
+    val ioError = current ?: return false
+    val extendedCode = ioError.message
+        ?.let { sqliteExtendedCodePattern.find(it)?.groupValues?.get(1)?.toIntOrNull() }
+        ?: return false
+    if (extendedCode == SQLITE_IOERR_READ || extendedCode == SQLITE_IOERR_SHORT_READ) {
+        return false
+    }
+    return usableBytes in 0 until OUT_OF_SPACE_USABLE_BYTES
+}
+
+internal fun isRecoverableByRecreate(error: Throwable): Boolean {
+    val message = error.message ?: return false
+    return message.startsWith("[nitro-error:storage_corruption] NitroStorage: Disk SQLite ") ||
+        message.startsWith("[nitro-error:storage_full] NitroStorage: Disk SQLite ")
+}
+
+internal fun Throwable.wrapStorageException(
     defaultMessage: String,
     defaultCode: String? = null,
 ): RuntimeException {
@@ -66,8 +95,34 @@ private fun Throwable.wrapStorageException(
 class AndroidStorageAdapter private constructor(private val context: Context) {
     private val sharedPreferences: SharedPreferences =
         context.getSharedPreferences("NitroStorage", Context.MODE_PRIVATE)
-    private val diskStore: DiskSqliteStore by lazy {
-        DiskSqliteStore(context, sharedPreferences)
+    private val diskStoreLock = Any()
+    private var openDiskStore: DiskSqliteStore? = null
+    private val diskStore: DiskSqliteStore
+        get() = synchronized(diskStoreLock) {
+            openDiskStore ?: DiskSqliteStore(context, sharedPreferences, diskDatabaseOpener)
+                .also { openDiskStore = it }
+        }
+
+    private fun recreateDiskStore() {
+        synchronized(diskStoreLock) {
+            openDiskStore?.let { store -> runCatching { store.close() } }
+            openDiskStore = null
+            DiskSqliteStore.deleteDatabaseFiles(context)
+            sharedPreferences.edit().clear().commit()
+            openDiskStore = DiskSqliteStore(context, sharedPreferences, diskDatabaseOpener)
+        }
+    }
+
+    private fun diskFullCodeFor(error: Throwable): String? {
+        if (!error.hasCause(SQLiteDiskIOException::class.java)) {
+            return null
+        }
+        val usableBytes = try {
+            StatFs(context.filesDir.path).availableBytes
+        } catch (statError: IllegalArgumentException) {
+            return null
+        }
+        return if (isOutOfSpaceFailure(error, usableBytes)) "storage_full" else null
     }
 
     private val masterKeyAlias = "${context.packageName}.nitro_storage.master_key"
@@ -549,6 +604,9 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         @Volatile
         private var instance: AndroidStorageAdapter? = null
 
+        @Volatile
+        internal var diskDatabaseOpener: DiskDatabaseOpener = ::openDiskDatabase
+
         private fun getInstanceOrThrow(): AndroidStorageAdapter {
             return instance ?: throw IllegalStateException(
                 "NitroStorage not initialized. Call AndroidStorageAdapter.init(this) in your MainApplication.onCreate(), " +
@@ -585,8 +643,22 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
         ): T {
             val instance = getInstanceOrThrow()
             try {
-                return instance.diskStore.block()
+                val store = instance.diskStore
+                return try {
+                    store.block()
+                } catch (closed: IllegalStateException) {
+                    val current = instance.diskStore
+                    if (current === store) {
+                        throw closed
+                    }
+                    current.block()
+                }
             } catch (e: SQLiteException) {
+                throw e.wrapStorageException(
+                    "NitroStorage: Disk SQLite $operation failed: ${e.message}",
+                    instance.diskFullCodeFor(e),
+                )
+            } catch (e: IllegalStateException) {
                 throw e.wrapStorageException(
                     "NitroStorage: Disk SQLite $operation failed: ${e.message}",
                 )
@@ -645,7 +717,22 @@ class AndroidStorageAdapter private constructor(private val context: Context) {
 
         @JvmStatic
         fun clearDisk() {
-            diskOperation("clear") { clear() }
+            try {
+                diskOperation("clear") { clear() }
+            } catch (e: RuntimeException) {
+                if (!isRecoverableByRecreate(e)) {
+                    throw e
+                }
+                val instance = getInstanceOrThrow()
+                try {
+                    instance.recreateDiskStore()
+                } catch (recreateError: SQLiteException) {
+                    throw recreateError.wrapStorageException(
+                        "NitroStorage: Disk SQLite clear failed: ${recreateError.message}",
+                        instance.diskFullCodeFor(recreateError),
+                    )
+                }
+            }
         }
 
         // --- Secure (async apply by default, sync commit when requested) ---

package/android/src/main/java/com/nitrostorage/DiskSqliteStore.kt

@@ -2,21 +2,49 @@ package com.nitrostorage
 
 import android.content.Context
 import android.content.SharedPreferences
+import android.database.DatabaseErrorHandler
 import android.database.sqlite.SQLiteDatabase
+import android.database.sqlite.SQLiteDatabaseCorruptException
+import android.database.sqlite.SQLiteException
+import java.io.ByteArrayOutputStream
 import java.io.File
 
+internal typealias DiskDatabaseOpener = (path: String, flags: Int) -> SQLiteDatabase
+
+internal fun openDiskDatabase(path: String, flags: Int): SQLiteDatabase {
+    return SQLiteDatabase.openDatabase(path, null, flags, DatabaseErrorHandler { })
+}
+
+internal fun openDiskDatabaseWithWalFallback(
+    path: String,
+    opener: DiskDatabaseOpener,
+): SQLiteDatabase {
+    val flags = SQLiteDatabase.CREATE_IF_NECESSARY or SQLiteDatabase.NO_LOCALIZED_COLLATORS
+    return try {
+        opener(path, flags or SQLiteDatabase.ENABLE_WRITE_AHEAD_LOGGING)
+    } catch (walError: SQLiteDatabaseCorruptException) {
+        throw walError
+    } catch (walError: SQLiteException) {
+        try {
+            opener(path, flags)
+        } catch (fallbackError: Exception) {
+            walError.addSuppressed(fallbackError)
+            throw walError
+        }
+    }
+}
+
 internal class DiskSqliteStore(
     context: Context,
     private val legacyPreferences: SharedPreferences,
+    opener: DiskDatabaseOpener = ::openDiskDatabase,
 ) {
     private val db: SQLiteDatabase =
-        SQLiteDatabase.openOrCreateDatabase(File(context.filesDir, DATABASE_NAME), null)
+        openDiskDatabaseWithWalFallback(databaseFile(context).path, opener)
 
     init {
         try {
-            // PRAGMA journal_mode returns a row; Android forbids result-bearing SQL on execSQL.
-            db.rawQuery("PRAGMA journal_mode=WAL", null).close()
-            db.execSQL("PRAGMA synchronous=NORMAL")
+            db.execSQL(synchronousPragmaFor(queryPragma("PRAGMA journal_mode")))
             db.execSQL(
                 "CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY NOT NULL, value TEXT NOT NULL)",
             )
@@ -30,6 +58,17 @@ internal class DiskSqliteStore(
         }
     }
 
+    private fun queryPragma(sql: String): String? {
+        return db.rawQuery(sql, null).use { cursor ->
+            if (cursor.moveToFirst()) cursor.getString(0) else null
+        }
+    }
+
+    @Synchronized
+    fun close() {
+        db.close()
+    }
+
     @Synchronized
     fun set(key: String, value: String) {
         db.execSQL(
@@ -40,9 +79,39 @@ internal class DiskSqliteStore(
 
     @Synchronized
     fun get(key: String): String? {
-        db.rawQuery("SELECT value FROM kv WHERE key = ? LIMIT 1", arrayOf(key)).use { cursor ->
-            return if (cursor.moveToFirst()) cursor.getString(0) else null
+        db.rawQuery(
+            "SELECT length(CAST(value AS BLOB)), " +
+                "CASE WHEN length(CAST(value AS BLOB)) <= $VALUE_CHUNK_BYTES THEN value END " +
+                "FROM kv WHERE key = ? LIMIT 1",
+            arrayOf(key),
+        ).use { cursor ->
+            if (!cursor.moveToFirst()) {
+                return null
+            }
+            if (!cursor.isNull(1)) {
+                return cursor.getString(1)
+            }
+            return readLargeValue(key, cursor.getLong(0))
+        }
+    }
+
+    private fun readLargeValue(key: String, byteCount: Long): String {
+        val bytes = ByteArrayOutputStream(byteCount.coerceAtMost(Int.MAX_VALUE.toLong()).toInt())
+        var offset = 1L
+        while (offset <= byteCount) {
+            val chunk = db.rawQuery(
+                "SELECT substr(CAST(value AS BLOB), ?, $VALUE_CHUNK_BYTES) FROM kv WHERE key = ?",
+                arrayOf(offset.toString(), key),
+            ).use { cursor ->
+                if (cursor.moveToFirst()) cursor.getBlob(0) else null
+            }
+            if (chunk == null || chunk.isEmpty()) {
+                break
+            }
+            bytes.write(chunk, 0, chunk.size)
+            offset += chunk.size
         }
+        return String(bytes.toByteArray(), Charsets.UTF_8)
     }
 
     @Synchronized
@@ -61,17 +130,13 @@ internal class DiskSqliteStore(
     @Synchronized
     fun setBatch(keys: Array<String>, values: Array<String>) {
         val count = minOf(keys.size, values.size)
-        db.beginTransaction()
-        try {
+        inTransaction {
             for (index in 0 until count) {
                 db.execSQL(
                     "INSERT OR REPLACE INTO kv(key, value) VALUES(?, ?)",
                     arrayOf(keys[index], values[index]),
                 )
             }
-            db.setTransactionSuccessful()
-        } finally {
-            db.endTransaction()
         }
     }
 
@@ -82,14 +147,10 @@ internal class DiskSqliteStore(
 
     @Synchronized
     fun removeBatch(keys: Array<String>) {
-        db.beginTransaction()
-        try {
+        inTransaction {
             for (key in keys) {
                 db.execSQL("DELETE FROM kv WHERE key = ?", arrayOf(key))
             }
-            db.setTransactionSuccessful()
-        } finally {
-            db.endTransaction()
         }
         removeLegacyKeys(keys.asIterable())
     }
@@ -107,19 +168,12 @@ internal class DiskSqliteStore(
 
     @Synchronized
     fun getKeysByPrefix(prefix: String): Array<String> {
-        val pattern = buildString {
-            for (character in prefix) {
-                // LIKE stops at NUL; startsWith below checks the complete prefix.
-                if (character == '\u0000') break
-                if (character == '%' || character == '_' || character == '\\') append('\\')
-                append(character)
-            }
-            append('%')
+        val cursor = if (hasUnpairedSurrogate(prefix)) {
+            db.rawQuery("SELECT key FROM kv WHERE key LIKE ? ESCAPE '\\'", arrayOf(likePattern(prefix)))
+        } else {
+            db.rawQuery("SELECT key FROM kv WHERE key >= ?1 AND key < (?1 || x'FF')", arrayOf(prefix))
         }
-        db.rawQuery(
-            "SELECT key FROM kv WHERE key LIKE ? ESCAPE '\\'",
-            arrayOf(pattern),
-        ).use { cursor ->
+        cursor.use {
             val keys = ArrayList<String>(cursor.count)
             while (cursor.moveToNext()) {
                 val key = cursor.getString(0)
@@ -156,8 +210,7 @@ internal class DiskSqliteStore(
             }
         }
 
-        db.beginTransaction()
-        try {
+        inTransaction {
             for ((key, value) in legacyPreferences.all) {
                 if (value is String) {
                     db.execSQL(
@@ -170,9 +223,25 @@ internal class DiskSqliteStore(
                 "INSERT OR REPLACE INTO meta(k, v) VALUES(?, ?)",
                 arrayOf(PREFS_MIGRATION_KEY, "1"),
             )
+        }
+    }
+
+    private inline fun inTransaction(block: () -> Unit) {
+        db.beginTransaction()
+        var failure: Throwable? = null
+        try {
+            block()
             db.setTransactionSuccessful()
+        } catch (error: Throwable) {
+            failure = error
+            throw error
         } finally {
-            db.endTransaction()
+            try {
+                db.endTransaction()
+            } catch (error: SQLiteException) {
+                val primary = failure ?: throw error
+                primary.addSuppressed(error)
+            }
         }
     }
 
@@ -186,8 +255,52 @@ internal class DiskSqliteStore(
         editor.apply()
     }
 
-    private companion object {
-        const val DATABASE_NAME = "nitro-storage-disk.sqlite"
-        const val PREFS_MIGRATION_KEY = "prefs_v1"
+    companion object {
+        private const val DATABASE_NAME = "nitro-storage-disk.sqlite"
+        private const val PREFS_MIGRATION_KEY = "prefs_v1"
+        private const val VALUE_CHUNK_BYTES = 512 * 1024
+
+        fun databaseFile(context: Context): File = File(context.filesDir, DATABASE_NAME)
+
+        fun deleteDatabaseFiles(context: Context) {
+            SQLiteDatabase.deleteDatabase(databaseFile(context))
+        }
+    }
+}
+
+private fun hasUnpairedSurrogate(value: String): Boolean {
+    var index = 0
+    while (index < value.length) {
+        val character = value[index]
+        if (Character.isHighSurrogate(character)) {
+            if (index + 1 >= value.length || !Character.isLowSurrogate(value[index + 1])) {
+                return true
+            }
+            index += 2
+        } else if (Character.isLowSurrogate(character)) {
+            return true
+        } else {
+            index += 1
+        }
+    }
+    return false
+}
+
+private fun likePattern(prefix: String): String {
+    return buildString {
+        for (character in prefix) {
+            if (character == '\u0000') break
+            if (character == '%' || character == '_' || character == '\\') append('\\')
+            append(character)
+        }
+        append('%')
+    }
+}
+
+internal fun synchronousPragmaFor(journalMode: String?): String {
+    return if (journalMode.equals("wal", ignoreCase = true)) {
+        "PRAGMA synchronous=NORMAL"
+    } else {
+        "PRAGMA synchronous=FULL"
     }
 }