Memory-Mapped I/O for Android SQLite

---
title: "Memory-Mapped I/O for Android SQLite: Eliminating Read Latency Spikes"
published: true
description: "Learn how SQLite's mmap_size pragma, WAL mode, and access pattern tuning eliminate p99 read latency spikes on memory-constrained Android devices."
tags: android, kotlin, architecture, performance
canonical_url: https://blog.mvpfactory.co/memory-mapped-io-android-sqlite-eliminating-read-latency-spikes
---

## What we're building

Today I'm going to walk you through a production-ready SQLite configuration that eliminates p99 read latency spikes on Android. We'll enable memory-mapped I/O, tune WAL checkpointing so mmap actually covers your hot data, and add device-aware sizing so you don't OOM-kill budget phones.

By the end, you'll have a `configureSQLiteMmap` function you can drop into any project that touches local databases — cached feeds, offline article stores, health tracking logs, anything content-heavy.

## Prerequisites

- Android project targeting API 21+
- Familiarity with SQLite pragmas and `SQLiteDatabase`
- A device or emulator for profiling (ideally a 3-4GB RAM device to see the difference)

## Step 1: Understand the double-buffering problem

Here is the gotcha that will save you hours. Standard `read()` syscalls hit **two** caches: SQLite's own page cache (~2MB via `PRAGMA cache_size`) and the OS filesystem buffer cache. When memory pressure hits — common on 3-4GB Android devices — the kernel evicts buffer cache pages. SQLite's next `read()` triggers a blocking disk I/O, spiking latency from ~0.1ms to **15-50ms**.

You're paying memory overhead for two caches and still eating cold reads when it matters most.

## Step 2: Enable memory-mapped I/O

When you set `PRAGMA mmap_size = 268435456` (256MB), SQLite maps the database file into its address space. Reads become pointer dereferences instead of `read()` syscalls. The improvement that matters is tail latency under memory pressure: **p99 drops from 15-50ms to 1-5ms** on a 4GB device at 80% memory pressure.

But first — check if your SQLite build even supports it:

kotlin
// Check effective mmap support at runtime
val db = SQLiteDatabase.openOrCreateDatabase(path, null)
val cursor = db.rawQuery("PRAGMA mmap_size = 268435456", null)
cursor.moveToFirst()
val effectiveMmapSize = cursor.getLong(0)
// If this returns 0, your SQLite build does not support mmap

The docs don't mention this, but Android's bundled SQLite ships with `SQLITE_MAX_MMAP_SIZE` set to `0` on many OEM builds prior to API 27. If you need guaranteed support, use [Requery's SQLite Android bindings](https://github.com/nicbell/reern) or SQLCipher — both bundle their own SQLite with mmap enabled.

## Step 3: Configure WAL mode properly

Let me show you a pattern I use in every project. mmap and WAL are complementary, but the interaction matters more than people expect. SQLite's mmap only applies to the **main database file** — the WAL is always read via standard I/O.

This means if your WAL grows unbounded, most hot reads bypass mmap entirely and you've gained almost nothing. Aggressive checkpointing fixes this:

kotlin
db.execSQL("PRAGMA journal_mode = WAL")
db.execSQL("PRAGMA wal_autocheckpoint = 100")
db.execSQL("PRAGMA mmap_size = 268435456")

Set `wal_autocheckpoint` to 100-200 pages so data moves back into the main file where mmap can serve it.

## Step 4: Add device-aware sizing

Here is the minimal setup to get this working safely across your entire device matrix:

kotlin
fun configureSQLiteMmap(db: SQLiteDatabase) {
val activityManager = context.getSystemService()
val memoryInfo = ActivityManager.MemoryInfo()
activityManager.getMemoryInfo(memoryInfo)

val totalRamMb = memoryInfo.totalMem / (1024 * 1024)

val mmapSize = when {
    totalRamMb >= 6000 -> 256 * 1024 * 1024L  // 256MB
    totalRamMb >= 4000 -> 128 * 1024 * 1024L   // 128MB
    totalRamMb >= 3000 -> 64 * 1024 * 1024L    // 64MB
    else -> 0L  // Disable on low-RAM devices
}

db.execSQL("PRAGMA mmap_size = $mmapSize")

}

This matters especially for apps running persistent background tasks. [HealthyDesk](https://play.google.com/store/apps/details?id=com.healthydesk), for example, periodically wakes to deliver break reminders — its SQLite reads need to be fast even when system memory is under pressure from foreground apps.

## Step 5: Profile with Perfetto

Don't deploy mmap blindly. Use Perfetto's `ftrace` integration to measure the difference:

bash

In your Perfetto trace config, enable:

- category: "mm_filemap" (page cache events)

- category: "filemap" (mmap fault tracing)

Look for `mm_filemap_add_to_page_cache` events — high frequency during database reads indicates cold mmap faults. Compare traces with and without mmap on your actual target devices.

## Gotchas

- **32-bit processes**: Mapping a large database risks address space exhaustion. The device-aware sizing above handles this, but double-check if you support 32-bit ABIs.
- **Large table scans on <2GB RAM devices**: Mapping a 500MB database under heavy memory pressure causes a storm of page faults and potential OOM kills. I've watched this happen on a budget device in a QA lab — it is not subtle. Disable mmap entirely below 3GB.
- **Sequential scans vs random lookups**: mmap wins easily on sequential access (feed loading, batch sync) thanks to kernel read-ahead. For random point lookups, the gain is modest — you eliminate syscall overhead but still fault on cold pages.
- **OEM SQLite builds**: Always check the runtime return value of `PRAGMA mmap_size`. A silent `0` means your entire optimization is a no-op.

## Wrapping up

The pattern is straightforward: enable mmap with device-aware sizing, keep your WAL aggressively checkpointed, and let Perfetto traces drive your configuration — not assumptions. The average-case improvement is modest, but eliminating that p99 tail is what makes your app feel responsive when the user is multitasking and memory is tight.