​

Ditto SDK 5.2 - Troubleshoot Faster. Operate Better.

​

Release Overview

​

Release Summary

​

1. Troubleshooting: Find and Fix Problems Faster

​

Generate and query support bundles with DQL

EXECUTE FUNCTION system_request_support_bundle()

SELECT * FROM system:support_bundles

​

See which documents aren’t syncing

​

More metrics, quieter logs

​

2. Wireless Stability: Bluetooth, Wi-Fi Aware, Apple P2P Wi-Fi

• Bluetooth Low Energy (BLE) is a short-range, low-power radio in nearly every phone. It’s always available, but it has less bandwidth.
• Wi-Fi Aware lets Android devices connect directly over Wi-Fi without a router or access point in the middle. It has more bandwidth for data transfer.
• Apple Wireless Direct Link (AWDL) is Apple’s version of Wi-Fi Aware. It’s the technology behind AirDrop, and it lets Ditto sync between nearby Apple devices without a router.

​

Bluetooth LE on Android handles channel failures gracefully

​

Wi-Fi Aware has better mesh formation and stability

• Meshes of three or more devices no longer split into isolated pairs that stop syncing with the rest of the mesh.
• When a connection looks unhealthy, Ditto refreshes its discovery sessions instead of restarting the whole Wi-Fi Aware stack.
• A subsystem restart no longer tears down a connection while a data path is carrying sync traffic, and rapid transport restarts no longer disrupt active connections.
• Two peers that discover each other at the same time no longer create competing connections that fail during startup.
• Connections no longer stall during concurrent peer discovery and connection updates, and Android network resources are released after peers disconnect, which prevents failures during repeated reconnects.

​

Apple peer-to-peer Wi-Fi recovers on its own

​

3. Connections: Faster Reconnects and Stalled-Connection Detection

​

Faster reconnects to peers you’ve seen before

​

Stalled connections are detected

​

Connection limits are enforced correctly

​

4. Memory and Storage Health

​

Live queries hold less memory

• Query results stay compact until you read them.
• Observers no longer keep observed documents fully decoded between updates, and reading a document no longer pins its decoded form in memory.
• Observers whose queries can’t be updated incrementally, such as projections or index-backed lookups, no longer keep a copy of the previous result set.
• Peak memory is lower while an observer builds its callback result.

​

Less wasted work

​

Bounded storage on long-running devices

​

Oversized documents no longer stall sync

​

5. Encryption at Rest for the SDK Data Store - Swift & Kotlin

​

Encrypt the local store with your own key

let keyBytes: Data = try loadKeyFromKeychain() // 32 bytes
var config = DittoConfig(
    databaseID: "REPLACE_ME_WITH_YOUR_DATABASE_ID",
    connect: .server(url: "REPLACE_ME_WITH_YOUR_URL")
)
config.encryptionKey = try DittoEncryptionKey.raw(keyBytes)
let ditto = try await Ditto.open(config: config)

val keyBytes: ByteArray = loadKeyFromSecureStorage() // 32 bytes
val config = DittoConfig(
    databaseId = "REPLACE_ME_WITH_YOUR_DATABASE_ID",
    connect = DittoConfig.Connect.Server(url = "REPLACE_ME_WITH_YOUR_URL"),
    encryptionKey = DittoEncryptionKey.raw(keyBytes)
)
val ditto = Ditto.open(config)

​

Typed encryption errors

​

Wipe a device cleanly

​

Apply System Parameters Before Ditto Starts

• Startup-only parameters can be set. Before, they could not be changed from the default.
• There is no window where Ditto unexpectedly runs on the defaults between open() and your ALTER SYSTEM call.
• Invalid names or values fail at open() instead of being silently ignored, so a typo shows up on the first run.

let config = DittoConfig(
    databaseID: "REPLACE_ME_WITH_YOUR_DATABASE_ID",
    connect: .server(url: "REPLACE_ME_WITH_YOUR_URL"),
    systemParameters: [
        "transports_websocket_so_keepalive_idle_secs": 60
    ]
)
let ditto = try await Ditto.open(config: config)

val config = DittoConfig(
    databaseId = "REPLACE_ME_WITH_YOUR_DATABASE_ID",
    connect = DittoConfig.Connect.Server(url = "REPLACE_ME_WITH_YOUR_URL"),
    systemParameters = mapOf(
        "transports_websocket_so_keepalive_idle_secs" to 60
    )
)
val ditto = Ditto.open(config)

const ditto = await Ditto.open({
  databaseID: "REPLACE_ME_WITH_YOUR_DATABASE_ID",
  connect: { url: "REPLACE_ME_WITH_YOUR_URL" },
  systemParameters: {
    transports_websocket_so_keepalive_idle_secs: 60,
  },
})

​

Upgrading to 5.2

​

Behavior changes to plan for

• startSync() fails with a configuration error if ngn_sync_enabled is set without ngn_data_streams_enabled. Previously the setting was silently ignored.
• A Small Peer drops a replication diff that would push a document over the hard size limit. That document gets no more updates until it’s evicted and synced again.
• Most virtual-collection observers fire only when data changes. Code that relied on periodic callbacks should query on its own schedule instead.
• The SQLite write-ahead log size monitor and automatic free-space reclaim are on by default.
• Flutter desktop: the default persistence directory moves to the application support directory. Existing databases in the previous location are still found when DittoConfig.persistenceDirectory is null.
• C#: .NET apps that target x86, ARM, or ARM64 Windows fail at compile time. Set DittoNativeWinSkipArchitectureValidation to true to bypass the check.
• Kotlin: DittoStore.newAttachment overloads that take Map<String, Any?> metadata are deprecated and throw IllegalArgumentException when a value isn’t a String. Use the new Map<String, String> overloads.

​

New warnings after upgrading

• Swift and Kotlin: the passphrase encryption error cases are deprecated in favor of the typed encryption errors.
• Kotlin: DittoStore.newAttachment overloads that take Map<String, Any?> metadata are deprecated. Use the Map<String, String> overloads.
• The network_enable_ngn and replication_over_ngn system parameters are deprecated in favor of ngn_data_streams_enabled and ngn_sync_enabled. The old names still work.
• Ditto logs a warning when the SQLite write-ahead log keeps growing. It usually points to a long-held read transaction.

