React Native SQLite WAL Offline Fix

What if your React Native app’s SQLite database wasn’t the villain locking up your UI, but just waiting for you to stop treating it like a web server toy?

React Native offline-first SQLite setups hit this wall hard. You’ve got users logging workout sets in airplane mode—no loaders, no crashes. But bam: SQLITE_BUSY. Database locked.

I’ve seen this circus for 20 years. Back when iOS devs wrestled SQLite in the App Store’s early days, everyone blamed renders or state. Sound familiar?

Why Is Your React Native SQLite Locking Up?

The original post nails it: concurrent reads and writes. Search queries fly while inserts pile up. Defaults? Conservative as a banker’s tie—rollback journal, full syncs on every write.

“I wasted 4 hours blaming React renders. Most of it was wrong. SQLite was doing exactly what I asked. I just hadn’t configured it for a mobile app that’s always doing something.”

That’s gold. Pure dev truth. Expo + expo-sqlite shines for real queries—joins, indexes, volume counts. AsyncStorage? Crumbles under load.

But here’s my cynical take: companies hype ‘offline-first’ like it’s magic. Who’s banking? Not your users staring at toasts. It’s the devs burning nights on PRAGMAs.

WAL—write-ahead log—rewrites the rules. Writers append to a log; readers hit the main DB untouched. No blocking the UI for ‘feels instant’ saves.

And get this: my unique angle? This echoes WebSQL’s death in 2010. Browsers killed it for concurrency woes. SQLite WAL? It’s WebSQL’s revenge, battle-tested on mobile.

How to Flip WAL On in Expo (And Not Screw It Up)

Startup hook. One function. Done.

import * as SQLite from 'expo-sqlite';

export const db = SQLite.openDatabaseSync('gym.db');

export function initDb() {
  // WAL improves read/write concurrency.
  db.execSync('PRAGMA journal_mode = WAL;');

  // Wait up to 2 seconds when the DB is busy.
  db.execSync('PRAGMA busy_timeout = 2000;');

  // Durability vs speed. NORMAL is fine for app data.
  db.execSync('PRAGMA synchronous = NORMAL;');

  // Basic schema for set logging.
  db.execSync(`
    CREATE TABLE IF NOT EXISTS sets (
      id TEXT PRIMARY KEY NOT NULL,
      workout_id TEXT NOT NULL,
      exercise_id TEXT NOT NULL,
      reps INTEGER NOT NULL,
      weight_kg REAL NOT NULL,
      created_at_ms INTEGER NOT NULL
    );
    CREATE INDEX IF NOT EXISTS idx_sets_workout ON sets(workout_id, created_at_ms);
  `);
}

Boom. WAL once. Busy timeout catches stragglers. Synchronous=NORMAL skips paranoia fsyncs—your sets won’t vanish in a crash.

Tested? Author logged timings. Batches dropped from seconds to milliseconds. UI butter.

Skeptical me asks: who profits from defaults that suck? SQLite’s embedded roots scream servers, not frantic mobile taps.

Batching Writes: The Boring Fix That Wins

Single INSERT per tap? Adorable. Until auto-save notes, timers, sync meta crash the party.

Batch ‘em. One transaction. Fewer locks, less fsync churn.

// writeBatch.ts
import { db } from './db';

type SetRow = {
  id: string;
  // ... rest
};

export async function writeSetsBatch(sets: SetRow[]) {
  return db.transactionSync((tx) => {
    for (const set of sets) {
      tx.executeSync(
        'INSERT OR REPLACE INTO sets (id, workout_id, exercise_id, reps, weight_kg, created_at_ms) VALUES (?, ?, ?, ?, ?, ?)',
        [set.id, set.workout_id, set.exercise_id, set.reps, set.weight_kg, Date.now()]
      );
    }
  });
}

Retry wrapper? Slap a busy handler loop. Failures? Rare ghosts.

Prediction: in two years, Expo docs will mandate this for offline-first. React Native’s exploding—devs need WAL or bust.

Measured it yourself? Log timings. Watch batches crush singles. UI stays responsive. Airplane mode? Solid.

But wait—PR spin alert. ‘Offline-first’ sells apps. Reality? Tune or die.

Does WAL Actually Make Money for Anyone?

Cynic hat on. Users get snappier apps. Devs save hours. Who’s cashing checks?

Fitness apps retain subs longer—no rage quits on locks. That’s revenue. SQLite? Free, open-source beast carrying mobile.

Historical parallel: Android’s Room library baked WAL early. iOS lagged; devs suffered. React Native bridges that gap now.

Tradeoffs? WAL files bloat a tad—vacuum weekly. iOS checkpoints auto. Fine.

Ignore? Your app’s a spinner factory.

React Native Offline-First Without the Headaches

Combine: WAL + batch + timeout + indexes. Schema? Workout_id index speeds queries.

Real app: 5-second sets log smooth. Counts, searches live-update.

Unique insight—forgotten gem: PRAGMA wal_autocheckpoint=100; tunes it tighter. Author skipped; I wouldn’t. Keeps -wal files lean.

Test on device. Emulators lie.

🧬 Related Insights

• Read more: Claude’s February Thinking Redaction Turned Power Coders into Frustrated Wranglers
• Read more: Deferring JS in WordPress: The Quiet Fix That Slashes Load Times Without Breaking Sites

Frequently Asked Questions

Will SQLite WAL fix my React Native database locked errors?

Yes—enables concurrent reads/writes. Pair with busy_timeout=2000ms. Errors plummet.

How do I enable WAL in Expo SQLite?

db.execSync(‘PRAGMA journal_mode = WAL;’); Call on init. Add synchronous=NORMAL for speed.

Is batching writes necessary with WAL?

Not always, but it slashes fsyncs. One transaction for multiple INSERTs—UI flies.