Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ditto.live/llms.txt

Use this file to discover all available pages before exploring further.

Ditto SDK v5 is a complete rearchitecture built on three years of powering mission-critical applications in retail, healthcare, logistics, and beyond. The result: automatic performance gains, a unified query language across every platform, and a 25% smaller SDK — with a developer experience rebuilt from the ground up.

Faster apps

Automatic performance improvements across queries and sync — your users notice the difference with zero code changes.
  • More responsive apps — query planner optimizations and shared statement caching kick in automatically
  • Lower sync latency — improved storage architecture and session handling get data where it needs to be, faster

Better developer experience

Clean initialization, schema-free iteration, platform-native APIs, and clearer error messages. Your team ships faster.
  • Simpler initialization — clean, modern patterns replace confusing legacy APIs across all platforms
  • No more schemas — start building immediately; iterate faster with field-level sync
  • Error messages that help — clearer diagnostics mean less time debugging, more time building

Production observability

Query internal metrics and debug issues without external tools. Solve production problems in minutes, not hours.
  • Built-in observability — query system metrics and configuration directly with DQL
  • Faster device reconnection — better session handling gets devices back online after network interruption

Simpler codebases

One query language, cleaner APIs, 25% smaller SDK. Less code to maintain means more time building features.
  • One query language — DQL handles all data operations consistently across mobile, web, and server
  • 25% smaller SDK — removed legacy code means faster startup and smaller bundle sizes

Future-proof foundation

Modern networking, platform modernization, extensible architecture. Built for the next 3+ years of edge computing.
  • Future-ready networking — modern transport architecture for tomorrow’s edge connectivity and mesh topologies
  • Most rigorously tested release — 44 scenarios, 9 builds, 40+ concurrent devices, 24-hour stability runs

Lower risk migrations

AI-powered tools, backwards compatibility, and incremental rollout support. Deploy with confidence.
  • Backwards compatible with v4.11+ — mixed-version meshes sync seamlessly; deploy incrementally with zero downtime
  • Comprehensive migration guides — step-by-step guides for every platform with before/after examples, common pitfalls, and testing checklists
  • AI migration scripts — platform-specific tools that intelligently transform v4 patterns to v5 equivalents with a 90%+ success rate

​
Rearchitected for Speed and Usability

​
Developer Experience Reimagined

v5 isn’t just faster — it’s fundamentally easier to work with. We’ve rebuilt the SDK around modern platform conventions and simplified every API surface.

​
Clean, Config-Based Initialization

Gone are the days of tangled initialization code mixing connection, authentication, and configuration logic. v5 introduces a clean, predictable pattern with clear separation of concerns: Configure → Initialize → Authenticate → Sync. Type-safe configuration with compile-time validation means fewer runtime surprises. No more disableCloudSync = true workarounds. No more updateTransportConfig hacks mixed into startup code. Just clean, explicit, easy-to-reason-about setup. 
// Configure
let config = DittoConfig(databaseId: "my-app")
    .persistenceDirectory(path)
    .minimumLogLevel(.info)

// Initialize
let ditto = try DittoFactory.create(config)

// Authenticate
ditto.auth.expirationHandler = { /* handle token refresh */ }
await ditto.auth.login(provider, token)

// Sync
await ditto.sync.start()

​
Platform Modernization Across the Board

We’ve rebuilt each SDK to embrace modern platform conventions, making Ditto feel truly native on every ecosystem — not like a cross-platform compromise.
Full Swift 6 support with Sendable conformance and async/await patterns replacing callbacks throughout the SDK. Swift Package Manager is now the only distribution method — CocoaPods is retired. Deployment targets raised to iOS 15+ and macOS 12+. Your Swift code is cleaner, safer, and easier to reason about.
The Android SDK has been completely rewritten from scratch using Kotlin Multiplatform. This isn’t a wrapper around a C library — it’s native Kotlin architecture shared across JVM platforms. Legacy callback patterns are gone, replaced with Flow-based reactive streams that integrate seamlessly with modern coroutine architectures. Auto-close patterns and use-after-close guards prevent the resource management bugs common in long-running apps.
.NET 8 is now required (upgraded from .NET Standard 2.1). DittoTransportConfig is now immutable using C# records, enabling compile-time safety and LINQ-style configuration patterns. Namespaces have been reorganized by feature: DittoSDK.Auth, DittoSDK.Store, DittoSDK.Sync, and more — making discovery intuitive and imports explicit.
All external dependencies have been removed from the JavaScript SDK. Smaller bundles, faster load times, and zero npm audit warnings. The cbor-redux dependency is now vendored internally. WebSocket sync is disabled by default — explicitly enable it only when needed, keeping the default footprint minimal.
Significant memory leak fixes & improved OS type safety. Scoped execute() APIs ensure resources are properly released even in long-running server processes.
The DocumentID class has been removed — document IDs are now raw JSON values (String, int, bool, null, List, Map). Resource management has been overhauled with automatic cleanup replacing manual runGarbageCollection() calls.
Custom log callbacks give Rust applications full control over log routing. Simplified error codes replace cryptic internal error strings. Future-based patterns replace callback interfaces throughout the API surface.
Significant API surface reduction with full C++11 compliance. Error handling modernized with clearer diagnostics and structured error types.

