ReaxDB #

The fastest NoSQL database for Flutter. Store millions of records with 21,000+ writes per second, instant reads from cache, and built-in encryption. Perfect for offline-first apps, real-time sync, and large datasets. Works on all platforms with zero native dependencies.

🆕 What's New in v1.1.0 #

• Secondary Indexes - Query any field with lightning speed
• Query Builder - Powerful API for complex queries
• Range Queries - Find documents between values
• Auto Index Updates - Indexes stay in sync automatically

Previous v1.0.1 #

• 4.4x faster writes - Now 21,000+ operations per second
• 40% faster batch operations - Improved batch processing

Features #

• High Performance: Zero-copy serialization and multi-level caching system
• Security: Built-in AES encryption with customizable keys
• ACID Transactions: Full transaction support with isolation levels
• Concurrent Operations: Connection pooling and batch processing
• Mobile Optimized: Hybrid storage engine designed for mobile devices
• Real-time Streams: Live data change notifications with pattern matching

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  reaxdb_dart: ^1.1.0

Then run:

flutter pub get

Quick Start #

Opening a Database #

import 'package:reaxdb_dart/reaxdb_dart.dart';

// Basic usage
final db = await ReaxDB.open('my_database');

// With custom configuration
final config = DatabaseConfig(
  memtableSizeMB: 16,
  pageSize: 8192,
  l1CacheSize: 2000,
  l2CacheSize: 10000,
  l3CacheSize: 50000,
  compressionEnabled: true,
  syncWrites: false,
);

final db = await ReaxDB.open(
  'my_database',
  config: config,
  encryptionKey: 'your-encryption-key',
);

Basic Operations #

// Store data
await db.put('user:123', {
  'name': 'John Doe',
  'email': 'john@example.com',
  'age': 30,
});

// Retrieve data
final user = await db.get('user:123');
print(user); // {name: John Doe, email: john@example.com, age: 30}

// Delete data
await db.delete('user:123');

Secondary Indexes (NEW!) #

// Create indexes for fast queries
await db.createIndex('users', 'email');
await db.createIndex('users', 'age');

// Query by any indexed field
final user = await db.collection('users')
    .whereEquals('email', 'john@example.com')
    .findOne();

// Range queries
final youngUsers = await db.collection('users')
    .whereBetween('age', 18, 30)
    .orderBy('age')
    .find();

// Complex queries
final results = await db.collection('users')
    .whereEquals('city', 'New York')
    .whereGreaterThan('age', 21)
    .limit(10)
    .find();

Batch Operations #

// Batch write for better performance
await db.putBatch({
  'user:1': {'name': 'Alice', 'age': 25},
  'user:2': {'name': 'Bob', 'age': 30},
  'user:3': {'name': 'Charlie', 'age': 35},
});

// Batch read
final users = await db.getBatch(['user:1', 'user:2', 'user:3']);

Transactions #

final txn = await db.beginTransaction();

try {
  await txn.put('account:1', {'balance': 1000});
  await txn.put('account:2', {'balance': 500});
  
  // Transfer money
  final account1 = await txn.get('account:1');
  final account2 = await txn.get('account:2');
  
  await txn.put('account:1', {'balance': account1['balance'] - 100});
  await txn.put('account:2', {'balance': account2['balance'] + 100});
  
  await txn.commit();
} catch (e) {
  await txn.rollback();
  rethrow;
}

Real-time Data Streams #

// Listen to all changes
final subscription = db.watchAll().listen((event) {
  print('${event.type}: ${event.key} = ${event.value}');
});

// Listen to specific patterns
final userStream = db.watchPattern('user:*').listen((event) {
  print('User updated: ${event.key}');
});

// Don't forget to cancel subscriptions
subscription.cancel();
userStream.cancel();

Advanced Features #

Atomic Operations

// Compare and swap
final success = await db.compareAndSwap('counter', 0, 1);
if (success) {
  print('Counter incremented');
}

Performance Monitoring

final stats = db.getPerformanceStats();
print('Cache hit ratio: ${stats['cache']['total_hit_ratio']}');

final dbInfo = await db.getDatabaseInfo();
print('Database size: ${dbInfo['database']['size']} bytes');
print('Total entries: ${dbInfo['database']['entries']}');

Configuration Options #

Performance Characteristics #

• Read Performance: 333,333 operations/second (~0.003ms latency)
• Write Performance: 21,276 operations/second (~0.047ms latency)
• Batch Operations: 3,676 operations/second
• Cache Hits: 555,555 operations/second (~0.002ms latency)
• Large Files: 4.8 GB/s write, 1.9 GB/s read
• Concurrent Operations: Up to 10 simultaneous operations
• Memory Efficiency: Multi-level caching with automatic promotion
• Storage Efficiency: LSM Tree with automatic compaction

Security #

ReaxDB provides built-in encryption support:

// Enable encryption with a custom key
final db = await ReaxDB.open(
  'secure_database',
  encryptionKey: 'your-256-bit-encryption-key',
);

All data is encrypted at rest using AES encryption when an encryption key is provided.

Architecture #

ReaxDB uses a hybrid storage architecture combining:

• LSM Tree: Optimized for write-heavy workloads
• B+ Tree: Fast range queries and ordered access
• Multi-level Cache: L1 (object), L2 (page), L3 (query) caching
• Write-Ahead Log: Durability and crash recovery
• Connection Pooling: Concurrent operation management

Error Handling #

try {
  final value = await db.get('nonexistent-key');
} on DatabaseException catch (e) {
  print('Database error: ${e.message}');
} catch (e) {
  print('Unexpected error: $e');
}

Best Practices #

1. Use batch operations for multiple writes to improve performance
2. Enable compression for storage efficiency with large datasets
3. Configure cache sizes based on your application's memory constraints
4. Use transactions for operations that must be atomic
5. Close databases properly to ensure data persistence
6. Monitor performance using built-in statistics methods

Closing the Database #

await db.close();

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing #

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

Support #

For issues, questions, or contributions, please visit our GitHub repository or contact our support team.