Flutter V4→V5 API Migration Guide

Documentation Index

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

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

​

Overview

​

AI Agent Prompt

I need help migrating a Ditto Flutter application from v4 to v5. Focus on these critical changes:

INITIALIZATION:
Replace `Ditto.open(identity: Identity)` with `Ditto.open(DittoConfig(...))`:
- `DittoConfig(databaseID: String, connect: DittoConfigConnect, ...)` replaces identity types
- `DittoConfigConnectServer(url: String)` replaces `OnlinePlaygroundIdentity` — URL is a plain `String`, NOT a `Uri`
- `DittoConfigConnectSmallPeersOnly(privateKey: String?)` replaces `OfflinePlaygroundIdentity` and `SharedKeyIdentity`
- `Ditto.openSync(config)` available as synchronous alternative
- `await Ditto.init()` must be called before any Ditto usage
- Remove `updateTransportConfig` WebSocket URL additions (cloud URL inferred from config)
- Remove `DQL_STRICT_MODE = false` workaround (now the v5 default)
- If your v4 app relied on `DQL_STRICT_MODE = true` (v4 default), set it BEFORE `sync.start()`:
  `await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = true")`

SYNC:
- `ditto.startSync()` → `ditto.sync.start()`
- `ditto.stopSync()` → `ditto.sync.stop()`
- `ditto.isSyncActive` → `ditto.sync.isActive`

AUTHENTICATION:
Set `expirationHandler` via async method after initialization — replaces `AuthenticationHandler` interface:
- `await ditto.auth.setExpirationHandler((Ditto ditto, Duration timeUntilExpiration) { ... })`
- `ditto.auth` is non-nullable — do NOT use `ditto.auth?.`
- Handler receives `Ditto` (not `Authenticator`) and `Duration` (not `int`)
- Called when `timeUntilExpiration == Duration.zero` (initial auth or expired) or `> 0` (token expiring)
- Use `Authenticator.developmentProvider` for playground tokens
- `ditto.auth.login(token: '...', provider: '...')` — returns `Future<AuthResponse>`
- Remove `loginWithCredentials()` — use token-based `login()` instead
- Remove `AuthenticationHandler` class/interface

TRANSPORT CONFIG:
Changed from mutable to immutable with builder pattern:
- `ditto.updateTransportConfig((builder) { builder.setAllPeerToPeerEnabled(true); })`
- Or: `ditto.transportConfig = ditto.transportConfig.withAllPeerToPeerEnabled(true);`
- `TransportConfig.withBigPeer(...)` removed — use `DittoConfig` server config

PRESENCE & PEERS:
- `PresenceGraph.remotePeers` changed from `List<Peer>` to `Set<Peer>` — use `.first` instead of `[0]`
- `Peer.peerKeyString` → `Peer.peerKey: String` (unified)
- `Peer.isConnectedToDittoCloud` → `Peer.isConnectedToDittoServer`
- `Connection.peerKeyString1/peerKeyString2` → `Connection.peer1/peer2`
- `ConnectionRequest.peerKeyString` → `ConnectionRequest.peerKey`

OBSERVERS:
- `registerObserver()` API is the same — callback-based with `onChange` parameter
- Observers also expose `Stream<QueryResult> changes` for reactive use
- No `signalNext` — backpressure handled internally by SDK

OTHER:
- `ditto.persistenceDirectory` → `ditto.absolutePersistenceDirectory`
- `HttpListenConfig.websocketSync` default changed from `true` to `false`
- `Ditto` and `Store` cannot be passed across Dart isolates
- `DittoLogger.setLogFile()` removed
- `SmallPeerInfoSyncScope` enum removed — use DQL `ALTER SYSTEM SET sync_scope`
- `SiteID` and `DocumentID` are no longer exported (internal types)
- Ditto Flutter SDK for MacOS now targets 12.0+ - if your project targets older releases you will need to raise the minimum version.
- Ditto Flutter SDK for iOS now targets 14.0+ - if your project targets older releases you will need to raise the minimum version.
- MacOS and iOS use CocoaPods for dependency management, because of this you will probably need to delete the Pod lock file and run `pod install` again.  This is a standard CocoaPods issue when upgrading dependencies.
- Ditto Flutter SDK for Android minimum SDK version is now 24 (Android 7.0 Nougat). If your project targets `minSdk = 23`, you must raise it.