​

Rollback

​

5.2.0 Common Changelog

• A new system:sync_degradations virtual collection for querying documents whose sync status is degraded (#DS-1314).
• A new system:support_bundles virtual collection for querying diagnostic support bundles with DQL (#SDKS-4758).
• The system_request_support_bundle() DQL function, which generates a support bundle on demand. Run it with EXECUTE FUNCTION system_request_support_bundle(). Not available in the JavaScript Web SDK (#SDKS-4758).
• The document sync protocol can trace how document changes propagate through the mesh, for diagnostics. Trace propagation through a Big Peer isn’t supported yet (#DS-1345).
• On Small Peers, the preview DQL function system_trace_sync_propagation requests propagation traces for later document changes in the same write transaction (#DS-1460).
• ditto.query.requests, ditto.query.failed, and ditto.query.execution_time metrics in system:metrics (#QE-1155).
• Ten new counters under ditto.network.dsoq.* in system:metrics. They expose connection callback failures, malformed messages, reliable and unreliable stream lifecycles, and certificate verification failures (#NETW-1758).
• The Small Peer system:metrics collection now exposes peer discovery counts, AWDL interface status, payload byte totals, and last-activity timestamps (#NETW-1989).
• The first 10,000 entries in system:indexes are now included in the logs bundle to help diagnose problems (#SPO-76).
• Small Peer info now includes disk usage entries for specific files in the ditto_store subdirectory (#SPO-657).
• INFO logs for DQL observer and subscription lifecycle events (#SPO-447).
• ngn_data_streams_enabled and ngn_sync_enabled system parameters for turning on Ditto Data Streams and sync over Data Streams separately (#NETW-2384).
• The forced_login_refresh_jitter_ms Small Peer system parameter, which sets the maximum random delay before refreshing login credentials after a remote peer rejects the current JWT (#NETW-2252).
• Opt-in transports_websocket_so_keepalive_user_timeout_enabled and transports_tcp_so_keepalive_user_timeout_enabled system parameters which close connections when sent data goes unacknowledged for too long. Available on Linux and Android only (#SPO-1197).
• The diffcaster_fixed_mesh_size system parameter for multicast sync on Small Peers, which spreads relay and repair responsibility across a fixed-size mesh. Set the same group size on every peer. The value takes effect at startup (#DS-1493).

• Queries that use a composite index with mixed ASC and DESC keys now return results in the correct order (#CCB-85).
• Indexed SELECT * queries now fetch full documents instead of reading only from the index (#CCB-85).
• Inserts into indexed collections that were empty before an upgrade now succeed (#CCB-88).
• DELETE and EVICT statements with a USE IDS clause now delete the specified documents. Previously the workaround was to filter on the _id field directly, for example WHERE _id = 1 (#QE-1186).
• ANY ... SATISFIES conditions that check more than one property, such as ANY car IN cars SATISFIES car.color = 'blue' AND car.type = 'SUV' END, are no longer dropped from queries (#QE-1144).
• Results are now sorted correctly when ORDER BY refers to a projection alias in a plan that sorts before fetching documents (#QE-1166).
• The query planner now generates correct index span ranges for expressions of the form constant operator field, such as 1 < a (#QE-1212).
• SELECT statements with long AND or OR chains in the WHERE clause no longer crash the app (#SDKS-4435).
• DQL requests that end abruptly, for example through StoreObserver::cancel(), now stop cleanly and release their resources, including the transaction (#QE-1176).
• Observers no longer stall when many are active at the same time (#SPO-1114).
• On Small Peers, retrying completion of a write transaction that’s already complete no longer cancels another write transaction that’s still in progress (#DS-1409).
• Completing a write transaction while an operation callback is still active now reports that the transaction is in use instead of hanging. You can retry completion after the callback returns (#DS-1410).
• Requesting an attachment that no document references anymore now delivers a terminal Deleted status to the fetch callback instead of retrying forever (#DS-842).
• On-disk logs no longer lose entries when log files rotate in quick succession, such as during heavy logging (#DXO-250).
• Peers that authenticate right after a revocation is created are no longer rejected. Revocations apply only to certificates issued before the revocation (#NETW-2280).
• Invalid TLS identity and certificate configuration now returns errors you can act on instead of being silently ignored or panicking (#NETW-2080).
• TLS peers with mismatched certificate identities are no longer retried over and over during peer discovery (#NETW-2378).
• A malformed datagram for a stream that hasn’t opened yet can no longer stall the connection. The datagram is dropped after its first unrecoverable decoding error (#NETW-1758).
• Mesh connections now limit how many incoming messages they buffer, to prevent excessive memory use during peer-to-peer sync (#NETW-2192).
• Peer-to-peer connections now reject malformed handshake metadata without disrupting the connection process (#NETW-2198).
• The presence graph no longer keeps disconnected client connections after a reconnect or a permanent connection failure (#NETW-2200).
• Forwarded IPv6 traffic with extension headers now preserves the correct upper-layer protocol (#NETW-2201).
• Repeated mDNS address refreshes no longer leave stale TCP connections behind, so Ditto stops trying old addresses after a peer’s address changes (#NETW-2212).
• QUIC path RTT and MTU metrics no longer keep stale per-peer values after a connection closes. Their aggregate values now reflect only live connections (#NETW-1766).
• Wi-Fi Aware connections now release Android network resources after peers disconnect, which prevents failures during repeated reconnects (#NETW-2079).
• mesh_chooser_max_wlan_connections now limits inbound and outbound LAN connections together. Previously, a peer could hold about twice the configured number (#SPO-1201).
• mesh_chooser_max_wlan_connections is now used even when you set it to its default value. Previously, Ditto used the deprecated mesh_chooser_max_wlan_clients instead (#SPO-1201).
• The deprecated mesh_chooser_max_wlan_clients is now used as a fallback even when you set it to its default value (#SPO-1201).
• When mesh_chooser_at_capacity_action is DropOldest or DropNewest, Ditto now waits until the incoming peer has finished connecting before it disconnects an existing peer. Previously a peer that never finished connecting could cause a healthy peer to be dropped (#SPO-1201).
• Turning on Ditto Data Streams while keeping sync on legacy channels no longer skips TCP listener auto-start, which could silently break LAN sync (#NETW-2384).
• Multicast sync now pauses sending when its configured network interface disappears and resumes once it’s back. This prevents repeated send errors and excessive log rotation (#NETW-2158).

• DQL query results stay compact until you read them, which reduces memory use for large result sets and store observers (#QE-1093).
• DQL store observers no longer keep observed documents fully decoded between updates, which reduces memory use when observing collections of large documents (#QE-1093).
• DQL store observers whose queries can’t reuse the previous result incrementally, such as projections or index-backed lookups, no longer keep a copy of the previous result set between updates (#QE-1093).
• Reading a document, including the documents a store observer delivers on each update, no longer pins its decoded form in memory. This reduces the memory that long-lived observers keep (#QE-1096).
• Peak memory use is lower while DQL store observers build callback results, especially for large result sets. Observer behavior and query results are unchanged (#SDKS-4510).
• Reconnecting to a recently seen peer over the TCP/TLS LAN transport can now use an abbreviated TLS handshake, which cuts reconnection time after a network interruption (#NETW-1027).
• Reconnecting to a recently seen peer over the UDP/NGN LAN transport is now faster after a network interruption, because the encrypted session is resumed instead of renegotiated (#NETW-1767).
• LAN peer discovery on Linux and Android now causes smaller network traffic spikes when many Small Peers start at the same time. Default Apple and Windows LAN discovery is unchanged (#SPO-1038).
• Most virtual-collection observers now fire only when data changes. Previously they fired periodically whether or not anything changed (#QE-1139).
• Store observers no longer re-run their queries after writes to collections they don’t observe (#QE-1116).
• Native WebSocket connections now turn on TCP keepalive (SO_KEEPALIVE), on both outbound client sockets and accepted server sockets. It acts as a kernel-level backstop for a connection whose runtime or timers have stalled. It’s on by default with a 30-second idle threshold, a 10-second probe interval, and 3 probes. You can configure it with the new transports_websocket_so_keepalive_enabled, _idle_secs, _interval_secs, and _retries system parameters. Browser and Wasm clients aren’t affected (#SPO-1164).
• Setting ngn_sync_enabled without ngn_data_streams_enabled now makes startSync() fail with a configuration error. Previously the setting was silently ignored (#NETW-2384).
• When a Small Peer receives a replication diff that would push a document over the hard size limit, it now drops the diff silently. The document gets no more updates until it’s evicted and synced again (#SPO-1008).
• Multicast peers that need the same attachment no longer each request it, which cuts request traffic by about 75% at the default settings (#DS-1632).
• attachments_want_suppression_threshold (default 1) and attachments_want_max_consecutive_suppressions (default 3) system parameters for tuning multicast attachment requests (#DS-1632).
• Pending multicast attachment requests retry as soon as a peer joins the group, which speeds up recovery after a network split (#DS-1632).
• Reliable UDP multicast changes requested on Android or iOS while sync is running now take effect after sync restarts. The active transport stays in place until the new configuration passes validation (#SDKS-4471).
• Small Peers now keep the SQLite write-ahead log from growing without bound on long-running devices, and reclaim free disk space automatically. If the log keeps growing, Ditto logs a warning that usually points to a long-held read transaction (#SPO-671).
• The Small Peer diagnostic support bundle now includes system:request_history entries (#SPO-1077).
• The UDP transport now logs retryable address and interface lookup failures at debug level instead of error level (#SPO-327).
• Sync on Streams and Attachments on Streams now write fewer repetitive session logs, and expected missing-session disconnects are logged as debug events (#SPO-328).
• The store observer API documentation now explains how to use signal-next to handle backpressure, and how pending updates collapse into at most one callback with the latest result (#SDKS-179).

• The network_enable_ngn and replication_over_ngn system parameters, in favor of ngn_data_streams_enabled and ngn_sync_enabled. The old names still work (#NETW-2384).

​

Swift-Specific Changes

• Encryption at rest with a raw key through DittoConfig.encryptionKey.
• Ditto.close() and Ditto.deleteStore(databaseID:persistenceDirectory:) for closing and deleting a local store, for example on logout.
• Typed encryption errors when a store fails to open: keyRequired, keyUnexpected, keyInvalid, unsupportedScheme, or metadataCorrupt. The passphrase error cases are deprecated.
• Set system parameters in DittoConfig.systemParameters instead of running ALTER SYSTEM after open. Ditto applies them before it starts, so startup-only settings now take effect.
• Boolean arguments created with JSONSerialization are stored as booleans instead of 0 or 1.
• AWDL peer-to-peer connectivity recovers automatically after temporary network setup failures.

​

5.2.0 Swift Specific Changes

• DittoConfig.encryptionKey for encryption at rest with a raw key (#SDKS-4775).
• Ditto.close() and Ditto.deleteStore(databaseID:persistenceDirectory:) for closing and deleting a local store (#SDKS-4662).
• Opening a store can now fail with a typed encryption error: keyRequired, keyUnexpected, keyInvalid, unsupportedScheme, or metadataCorrupt (#SDKS-4805).
• DittoConfig.systemParameters for applying system parameter overrides when opening a Ditto instance (#SDKS-1634).

• Boolean arguments to DittoStore.execute created with JSONSerialization are now stored as booleans instead of 0 or 1 (#SDKS-4104).
• AWDL peer-to-peer connectivity on Apple platforms now recovers automatically after temporary network setup failures instead of staying unavailable until the app restarts (#NETW-2081).

• The passphrase encryption error cases (#SDKS-4805).

​

Ditto SDK 5.1 — Faster Local Queries. More Capable Query Engine.

• Evictions are 53.6× faster and deletes are 43.0× faster on average. This speeds up routine local data clean-up, like clearing the orders from a point-of-sale terminal.
• A full-collection COUNT(*) fell from 149.03 ms to 0.89 ms, which is 167× faster on average. This speeds up badge counts and dashboard totals across an app.

• JOIN combines local collections in a single SELECT, removing the need to run separate queries and merge their results in application code.
• ADVISE looks at a query and tells you the indexes to create to make it faster, all without running it or reading a document.

• If a device is lost or stolen, it’s easier to revoke the device’s certificate, disconnect it from the mesh, and prevent the device from sending or receiving data.
• Revocations travel peer to peer and reach devices even when they can’t see the cloud. Connections from revoked peers are terminated and refused.

• Identifying problems is easier with better tools for analyzing deployed devices, starting with support bundles that capture the device’s effective configuration.
• Corrupted replication metadata is detected and rebuilt automatically, so field issues can be solved without a site visit.

• Multicast allows Ditto to scale to large networks with many edge devices. Edge devices subscribe to a shared group for data sync, which has lower connection cost at scale.
• Opt-in beta capability in the Swift, Kotlin/KMP, Flutter, and Rust SDKs. Support will expand to additional SDKs in the future.

• Upgrading to Ditto SDK 5.1 changes the on-disk index format.
• If you need to downgrade from Ditto SDK 5.1 or later, migrate through Ditto 5.0.2+. You can also migrate through Ditto 4.14.6+.

​

1. Performance: Faster Queries, Lower Memory Use

​

Android retail benchmark

​

Dramatically faster document counts

​

Lower memory use

​

2. Query Engine: New Ditto Query Capabilities

​

Join collections locally

SELECT task._id, task.title, project.name
FROM tasks AS task
JOIN projects AS project ON task.projectId = project._id
WHERE task.status = 'open'

​

Create composite indexes

CREATE INDEX IF NOT EXISTS status_created_idx
ON tasks (status, createdAt DESC)

SELECT * FROM tasks
WHERE status = 'open'
ORDER BY createdAt DESC

​

Find the right indexes with ADVISE

ADVISE SELECT * FROM tasks WHERE estimateHours > 8

{
  "advice": {
    "statement": "select * from tasks where estimateHours > 8",
    "suggestedIndexes": [
      {
        "collection": "tasks",
        "reason": "range predicates on `estimateHours`",
        "statement": "CREATE INDEX IF NOT EXISTS adv_tasks_estimateHours ON default:`tasks` (`estimateHours` ASC)"
      }
    ]
  }
}

​

Return changed documents with RETURNING

UPDATE tasks
SET status = 'done'
WHERE projectId = 'proj-42' AND status = 'open'
RETURNING _id, status

​

Control long-running requests

​

3. Security: Expanded Certificate Revocation

​

4. Troubleshooting: Identify Problems and Recover Automatically

• A configurable Unix debug_socket lets you remotely run DQL diagnostics against an edge device.
  • You can inspect a live device directly rather than reproducing the problem in a lab.
• Nine new network counters under ditto.network.dsoq.* surface Ditto Sync over QUIC (DSOQ) protocol failures in your existing production metrics, without debug logs.
• SQLite metrics distinguish the application data store from replication metadata databases on supported Unix platforms, showing which one is driving disk activity.

​

5. Transport at Scale: Multicast Beta

​

Upgrading to 5.1

​

Tested rollback compatibility

​

Swift-Specific Changes

• Store observers now deliver callbacks on the queue specified by the deliverOn parameter.
• The store observation handler type aliases are now @Sendable.
• Exceptions thrown by application callbacks preserve their original call stack, so crash reporters attribute them to the throwing code instead of to Ditto.
• Custom identity providers no longer stall the SDK during the first credential refresh.

​

Platform changes

• Intel (x86_64) Mac support and tvOS support are removed.
• DittoSwiftTools now requires iOS 15+, Mac Catalyst 15+, or macOS 12+.
• The bundled DittoSwiftPresenceViewer is removed. Use DittoPresenceViewer from DittoSwiftTools instead.
• The CBOR enum and obsolete CBOR-specific store errors are deprecated.

​

Swift Specific Changelog

• DittoMulticastBetaConfig and DittoPeerToPeer.multicastBeta for configuring the beta reliable UDP multicast transport. The transport is disabled by default and currently supported on iOS and macOS. On iOS, changes requested while sync is active take effect after sync is stopped and successfully started again, when Ditto validates the required platform configuration. (#SDKS-4471)
• DittoConnectionType.multicast enum option representing beta reliable UDP multicast connections. The transport is currently supported on iOS and macOS. (#SDKS-4471)
• DiskUsageInspectorView in DittoSwiftTools: a SwiftUI diagnostic view that shows live total disk usage, health status against an adjustable threshold, growth-rate trend, and projected time to threshold. Opt-in scans add per-collection rankings and a per-collection document-size histogram. (#SUPP-284)

• DittoSwiftTools minimum platform requirements are raised to iOS 15+, Mac Catalyst 15+, and macOS 12+ (previously iOS 14+, Mac Catalyst 14+, and macOS 11+). The tvOS 15+ requirement is unchanged. (#SDKS-3141)
• The DittoStoreObservationHandler, DittoStoreObservationHandlerWithSignalNext, and DittoSignalNext type aliases are now @Sendable. (#SDKS-3856)

• Uncaught exceptions thrown inside SDK callback closures are now re-raised with the original call stack preserved, so crash reporters attribute the crash to the throwing code instead of reporting a SIGABRT inside Ditto. (#SDKS-3483)
• Custom identity providers using DITIdentityProvider no longer stall the SDK the first time a credential refresh is requested. The refresh request is released immediately so the peer is not blocked. (#SDKS-3623)
• DittoStore.registerObserver now dispatches its callback on the queue specified by the deliverOn parameter, resolving a crash when used with Swift concurrency. (#SDKS-3856)

• DittoPeerOS.tvOS. The case is retained so peers running older SDK versions on tvOS can still be identified in the presence graph. (#SDKS-3944)
• The CBOR enum and the DittoError.StoreErrorReason cases invalidDocumentStructure(cbor:) and nonStringKeyInDocument(key:). The SDK no longer produces these; they will be removed in a future version. (#SDKS-4009)

• Support for Intel (x86_64) Macs. (#SDKS-2924)
• The DittoSwiftPresenceViewer framework target and podspec. Use the DittoPresenceViewer product from DittoSwiftTools via Swift Package Manager instead. (#SDKS-3141)
• tvOS platform support. (#SDKS-3944)

​

DQL for All Data Operations

​

DQL for All Data Operations

​

What Changed

• Legacy query builder removed: All store.collection() methods and fluent query APIs are no longer available
• Full feature parity: Every legacy operation has a DQL equivalent
• Single query language: DQL handles reads, writes, subscriptions, and observers
• Works everywhere: Same syntax across mobile, server, and web
• SQL-familiar: Standard SQL patterns for immediate productivity

​

Why One Query Language

​

Core Improvements

​

Simplified Initialization & Configuration

​

What’s New

• Unified configuration object: All initialization parameters are set through DittoConfig factory methods
• Fallible initialization: Explicit error handling during setup catches configuration issues early
• Asynchronous patterns: Native async/await support where appropriate for each platform
• Simplified authentication: Clearer authorization client that’s easier to understand and implement

​

What This Solves

​

Accessing Configuration at Runtime

// Example: Access database ID
const config = ditto.config;  // or ditto.getConfig() depending on SDK
const databaseID = config.databaseID;

​

Availability

​

Schema-Free Data Modeling

​

What’s New

• Field-level sync: Ditto syncs individual field changes instead of replacing entire objects
• Automatic type inference: No need to pre-define collection schemas or CRDT types
• Nested structures: Insert complex JSON-like documents without type definitions
• Concurrent updates merge: When peers update different fields simultaneously, both changes are preserved

​

What This Solves

• Add-wins behavior on objects: When peers create or modify objects, additions are preserved rather than overwritten
• Field-level delta sync on all nodes: Every field in your document syncs independently, reducing bandwidth and enabling fine-grained conflict resolution throughout the entire document structure

​

New Customers

​

Migrating Customers

ALTER SYSTEM SET DQL_STRICT_MODE = true

​

Migration Considerations

• Data syncs successfully between peers regardless of different strict mode settings
• Each peer interprets data based on its own strict mode setting when reading/writing
• With DQL_STRICT_MODE=false: Objects are inferred as MAPs (field-level merging)
• With DQL_STRICT_MODE=true: Objects without explicit type definitions are treated as REGISTERs (whole object replacement)

• Collections/documents created, modified, or read while strict mode is disabled will use inferred types (objects → MAPs by default)
• Collections/documents created, modified, or read while strict mode is enabled use default REGISTER type and require explicit definitions for other types

• If mixing settings, explicitly define MAP types in collection definitions on peers with strict mode enabled

​

New DQL Query Features

​

CASE Statements

-- Match a field against multiple values
SELECT CASE a
  WHEN 1 THEN 'one'
  WHEN 2 THEN 'two'
  ELSE 'neither'
END
FROM test

-- Use conditional expressions
SELECT CASE
  WHEN a = 1 THEN 'one'
  WHEN a = 2 THEN 'two'
  ELSE 'neither'
END
FROM test

​

BETWEEN Expressions

<expr> BETWEEN <low-expr> AND <high-expr>

SELECT * FROM test WHERE a BETWEEN 1 AND 10

​

Array & Object Search Syntax

(ANY|EVERY|ANY AND EVERY) [name:] value (IN|WITHIN) expression SATISFIES condition END

• IN - Searches the array/object directly
• WITHIN - Searches recursively through nested structures
• ANY - Returns true if at least one element matches
• EVERY - Returns true if all elements match (empty arrays/objects pass)
• ANY AND EVERY - Like EVERY, but empty arrays/objects fail

-- Check if any element in an array equals 2
SELECT ANY x IN [1,2,3] SATISFIES x = 2 END
FROM system:dual

-- Check if any nested element equals 2
SELECT ANY x WITHIN [1,[2],3] SATISFIES x = 2 END
FROM system:dual

-- Check if all elements equal 1 (or are arrays)
SELECT EVERY x WITHIN [1,[1],1]
SATISFIES x = 1 OR type(x) = 'array' END
FROM system:dual

-- Check if any field value equals 2
SELECT ANY x IN {'a':1,'b':2,'c':3} SATISFIES x = 2 END
FROM system:dual

-- Check if any nested field value equals 2
SELECT ANY x WITHIN {'a':1,'b':{'d':2},'c':3} SATISFIES x = 2 END
FROM system:dual

-- Find documents where first array element is less than zero
SELECT * FROM test
WHERE ANY n:v IN test.array_field SATISFIES n = 0 AND v < 0 END

-- Find documents where any nested field is NULL
SELECT * FROM test
WHERE ANY v WITHIN test.details SATISFIES v IS NULL END

-- Find orders where items were modified after order date
SELECT * FROM orders o
WHERE ANY v IN o.items SATISFIES v.modified > o.order_date END

​

Array & Object Transformation Syntax

ARRAY valueExpr FOR [name:] value IN source [WHEN condition] END

OBJECT nameExpr:valueExpr FOR name:value IN source [WHEN condition] END

-- Transform array elements to objects with index
ARRAY {"index":i,"val":v} FOR i:v IN [1,2,3] WHEN v%2 = 0 END
-- Result: [{"index":1,"val":2}]

-- Convert numbers to strings, excluding value 1
ARRAY cast(v,'string') FOR v IN [1,2,3] WHEN v != 1 END
-- Result: ["2","3"]

-- Transform string characters with conditional logic
ARRAY CASE WHEN i%2 = 0 THEN "foo" ELSE "bar" END
FOR i:v IN split("hello","") END
-- Result: ["foo","bar","foo","bar","foo","bar"]

-- Extract values from object into array
ARRAY v FOR n:v IN {"a":"one","b":"two"} END
-- Result: ["one","two"]

-- Transform object keys to uppercase, filter by value length
OBJECT upper(n):v FOR n:v IN {"a":"one","b":"two","c":"three"}
WHEN len(v) = 3 END
-- Result: {"A":"one","B":"two"}

-- Convert array to object with generated field names
OBJECT "field_"||cast(i,"string"):v FOR i:v IN [1,2,3] END
-- Result: {"field_0":1,"field_1":2,"field_2":3}

-- Filter object by value type
OBJECT n:v FOR n:v IN {"a":1,"b":[],"c":2}
WHEN type(v) != 'array' END
-- Result: {"a":1,"c":2}

• If source evaluates to MISSING, the result is MISSING
• For arrays: if source is not an array/object, the result is NULL
• For objects: duplicate field names will overwrite previous values
• Elements/fields where valueExpr evaluates to MISSING are excluded from the result

​

Extended String Literals

-- Use escape sequences in string literals
SELECT * FROM messages
WHERE content = 'Line 1\nLine 2\tTabbed'

-- [PLACEHOLDER: Add more escape sequence examples if needed]

​

Hexadecimal Numeric Constants

-- Use hexadecimal literals
SELECT * FROM config
WHERE flags = 0xFF

-- [PLACEHOLDER: Add more hex literal examples if needed]

​

Performance & Platform

​

DQL Query Performance Improvements

​

Query Planner Enhancements

• Automatic ID scan conversion: Equality filters on _id fields automatically convert to ID scans, bypassing index lookups when exact document IDs are known
• Deferred document fetching: Query planner can defer fetching full documents until after sorting and applying offset/limit when index access supports it
• Improved covering index support: More scenarios where the query planner can satisfy queries entirely from index data without retrieving documents
• Index-only queries: Additional cases where queries can be answered using only index scans

​

Streaming Query Execution

• Reduced memory overhead: Results are streamed rather than fully materialized where possible
• DISTINCT operator streaming: DISTINCT queries now stream results, reducing memory usage for large result sets
• Improved operator inlining: Query operators can be inlined into producers for better performance

​

Shared Statement Cache

• Plan reuse: Compiled query plans are cached and reused for identical or similar statements, eliminating redundant parsing and planning overhead
• Automatic validation: Cached plans are automatically verified and invalidated when collection schemas or system directives change
• Dynamic sizing: The cache automatically resizes based on workload patterns
• Improved large statement performance: Particularly benefits complex queries and larger statements by avoiding expensive re-compilation

​

Data Sync Performance Improvements

​

What’s New

• Tiered blob storage: Smaller sync updates avoid unnecessary disk I/O by using optimized storage tiers
• Improved session handling: Better avoidance of session resets on reconnection when in-flight updates were lost
• Optimized fsync policy: Document sync avoids forcing files to disk by default, decreasing I/O and improving latency

​

Impact

• Faster sync operations: Reduced disk I/O overhead leads to quicker data synchronization
• Lower latency: Optimized file handling decreases sync latency across the board
• Better reconnection handling: Fewer redundant updates after temporary disconnections
• Improved efficiency: Reduced disk operations lower memory and CPU pressure during sync

​

Local System Observability

​

New Virtual Collections

• Query performance metrics and diagnostics in real-time
• Access counters, timers, and other operational metrics via DQL
• Monitor system health and performance without external tools

• Query peer_key, database_id, and configuration settings
• Inspect runtime configuration and system parameters
• Useful for debugging and operational awareness

• Inspect the query plan cache
• View cached statements and their execution plans
• Supports DELETE operations to clear specific cached statements
• Helps optimize query performance and troubleshoot query planning

​

Usage Example

-- Query system information
SELECT * FROM system:system_info

-- View cached query statements
SELECT * FROM system:shared_statements

-- Access metrics
SELECT * FROM system:metrics
WHERE metric_name = 'sync.documents_synced'

-- Clear a specific cached statement
DELETE FROM system:shared_statements
WHERE statement_id = 'abc123'

​

Additional Improvements

​

Reliability & Error Handling

• Enhanced diagnostics: Improved logging when peers receive data that cannot be deserialized
• Recovery mechanisms: Additional recovery paths for document deserialization errors
• Smart log levels: Connection failures start at warning level, escalate to error only after repeated failures
• Panic messages: Filtered to remove internal Rust machinery frames for improved readability

​

Networking Improvements

• Graceful shutdown: Network connections close cleanly when Ditto is stopped
• Faster disconnection detection: When a peer crashes, Ditto stops attempting to connect within 15 seconds (previously up to 75 minutes)
• mDNS improvements: More reliable mDNS discovery, configurable service names, better address filtering
• BLE improvements: Fixed connection issues on Android 9 and earlier devices
• WebSocket BYOD support: Bring Your Own Discovery now supports WebSocket connections
• Connection cleanup: Fixed deadlock where devices could fail to establish new P2P connections until restarted

​

DQL Engine Improvements

• Better error messages: Improved parser error messages for invalid DQL syntax
• Transaction safety: Fixed deadlock scenarios in concurrent transactions
• Index correctness: Fixed issues where index scans could yield incorrect results on document deletion

​

Logging & Diagnostics

• Better disk utilization: On-disk logs resume writing to incomplete files, making better use of available space
• Compressed size limits: Log file limits now apply to compressed size, significantly increasing retention
• Explicit flushing: Logs explicitly flushed before aborting due to panic
• Virtual collections: New system:metrics and system:system_info collections for DQL access to metrics and system information

​

Platform Support

• Linux aarch64: Kotlin SDK now supports ARM64 Linux (Raspberry Pi, AWS Graviton, etc.)
• Swift 6: Full Swift 6 support with Sendable conformance
• 16KB alignment: React Native Android meets Google Play’s November 2025 requirement

​

Upgrading to v5

​

Terminology Updates

​

Database ID (formerly App ID)

• appID → databaseID in all configuration methods
• getAppId() → getConfig().databaseId in SDK APIs
• Portal and documentation updated to use “Database ID” terminology

​

Ditto Server (formerly Ditto Cloud)

• isConnectedToDittoCloud → isConnectedToDittoServer in presence APIs
• Documentation updated to use “Ditto Server” terminology

​

Breaking Changes

​

Removed APIs

​

Legacy Query Builder (All SDKs)

• store.collection() → Use DQL INSERT, UPDATE, EVICT statements
• collection.find() → Use DQL SELECT queries
• collection.findById() → Use DQL with _id filter
• Live queries → Use DQL observers with store.registerObserver()
• Write transactions → Use store.transaction() with DQL

​

Legacy Initialization (All SDKs)

• Identity classes and all subclasses removed
• Ditto(identity:, persistenceDirectory:) constructors removed
• Use DittoConfig factory methods and Ditto.open() instead

​

Sync Methods Moved

• ditto.startSync() → ditto.sync.start()
• ditto.stopSync() → ditto.sync.stop()
• ditto.isSyncActive → ditto.sync.isActive

​

Other Removals

• disableSyncWithV3() - no longer needed, v3 sync removed entirely
• AttachmentToken - use dictionary variant
• Transport diagnostics APIs - obsolete, removed
• Various deprecated presence properties (queryOverlapGroup, meshRole, etc.)
• Emoji log level headings - setting had no effect, removed

​

Behavioral Changes

• DQL strict mode: Now defaults to false - no schema definitions required, automatic CRDT type inference
• String literals in DQL: Double quotes now delimit strings (not identifiers) for JSON compatibility
• Subscription queries: Reject LIMIT and ORDER BY with <dql> Unsupported feature: Limit or Order by — see Subscriptions
• Observer ordering: Observers require explicit ORDER BY clause for stable ordering
• WebSocket sync: Disabled by default in new TransportConfig instances - must explicitly enable
• Document IDs: null is no longer allowed as a document ID

​

SDK Size Reduction

• Smaller application binary sizes
• Reduced memory usage
• Faster SDK initialization
• Simpler maintenance and debugging

​

Swift Migration Guide

• Updating from DittoIdentity to DittoConfig-based initialization
• Replacing legacy query builder operations with DQL statements
• Migrating collection observers to DQL observers
• Updating authentication patterns

​

Swift-Specific Changes

​

Removed Platform Support

• tvOS - No longer supported in v5.0
• visionOS (beta) - No longer supported in v5.0

​

Platform Requirements

• iOS: 15.0 (previously 13.0)

• Full support for Swift 6 strict concurrency checking
• All public classes marked as final
• Most public types marked as Sendable
• Introduced dedicated typealiases:
  • DittoTransactionScope for DittoStore.transaction() scope closures
  • DittoAttachmentFetchEventHandler for DittoStore.fetchAttachment() event handlers

​

Removed

• CocoaPods distribution has been completely removed starting with v5.0
• Use Swift Package Manager (SPM) or XCFrameworks for integration
• CocoaPods is effectively end-of-life and no longer maintained

• The deprecated DittoObjC SDK has been removed
• No longer required as a dependency for DittoSwift

• DittoExperimental.jsonByTranscoding(cbor:) method
• DittoTransportSnapshot - Leftover from previously removed APIs

​

API Changes

• DittoSyncSubscription.queryArguments no longer guaranteed to be strictly equal to original arguments due to serialization roundtrip
• DittoStoreObserver.queryArguments no longer guaranteed to be strictly equal to original arguments due to serialization roundtrip
• Added queryArgumentsCBORData and queryArgumentsJSONData properties for custom decoding
• Added overloads accepting Codable-conforming arguments for subscriptions and observers

• Added DittoStore.newAttachment(data:) - Create attachments from in-memory data without file URL
• Changed DittoAttachment.len type from Int to UInt64

• Renamed DiskUsage to DittoDiskUsage
• Renamed DiskUsageItem to DittoDiskUsageItem
• Renamed DiskUsage.DiskUsageObserverHandle to DittoDiskUsageObserver and made it top-level

• Renamed DittoPeer.peerKeyString to DittoPeer.peerKey
• Renamed DittoConnectionRequest.peerKeyString to DittoConnectionRequest.peerKey
• Renamed DittoConnection.peerKeyString1 to DittoConnection.peer1
• Renamed DittoConnection.peerKeyString2 to DittoConnection.peer2
• Renamed DittoPeer.osV2 to DittoPeer.os

• Converted DittoAuthenticationRequest from Objective-C typealias to pure Swift class
• Converted DittoAuthenticationSuccess from Objective-C typealias to pure Swift class
• Renamed DittoAuthenticationRequest.appId to DittoAuthenticationRequest.databaseID

​

Bug Fixes

• Fixed iOS mDNS occasionally being very slow to operate (#18682)
• Fixed mDNS failing to advertise/browse with correct info (#NETW-883)

​

Migration Example

let config = DittoConfig(
    databaseID: "your-database-id",  // was: appID
    connect: .server(url: URL(string: "REPLACE_ME_WITH_YOUR_URL")!)
)
let ditto = try await Ditto.open(config: config)

// Set up authentication
ditto.auth?.expirationHandler = { ditto, secondsRemaining in
    ditto.auth?.login(token: "your-token", provider: .development) { clientInfo, error in
        // Handle auth result
    }
}

try ditto.sync.start()  // was: ditto.startSync()

let identity = DittoIdentity.onlinePlayground(
    appID: "your-app-id",
    token: "your-token"
)
let ditto = Ditto(identity: identity)

try ditto.startSync()

​

Accessing Configuration at Runtime

let config = ditto.config
let databaseID = config.databaseID  // Replaces ditto.appID from v4

​

Migration Path

try await store.execute(
    "UPDATE cars SET miles = 50000 WHERE _id = 'abc123'"
)

store.collection("cars")
    .findByID("abc123")
    .update { doc in
        doc["miles"].set(50000)
    }

store.registerObserver(
    query: "SELECT * FROM cars WHERE miles > 100000"
) { result in
    // handle changes
}

store.collection("cars")
    .find("miles > 100000")
    .observe { docs, event in
        // handle changes
    }

​

How It Works

// Objects are automatically inferred as MAPs - no definition needed
let newProduct: [String: Any] = [
    "_id": "123",
    "name": "Widget",
    "metadata": [
        "manufacturer": "Acme Corp",
        "warehouse": "East"
    ]
]

try await store.execute(
    query: """
    INSERT INTO products
    DOCUMENTS (:newProduct)
    """,
    arguments: ["newProduct": newProduct]
)

// Query without type definitions
try await store.execute("""
    SELECT * FROM products WHERE _id = '123'
""")

// Must explicitly define MAP types to use objects
let newProduct: [String: Any] = [
    "_id": "123",
    "name": "Widget",
    "metadata": [
        "manufacturer": "Acme Corp",
        "warehouse": "East"
    ]
]

try await store.execute(
    query: """
    INSERT INTO COLLECTION products (metadata MAP)
    DOCUMENTS (:newProduct)
    """,
    arguments: ["newProduct": newProduct]
)

// Query with explicit MAP definition
try await store.execute("""
    SELECT * FROM COLLECTION products (metadata MAP)
    WHERE _id = '123'
""")

​

Migration

// Database ID
let config = DittoConfig(
    databaseID: "your-id",
    connect: .server(url: URL(string: "REPLACE_ME_WITH_YOUR_URL")!)
)

// Presence API
if peer.isConnectedToDittoServer {
    // handle connection
}

// App ID
let identity = DittoIdentity.onlinePlayground(
    appID: "your-id",
    token: "your-token"
)

// Presence API
if peer.isConnectedToDittoCloud {
    // handle connection
}

​

Swift Specific Changes

• iOS mDNS occasionally very slow to operate (#18682)
• mDNS failed to advertise/browse with correct info (#NETW-883)

• The queryArguments property on DittoSyncSubscriptions is no longer guaranteed to be strictly equal to the original arguments passed when registering the sync subscription. This is due to a serialization roundtrip, which may affect equality checks, particularly for non-primitive values. If you want to decode query arguments into a specific type, then use the queryArgumentsCBORData or queryArgumentsJSONData properties now available on DittoSyncSubscription instances and decode things as required (#17003)
• The queryArguments property on DittoStoreObservers is no longer guaranteed to be strictly equal to the original arguments passed when registering the store observer. This is due to a serialization roundtrip, which may affect equality checks, particularly for non-primitive values. If you want to decode query arguments into a specific type, then use the queryArgumentsCBORData or queryArgumentsJSONData properties now available on DittoStoreObserver instances and decode things as required (#17003)
• DittoAttachment.len type from Int to UInt64 (#18587)
• Minimum deployment targets are now macOS 12.0 and iOS 15.0 (#19096)
• Renamed DiskUsage to DittoDiskUsage to match the rest of the APIs (#19351)
• Renamed DiskUsageItem to DittoDiskUsageItem to match the rest of the APIs (#19351)
• Renamed DiskUsage.DiskUsageObserverHandle to DittoDiskUsageObserver and made it top-level to match the rest of the APIs (#19351)
• DittoAuthenticationRequest and DittoAuthenticationSuccess converted from Objective-C typealiases to pure Swift classes (#19683)
• DittoAuthenticationRequest.appId property renamed to DittoAuthenticationRequest.databaseID to match the updated terminology in DittoConfig (#19683)
• DittoPeer.peerKeyString property renamed to DittoPeer.peerKey (#SDKS-1186)
• DittoConnectionRequest.peerKeyString property renamed to DittoConnectionRequest.peerKey (#SDKS-1186)
• DittoConnection.peerKeyString1 property renamed to DittoConnection.peer1 (#SDKS-1186)
• DittoConnection.peerKeyString2 property renamed to DittoConnection.peer2 (#SDKS-1186)
• The default value of DittoTransportConfig.listen.websocketSync is now false. It must be explicitly set to true to enable websocket sync (#SDKS-1641)
• Renamed DittoPeer.isConnectedToDittoCloud to DittoPeer.isConnectedToDittoServer to reflect updated terminology (#SDKS-2189)
• DittoPeer.osV2 property has been renamed to DittoPeer.os. The corresponding DittoPeer initializer parameter has also been updated accordingly
• Upgraded DittoSwift SDK to support Swift 6 (#17934)
• Marked all public classes as final (#17934)
• Marked most public types as Sendable (#17934)

• queryArgumentsCBORData and queryArgumentsJSONData properties to DittoSyncSubscription instances. If you want to decode query arguments into a specific type, then use these and decode things as required (#17003)
• An overload of DittoSync’s registerSubscription method that takes an arguments value that is Codable-conforming (#17003)
• queryArgumentsCBORData and queryArgumentsJSONData properties to DittoStoreObserver instances. If you want to decode query arguments into a type you can specify then use these and decode things as required (#17026)
• An overload of DittoStore’s registerObserver method that takes an arguments value that is Codable-conforming (#17026)
• DittoStore.newAttachment(data:) to create attachments directly from in-memory data, without requiring a file URL (#18587)
• Introduced dedicated typealias DittoTransactionScope for the scope closure of DittoStore.transaction() (#17934)
• Introduced dedicated typealias DittoAttachmentFetchEventHandler for the onFetchEvent closure of DittoStore.fetchAttachment() (#17934)

• DittoError.TransportErrorReason and DittoError.transportError for future removal (#1969)

• Ditto.disableSyncWithV3() as Ditto v5 no longer supports syncing with v3 (#19340)
• DittoError.MigrationErrorReason and its only disableSyncWithV3Failed case, since v3 sync is no longer available in Ditto v5 (#19340)
• The deprecated DittoObjC SDK has been removed and is not required as a dependency for DittoSwift anymore (#17923)
• CocoaPods support. Starting with version 5.0, DittoSwift is no longer distributed via Cocoapods. Ditto has moved fully to SwiftPM, as Cocoapods is effectively end-of-life and no longer maintained. Please integrate DittoSwift via SwiftPM going forward (#19635)
• Ditto.transportDiagnostics() and DittoTransportDiagnostics, as these APIs are now obsolete (#SDKS-812)
• DittoTransportSnapshot, a leftover from previously deprecated and already removed APIs (#SDKS-812)
• DittoExperimental.jsonByTranscoding(cbor:) method (#SDKS-855)
• All deprecated APIs
• DittoAttachmentToken class is obsolete and has been removed. Please use the dictionary variant instead