https://github.com/champ96k/quanta_db
High-performance NoSQL local database built entirely in Dart
https://github.com/champ96k/quanta_db
dart dart-lang dart-library dart-package dartlang db flutter flutter-apps flutter-database flutter-plugin local-database localstorage
Last synced: 10 months ago
JSON representation
High-performance NoSQL local database built entirely in Dart
- Host: GitHub
- URL: https://github.com/champ96k/quanta_db
- Owner: champ96k
- License: mit
- Created: 2025-05-17T10:55:43.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2025-06-05T08:14:52.000Z (11 months ago)
- Last Synced: 2025-06-09T05:44:22.114Z (11 months ago)
- Topics: dart, dart-lang, dart-library, dart-package, dartlang, db, flutter, flutter-apps, flutter-database, flutter-plugin, local-database, localstorage
- Language: Dart
- Homepage: https://quantadb.netlify.app/
- Size: 5.22 MB
- Stars: 27
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# QuantaDB
[](https://github.com/sponsors/champ96k)
[](https://pub.dev/packages/quanta_db)
[](https://github.com/champ96k/quanta_db/blob/master/LICENSE)
[](https://github.com/champ96k/quanta_db/actions/workflows/dart.yml)
[](https://codecov.io/gh/champ96k/quanta_db)
[](https://quantadb.netlify.app/)
> ⚠️ **BETA RELEASE**
> This project is currently in **beta**. While it's functional and available for use, it may still undergo changes. Please use with caution in production environments and report any bugs or issues.
📚 **Documentation**: Visit our [documentation site](https://quantadb.netlify.app/) for detailed guides and API references.
A high-performance, type-safe NoSQL database for Dart and Flutter applications.
## Features
- 🚀 **Performance**: Optimized for speed with LSM-Tree storage
- 🔒 **Type Safety**: Compile-time type checking and validation
- 🔄 **Reactive**: Real-time data synchronization
- 📊 **Query Engine**: Powerful querying capabilities
- 🔄 **Transactions**: ACID-compliant transactions
- 📈 **Scalability**: Efficient handling of large datasets
- 🛠 **Developer Experience**: Annotation-driven code generation
- 🔄 **Schema Migrations**: Automatic schema version management
- ✅ **Field Validation**: Built-in validation with custom rules
- 🔐 **Access Control**: Field-level visibility control
- 🔄 **Relationships**: Support for one-to-many and many-to-many relationships
## Installation
Add this to your package's `pubspec.yaml` file:
```yaml
dependencies:
quanta_db: ^0.0.6
```
You can install packages from the command line:
```bash
$ dart pub get
```
## Quick Start
```dart
import 'package:quanta_db/quanta_db.dart';
void main() async {
// Open the database
final db = await QuantaDB.open('my_database');
// Define your model
@QuantaEntity(version: 1)
class User {
@QuantaId()
final String id;
@QuantaField(required: true)
final String name;
@QuantaIndex()
final String email;
User({required this.id, required this.name, required this.email});
}
// Insert data
final user = User(id: '1', name: 'John', email: 'john@example.com');
await db.put('user:1', user);
// Query data
final queryEngine = QueryEngine(db.storage);
final users = await queryEngine.query(
Query().where((user) => user.name.startsWith('J'))
);
print('Users: $users');
// Close the database
await db.close();
}
```
## Usage
### Basic Operations
```dart
// Open database
final db = await QuantaDB.open('my_database');
// Put data
await db.put('key', {'name': 'value'});
// Get data
final data = await db.get('key');
// Delete data
await db.delete('key');
// Close database
await db.close();
```
### Using Annotations
QuantaDB provides a rich set of annotations for defining your data models:
#### Entity Annotations
```dart
@QuantaEntity(version: 1)
class User {
@QuantaId()
final String id;
@QuantaField(required: true)
final String name;
}
```
#### Index Annotations
```dart
@QuantaIndex()
final String email;
@QuantaCompositeIndex(fields: ['firstName', 'lastName'])
final String fullName;
```
#### Relationship Annotations
```dart
@QuantaHasMany(targetEntity: Post, foreignKey: 'userId')
final List posts;
@QuantaManyToMany(targetEntity: Group)
final List groups;
```
### Type Support
The code generator supports a comprehensive range of data types:
#### Primitive Types
```dart
final String name;
final int age;
final double score;
final bool isActive;
final DateTime createdAt;
```
#### Complex Types
```dart
final List tags;
final Map metadata;
final Set permissions;
```
#### Enums
```dart
enum UserType { admin, user, guest }
final UserType? userType;
```
### Field Validation
```dart
@QuantaField(
required: true,
min: 0,
max: 120,
pattern: r'^[a-zA-Z]+$'
)
final String name;
```
### Reactive Fields
```dart
@QuantaReactive()
final DateTime lastLogin;
// Watch for changes
final queryEngine = QueryEngine(db.storage);
final stream = queryEngine.watch(
Query().where((user) => user.lastLogin != null)
);
await for (final user in stream) {
print('User logged in at: ${user.lastLogin}');
}
```
## Performance
QuantaDB is designed for speed. Here are benchmark results comparing QuantaDB's performance for 10,000 operations:
| Operation | QuantaDB | Hive | SQLite |
| --------- | -------- | ----- | ------ |
| Write | 30ms | 216ms | 3290ms |
| Read | 9ms | 8ms | 299ms |
| Batch | 15ms | 180ms | 2800ms |
| Query | 25ms | 45ms | 150ms |
**As you can see, QuantaDB demonstrates significantly faster performance across all operations.**
**[Check out the benchmark code here](https://github.com/champ96k/quanta_db/blob/master/example/demo_example/lib/complete_example.dart)** to run it yourself and see the details.
## Why QuantaDB?
Existing local databases for Dart/Flutter often have external dependencies or performance limitations. QuantaDB aims to overcome these challenges by implementing a Log-Structured Merge Tree (LSM-Tree) storage engine from scratch in pure Dart, coupled with an annotation-driven code generation system for a developer-friendly experience.
Our goals include:
- Achieving competitive read and write performance.
- Providing a simple and intuitive API.
- Ensuring data durability and consistency.
- Supporting complex data models with relationships and indexing.
- Offering a reactive query system for real-time updates.
## Architecture
QuantaDB is built with a layered architecture to separate concerns and improve maintainability. The core of the database is the LSM-Tree storage engine.
### High-Level Architecture
Below is a high-level overview of the QuantaDB architecture:
- **Application Layer**: Provides the public API and integrates with the annotation and code generation systems.
- **Core Engine Layer**: Contains the central logic for query processing, LSM storage management, and transactions.
- **Storage Layer**: Implements the core storage components like MemTable, SSTable Manager, Bloom Filters, and Compaction.
- **Platform Layer**: Interacts with the underlying file system and utilizes isolate workers for background tasks.
### Data Flow
Here's a diagram illustrating the typical data flow within QuantaDB:
- Data enters through the API.
- Queries are processed by the Query Engine.
- Write operations go through the MemTable and are eventually flushed to SSTables.
- Read operations utilize Bloom Filters and the MemTable before hitting SSTables.
- Compaction runs in the background to merge and optimize SSTables.
## Additional Information
- [Documentation](https://quantadb.netlify.app/)
- [API Reference](https://pub.dev/documentation/quanta_db/latest/)
- [GitHub Repository](https://github.com/champ96k/quanta_db)
- [Issue Tracker](https://github.com/champ96k/quanta_db/issues)
- [Discussions](https://github.com/champ96k/quanta_db/discussions)
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
- **Tushar Nikam** - [LinkedIn](https://www.linkedin.com/in/tushar-nikam-dev/)
## Contributors
### Code Contributors
### Issue Contributors
> View all contributors and their issues on our [GitHub Issues page](https://github.com/champ96k/quanta_db/issues)
---
Made with ❤️ by the QuantaDB Team