​

Ditto Instance Initialization

import 'package:ditto_live/ditto_live.dart';

// 1. Initialize the Ditto system (required before any Ditto usage)
await Ditto.init();

// 2. Configure
final config = DittoConfig(
    databaseID: 'your-database-id',
    connect: DittoConfigConnectServer(
        url: 'https://your-database-id.cloud.ditto.live',
    ),
);

// 3. Open
final ditto = await Ditto.open(config);
// OR synchronous: final ditto = Ditto.openSync(config);

// 4. Authenticate (required for server connections)
await ditto.auth.setExpirationHandler((ditto, timeUntilExpiration) {
    ditto.auth.login(
        token: 'your-token',
        provider: Authenticator.developmentProvider,
    );
});

// 5. Start sync
ditto.sync.start();

• Clear separation of connection, initialization, and authentication concerns
• Async initialization prevents blocking the main thread
• No workarounds needed (transport config, DQL strict mode, v3 sync disable)
• Type-safe configuration with compile-time validation

final config = DittoConfig(
    databaseID: 'your-database-id',
    connect: DittoConfigConnectServer(
        url: 'https://your-database-id.cloud.ditto.live',
    ),
);
final ditto = await Ditto.open(config);
ditto.sync.start();

// Set handler after Ditto.open() — note: setExpirationHandler is async
await ditto.auth.setExpirationHandler((ditto, timeUntilExpiration) {
    // Called for initial auth (timeUntilExpiration == Duration.zero)
    // and when token is expiring
    ditto.auth.login(
        token: 'your-token',
        provider: Authenticator.developmentProvider,
    );
});

​

Additional Changes

​

DQL Strict Mode Behavior Change

final config = DittoConfig(
    databaseID: 'your-database-id',
    connect: DittoConfigConnectServer(
        url: 'https://your-database-id.cloud.ditto.live',
    ),
);
final ditto = await Ditto.open(config);

// IMPORTANT: Set strict mode BEFORE starting sync or running queries
await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = true");

// Now safe to start sync
ditto.sync.start();

final config = DittoConfig(
    databaseID: 'your-database-id',
    connect: DittoConfigConnectServer(
        url: 'https://your-database-id.cloud.ditto.live',
    ),
);
final ditto = await Ditto.open(config);

// No need to set DQL_STRICT_MODE - false is now the default
ditto.sync.start();

​

Default Persistence Directory

final config = DittoConfig(
    databaseID: 'your-database-id',
    connect: DittoConfigConnectServer(
        url: 'https://your-database-id.cloud.ditto.live',
    ),
    persistenceDirectory: '/app/data/ditto',  // custom path to preserve v4 data
);

​

Observer Changes

final observer = ditto.store.registerObserver(
    "SELECT * FROM cars WHERE color = :color",
    arguments: {"color": "red"},
    onChange: (result) {
        setState(() { _cars = result.items; });
    },
);

// Cleanup
observer.cancel();

// Alternative: use the Stream-based API
final observer = ditto.store.registerObserver(
    "SELECT * FROM cars WHERE color = :color",
    arguments: {"color": "red"},
);
observer.changes.listen((result) {
    setState(() { _cars = result.items; });
});

• The observer lifecycle pattern (retain, .cancel(), cleanup) is the same as v4
• v5 observers expose a Stream<QueryResult> changes property for reactive use
• StoreObserver.queryString and queryArguments properties available for introspection

​

Back Pressure

// Observers use Stream internally — backpressure is handled by the SDK
final observer = ditto.store.registerObserver(
    "SELECT * FROM cars WHERE color = :color",
    arguments: {"color": "blue"},
    onChange: (result) {
        setState(() { _cars = result.items; });
    },
);

​

