NyaruDB2: A Mobile-First Experiment in Table Partitioning for iOS

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 query.where(\.category, .equal("Fruit")) let fruits = try await query.execute() print("Fruits:", fruits) Learn More & Contribute

Apr 26, 2025 - 01:29

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)