​

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

​

Flutter-Specific Changes

​

Requirements

• Dart 3.5.4 or later
• Flutter 3.24.5 or later
• Apple framework targets are arm64-only; Intel (x86_64) support is removed.

​

Flutter Specific Changelog

• Store.execute no longer incurs per-call startup overhead when dispatching many small queries, restoring throughput comparable to SDK 4.x while keeping the calling isolate unblocked during query execution. (#SDKS-3879)

• Store.registerObserverV2() method for registering store observers with automatic signal-next backpressure that integrates with Dart stream pause/resume. (#SDKS-2389)
• Store.registerObserverWithSignalNext() method for registering store observers with manual signal-next backpressure control. (#SDKS-2389)
• StoreObserverV2 class with explicit signal-next backpressure control and a single-subscription changes stream. (#SDKS-2389)
• Flutter Web support for Store.registerObserverV2() and Store.registerObserverWithSignalNext(). (#SDKS-2429)
• DittoSyncPermissions utility class for querying required and missing Android permissions. (#SDKS-3178)
• Store.experimentalSkipExecuteIsolateOffload flag (default: false). When set to true, Store.execute runs on the calling isolate instead of dispatching to a background isolate, improving throughput for apps that issue many small queries in sequence. (#SDKS-3878)
• Ditto.observeTransportConditions() for surfacing transport health and configuration issues (missing permissions, disabled hardware, unapplied config) reported by the underlying transports. (#SDKS-439)
• MulticastBetaConfig and PeerToPeer.multicastBeta for configuring the beta reliable UDP multicast transport. The transport is disabled by default and currently supported on Android and iOS. On Android and iOS, changes requested while sync is active take effect after sync is stopped and successfully started again, when Ditto validates platform prerequisites. (#SDKS-4471)
• ConnectionType.multicast enum option representing beta reliable UDP multicast connections. The transport is currently supported on Android and iOS. (#SDKS-4471)

• The Android Context is now set automatically in DittoPlugin.onAttachedToEngine(). (#SDKS-3178)
• Ditto.init() is now optional; Ditto.open() initializes automatically. (#SDKS-3178)

• Crashes when force-closing apps that use a connection request handler. (#SDKS-2673)
• Presence observer callbacks are properly cleaned up when Ditto.close() is called, preventing SIGABRT crashes during shutdown. (#SDKS-3134)
• Ditto.close() now explicitly stops sync before shutdown. (#SDKS-3617)
• Auth expiration handler callbacks are properly cleaned up when Ditto.close() is called, preventing SIGABRT crashes during shutdown. (#SDKS-3626)
• Custom log callbacks are properly cleaned up when Ditto.close() is called, preventing SIGABRT crashes during isolate shutdown. (#SDKS-3630)
• Ditto.close() no longer waits an extra ~500 ms when any presence observer was used. (#SDKS-3762)
• Active StoreObserver, StoreObserverV2, and SyncSubscription instances now report being cancelled after the owning Ditto is closed: isCancelled reports true and cancel() is a no-op, as documented. (#SDKS-3916)

• Presence.connectionRequestHandler no longer leaks memory each time a remote peer requests a connection. (#SDKS-3800)
• When Presence.connectionRequestHandler throws or its returned Future rejects, the connection is now denied immediately instead of after a ~10-second wait. (#SDKS-3800)
• Presence.observe() now delivers an immediate first callback with the current presence graph, matching the documented behavior and the other SDKs. (#SDKS-804)

• Memory leaks that caused the SDK’s memory usage to grow over time during normal use of sync subscriptions, presence, query results, and attachments. (#SDKS-3638)
• A StoreObserver registered without an onChange callback now defers matching queries against the store until the first listener attaches to StoreObserver.changes. Observers that are registered but never listened to no longer emit events or run query work. Observers registered with an onChange callback are unaffected. (#SDKS-3878)
• StoreObserver.cancel() no longer crashes the app when called while observer callbacks are in flight, which could occur with active sync over large collections. (#SPO-1022)

• Authenticator.login() is now offloaded to a background isolate so a slow authentication webhook no longer blocks the UI on VM platforms. (#SDKS-1888)
• Android apps with isMinifyEnabled = true no longer crash on Ditto initialization. The required Android libraries used by the Flutter plugin now correctly bundle the consumer-rules.pro keep rules. (#SDKS-2626)
• Crash on Flutter Web when reading Authenticator.developmentProvider. (#SDKS-2699)
• TransportConfigBuilder.setAllPeerToPeerEnabled(false) no longer leaves AWDL enabled on iOS/macOS or Wi-Fi Aware enabled on Android. (#SDKS-3591)
• ditto.sync.isActive no longer reports true after ditto.auth.logout(). (#SDKS-649)

• Intel (x86_64) support from the Flutter SDK’s Apple framework. iOS Simulator and macOS targets are now arm64-only. (#SDKS-4033)

​

5.0.3 Flutter Specific Changes

​

5.0.2 Flutter Specific Changes

​

5.0.1 Flutter Specific Changes

​

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 unless DQL_RESTRICT_SUBSCRIPTION=false
• 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

​

Flutter 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

​

Flutter-Specific Changes

​

Breaking: Resource Management

• All classes that manage resources must now be manually freed
• This standardizes finalization across the SDK
• Ensures proper resource cleanup and prevents leaks

​

API Changes

• StoreObserver.changes is now a single-subscription stream (previously multi-subscription)

• SyncSubscription.queryArguments no longer guaranteed to be strictly equal to original arguments due to serialization roundtrip
• Added queryArgumentsCborBytes and queryArgumentsJsonString properties for custom decoding

• Throwing in a transaction scope now correctly rolls back the transaction

• TransportConfig types are now immutable and const
• Added builder types for mutable configuration
• ditto.updateTransportConfig callback parameter now takes TransportConfigBuilder instead of TransportConfig

• Added DittoConfig class to encompass all initialization data
• Ditto.open now takes optional DittoConfig instead of Identity and persistenceDirectory
• Added ditto.auth.expirationHandler - callback for when authorization is expiring
• Removed AuthenticationHandler - Use ditto.auth.expirationHandler instead
• Removed Identity and all subtypes - Use DittoConfig instead

• Added more ergonomic APIs for interacting with PresenceGraph and related types

• Removed DocumentID class from public API
• Document IDs now returned as raw JSON values (dynamic type) instead of wrapped in DocumentID class
• QueryResult.mutatedDocumentIDs() now returns List<dynamic> instead of List<DocumentID>
• Document IDs can be any JSON-compatible type: strings, integers, booleans, null, lists, or maps

• Removed Peer.peerKeyString - Use Peer.peerKey instead
• Removed ConnectionRequest.peerKeyString - Use ConnectionRequest.peerKey instead
• Removed Connection.peerKeyString1 - Use Connection.peer1 instead
• Removed Connection.peerKeyString2 - Use Connection.peer2 instead

• Removed setLogFile() method - Use exportLogs() instead

• Removed SmallPeerInfoSyncScope and syncScope property

• Added Authenticator.developmentProvider constant for sandbox identity providers
• Removed siteID from identity APIs

​

Performance Improvements

• ditto.store.execute calls now offloaded to background isolates on VM platforms
• Makes store operations non-blocking

​

Bug Fixes

• Fixed memory safety bug that caused sporadic use-after-free errors (#18504)
• Fixed race condition in StoreObserver that could throw when cancelling while callbacks are arriving (#SDKS-2494)
• Fixed DittoError being thrown where DittoException should have been thrown (#16925)

​

Migration Example

// Configure Ditto with server connection
final config = DittoConfig(
    databaseID: 'your-database-id',  // was: appID
    connect: DittoConfigConnectServer(url: 'REPLACE_ME_WITH_YOUR_URL')
);
final ditto = await Ditto.open(config);

// Set up authentication
await ditto.auth.setExpirationHandler((dittoAuth, timeUntilExpiration) async {
    final authResult = await dittoAuth.auth.login(
        token: 'your-token',
        provider: Authenticator.developmentProvider
    );
    if (authResult.exception != null) {
        throw authResult.exception!;
    }
});

await ditto.sync.start();  // was: ditto.startSync()

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

await ditto.startSync();

​

Accessing Configuration at Runtime

final config = ditto.config;
final databaseID = config.databaseID;  // Replaces ditto.appID from v4

​

Migration Path

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

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

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

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

​

How It Works

// Objects are automatically inferred as MAPs - no definition needed
await store.execute("""
    INSERT INTO products
    DOCUMENTS ({
        _id: '123',
        name: 'Widget',
        metadata: {
            manufacturer: 'Acme Corp',
            warehouse: 'East'
        }
    })
""");

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

// Must explicitly define MAP types to use objects
await store.execute("""
    INSERT INTO COLLECTION products (metadata MAP)
    DOCUMENTS ({
        _id: '123',
        name: 'Widget',
        metadata: {
            manufacturer: 'Acme Corp',
            warehouse: 'East'
        }
    })
""");

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

​

Migration

// Database ID
final config = DittoConfig.onlinePlayground(
    databaseID: "your-id",  // was: appID
    token: "your-token"
);

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

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

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

​

Flutter Specific Changes

• Several places where DittoError was thrown where DittoException should have been thrown (#16925)
• Standardized finalization so that all classes that manage resources must now be manually freed (#17275)
• Throwing in a transaction scope will now correctly rollback a transaction (#17808)
• Memory safety bug that can caused sporadic use-after-free errors (#18504)
• A race condition in StoreObserver that could throw when cancelling an observer while callbacks are still arriving (#SDKS-2494)
• History tracking is now correctly disabled by default. Previously, the Flutter SDK unintentionally enabled history tracking, causing the __history local-only collection to grow without bound. Apps that used a previous version of the Flutter SDK should execute EVICT FROM __history during app initialization to purge accumulated history data (#SPO-650)

• StoreObserver.changes is now a single-subscription stream
• The queryArguments property on SyncSubscriptions 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 queryArgumentsCborBytes or queryArgumentsJsonString properties now available on SyncSubscription instances and decode things as required (#17003)
• TransportConfig types are now immutable, const, and have builder types (#17876)
• ditto.updateTransportConfig’s callback parameter now takes a TransportConfigBuilder instead of a TransportConfig (#17876)
• Ditto.open now takes an optional DittoConfig instead of an Identity and persistenceDirectory (#17937)
• Offloads ditto.store.execute calls to background isolates to make them non-blocking on VM platforms (#18455)
• QueryResult.mutatedDocumentIDs() now returns List<dynamic> instead of List<DocumentID>. Document IDs can be any JSON-compatible type: strings, integers, booleans, null, lists, or maps (#SDKS-1166)

• queryArgumentsCborBytes and queryArgumentsJsonString properties to SyncSubscription instances. If you want to decode query arguments into a specific type, then use these and decode things as required (#17003)
• DittoConfig class to encompass all data needed to initialize a Ditto instance (#17937)
• Ditto.openSync factory for synchronously creating a Ditto instance, complementing the async Ditto.open (#17937)
• ditto.auth.expirationHandler - a callback that is called when authorization is expiring (#17937)
• More ergonomic APIs for interacting with PresenceGraph, and related types (#17954)
• Authenticator.developmentProvider constant for use with sandbox identity providers (#SDKS-2594)

• setLogFile() method. Use exportLogs() instead (#19399)
• SmallPeerInfoSyncScope and syncScope property (#19402)
• DocumentID class has been removed from the public API. Document IDs are now returned as raw JSON values (dynamic type) instead of being wrapped in a DocumentID class (#SDKS-1166)
• Peer.peerKeyString. Use Peer.peerKey instead (#SDKS-1182)
• ConnectionRequest.peerKeyString. Use ConnectionRequest.peerKey instead (#SDKS-1182)
• Connection.peerKeyString1. Use Connection.peer1 instead (#SDKS-1182)
• Connection.peerKeyString2. Use Connection.peer2 instead (#SDKS-1182)
• Legacy identity configuration APIs are no longer supported in Ditto v5 (#SDKS-2435)
• AuthenticationHandler - please use ditto.auth.expirationHandler instead (#17937)
• Identity and all subtypes - please use DittoConfig instead (#17937)
• siteID from identity APIs (#SDKS-696)