LiteDocumentStore 0.1.0

LiteDocumentStore

A high-performance, single-file application data format using C#, SQLite (Microsoft.Data.Sqlite), and Dapper.

Core Architecture

Primary Format

A single SQLite .db file acting as an "Application File Format".

Data Storage Strategy

Treat SQLite as a hybrid relational/document store. JSON data is stored in JSONB format (binary JSON introduced in SQLite 3.45+) for optimal storage efficiency and query performance.

Data Access Layer

Use Dapper for next-to-zero mapping overhead.

Custom Logic

Automatic JSON serialization/deserialization of C# objects into SQLite BLOB columns using JSONB format.

Performance Requirements

• Minimize System Calls: The design must utilize SQLite's ability to be up to 35% faster than raw file I/O for small blobs by reducing open() and close() operations.
• Transaction Batching: Writes should be grouped into transactions to maintain high write speed.
• Async Operations: All database operations are async for optimal performance and scalability.
• JSONB Format: Uses SQLite's JSONB format for binary-optimized JSON storage to eliminate repetitive parsing overhead.

Configuration

The library defaults to WAL (Write-Ahead Logging) mode and synchronous = NORMAL for optimal balance between safety and performance.

Usage

Installation

Build the project:

dotnet build

Requirements

• .NET 10
• SQLite 3.45+ (for JSONB support)

Features

• ✅ Generic Repository Pattern: Type-safe CRUD operations with automatic table naming
• ✅ Async/Await: All database operations are fully async
• ✅ JSONB Format: Uses SQLite 3.45+ JSONB for binary-optimized JSON storage
• ✅ Virtual Columns: Index JSON properties for up to 1,300x faster queries
• ✅ Transaction Support: Batch operations for high-performance writes
• ✅ WAL Mode: Automatically configured for optimal concurrency
• ✅ Zero SQL Injection Risk: Table names derived from types, not user input
• ✅ Cross-Platform: Works on Windows, Linux, and macOS
• ✅ .NET 10: Built on the latest .NET platform
• ✅ Comprehensive Tests: Unit and integration tests with xUnit

Dependencies

• .NET 10
• Dapper
• Microsoft.Data.Sqlite

JSONB Storage Benefits

The library uses SQLite's JSONB functions introduced in version 3.45+:

• More compact storage (binary format)
• Faster queries on JSON data
• Reduced parsing overhead
• Compatible with SQLite's JSON functions

CI/CD

This project uses GitHub Actions for continuous integration and deployment:

• Continuous Integration: Automated builds and tests on every push and PR
• Multi-platform Testing: Tests run on Ubuntu, Windows, and macOS
• Code Quality: Automated code analysis, formatting checks, and security scans
• NuGet Publishing: Automated package publishing on GitHub releases
• Dependency Updates: Dependabot keeps dependencies up to date

See .github/WORKFLOWS.md for detailed CI/CD documentation.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Ensure all tests pass: dotnet test
5. Submit a pull request

CI will automatically validate your changes.

License

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