Lightweight, high-performance embedded database for Swift

NyaruDB2 is an embedded database optimized for iOS and macOS applications, designed to handle large datasets efficiently using modern Swift Concurrency. It provides:

• Automatic Sharding with parallel I/O
• Multi-Algorithm Compression (GZIP, LZFSE, LZ4)
• Actor-Safe B-Tree Indexing
• Cost-Based Query Planner with shard pruning
• Lazy Loading via AsyncThrowingStream

1. Installation
2. Quick Start Example
3. Key Features
4. Architecture
5. Documentation
6. Contributing
7. License
8. Acknowledgements

NyaruDB2 supports Swift Package Manager:

// swift-tools-version:5.9

let package = Package(
    name: "YourApp",
    dependencies: [
        .package(url: "https://github.com/galileostudio/NyaruDB2.git", from: "0.1.0-alpha")
    ],
    targets: [
        .target(
            name: "YourApp",
            dependencies: ["NyaruDB2"]
        )
    ]
)

Requirements:

• Xcode 15+
• Swift 5.9+
• iOS 15+ / macOS 12+

import NyaruDB2

// Define a model
struct User: Codable, Equatable {
    let id: Int
    let name: String
    let createdAt: String
}

// 1. Initialize the database
let db = try NyaruDB2(
    path: "NyaruDB_Demo",
    compressionMethod: .lzfse,
    fileProtectionType: .completeUntilFirstUserAuthentication
)

// 2. Create a partitioned collection
let users = try await db.createCollection(
    name: "Users",
    indexes: ["id"],
    partitionKey: "createdAt"
)

// 3. Bulk insert documents
try await users.bulkInsert([
    User(id: 1, name: "Alice", createdAt: "2024-01"),
    User(id: 2, name: "Bob", createdAt: "2024-02")
])

// 4. Perform a query
var query = try await users.query() as Query<User>
query.where(\User.id, .greaterThan(1))
let results = try await query.execute()
print(results)

• Sharded Storage: automatic partitioning by configurable shard keys
• Multi-Algorithm Compression: GZIP, LZFSE, LZ4 via Compression.framework
• Actor-Safe B-Tree Indexing: configurable minimum degree for performance tuning

• Type-Safe Query Builder: supports 15+ predicates (equal, range, contains, startsWith, etc.)
• Lazy Loading: AsyncThrowingStream for memory-efficient iterating
• Cost-Based Query Planner: selects optimal indexes and prunes shards using statistics

• StatsEngine: CollectionStats, GlobalStats with shard count, document count, and sizes
• IndexStats: tracks value distribution, selectivity, access counts

NyaruDB2/
├── Sources/
│   ├── NyaruDB2/
│   │   ├── Core/
│   │   │   ├── Commons/          # FileProtection, DynamicDecoder
│   │   │   ├── IndexManager/     # BTreeIndex, IndexManager
│   │   │   ├── QueryEngine/      # Query, QueryPlanner, ExecutionPlan
│   │   │   ├── StatsEngine/      # CollectionStats, GlobalStats
│   │   │   └── StorageEngine/    # ShardManager, Compression, StorageEngine
│   │   ├── CollectionEngine/     # DocumentCollection, CollectionCatalog
│   │   └── NyaruDB2.swift        # public API
│   └── Benchmark/                # performance test suite
└── Tests/                        # unit and integration tests

Full API reference:
🔗 https://nyarudb2.docs.example.com

1. Fork the repository
2. Create a feature branch: git checkout -b feature/awesome
3. Commit your changes: git commit -m "Add awesome feature"
4. Push to your branch: git push origin feature/awesome
5. Open a Pull Request

Please see CONTRIBUTING.md for details.

Apache 2.0 © 2025 galileostudio. See LICENSE.

Inspired by the original NyaruDB by kelp404. Many thanks for the foundational ideas.