​

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).

​

5.2.0 C++ Specific Changes

• DittoConfig::system_parameters and DittoConfig::set_system_parameters() for applying system parameter overrides when opening a Ditto instance (#SDKS-1637).
• Opening a store can now fail with a typed encryption error: EncryptionKeyRequiredError, EncryptionKeyUnexpectedError, EncryptionKeyInvalidError, EncryptionUnsupportedSchemeError, or EncryptionMetadataCorruptError (#SDKS-4805).

​

C#-Specific Changes

• .NET Android apps that resolve Xamarin.Kotlin 2.x packages, such as .NET 10 MAUI apps, no longer abort at startup with “Built-in class kotlin.Any is not found”. The Wi-Fi Aware and BLE transports start correctly.
• Ditto.Open() no longer crashes on 32-bit ARM Android devices (armeabi-v7a).
• CBOR unsigned integers above Int64.MaxValue decode as ulong instead of null.
• 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. Typed DittoEncryptionException subclasses report why a store failed to open.
• Android gets the Wi-Fi Aware and Bluetooth LE hardening described in the common changes.

​

Behavior changes

• .NET apps that target unsupported Windows process architectures (x86, ARM, ARM64) fail with a compile-time error. Set DittoNativeWinSkipArchitectureValidation to true to bypass the check.

​

5.2.0 C# Specific Changes

• DittoConfig.SystemParameters for applying system parameter overrides when opening a Ditto instance (#SDKS-1639).
• Opening a store can now fail with a DittoEncryptionException subclass: DittoEncryptionKeyRequiredException, DittoEncryptionKeyUnexpectedException, DittoEncryptionKeyInvalidException, DittoEncryptionUnsupportedSchemeException, or DittoEncryptionMetadataCorruptException (#SDKS-4805).
• On Android, the transports_wifi_aware_scan_yield_enabled system parameter (default off) lets Wi-Fi Aware briefly release its data paths so a disconnected device or weak link can scan for a stronger access point (#NETW-2387).

• .NET apps that target unsupported Windows process architectures (x86, ARM, ARM64) now fail with a compile-time error. Set DittoNativeWinSkipArchitectureValidation to true to bypass the check (#SPO-1127).

• Ditto.Open() no longer crashes on 32-bit ARM Android devices (armeabi-v7a) (#SDKS-4674).
• .NET Android apps that resolve Xamarin.Kotlin 2.x packages, such as .NET 10 MAUI apps, no longer abort at startup with “Built-in class kotlin.Any is not found”, and the Wi-Fi Aware and BLE transports start correctly (#SPO-1204).
• On Android, DittoSyncPermissions.RequestPermissionsAsync() no longer crashes when called from a background thread (#NETW-2077).
• 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).
• Wi-Fi Aware peers on Android no longer create competing connections when both devices discover each other at the same time, which could cause a connection failure during startup (#NETW-2240).
• DittoPresence.ConnectionRequestHandler failures now log why the connection request was denied (#SDKS-3486).
• CBOR unsigned integers above Int64.MaxValue in query results and documents now decode as ulong instead of null (#SDKS-4508).
• Wi-Fi Aware meshes of three or more Android devices no longer split into isolated pairs that stop syncing with the rest of the mesh (#NETW-2324).
• Wi-Fi Aware on Android now refreshes its discovery sessions instead of restarting the whole Wi-Fi Aware stack when a connection looks unhealthy (#NETW-2340).
• Wi-Fi Aware connections on Android are no longer torn down by a subsystem restart while a data path is carrying sync traffic (#NETW-2223).
• Rapid transport restarts on Android no longer disrupt active Wi-Fi Aware connections (#NETW-2241).
• Wi-Fi Aware connections on Android no longer stall during concurrent peer discovery and connection updates (#NETW-2078).
• Wi-Fi Aware on Android no longer reports scanning as online after the transport has stopped (#NETW-2079).
• Android apps no longer crash when a transport leaves a Java exception pending on a native thread (#NETW-2038).
• Android BLE no longer crashes the app when an L2CAP channel can’t be opened or closed, for example when Bluetooth is turned off while peers are connecting. Bluetooth sync continues over GATT (#SPO-1205).

​

Flutter-Specific Changes

• Hot restarting an app while a store observer is active during sync no longer crashes.
• Authenticator.logout accepts an optional cleanup callback that runs after logout completes, for example to clear the store.
• Store.observers returns the active StoreObserver instances, matching Store.attachmentFetchers.
• 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.
• Android gets the Wi-Fi Aware and Bluetooth LE hardening described in the common changes, plus DittoSyncPermissions.requiredMulticastPermissions() for reliable UDP multicast.

​

Behavior changes

• On desktop platforms, Ditto.defaultRootDirectory now resolves to the application support directory instead of the documents directory. When DittoConfig.persistenceDirectory is null, existing databases in the previous location are still found on upgrade.

​

5.2.0 Flutter Specific Changes

• DittoConfig.systemParameters for applying system parameter overrides when opening a Ditto instance (#SDKS-1640).
• Authenticator.logout accepts an optional cleanup callback (AuthenticationLogoutCleanupHandler) that runs after logout completes, for example to clean up the store (#SDKS-1948).
• Store.observers getter that returns the currently active StoreObserver instances, matching Store.attachmentFetchers (#SDKS-3917).
• DittoSyncPermissions.requiredMulticastPermissions() returns the Android permissions that reliable UDP multicast needs, including ACCESS_LOCAL_NETWORK where applicable (#SDKS-4471).
• Opening a store can now fail with a DittoEncryptionException whose reason is keyRequired, keyUnexpected, keyInvalid, unsupportedScheme, or metadataCorrupt (#SDKS-4805).
• On Android, the transports_wifi_aware_scan_yield_enabled system parameter (default off) lets Wi-Fi Aware briefly release its data paths so a disconnected device or weak link can scan for a stronger access point (#NETW-2387).

• On desktop platforms, Ditto.defaultRootDirectory now resolves to the application support directory (getApplicationSupportDirectory()) instead of the documents directory. When DittoConfig.persistenceDirectory is null, existing databases in the previous default location are still found on upgrade (#SDKS-3900).

• A crash when a Flutter app was hot restarted while a store observer was active during sync (#SDKS-4719).
• Ditto.open() no longer crashes during initialization on 32-bit Android devices that report the armv8l architecture (#SDKS-4674).
• 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).
• Wi-Fi Aware peers on Android no longer create competing connections when both devices discover each other at the same time, which could cause a connection failure during startup (#NETW-2240).
• Wi-Fi Aware meshes of three or more Android devices no longer split into isolated pairs that stop syncing with the rest of the mesh (#NETW-2324).
• Wi-Fi Aware on Android now refreshes its discovery sessions instead of restarting the whole Wi-Fi Aware stack when a connection looks unhealthy (#NETW-2340).
• Wi-Fi Aware connections on Android are no longer torn down by a subsystem restart while a data path is carrying sync traffic (#NETW-2223).
• Rapid transport restarts on Android no longer disrupt active Wi-Fi Aware connections (#NETW-2241).
• Wi-Fi Aware connections on Android no longer stall during concurrent peer discovery and connection updates (#NETW-2078).
• Wi-Fi Aware on Android no longer reports scanning as online after the transport has stopped (#NETW-2079).
• Android apps no longer crash when a transport leaves a Java exception pending on a native thread (#NETW-2038).
• Android BLE no longer crashes the app when an L2CAP channel can’t be opened or closed, for example when Bluetooth is turned off while peers are connecting. Bluetooth sync continues over GATT (#SPO-1205).

​

5.2.0 Go Specific Changes

• DittoConfig.SystemParameters and WithSystemParameters() for applying system parameter overrides when opening a Ditto instance (#SDKS-4500).

• 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).

​

Java-Specific Changes

• Negative integers in DQL query arguments are now encoded correctly. Before 5.2, a negative argument was stored as one less than the value passed, so a value passed as -5 was stored as -6. Documents written or matched with negative integers on any 5.x version may be wrong. Read the Fixed section below for more information.
• Set system parameters in DittoConfig.Builder.systemParameters() instead of running ALTER SYSTEM after open. Ditto applies them before it starts, so startup-only settings now take effect.
• DittoTransactionInfo.getHintOrNull() returns null when no transaction hint was provided, so you can tell an unset hint from an empty one.
• Typed DittoException.EncryptionException reasons report why a store failed to open.

​

5.2.0 Java Specific Changes

• DittoConfig.Builder.systemParameters() for applying system parameter overrides when opening a Ditto instance (#SDKS-1635).
• DittoTransactionInfo.getHintOrNull(), which returns null when no transaction hint was provided. getHint() still returns an empty string in that case (#SDKS-4318).
• Opening a store can now fail with a DittoException.EncryptionException whose reason is KeyRequired, KeyUnexpected, KeyInvalid, UnsupportedScheme, or MetadataCorrupt (#SDKS-4805).

• Negative integers in DQL query arguments are now encoded correctly. Before this fix, a negative argument was stored and compared as one less than the value you passed. A value passed as -5 was stored as -6, so documents written or matched with negative integers may be wrong. Values such as Integer.MIN_VALUE also no longer fail to serialize (#SDKS-4493).

• DittoFactory.create() no longer crashes during initialization on 32-bit Android devices that report the armv8l architecture (#SDKS-4674).
• 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).

​

JavaScript & React Native-Specific Changes

• React Native iOS builds succeed with React Native 0.86.
• React Native Android builds honor the Kotlin, SDK, and NDK version overrides in gradle.properties, which unblocks Expo apps.
• React Native connection request handlers can read identity service metadata without a “not implemented” error.
• 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.
• Opening a store can fail with a typed encryption/* error code, such as encryption/key-required. The encryption/extraneous-passphrase-given code is deprecated.
• React Native on Android gets the Wi-Fi Aware and Bluetooth LE hardening described in the common changes.

​

5.2.0 JavaScript & React Native Specific Changes

• DittoConfig.systemParameters for applying system parameter overrides when opening a Ditto instance (#SDKS-1636).
• Opening a store can now fail with an encryption/key-required, encryption/key-unexpected, encryption/key-invalid, encryption/unsupported-scheme, or encryption/metadata-corrupt error code (#SDKS-4805).
• On Android, the transports_wifi_aware_scan_yield_enabled system parameter (default off) lets Wi-Fi Aware briefly release its data paths so a disconnected device or weak link can scan for a stronger access point (#NETW-2387).

• React Native iOS builds now succeed with React Native 0.86 (#SDKS-4884).
• React Native Android builds now honor the Kotlin, SDK, and NDK version overrides in gradle.properties, which unblocks Expo apps (#SDKS-4883).
• React Native connection request handlers can now read identity service metadata without a “not implemented” error (#SDKS-2575).
• Wi-Fi Aware peers on Android no longer create competing connections when both devices discover each other at the same time, which could cause a connection failure during startup (#NETW-2240).
• Wi-Fi Aware meshes of three or more Android devices no longer split into isolated pairs that stop syncing with the rest of the mesh (#NETW-2324).
• Wi-Fi Aware on Android now refreshes its discovery sessions instead of restarting the whole Wi-Fi Aware stack when a connection looks unhealthy (#NETW-2340).
• Wi-Fi Aware connections on Android are no longer torn down by a subsystem restart while a data path is carrying sync traffic (#NETW-2223).
• Rapid transport restarts on Android no longer disrupt active Wi-Fi Aware connections (#NETW-2241).
• Wi-Fi Aware connections on Android no longer stall during concurrent peer discovery and connection updates (#NETW-2078).
• Wi-Fi Aware on Android no longer reports scanning as online after the transport has stopped (#NETW-2079).
• Android apps no longer crash when a transport leaves a Java exception pending on a native thread (#NETW-2038).
• Android BLE no longer crashes the app when an L2CAP channel can’t be opened or closed, for example when Bluetooth is turned off while peers are connecting. Bluetooth sync continues over GATT (#SPO-1205).
• 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 encryption/extraneous-passphrase-given error code (#SDKS-4805).

​

Kotlin-Specific Changes

• Negative integers in DQL query arguments are now encoded correctly. Before 5.2, a negative argument was stored as one less than the value passed, so a value passed as -5 was stored as -6. Documents written or matched with negative integers on any 5.x version may be wrong. Read the Fixed section below for more information.
• Encryption at rest with a raw 32-byte key through DittoConfig.encryptionKey, plus DittoFactory.deleteStore() for wiping a local store and typed DittoException.EncryptionException reasons when a store fails to open.
• 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.
• Wi-Fi Aware hardening on Android: meshes of three or more devices no longer split into isolated pairs, sessions refresh instead of restarting the stack, and active transfers survive subsystem restarts. The opt-in transports_wifi_aware_scan_yield_enabled parameter lets a weak link scan for a stronger access point.
• Android BLE no longer crashes when an L2CAP channel can’t be opened or closed. Sync continues over GATT.
• DittoAuthenticator.login() failures expose AuthenticationException.failureCode, so your app can tell rejected credentials from retryable failures.
• DittoSyncPermissions.requiredMulticastPermissions() returns the Android permissions that reliable UDP multicast needs.
• DittoAndroidTools adds a support bundle screen for requesting, viewing, and exporting diagnostic bundles.

​

Behavior changes

• DittoStore.newAttachment overloads that take Map<String, Any?> metadata are deprecated and now throw IllegalArgumentException for non-string values. Use the new Map<String, String> overloads.
• DittoFactory.create() no longer crashes on 32-bit Android devices that report the armv8l architecture.

​

5.2.0 Kotlin Specific Changes

• DittoConfig.encryptionKey, which takes a DittoEncryptionKey.raw(...) value, for encryption at rest with a raw 32-byte key (#SDKS-4776).
• DittoFactory.deleteStore(databaseId, persistenceDirectory) for deleting a local store (#SDKS-4662).
• Opening a store can now fail with a DittoException.EncryptionException whose reason is KeyRequired, KeyUnexpected, KeyInvalid, UnsupportedScheme, or MetadataCorrupt (#SDKS-4805).
• DittoConfig.systemParameters for applying system parameter overrides when opening a Ditto instance (#SDKS-1635).
• DittoTransactionInfo.hintOrNull, which is null when no transaction hint was provided. hint still returns an empty string in that case (#SDKS-4318).
• DittoStore.newAttachment overloads that take Map<String, String> metadata (#SDKS-4320).
• DittoSyncPermissions.requiredMulticastPermissions() returns the Android permissions that reliable UDP multicast needs, including ACCESS_LOCAL_NETWORK where applicable (#SDKS-4471).
• The transports_wifi_aware_scan_yield_enabled system parameter (default off) lets Wi-Fi Aware briefly release its data paths so a disconnected device or weak link can scan for a stronger access point (#NETW-2387).
• A support bundle screen in DittoAndroidTools for requesting, viewing, and exporting diagnostic support bundles (#SDKS-4758).

• Negative integers in DQL query arguments are now encoded correctly. Before this fix, a negative argument was stored and compared as one less than the value you passed. A value passed as -5 was stored as -6, so documents written or matched with negative integers may be wrong. Values such as Int.MIN_VALUE also no longer fail to serialize (#SDKS-4493).

• DittoFactory.create() no longer crashes during initialization on 32-bit Android devices that report the armv8l architecture (#SDKS-4674).
• Android BLE no longer crashes the app when an L2CAP channel can’t be opened or closed, for example when Bluetooth is turned off while peers are connecting. Bluetooth sync continues over GATT (#SPO-1205).
• DittoAuthenticator.login() failures now expose AuthenticationException.failureCode, which distinguishes rejected credentials from retryable or unknown failures (#SPO-1112).
• DittoStore.fetchAttachment() now resolves exactly once when cancellation races with completion or deletion (#SDKS-4558).
• The DittoStore.fetchAttachment() API documentation now correctly describes the returned DittoAttachmentFetchResult and how to cancel a fetch (#SDKS-3960).
• Wi-Fi Aware meshes of three or more Android devices no longer split into isolated pairs that stop syncing with the rest of the mesh (#NETW-2324).
• Wi-Fi Aware on Android now refreshes its discovery sessions instead of restarting the whole Wi-Fi Aware stack when a connection looks unhealthy (#NETW-2340).
• Wi-Fi Aware connections on Android are no longer torn down by a subsystem restart while a data path is carrying sync traffic (#NETW-2223).
• Rapid transport restarts on Android no longer disrupt active Wi-Fi Aware connections (#NETW-2241).
• Wi-Fi Aware peers no longer create competing connections when both devices discover each other at the same time, which could cause a connection failure during startup (#NETW-2240).
• Wi-Fi Aware connections on Android no longer stall during concurrent peer discovery and connection updates (#NETW-2078).
• Wi-Fi Aware on Android no longer reports scanning as online after the transport has stopped (#NETW-2079).
• Android apps no longer crash when a transport leaves a Java exception pending on a native thread (#NETW-2038).

• DittoStore.newAttachment overloads that take Map<String, Any?> metadata. They now throw IllegalArgumentException when a value isn’t a String (#SDKS-4320).

​

5.2.0 Rust Specific Changes

• DittoError::is_encryption_error and DittoError::encryption_error_kind identify store-open encryption failures: key required, key unexpected, key invalid, unsupported scheme, or metadata corrupt (#SDKS-4805).

• Opening Ditto with invalid system parameters now reports CoreApiErrorKind::ValidationInvalidDittoConfig from DittoError::kind() (#SDKS-1638).
• 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).

• DatabaseId::default_auth_url() and DatabaseId::default_sync_url(). Use the URL from the Ditto Portal instead (#SDKS-3024).
• The passphrase-era CoreApiErrorKind and DittoErrorCode variants (#SDKS-4805).

​

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).