@basepurpose/rxdb-sqlite

A free, open-source, cross-platform SQLite storage adapter for RxDB

Looking for the official, production-optimized SQLite storage? See RxDB Premium SQLite.

This is a community-built alternative, scoped under @basepurpose.

Why This Exists

RxDB is an excellent local-first, offline-capable database for JavaScript applications. Its production-ready SQLite storage requires a paid premium license, which can be a barrier for solo developers, startups, open source projects, students, and non-profits.

This project provides a free, MIT-licensed SQLite storage adapter that works across multiple platforms.

Platform Support

| Platform | SQLite Implementation | Testing Status | |----------|----------------------|----------------| | React Native (Android) | expo-sqlite | Verified on device | | React Native (iOS) | expo-sqlite | Tests pass, needs device verification | | Browser | @sqlite.org/sqlite-wasm + OPFS | Tests pass, needs device verification | | Node.js | better-sqlite3 | Tests pass, needs device verification | | Bun | bun:sqlite (native) | Tests pass, needs device verification | | Electron | better-sqlite3 | Tests pass, needs device verification | | Capacitor (iOS/Android) | @capacitor-community/sqlite | Tests pass, needs device verification | | Tauri (Windows/macOS/Linux) | @tauri-apps/plugin-sql | Tests pass, needs device verification |

671 tests pass across 28 test suites. Only React Native on Android has been verified on a real device so far. Community help testing other platforms is welcome -- please open an issue with your results.

Installation

npm install @basepurpose/rxdb-sqlite

Platform-Specific Dependencies

| Platform | Additional Install | |----------|-------------------| | Browser | None (WASM bundled) | | Node.js | npm install better-sqlite3 | | Bun | None (native SQLite) | | React Native | npx expo install expo-sqlite | | Electron | npm install better-sqlite3 | | Capacitor | npm install @capacitor-community/sqlite && npx cap sync | | Tauri | Add tauri-plugin-sql to Cargo.toml |

Quick Start

import { createRxDatabase } from 'rxdb';
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite';

const db = await createRxDatabase({
  name: 'mydb',
  storage: getRxStorageSQLite()
});

await db.addCollections({
  users: {
    schema: {
      version: 0,
      primaryKey: 'id',
      type: 'object',
      properties: {
        id: { type: 'string', maxLength: 100 },
        name: { type: 'string' },
        email: { type: 'string' }
      },
      required: ['id', 'name']
    }
  }
});

await db.users.insert({ id: 'user-1', name: 'Alice', email: '[email protected]' });

Platform-Specific Imports

// Browser (WASM + OPFS)
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/browser';

// Node.js
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/node';

// Bun
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/bun';

// React Native (Expo)
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/react-native';

// Electron
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/electron';

// Capacitor (iOS/Android)
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/capacitor';

// Tauri (Desktop)
import { getRxStorageSQLite } from '@basepurpose/rxdb-sqlite/tauri';

Features

Mango Query Support

All standard RxDB query operators work:

const results = await db.users.find({
  selector: {
    $and: [
      { age: { $gte: 18 } },
      { status: { $in: ['active', 'pending'] } },
      { 'address.country': 'US' }
    ]
  },
  sort: [{ name: 'asc' }],
  limit: 10
}).exec();

Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $type, $and, $or, $not, $nor, $elemMatch, $size, $all, $regex, $text

Reactive Queries

db.users.find().$.subscribe(users => {
  console.log('Users updated:', users);
});

Attachments

Store binary data alongside documents:

const doc = await db.posts.findOne('post-1').exec();
await doc.putAttachment({
  id: 'image.jpg',
  data: imageBase64String,
  type: 'image/jpeg'
});

Full-Text Search (FTS5)

const schema = {
  // ... your schema
  fulltext: {
    fields: ['title', 'content'],
    tokenizer: 'unicode61' // 'unicode61' | 'porter' | 'ascii' | 'trigram'
  }
};

const results = await db.articles.find({
  selector: { $text: 'javascript tutorial' }
}).exec();

Index Advisor

Analyze queries and get index suggestions:

import { analyzeQuery, suggestIndexes } from '@basepurpose/rxdb-sqlite';

const suggestions = suggestIndexes(
  { selector: { status: 'active', age: { $gte: 18 } } },
  'users'
);

Replication

Works with all RxDB replication plugins (CouchDB, Supabase, GraphQL, etc.):

import { replicateCouchDB } from 'rxdb/plugins/replication-couchdb';

const replication = replicateCouchDB({
  collection: db.users,
  url: 'https://your-couchdb.example.com/users',
  live: true,
  pull: {},
  push: {}
});

Multi-Tab Support (Browser)

Changes in one tab automatically sync to other tabs via BroadcastChannel.

RxDB Plugin Compatibility

Works with CRDT, Encryption, Replication, Backup, and Migration plugins.

Configuration

getRxStorageSQLite({
  debug: true,

  pragma: {
    journal_mode: 'WAL',
    synchronous: 'NORMAL',
    cache_size: -64000,   // 64MB cache
    temp_store: 'MEMORY'
  }
});

API Reference

getRxStorageSQLite(options?)

Creates an RxStorage instance. Platform is auto-detected, or use a platform-specific import.

| Option | Type | Description | |--------|------|-------------| | debug | boolean | Enable debug logging (default: false) | | adapter | SQLiteAdapterFactory | Custom adapter factory | | pragma | SQLitePragmaSettings | SQLite PRAGMA settings | | browser | BrowserAdapterOptions | Browser-specific options | | capacitor | CapacitorAdapterOptions | Capacitor-specific options | | tauri | TauriAdapterOptions | Tauri-specific options | | node | NodeAdapterOptions | Node.js-specific options | | bun | BunAdapterOptions | Bun-specific options | | reactNative | ReactNativeAdapterOptions | React Native-specific options | | electron | ElectronAdapterOptions | Electron-specific options |

Utility Functions

import {
  closeAllSQLiteConnections,
  isDatabaseOpen,
  translateMangoToSQL,
  buildSelectQuery,
  buildCountQuery,
} from '@basepurpose/rxdb-sqlite';

Browser Requirements

For optimal performance, serve with these headers to enable SharedArrayBuffer:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

The storage falls back to a slower mode if these headers aren't available.

Error Codes

| Code | Description | |------|-------------| | SQLITE_STORAGE_CLOSED | Operation on closed instance | | SQLITE_ATTACHMENT_NOT_FOUND | Attachment doesn't exist | | SQLITE_DIGEST_MISMATCH | Attachment digest verification failed | | SQLITE_INVALID_DOCUMENT_ID | Invalid document ID | | MANGO_QUERY_ERROR | Invalid query operator or syntax |

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

git clone https://github.com/basepurpose/rxdb-sqlite.git
cd rxdb-sqlite
bun install
bun test
bun run build

License

MIT -- see LICENSE.

Acknowledgments

• RxDB -- the database this storage powers
• @sqlite.org/sqlite-wasm -- official SQLite WASM build
• @capacitor-community/sqlite -- Capacitor SQLite plugin
• @tauri-apps/plugin-sql -- Tauri SQL plugin

Built By

basepurpose -- a maker lab building open-source tools.