Turso FTS React Native SDK

Android React Native bindings for the Turso FTS fork. Local connections enable FTS index methods and WITHOUT ROWID tables without consumer feature flags. FTS indexes require rowid tables: the engine rejects indexes on WITHOUT ROWID tables. See PATCHES.md for the build and validation commands.

Installation

npm install @unni-craftsman/turso-fts-react-native

iOS

cd ios && pod install

Android

The Rust libraries are built with Android API level 31. Run make android before packaging to populate the gitignored libs/android/ directory.

Quick Start

import { Database, getDbPath } from '@unni-craftsman/turso-fts-react-native';

// Get platform-specific writable path
const dbPath = getDbPath('myapp.db');

// Create database with sync
const db = new Database({
  path: dbPath,
  url: 'libsql://your-db.turso.io',
  authToken: 'your-auth-token',
});

// Connect (bootstraps from remote if empty)
await db.connect();

// Query local replica (fast)
const users = await db.all('SELECT * FROM users');

// Make local changes
await db.run('INSERT INTO users (name) VALUES (?)', ['Alice']);

// Sync with remote
await db.push();  // Push local changes
await db.pull();  // Pull remote changes

// Close when done
await db.close();

Local-Only Database

const db = new Database({ path: getDbPath('local.db') });
await db.connect();

await db.exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)');
await db.run('INSERT INTO users (name) VALUES (?)', ['Bob']);
const user = await db.get('SELECT * FROM users WHERE id = ?', [1]);

await db.close();

Encrypted Remote Database

const db = new Database({
  path: getDbPath('encrypted.db'),
  url: 'libsql://your-db.turso.io',
  authToken: 'your-auth-token',
  remoteEncryption: {
    cipher: 'aes256gcm',
    key: 'base64-encoded-key',
  },
});

API

Database Methods

| Method | Description | |--------|-------------| | connect() | Open/bootstrap the database | | exec(sql) | Execute SQL (no results) | | run(sql, params?) | Execute SQL, return { changes, lastInsertRowid } | | get(sql, params?) | Query single row | | all(sql, params?) | Query all rows | | prepare(sql) | Create prepared statement | | close() | Close database |

Sync Methods (when url is provided)

| Method | Description | |--------|-------------| | push() | Push local changes to remote | | pull() | Pull remote changes to local | | sync() | Push then pull | | stats() | Get sync statistics |

Transactions

await db.transaction(async () => {
  await db.run('INSERT INTO users (name) VALUES (?)', ['Alice']);
  await db.run('INSERT INTO users (name) VALUES (?)', ['Bob']);
  // Commits on success, rolls back on error
});

License

This project is licensed under the MIT license.

Links

• Turso Documentation
• GitHub
• npm