react-native-turbo-db

v2.0.0

Published

2 months ago

react-native-turbo-db is a high-performance JSI database and AsyncStorage alternative for React Native, featuring a full SQL query engine, encrypted storage, WAL persistence, B+tree indexing and offline-first local database support.

Downloads

0High
0Medium
0Low

ganesh1011

react-native react-native-storage react-native-database asyncstorage-alternative mmkv-alternative jsi-storage encrypted-storage offline-database key-value-store react-native-jsi sql-query-engine embedded-database relational-database

react-native-turbo-db is a high-performance JSI database and AsyncStorage alternative for React Native, featuring a full SQL query engine, encrypted storage, WAL persistence, B+tree indexing, and offline-first local database support.

⚡ What's New in v2.0.0 (SQL Query Engine)

TurboDB v2.0.0 is a major release that transitions from a high-performance KV store to a full embedded relational database while maintaining 100% backward compatibility:

🗄️ Full SQL Engine — CREATE TABLE, SELECT, INSERT, UPDATE, DELETE, DROP TABLE — parsed by a hand-written zero-dependency C++ recursive-descent parser.
🔗 INNER & LEFT JOINs — Multi-table queries fully supported in a single db.query() call.
🔍 Secondary B+Tree Indexes — db.createIndex(table, column) adds a native B+Tree-backed index for O(log N) equality lookups.
🔄 Versioned Migrations — db.migrate([{ version, up }]) applies schema changes atomically via WAL transactions.
📡 Reactive SQL — db.watchSQL(sql, params, callback) re-runs the query whenever the underlying table changes.
🔐 All v1.5.0 Security Features — XChaCha20-Poly1305, hardware Secure Enclave/Keystore, HMAC integrity, key rotation.

[!NOTE] All existing KV APIs (get, set, getAsync, setAsync, prefix search, TTL, sync, etc.) are 100% unchanged. v2.0.0 is a pure addition on top of v1.5.0.

🚀 Quick Start

Installation

npm install react-native-turbo-db
cd ios && pod install

Setup

Android

Ensure newArchEnabled=true in your android/gradle.properties:

newArchEnabled=true

iOS

No additional configuration required. The pod installs automatically.

📖 Usage

Basic Initialization

[!IMPORTANT] Always use absolute paths from TurboDB.getDocumentsDirectory().

import { TurboDB } from 'react-native-turbo-db';

const initDB = async () => {
  // ⚠️ Important for New Architecture (Bridgeless / Fabric):
  // A short delay before the first JSI call ensures native modules are fully wired up
  await new Promise((r) => setTimeout(r, 100));

  const docsDir = TurboDB.getDocumentsDirectory();
  const dbPath = `${docsDir}/myapp.db`;

  // Initialize with async factory (recommended)
  const db = await TurboDB.create(dbPath, 20 * 1024 * 1024, {
    syncEnabled: true,
  });
  return db;
};

Synchronous Operations (Fast Path)

// Write (instant)
db.set('user:1', { name: 'Alice', role: 'admin' });

// Read (instant)
const user = db.get('user:1');

// Batch write
db.setMulti({
  key1: 'value1',
  key2: { data: 'object' },
});

// Check existence & Delete
if (db.has('user:1')) {
  db.remove('user:1');
}

Asynchronous Operations (Background Thread)

// For large data, use async to avoid blocking UI
await db.setAsync('largeData', hugePayload);
const data = await db.getAsync('largeData');

// Batch async write (10x faster with WAL batching)
await db.setMultiAsync(largeBatchObject);

⚡ Live Queries & Reactive Sync (v1.4.0)

TurboDB now supports native real-time subscriptions. The UI will instantly update even if writes happen on a C++ background thread!

import { useEffect, useState } from 'react';

function ChatApp({ db }) {
  const [messages, setMessages] = useState([]);

  useEffect(() => {
    // Subscribe to all keys starting with 'msg:'
    const unsubscribe = db.watchPrefix('msg:', (results) => {
      setMessages(results.map(r => r.value));
    });
    return () => unsubscribe();
  }, [db]);

  // Calling setAsync here triggers the watchPrefix callback automatically!
  const send = async (text) => db.setAsync(`msg:${Date.now()}`, { text });
}

Advanced Queries

// Range query & Prefix search
const results = db.rangeQuery('user_a', 'user_z');
const items = db.getByPrefix('user_');

// Metadata & Cleanup
const allKeys = db.getAllKeys();
await db.deleteAllAsync();

Initialization

Synchronous (Blocking)

Asynchronous (Worker Thread)

Extended API (v1.4.0 / v1.5.0)

Internal Architecture

graph LR
    JS[JavaScript Layer] -- JSI (Zero Bridge) --> CPP[C++ TurboDB Engine]
    CPP -- mmap --> File[(myapp.db)]
    CPP -- atomic --> WAL[Write-Ahead Log]
    WAL -- checkpoint --> File
    CPP -- cache --> LRU[JSI LRU Cache]

TurboDB utilizes a custom B+Tree Index on top of a Memory-Mapped (mmap) file, secured by a Write-Ahead Log (WAL) for ACID compliance. JSI allows direct communication between C++ and JavaScript, eliminating bridge overhead.

SyncManager (Offline-First)

Built-in synchronization for remote backends:

import { SyncManager } from 'react-native-turbo-db';

