NyaruDB2

What is NyaruDB2?

NyaruDB2 is an experimental, embeddable database library for iOS & macOS, written in Swift. Its primary goal is to explore table partitioning and indexed queries in a mobile context—think of lightweight shards instead of one monolithic file.

⚠️ Disclaimer: This is very much a proof-of-concept. APIs may change, and it’s not intended for production use… yet!

Key Concepts

  • Partitioning (Sharding): Split collections into multiple files (“shards”) based on a key (e.g. a category field), reducing I/O for targeted queries.
  • Indexes: Built-in B-Tree indexes accelerate equality, range, prefix and substring searches.
  • Compression: Supports multiple algorithms (none, GZIP, LZFSE, LZ4) to trade off size vs. CPU.

Core Features

  • Actor-Backed B-Tree Indexes Provide equality and range queries (equal, greaterThan, between, startsWith, contains) using a thread-safe, in-memory B-Tree implementation.
  • Async/Await API Non-blocking insert, fetch, update, and delete operations with a fluent query builder.
  • Pluggable Compression Choose between gzip, LZFSE, or LZ4 on a per-shard basis.

Installation

Add NyaruDB2 to your Package.swift:

// swift-tools-version:5.9
import PackageDescription

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

Then run:

swift package update

Quick Start 

import NyaruDB2

// 1. Initialize
let db = try NyaruDB2(
  path: "AppData",
  shardKey: "category",            // enable partitioning on “category”
  compressionMethod: .gzip,        // compress shards with GZIP
  fileProtectionType: .completeUntilFirstUserAuthentication
)

// 2. Define your model
struct Item: Codable, Equatable {
  let id: Int
  let name: String
  let category: String
}

// 3. Insert documents
let items = [
  Item(id: 1, name: "Apple", category: "Fruit"),
  Item(id: 2, name: "Carrot", category: "Vegetable"),
]
try await db.bulkInsert(items, into: "Inventory")

// 4. Query with auto-shard pruning
var query = try await db.query(from: "Inventory") as Query<Item>
query.where(\.category, .equal("Fruit"))
let fruits = try await query.execute()

print("Fruits:", fruits)

Learn More & Contribute

🔗 Repo: https://github.com/galileostudio/nyarudb2

📄 Docs: https://galileostudio.github.io/nyarudb2/

This project is an open playground for database ideas on mobile. Feedback, stars ⭐, issues and PRs are very welcome!

Demetrius Albuquerque*