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*