PresenceGraph.remotePeers Type Changed

// v4 — List, index access works
final first = graph.remotePeers[0];

// v5 — Set, use .first
final first = graph.remotePeers.first;
// Or: graph.remotePeers.toList()[0]

​

WebSocket Sync Default Changed

​

TransportConfig Now Immutable

// v5 — Using updateTransportConfig (recommended)
ditto.updateTransportConfig((builder) {
    builder.setAllPeerToPeerEnabled(true);
});

// v5 — Using builder pattern directly
final newConfig = ditto.transportConfig.toBuilder()
    ..setAllPeerToPeerEnabled(true);
ditto.transportConfig = newConfig.build();

// v5 — Using immutable copy method
ditto.transportConfig = ditto.transportConfig.withAllPeerToPeerEnabled(true);

// v4 — TransportConfig was mutable
ditto.updateTransportConfig((config) {
    config.setAllPeerToPeerEnabled(true);
    config.connect.webSocketUrls.add('wss://...');
});

​

Isolate Restriction

​

API Renames

​

Key Initialization Changes

​

Authentication API Changes

​

APIs Removed Without Replacement

​

New APIs in v5

• Ditto.init() — required static initialization before using any Ditto features (throws if not called)
• DittoConfig / DittoConfigConnectServer / DittoConfigConnectSmallPeersOnly — new configuration hierarchy replacing all identity types
• Ditto.openSync(config) — synchronous constructor alternative to async Ditto.open(config)
• Ditto.defaultRootDirectory — static helper for default persistence path
• ditto.config — access the config object used to open the instance
• AuthenticationExpirationHandler typedef — replaces AuthenticationHandler interface
• Authenticator.developmentProvider — constant for development auth provider
• Authenticator.setExpirationHandler() — async method to set the expiration handler
• SyncSubscription.queryArgumentsCborBytes / queryArgumentsJsonString — inspect subscription query arguments
• Builder types for all transport config sub-types (TransportConfigBuilder, PeerToPeerBuilder, etc.)
• TransportConfig.withAllPeerToPeerEnabled(bool) — immutable copy method for enabling P2P transports
• Ditto and Store marked @pragma("vm:isolate-unsendable") for safety

​

Migration Checklist

​

Initialization

• Ensure await Ditto.init() is called before any Ditto usage
• Replace Ditto.open(identity:) with Ditto.open(DittoConfig(...))
• Create DittoConfig with databaseID and connect mode
• Update identity types to DittoConfigConnect* variants
• Use String URLs (not Uri) for DittoConfigConnectServer
• Remove updateTransportConfig calls for WebSocket URLs (cloud URL inferred from config)
• Set DQL_STRICT_MODE=true BEFORE sync.start() if maintaining v4 behavior
• Update startSync() → sync.start()

​

Authentication

• Replace AuthenticationHandler interface with AuthenticationExpirationHandler typedef
• Set handler via await ditto.auth.setExpirationHandler(...) after Ditto.open()
• Update handler signature: receives (Ditto ditto, Duration timeUntilExpiration), not (Authenticator, int)
• Replace loginWithCredentials(username:password:provider:) with login(token:provider:)
• Use Authenticator.developmentProvider for dev tokens
• Remove ?. on ditto.auth — it is non-nullable in v5

​

Breaking Changes

• Update remotePeers[0] → remotePeers.first (type changed from List to Set)
• Check HttpListenConfig.websocketSync — must be explicitly enabled now (default is false)
• Update TransportConfig usage to builder pattern: .toBuilder()...build() or updateTransportConfig()
• Update peerKeyString → peerKey
• Update isConnectedToDittoCloud → isConnectedToDittoServer
• Update persistenceDirectory → absolutePersistenceDirectory
• Do not pass Ditto or Store across isolates
• Set persistenceDirectory in DittoConfig if maintaining v4 directory structure

​

Verification

• Build compiles with zero errors
• Observers update data immediately
• Authentication works before sync starts
• No remotePeers index access errors
• WebSocket sync works if needed (explicitly enabled)