# VelesDB Mobile Deployment: A Complete Guide to iOS and Android Integration

> Deploy VelesDB on iOS and Android with the velesdb-mobile crate. This guide details native integration using UniFFI-generated Swift and Kotlin bindings for seamless mobile deployment.

- Repository: [Wiscale/velesdb](https://github.com/cyberlife-coder/velesdb)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Yes, VelesDB can be deployed on both iOS and Android devices through the `velesdb-mobile` crate, which compiles the Rust core engine into native libraries with UniFFI-generated Swift and Kotlin bindings.**

The `cyberlife-coder/velesdb` repository ships a dedicated mobile crate that packages the same high-performance vector, graph, and column-store logic used in server deployments into a 15 MB binary (or under 5 MB with compression) capable of running fully offline on mobile hardware.

## Architecture of VelesDB Mobile Deployment

The mobile deployment strategy centers on exposing the existing `velesdb-core` Rust engine through a Foreign Function Interface (FFI) layer, eliminating code duplication while providing idiomatic APIs for each platform.

### Core Engine Reuse via UniFFI

In [`crates/velesdb-mobile/src/lib.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-mobile/src/lib.rs), the `VelesDatabase` and `VelesCollection` structs wrap the core engine using **UniFFI** to generate type-safe bindings. This approach exposes mobile-specific methods including `open`, `createCollectionWithStorage`, `upsert`, `search`, and `multiQuerySearch` directly to Swift and Kotlin without manual JNI or Objective-C bridging code.

The crate compiles to a static library (`.a`) for iOS and a shared library (`.so`) for Android, linking against the same SIMD-optimized kernels found in `crates/velesdb-core/src/simd_native`. When built for aarch64 targets, the mobile library automatically enables ARM NEON instructions for vectorized operations.

### Thread Safety and Memory Management

Both `VelesDatabase` and `VelesCollection` are wrapped in `Arc` (atomic reference counting) within the Rust implementation at `crates/velesdb-mobile/src/lib.rs#L71-L86`. This design allows safe concurrent access from UI threads and background workers on mobile platforms, with the Rust borrow checker enforcing memory safety across the FFI boundary.

### Storage Modes for Constrained Devices

The `StorageMode` enum defined in [`crates/velesdb-mobile/src/types.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-mobile/src/types.rs) provides three quantization levels to balance accuracy against memory constraints:

- **Full**: No compression, maximum recall
- **SQ8**: 4× compression with approximately 1% recall loss (recommended for mobile)
- **Binary**: 32× compression for extreme memory constraints

## Building VelesDB for iOS

The iOS build targets `aarch64-apple-ios` for physical devices and `aarch64-apple-ios-sim` for the simulator. The output is packaged as an `.xcframework` containing the static library and Swift module map.

### Swift Integration Example

After importing the generated Swift bindings into your Xcode project, initialize the database in your app's Documents directory:

```swift
import VelesDB

// Open database in app container
let db = try VelesDatabase.open(path: documentsPath + "/velesdb")

// Create collection with SQ8 compression for 4× memory reduction
try db.createCollectionWithStorage(
    name: "embeddings",
    dimension: 384,            // e.g., MiniLM-L6-v2 vectors
    metric: .cosine,
    storageMode: .sq8
)

// Retrieve collection handle
guard let collection = try db.getCollection(name: "embeddings") else {
    fatalError("Collection not created")
}

// Insert vector with JSON payload
let point = VelesPoint(
    id: 1,
    vector: embedding,
    payload: "{\"title\":\"On-Device Semantic Search\"}"
)
try collection.upsert(point: point)

// Execute nearest-neighbor search
let results = try collection.search(vector: queryEmbedding, limit: 10)
results.forEach { result in
    print("ID: \(result.id), Score: \(result.score)")
}

```

## Building VelesDB for Android

Android builds use `cargo ndk` to compile for multiple ABIs (arm64-v8a, armeabi-v7a, x86_64). The resulting `.so` files and Kotlin bindings are packaged as an AAR for Gradle integration.

### Kotlin Integration Example

Access the native library through the generated Kotlin bindings in your Android project:

```kotlin
import com.velesdb.mobile.*

// Initialize database in private app storage
val db = VelesDatabase.open("${context.filesDir}/velesdb")

// Configure collection with mobile-optimized storage
db.createCollectionWithStorage(
    "embeddings",
    384u,
    DistanceMetric.COSINE,
    StorageMode.SQ8
)

val collection = db.getCollection("embeddings")
    ?: throw IllegalStateException("Collection missing")

// Upsert vector data
val point = VelesPoint(
    id = 1uL,
    vector = modelOutput,
    payload = """{"category":"mobile_rag"}"""
)
collection.upsert(point)

// Perform similarity search
val results = collection.search(queryVector, 10u)
results.forEach { 
    Log.d("VelesDB", "Hit: ${it.id} with score ${it.score}")
}

```

## Advanced Mobile Features

Beyond basic vector search, the mobile deployment supports sophisticated query patterns essential for on-device AI applications.

### Multi-Query Fusion (MQG)

The `multiQuerySearch` method, implemented in `crates/velesdb-mobile/src/lib.rs#L260-L274`, enables running multiple query vectors in parallel and fusing results using **Reciprocal Rank Fusion (RRF)** with a default $k=60$ parameter.

**Swift:**

```swift
let fusedResults = try collection.multiQuerySearch(
    vectors: [queryVariant1, queryVariant2, queryVariant3],
    limit: 10,
    strategy: .rrf(k: 60)
)

```

**Kotlin:**

```kotlin
val results = collection.multiQuerySearch(
    vectors = listOf(q1, q2, q3),
    limit = 10u,
    strategy = FusionStrategy.Rrf(k = 60u)
)

```

### Graph Traversal and Agent Support

The mobile crate includes optional modules for graph operations ([`crates/velesdb-mobile/src/graph.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-mobile/src/graph.rs)) and AI agent utilities ([`crates/velesdb-mobile/src/agent.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-mobile/src/agent.rs)), supporting on-device RAG (Retrieval-Augmented Generation) workflows without network connectivity.

## Performance Characteristics and Binary Size

The mobile build produces a **15 MB** binary for the full-precision engine. Enabling **SQ8** quantization reduces the footprint to under **5 MB** while maintaining sub-millisecond vector search latency on modern ARM chips. The binary includes ARM NEON SIMD kernels from `crates/velesdb-core/src/simd_native`, ensuring hardware-accelerated distance calculations on both iOS and Android devices.

## Summary

- **VelesDB mobile deployment** is supported through the `velesdb-mobile` crate, which compiles the Rust core to platform-specific libraries.
- **UniFFI** generates type-safe Swift and Kotlin bindings from [`crates/velesdb-mobile/src/lib.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-mobile/src/lib.rs), exposing `VelesDatabase` and `VelesCollection` APIs.
- **Storage modes** (Full, SQ8, Binary) in [`crates/velesdb-mobile/src/types.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-mobile/src/types.rs) allow trading recall for memory efficiency on constrained devices.
- **Thread-safe architecture** using `Arc` wrapping enables safe concurrent access from mobile UI and background threads.
- **Multi-query fusion** and graph traversal APIs support advanced on-device AI applications like mobile RAG.

## Frequently Asked Questions

### Does VelesDB mobile require an internet connection?

No. Once the native library is bundled in your iOS or Android app, VelesDB operates entirely offline. The vector search, graph traversal, and data persistence all happen locally on the device using the embedded binary compiled from `velesdb-core`.

### What is the memory overhead of running VelesDB on a mobile device?

The base binary adds approximately 15 MB to your app size, or under 5 MB when using SQ8 quantization. At runtime, memory usage depends on dataset size, but the SQ8 mode provides 4× compression and Binary mode offers 32× compression, allowing million-scale vector databases to fit within mobile RAM constraints.

### Can I use the same Rust core for both server and mobile deployments?

Yes. The `velesdb-mobile` crate links directly against `velesdb-core` without forking the code, ensuring identical search semantics and recall characteristics across platforms. The core's ARM NEON SIMD kernels in `crates/velesdb-core/src/simd_native` automatically activate when targeting mobile aarch64 architectures.

### How do I handle database migrations or schema changes in mobile apps?

The `VelesDatabase` struct provides collection management methods that allow creation, deletion, and inspection of collections at runtime. Since VelesDB uses a file-based storage backend, you can implement migration logic in your Swift or Kotlin code by checking collection metadata and re-indexing data when your app updates, treating the database file similarly to SQLite migrations.