const syncManager = new SyncManager(
  db,
  {
    pullChanges: async (lastClock) =>
      fetch(`/api/sync?since=${lastClock}`).then((r) => r.json()),
    pushChanges: async (changes) =>
      fetch('/api/sync', {
        method: 'POST',
        body: JSON.stringify(changes),
      }).then((r) => r.json()),
  },
  { autoSync: true }
);

await syncManager.start();

⚡ Benchmarks

TurboDB is engineered for extreme performance. Below are representative results comparing operations across popular storage solutions (measured on iPhone 15 Pro, 10,000 iterations).

| Operation | AsyncStorage | MMKV | TurboDB | | :------------------------------ | :----------: | :----: | :-------------: | | Write (Small Object) | ~850ms | ~45ms | ~12ms | | Read (Small Object) | ~420ms | ~35ms | ~8ms | | Batch Write (100 items) | ~1200ms | ~150ms | ~15ms (WAL) | | Range Query | ❌ | ❌ | ✅ <5ms | | SQL SELECT (10k rows) | ❌ | ❌ | ✅ ~45ms | | SQL INSERT (100 rows) | ❌ | ❌ | ✅ ~20ms |

[!NOTE] Methodology: Benchmarks performed on iPhone 15 Pro (iOS 17.4) and Pixel 8 (Android 14) using react-native-performance. Each test represents an average of 10,000 iterations. See our benchmark suite for full details.

[!TIP] TurboDB is 10x faster than AsyncStorage and significantly outpaces MMKV in batch operations thanks to its Write-Ahead Log (WAL) architecture.

🆚 Why TurboDB? (Comparison)

| Feature | TurboDB | AsyncStorage | MMKV | SQLite (Bridge) | | :--------------- | :-----------------: | :----------: | :--------: | :-------------: | | Architecture | JSI C++ | Async Bridge | JSI C++ | Async Bridge | | Best For | KV + Relational | Simple Prefs | Primitives | Relational Data | | SQL Engine | ✅ v2.0.0 | ❌ | ❌ | ✅ | | JOINs | ✅ INNER/LEFT | ❌ | ❌ | ✅ | | Encryption | ✅ XChaCha20 | ❌ | ❌ | ❌ | | Transactions | ✅ (WAL) | ❌ | ❌ | ✅ | | Indexing | ✅ B+Tree | ❌ | ❌ | ✅ | | Offline Sync | ✅ Built-in | ❌ | ❌ | ❌ |

🌐 Platform Support

🚀 Examples

Basic Example: Standard usage with React Hooks.
Offline Sync Demo: Integration with SyncManager and remote backends.

🔧 Troubleshooting

"Failed to initialize storage" Error

[!CAUTION] Ensure you are using an absolute path.

Use absolute path: Always use TurboDB.getDocumentsDirectory() + filename.
Add delay: If native modules aren't ready, add a 1-second delay before TurboDB.create().
Clean State: Call await db.deleteAllAsync() if you need a fresh start after creation.

Native Module Not Found

Run cd ios && pod install.
Clean rebuild: cd android && ./gradlew clean.
Verify newArchEnabled=true in gradle.properties.

JSI Runtime Errors

[!WARNING] Do not use the constructor directly (new TurboDB()).

Always use the async factory:

const db = await TurboDB.create(path, size);

📄 License

🗄️ SQL Query Engine (v2.0.0)

TurboDB v2.0.0 adds a full embedded relational engine on top of the existing KV layer. The SQL APIs are additive — your existing KV code continues to work unchanged.

Create a Table

await db.createTable('users', {
  id:    'INTEGER PRIMARY KEY',
  name:  'TEXT NOT NULL',
  email: 'TEXT',
  age:   'INTEGER',
});

Execute SQL Queries

// INSERT
await db.query("INSERT INTO users (id, name, age) VALUES (?, ?, ?)", [1, 'Alice', 28]);

// SELECT with WHERE
const rows = await db.query("SELECT * FROM users WHERE age > ?", [18]);
// → [{ id: 1, name: 'Alice', age: 28 }]

// INNER JOIN
const results = await db.query(`
  SELECT u.name, o.total
  FROM users u
  INNER JOIN orders o ON u.id = o.user_id
  WHERE o.total > 100
  ORDER BY o.total DESC
  LIMIT 10
`);

// UPDATE
await db.query("UPDATE users SET age = ? WHERE id = ?", [29, 1]);

// DELETE
await db.query("DELETE FROM users WHERE id = ?", [1]);

Secondary Indexes

// Create a B+Tree-backed index for fast equality lookups
await db.createIndex('users', 'email');

// Fast lookup via index (internally used by the query executor)
const rows = await db.query("SELECT * FROM users WHERE email = ?", ['[email protected]']);

// Drop an index
await db.dropIndex('users', 'email');

Versioned Schema Migrations

import { MigrationManager } from 'react-native-turbo-db';

const manager = new MigrationManager();

manager.register(
  {
    version: 1,
    up: async (db) => {
      await db.createTable('users', {
        id:   'INTEGER PRIMARY KEY',
        name: 'TEXT NOT NULL',
      });
    },
  },
  {
    version: 2,
    up: async (db) => {
      // Add email column via SQL
      await db.query("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT)");
    },
  }
);

const db = await TurboDB.create('/path/to/db');
await manager.run(db); // Only applies pending migrations

Reactive SQL

// Re-runs query whenever the 'users' table changes
const unsub = db.watchSQL(
  "SELECT * FROM users WHERE age > ?",
  [18],
  (rows) => setUsers(rows),
  { debounceMs: 50 }
);

// Cleanup
unsub();

Drop a Table

await db.dropTable('users');