@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: 'alice@example.com' });

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.