​
Error Messages That Actually Help

We’ve completely overhauled error reporting across the SDK. Clearer DQL parser errors, improved diagnostics, and more actionable error messages mean less time debugging and more time building. When something goes wrong, you’ll know exactly what happened and how to fix it — no more cryptic error codes, no more hunting through stack traces.

​
Schema-Free by Default

v5 changes the default data model from whole-object replacement to field-level merging. Documents are stored as MAP types by default, meaning concurrent updates to different fields are preserved — not overwritten. Unlike v4’s strict whole-object replacement semantics, v5 defaults to schema-free mode where changes merge intelligently at the field level. Automatic type inference means you can iterate rapidly without writing complex schema migrations or managing database versions. Define schemas only where you need them — like attachments and counters — and let Ditto handle the rest.
  • No upfront schema definitions — insert data immediately and iterate without type migrations
  • Field-level delta sync — only changed fields sync across the mesh, reducing bandwidth
  • Automatic conflict resolution — when two peers update different fields simultaneously, both changes survive
  • Faster prototyping — start building immediately, add structure as your application evolves
For teams migrating from v4: strict mode (whole-object replacement) is preserved with a single config flag. Your existing behavior is unchanged by default on migration.

​
Production-Ready Observability

v5 extends the ability to query your Ditto instance’s internal state using DQL itself. Virtual collections expose runtime metrics, configuration, and performance data as queryable collections — no external tools, no log aggregation delays. 
-- Query all active subscriptions
SELECT * FROM system:system_info
WHERE starts_with('local_subscriptions', key)
Available virtual collections:
CollectionWhat it exposes
system:system_infoRuntime configuration, platform details, and deployment parameters
system:request_historyQuery the history of requests processed by the Ditto store, including execution metadata and error details.
system:shared_statementsQuery plan cache — which queries are being reused and how they’re being optimized
Virtual collections are local-only — they never replicate across the mesh — making them safe for production monitoring without affecting sync behavior.

​
Remote Query from the Portal

Combine virtual collections with the Ditto Portal’s remote query feature to debug production issues from your desk. Query system:metrics against any device in your fleet in real time — no SSH, no app updates, no special builds. It’s like having a SQL console into every device in your deployment. Investigate a customer-reported performance issue by running DQL directly against their device to inspect query execution times, verify configuration, or examine the query plan cache.

​
Performance You Get for Free

v5’s intelligent query planner automatically optimizes your queries — no code changes required. Upgrade and your app gets faster. Query engine improvements:
  • Automatic ID scan conversion — equality filters on _id use fast document ID scans instead of full collection scans
  • Deferred document fetching — for queries needing only specific fields, full documents aren’t fetched until absolutely necessary
  • Covering index improvements — more queries satisfied entirely from indexes, without touching document data
  • Shared statement cache — query plans are cached and reused across executions, with automatic invalidation when schemas change
  • Streaming DISTINCT — results stream instead of buffering everything in memory; lower overhead on constrained devices
  • Specialized COUNT(*) plans — highly optimized count queries that skip unnecessary work
  • Statistics-driven planning — the query planner uses real collection statistics for cost-based optimization on Big Peer
Sync and storage improvements:
  • Tiered blob storage — keeps frequently-accessed data hot; moves cold data to efficient storage; smaller sync updates avoid unnecessary disk I/O
  • Session reset avoidance — better reconnection logic minimizes redundant re-sync when devices rejoin the mesh
  • Batched updates — multiple store operations batched at the SQLite level for fewer round trips
  • Optimized fsync policy — sync operations avoid forcing files to disk by default, dramatically reducing latency on mobile
Networking improvements:
  • UDP multicast support with packet loss resilience for fast local mesh discovery
  • Multi-NIC support on Android — sync across multiple network interfaces simultaneously
  • WiFi Aware UDP transport — faster direct device-to-device connectivity on Android
  • Connection watchdogs — stalled connections torn down automatically to prevent resource exhaustion
  • Faster peer crash detection — stops connection attempts in under 15 seconds
