Posted on Apr 25

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