All of these gains are automatic. Upgrade to v5 and your app gets faster with zero code changes.

​
DQL Everywhere: One Query Language to Rule Them All

Say goodbye to maintaining multiple query systems. Ditto v5 makes DQL (Ditto Query Language) the single data API across every platform — mobile, web, and server. We’ve completely removed the legacy query builder and retired 62+ deprecated APIs across 7 languages, leaving you with one powerful, unified interface. If you know SQL, you already know DQL. Familiar syntax like SELECT, INSERT, UPDATE, and DELETE means faster onboarding for new developers and zero context switching between platforms. New DQL capabilities ship once and every platform benefits simultaneously. New in DQL v5:
  • CASE/WHEN/ELSE — build conditional logic directly in queries without pulling data into the app layer
  • BETWEEN — clean range comparisons for dates, numbers, and more
  • ANY / EVERY — search within arrays and objects; perfect for tags, attributes, and nested structures
  • Array & object transformation — object_set, object_unset, object_concat, array_contains, array_length, and 60+ more built-in functions
  • Date/time operations — date_add, date_sub, date_diff, date_format, date_range for rich temporal queries
  • CREATE INDEX / DROP INDEX — explicit index management on Big Peer for production query tuning
  • PROFILE statement — analyze query execution plans and diagnose slow queries
  • INSERT ... ON ID CONFLICT — fine-grained conflict strategies: FAIL, DO NOTHING, or DO UPDATE
  • Remote UPDATE, INSERT, DELETE — full write support via remote query, not just SELECT
Write queries once, deploy everywhere. Your team moves faster, your codebase stays cleaner, and your developers stay productive.

DQL Reference

Full language reference, syntax guide, and function library.

​
The Most Tested Ditto Release Ever

This is production-ready infrastructure, not a move-fast-and-break-things release. v5 has been through the most rigorous testing program in Ditto’s history. Mesh testing at scale:
  • 40+ concurrent devices running simultaneously across iOS, Android, and mixed-platform meshes — real devices, real network conditions, real data
  • 44 test scenarios across 9 build configurations covering every combination of platform, transport, and deployment pattern
  • 24-hour continuous stability runs under sustained load to catch memory leaks, connection edge cases, and long-running behavior that only surfaces after hours of operation
Real-world data and networks:
  • Datasets validated from 1MB up to 50MB+ product catalogs, retail inventories, and healthcare records
  • LAN, BLE, WiFi Aware, AWDL, and mixed transport tested under network partitions, poor connectivity, and intermittent failures
  • Background/foreground transitions, crash recovery, memory pressure, and connection churn — the cases that break normal databases
v4 ↔ v5 backwards compatibility: Extensively tested heterogeneous meshes mixing v4.11+ and v5 devices. Your iOS app on v5 syncs perfectly with Android devices still on v4. Deploy incrementally, validate in production, rollback if needed — data format is unchanged.

​
Migration Made Simple

We know migrations can be daunting. That’s why we’ve built tools and strategies to make the v4 → v5 transition as painless as possible.

​
AI-Powered Migration Assistants

We’ve built AI migration assistants for every SDK that automate the code transformation process. These aren’t simple find-and-replace tools — they understand your code structure and intelligently transform v4 patterns to v5 equivalents: callbacks to async/await, legacy query builder to DQL, old initialization to DittoConfig.
  • 90%+ automated migration success rate across complex real-world codebases, including our own sample apps and customer projects
  • Platform-specific intelligence — each tool understands the nuances of Swift, Kotlin, C#, JavaScript, Rust, and more

​
Incremental Migration Strategy

  • No big-bang deployments — deploy to a subset of devices, validate with real production traffic, and expand at your own pace
  • Mixed mesh support — run v4.11+ and v5 devices in the same mesh during your migration; sync works seamlessly across versions
  • Rollback safety — if you encounter issues, redeploy your v4 build; data remains intact with no format changes

​
Migration Guides

Start with your platform’s migration guide:

Swift

Kotlin

Flutter

React Native

JavaScript (Web)

JavaScript (Node.js)

Java

C#

C++

Rust

v4 receives 18 months of long-term support including security patches and critical bug fixes. Take your time — new features ship to v5 only, but your v4 production deployments are supported well into 2026.

​
Full Release Notes

The highlights above only scratch the surface. Every SDK has its own set of platform-specific improvements, bug fixes, and API refinements that didn’t make the headliner list — but matter to you if you’re shipping on that platform. Find the full changelog for your language:

Swift

Kotlin

Flutter

React Native

JavaScript (Web)

JavaScript (Node.js)

Java

C#

C++

Rust

Go