Swift V4→V5 API Migration Guide

Overview

This guide covers the essential changes needed to migrate your Ditto Swift app from v4 to v5. The main architectural shift is moving from identity-based initialization to a four-phase configuration model with async/await APIs. Also required: v5 uses DQL (Ditto Query Language) for all data operations. See the DQL Migration Guide for query migration steps.

AI Agent Prompt

Use this prompt when working with an AI coding assistant to migrate your Ditto Swift app from v4 to v5.

Copy AI Migration Prompt (Click to Expand)

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

VERIFY AGAINST GROUND TRUTH:
Before changing any call site, verify the exact v5 signature against the API reference rather than trusting prose. The v5 reference is a JS-rendered DocC site that returns a blank shell to web-fetch tools, but the underlying DocC JSON is machine-readable and gives exact signatures and member lists. Fetch the per-symbol JSON at:
  https://software.ditto.live/cocoa/DittoSwift/<version>/api-reference/data/documentation/dittoswift/<symbol>.json
The SDK version is part of the URL — replace `<version>` with the exact version you are upgrading TO (e.g. `5.0.1`, `5.0.0`, or any later `5.x` release). Signatures can differ between patch releases, so use your target version, not the example. For example, for 5.0.1 the `DittoStore` symbol is at `.../DittoSwift/5.0.1/api-reference/data/documentation/dittoswift/dittostore.json`, `DittoStoreObserver` at `.../dittoswift/dittostoreobserver.json`, etc. Lowercase the symbol name. When a signature below disagrees with the DocC JSON for your version, trust the JSON.
When you need a member (initializer, method, property, nested enum), do NOT hand-construct its slug from a guessed signature — that is the main source of 404s (e.g. assuming a `databaseID:connect:persistenceDirectory:identityID:...` init that doesn't exist; the real init has no `identityID`). Instead fetch the parent TYPE's JSON (e.g. `dittoconfig.json`): its `topicSections` lists the exact slug of each member and its declaration fragments give the authoritative signature, so you anchor on real symbols rather than guessing. To browse symbol names, the human-readable index is at `https://software.ditto.live/cocoa/DittoSwift/<version>/api-reference/documentation/dittoswift/`.

REMOVED PLATFORM SUPPORT (CHECK FIRST):
Before migrating, confirm the app does not target a platform that v5 dropped. v5 removes support for:
- tvOS — no longer supported in v5.0
- visionOS (beta) — no longer supported in v5.0
If the project targets tvOS or visionOS, STOP and flag this: there is no v5 SDK for these platforms, so the app cannot upgrade to v5 while it ships on them. The user must drop the platform target or stay on v4. Do not attempt to migrate these targets — surface the blocker and have them reach out to Ditto customer support.

INITIALIZATION:


- Parameter labels are case-sensitive: `databaseID` (uppercase `ID`), and `ditto.config.databaseID` replaces `ditto.appID`.
- `DittoSwift` no longer re-exports `Foundation`. In v4, importing `DittoSwift` transitively brought in `Foundation` symbols (`URL`, `Date`, `NSLog`, `Notification`, etc.); in v5 it does not. Any file that uses a Foundation type now needs an explicit `import Foundation`. Audit every file that imports `DittoSwift` without also importing `Foundation`.
- In v4 when adding the `DittoSwift` package, it would add in the `DittoObjC` package product dependencies. In v5, `DittoObjC` is no longer a separate product — it's bundled into `DittoSwift`. This means that you no longer need to add the `DittoObjC` package product dependencies to your project and you need to remove the `DittoObjC` package product dependencies from your project in order to get the project to build.
- These are the following places the `DittoObjC` package product dependencies are usually used:
    - 1. `PBXBuildFile` section — removed the `DittoObjC in Frameworks` entry
    - 2. `PBXFrameworksBuildPhase` — removed `DittoObjC in Frameworks` from the `files` array
    - 3. `PBXNativeTarget.packageProductDependencies` — removed the `DittoObjC` reference
    - 4. `XCSwiftPackageProductDependency` — removed the entire `DittoObjC` dependency entry
- Replace `Ditto(identity:)` with `try await Ditto.open(config:)` using async/await.
- Create a `DittoConfig` with `databaseID` and a connect mode
- `.onlinePlayground(appID:token:enableDittoCloudSync:customAuthURL:)` → `DittoConfig(databaseID: appID, connect: .server(url:))` + the `token` moves to auth: set `ditto.auth?.expirationHandler` and call `login(token:provider: .development)` inside it. Do NOT drop the token — only `appID` and the connect mode go into `DittoConfig`; the token is no longer part of the identity/config.
- `.onlineWithAuthentication(appID:enableDittoCloudSync:customAuthURL:)` → `DittoConfig(databaseID: appID, connect: .server(url:))` + auth `expirationHandler`
- `.server(url:)` takes a `URL`, not a `String`. The case is `case server(url: URL)`. Emit `.server(url: URL(string: "https://...")!)` (or a safely-unwrapped `URL`) — a string literal will not compile.
- The `.server` URL is environment-specific: copy the **URL** from the Ditto Portal (Connect via SDK) as-is. Do NOT construct it from the database ID. This is the portal's **URL** value — an `https://` URL. v5 takes no separate WebSocket (`wss://`) URL; do not paste a `wss://` value here.
- `.offlinePlayground(appID:)` → `DittoConfig(databaseID: appID, connect: .smallPeersOnly())`
- `.offlinePlayground()` (zero-arg form, no `appID`) → `DittoConfig(databaseID: "<your-database-id>", connect: .smallPeersOnly())`. The zero-arg v4 form had no `appID`, but v5 `databaseID` is required — supply any non-empty string. For tests/playgrounds, `"test"` is fine.
- `.sharedKey(appID:sharedKey:)` → `DittoConfig(databaseID: appID, connect: .smallPeersOnly(privateKey: sharedKey))`
- `.manual(certificateConfig:)` → **No replacement** — removed in v5
- `.smallPeersOnly()` is equivalent to `.smallPeersOnly(privateKey: nil)` — the parameter has a default value of `nil`, so prefer the shorter form when there is no shared key.
- The `Ditto(identity:)` initializer is removed. You MUST use `try await Ditto.open(config:)` or `Ditto.openSync(config:)`
- Remove `disableSyncWithV3()` calls — v3 protocol is fully dropped in v5
- Remove `updateTransportConfig` workaround patterns for adding websocket URLs — `DittoConfig` handles the server URL directly. Note: `updateTransportConfig` itself still exists in v5 for advanced transport configuration
- Remove `ditto.store.execute(query: "ALTER SYSTEM SET DQL_STRICT_MODE = false")` — v5 defaults to `false`
- IMPORTANT: If your v4 app used the default (strict=true), set `DQL_STRICT_MODE=true` BEFORE starting sync to maintain v4 behavior. Objects that were replaced whole in v4 will silently merge at field level in v5 without this.
- v5 default persistence directory is `ditto-{databaseID}` (was `ditto` in v4). Set `persistenceDirectory` explicitly if maintaining v4 directory structure.
- `persistenceDirectory` is an initializer parameter on `DittoConfig`. The full init signature is:
  ```swift
  public init(databaseID: String,
              connect: DittoConfigConnect,
              persistenceDirectory: URL? = nil,
              experimental: DittoConfigExperimental = .init())
  ```
  Pass it at construction:
  ```swift
  let config = DittoConfig(
      databaseID: "my-app",
      connect: .server(url: serverURL),
      persistenceDirectory: URL(fileURLWithPath: "/app/sandbox/ditto")
  )
  ```
- Configure logging via the `DittoLogger` type (e.g. `DittoLogger.minimumLogLevel = .info`); `DittoConfig` itself exposes only `databaseID`, `connect`, `persistenceDirectory`, and `experimental`.
- Create the instance with `try await Ditto.open(config:)` (async) or `try Ditto.openSync(config:)` (sync). Where to use which: use `try await Ditto.open(config:)` from an async context (`Task`, async function). Use `try Ditto.openSync(config:)` from a non-async context — most importantly a SwiftUI `App.init()`, which is not async and cannot `await`. `App.init` is an extremely common host for Ditto setup, so prefer `openSync` there rather than wrapping setup in a detached `Task`.

SYNC:
The sync API moved from top-level Ditto methods to the `ditto.sync` sub-object.
- `try ditto.startSync()` → `try ditto.sync.start()`
- `ditto.stopSync()` → `ditto.sync.stop()`
- `ditto.isSyncActive` → `ditto.sync.isActive`

AUTHENTICATION:
The `DittoAuthenticationDelegate` protocol is removed. Replace with the `expirationHandler` closure.
- Set `ditto.auth?.expirationHandler = { expiredDitto, timeUntilExpiration in ... }` after `Ditto.open(config:)`
- The handler signature is `@Sendable (_ ditto: Ditto, _ timeUntilExpiration: TimeInterval) async -> Void`
- Inside the handler, call `expiredDitto.auth?.login(token:provider:completion:)` (use a distinct closure parameter name to avoid shadowing the outer `ditto`)
- Use `.development` provider for playground/test tokens
- The handler is called when `timeUntilExpiration == 0` (initial auth or expired) and when `timeUntilExpiration > 0` (token expiring soon — refresh). Handle both cases.
- `authenticator.loginWithToken(_:provider:completion:)` → `ditto.auth?.login(token:provider:completion:)`
- `DittoAuthenticationDelegate.authenticationRequired(authenticator:)` → removed, use `expirationHandler` with `timeUntilExpiration == 0`
- `DittoAuthenticationDelegate.authenticationExpiringSoon(authenticator:secondsRemaining:)` → removed, use `expirationHandler` with `timeUntilExpiration > 0`
- `ditto.delegate = MyAuthDelegate()` → `ditto.auth?.expirationHandler = { ... }`

OBSERVERS:
The callback-based `registerObserver` API is the same in v5 — it returns `DittoStoreObserver` with callback handlers.
- `ditto.store.registerObserver(query:arguments:deliverOn:handler:)` → same API, returns `DittoStoreObserver`
- v5 adds `Codable` argument overloads: `registerObserver(query:arguments: Codable, deliverOn:handler:)`
- Call `item.dematerialize()` after extracting data from `DittoQueryResultItem` to free native memory — do not use the item after this call
- Tear down with `observer.cancel()`.

BACK PRESSURE (Signal Next):
Use `registerObserver(query:arguments:deliverOn:handlerWithSignalNext:)` when your handler needs time to process results.
- Changes that occur while your handler is processing are coalesced — you get one callback with the latest state, not every intermediate change
- You must call `signalNext()` to receive the next update
- Standard observer auto-signals after handler returns

COLLECTION API → DQL:
All `.collection()` APIs are **removed**. Replace with `store.execute()` using DQL.
- `ditto.store.collection("cars").find("color == 'blue'").exec()` → `try await ditto.store.execute(query: "SELECT * FROM cars WHERE color = :color", arguments: ["color": "blue"])`
- `ditto.store.collection("cars").findByID(id).exec()` → `try await ditto.store.execute(query: "SELECT * FROM cars WHERE _id = :id", arguments: ["id": id])`
- `ditto.store.collection("cars").upsert(value)` → `try await ditto.store.execute(query: "INSERT INTO cars DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE", arguments: ["doc": value])`
- `ditto.store.collection("cars").findByID(id).update { doc in doc?["color"].set("green") }` → `try await ditto.store.execute(query: "UPDATE cars SET color = :color WHERE _id = :id", arguments: ["color": "green", "id": id])`
- `ditto.store.collection("cars").findByID(id).remove()` → `try await ditto.store.execute(query: "DELETE FROM cars WHERE _id = :id", arguments: ["id": id])`
- `ditto.store.collection("cars").findByID(id).evict()` → `try await ditto.store.execute(query: "EVICT FROM cars WHERE _id = :id", arguments: ["id": id])`
- Always use parameterized queries with `:paramName` — NEVER use string interpolation in DQL queries

LIVE QUERIES → STORE OBSERVERS:
- `collection.find("...").observeLocal { docs, event in ... }` → `ditto.store.registerObserver(query: "SELECT * FROM ...", arguments: [...]) { result in ... }`
- `liveQuery?.stop()` → `observer.cancel()`
- v4 handler: `(docs: [DittoDocument], event: DittoLiveQueryEvent) -> Void`
- v5 handler: `(result: DittoQueryResult) -> Void` where result has `.items` containing `DittoQueryResultItem` objects
- Extract your model from `item.jsonData()` then call `item.dematerialize()` to free native memory
- When using `item.jsonData()`, you need to make sure you import the Swift Foundation framework

SUBSCRIPTIONS:
- `ditto.store.collection("cars").find("color == 'red'").subscribe()` → `try ditto.sync.registerSubscription(query: "SELECT * FROM cars WHERE color = :color", arguments: ["color": "red"])`
- `arguments:` is optional — the signature is `registerSubscription(query:arguments:)` with `arguments: [String: Any?]? = nil`. For an unparameterized subscription like `SELECT *`, call `try ditto.sync.registerSubscription(query: "SELECT * FROM cars")` with no `arguments:`.
- `DittoSubscription` → replaced by `DittoSyncSubscription`
- Tear down a subscription with `subscription.cancel()`.

TRANSACTIONS:
- Existing `store.transaction(hint:with:)` calls still compile in v5 (the new parameters have defaults), so no change is required.
- v5 signature is `transaction(hint: String? = nil, isReadOnly: Bool = false, with scope: DittoTransactionScope<T>)` where `DittoTransactionScope<T> = (DittoTransaction) async throws -> T`.
- For read-only transactions, pass `isReadOnly: true` — it lets Ditto optimize the transaction.

COUNTERS:
- `doc?["viewCount"].counter?.increment(by: 1.0)` → `try await ditto.store.execute(query: "UPDATE cars APPLY viewCount PN_INCREMENT BY :n WHERE _id = :id", arguments: ["n": 1, "id": id])`
- DO NOT initialize counter fields in insert documents. Counters are created on first `PN_INCREMENT`. Inserting `0` creates a REGISTER, not a COUNTER.
- Decrement by passing a negative value: `["n": -1]`

PRESENCE:
- `peer.peerKeyString` → `peer.peerKey` (type is `String` in both v4 and v5, but property renamed)
- `peer.osV2` → `peer.os`
- `peer.isConnectedToDittoCloud` → `peer.isConnectedToDittoServer`
- `connection.peerKeyString1` / `peerKeyString2` → `connection.peer1` / `connection.peer2` (now `String`)
- `connection.approximateDistanceInMeters` → **removed, no replacement**
- `ditto.observePeers(_:)` → `ditto.presence.observe(didChangeHandler:)`
- `DittoRemotePeer` struct (deprecated) → use `DittoPeer` in `DittoPresenceGraph`
- `DittoAddress` struct → removed

DITTO CLASS:
- `Ditto(identity:)` → `try await Ditto.open(config:)` or `Ditto.openSync(config:)`
- `ditto.activated` → `ditto.isActivated`
- `ditto.appID` → `ditto.config.databaseID`
- `ditto.transportDiagnostics()` → removed
- `ditto.runGarbageCollection()` → removed (automatic in v5)
- `ditto.disableSyncWithV3()` → removed (v3 protocol dropped)
- `ditto.isHistoryTrackingEnabled` → removed

DISK USAGE:
- `DiskUsage` → `DittoDiskUsage`
- `diskUsage.exec` → `diskUsage.item`
- `DiskUsageObserverHandle` → `DittoDiskUsageObserver`
- `DiskUsageItem` → `DittoDiskUsageItem` (property names `.path`, `.sizeInBytes`, `.childItems` are unchanged)

LOGGING:
- `DittoLogger` class name is unchanged in both v4 and v5, but is now `final` and `Sendable` in v5
- `DittoLogger.enabled` → `DittoLogger.isEnabled` (e.g. `DittoLogger.enabled = false` → `DittoLogger.isEnabled = false`)
- `DittoLogger.setLogFile()` → removed — use `export(to:)` instead

ERRORS:
- `DittoSwiftError` typealias → removed, use `DittoError` directly
- `migrationError` error case → removed

TRANSPORT CONFIG:
- `DittoHTTPListenConfig.staticContentPath` → removed
- Default `webSocketSync` — check if your app relied on v4 default; explicitly set `true` if needed

TYPES & PROTOCOLS:
- `DittoConnectionPriority` enum → removed
- `DittoTransportSnapshot` struct → removed (with transport diagnostics)
- `DittoExperimental.jsonByTranscoding(cbor:)` → removed
- All public types are now `final` and `Sendable` for Swift concurrency
- `DittoConfig` and `DittoConfigConnect` conform to `Sendable` and `Codable`
- `DittoConnection` now conforms to `Identifiable`, `Equatable`, `Hashable`, and `Sendable`

SWIFT 6 COMPATIBILITY:
- `DittoConnection` gaining `Identifiable` conformance causes `filter` ambiguity in Swift 6. Fix: annotate closure parameter explicitly:
  ```swift
  // BROKEN in Swift 6
  connections.filter { $0.peer1 == localKey }
  // FIXED
  connections.filter { (conn: DittoConnection) in conn.peer1 == localKey }
  ```
- Auth handler: `expirationHandler` closure is `@Sendable` and `async`. If your Ditto manager is an `actor`, use `await` when accessing actor-isolated state inside `Task { }` blocks within the handler.
- DELETE any v4-era retroactive `Sendable` shims. v5 declares `Sendable` in-module for `Ditto`, `DittoQueryResult`, `DittoTransactionCompletionAction`, `DittoStoreObserver`, and more. A leftover `extension X: @retroactive @unchecked Sendable {}` (common in Swift 6 codebases that adopted strict concurrency before the SDK did) now produces: `conformance of 'X' to protocol 'Sendable' was already stated in the type's module 'DittoSwift'`. Search for `@retroactive` and `@unchecked Sendable` extensions on Ditto types and remove them.

REMOVED APIs (no replacement):
- `ditto.transportDiagnostics()` — low-level transport debug info
- `ditto.runGarbageCollection()` — CRDT GC controls
- `ditto.disableSyncWithV3()` — v3 protocol fully dropped
- `ditto.isHistoryTrackingEnabled` — history tracking removed
- `DittoIdentity.manual(certificateConfig:)` — manual identity type
- `Connection.approximateDistanceInMeters` — peer distance estimation
- `DittoHTTPListenConfig.staticContentPath` — static file serving
- `DittoStore.queriesHash(queries:)` — hash-based query deduplication
- `DittoStore.queriesHashMnemonic(queries:)` — query mnemonic hashing
- `DittoConnectionPriority` enum — connection priority
- `DittoTransportSnapshot` struct — removed with transport diagnostics
- `DittoRemotePeer` struct (deprecated) — use `DittoPeer` in `DittoPresenceGraph`
- `DittoAddress` struct — removed
- `DittoExperimental.jsonByTranscoding(cbor:)` — CBOR-to-JSON utility
- `DittoSwiftError` typealias — use `DittoError` directly
- `migrationError` error case — removed
- `DittoLogger.setLogFile()` — use `export(to:)` instead

NEW APIs:
- `Ditto.open(config:): async throws -> Ditto` — async factory method
- `Ditto.openSync(config:): throws -> Ditto` — synchronous factory alternative
- `ditto.config: DittoConfig` — read the config used to open this instance
- `ditto.isActivated: Bool` — replaces `ditto.activated`
- `DittoStore.newAttachment(data: Data, metadata:)` — create attachment from in-memory `Data` (v4 was file path only)
- `DittoStore.registerObserver(query:arguments: some Codable, ...)` — overloads accepting `Codable` query arguments
- `DittoSync.registerSubscription(query:arguments: some Codable)` — overload accepting `Codable` arguments
- `DittoDiskUsageObserver` — standalone observer class (was nested `DiskUsage.DiskUsageObserverHandle`)
- `DittoDiskUsageItem` — renamed from `DiskUsageItem`
- `DittoSyncSubscription.queryArgumentsCBORData` / `.queryArgumentsJSONData` / `.id` — introspection properties
- `DittoConnection` conforms to `Identifiable`, `Equatable`, `Hashable`, and `Sendable`
- All public types now `final` and `Sendable` for Swift concurrency
- `DittoConfig` and `DittoConfigConnect` conform to `Sendable` and `Codable`
- `DittoSmallPeerInfo.metadataJSONString` removed — use `metadataJSONData` instead (which already existed in v4)

BEFORE (v4):
```swift
let ditto = Ditto(
    identity: .onlinePlayground(
        appID: "your-app-id",
        token: "your-token",
        enableDittoCloudSync: false,
        customAuthURL: URL(string: "REPLACE_ME_WITH_YOUR_URL")
    )
)

ditto.updateTransportConfig { config in
    config.connect.webSocketURLs.insert("wss://...")
}
ditto.disableSyncWithV3()
try? ditto.store.execute(query: "ALTER SYSTEM SET DQL_STRICT_MODE = false")
try? ditto.startSync()

// Observer — callback with manual cleanup
var observer: DittoStoreObserver?
observer = ditto.store.registerObserver(
    query: "SELECT * FROM cars WHERE color = :color",
    arguments: ["color": "red"]
) { result in
    DispatchQueue.main.async {
        self.cars = result.items.compactMap { Car($0.jsonData()) }
    }
}

// Must manually cancel in deinit
deinit { observer?.cancel() }

// Presence
ditto.observePeers { peers in
    for peer in peers {
        print(peer.peerKeyString, peer.isConnectedToDittoCloud)
    }
}

// Cleanup
observer?.cancel()
ditto.stopSync()
```

AFTER (v5):
```swift
let config = DittoConfig(
    databaseID: "your-database-id",
    connect: .server(url: URL(string: "REPLACE_ME_WITH_YOUR_URL")!)
)
let ditto = try await Ditto.open(config: config)

// Authentication
ditto.auth?.expirationHandler = { expiredDitto, timeUntilExpiration in
    expiredDitto.auth?.login(token: "your-token", provider: .development) { clientInfo, error in
        if let error = error {
            print("Ditto auth failed: \(error), client info: \(String(describing: clientInfo)), time until expiration: \(timeUntilExpiration)s")
        }
    }
}

// If maintaining v4 behavior, set strict mode BEFORE starting sync
// try await ditto.store.execute(query: "ALTER SYSTEM SET DQL_STRICT_MODE = true")

try ditto.sync.start()

// Observer — callback-based, same pattern as v4 but with dematerialize()
let observer = try ditto.store.registerObserver(
    query: "SELECT * FROM cars WHERE color = :color",
    arguments: ["color": "red"]
) { result in
    let cars = result.items.compactMap { item -> Car? in
        let car = Car(item.jsonData())
        item.dematerialize()  // Free native memory — do not use item after this
        return car
    }
    DispatchQueue.main.async { self.cars = cars }
}
// Cleanup: observer.cancel()

// Subscription — DQL-based
let sub = try ditto.sync.registerSubscription(
    query: "SELECT * FROM cars WHERE color = :color",
    arguments: ["color": "red"]
)

// Presence
ditto.presence.observe { graph in
    let allPeers = [graph.localPeer] + graph.remotePeers
    for peer in allPeers {
        print(peer.peerKey, peer.isConnectedToDittoServer)
    }
}

// Cleanup
sub.cancel()
ditto.sync.stop()
```

CHECKLIST:

Initialization:
- Replace `Ditto(identity:)` with `try await Ditto.open(config:)`
- Add `try await` for initialization — `Ditto.open(config:)` is async and throws
- Create `DittoConfig` with `databaseID` and connect mode (`.server(url:)` or `.smallPeersOnly(privateKey:)`)
- Set `DQL_STRICT_MODE=true` BEFORE `sync.start()` if maintaining v4 strict behavior
- Set `persistenceDirectory` if maintaining v4 directory structure
- Remove `disableSyncWithV3()` calls
- Remove `updateTransportConfig` workaround patterns for websocket URLs (method still exists for advanced use)
- Remove `ditto.store.execute(query: "ALTER SYSTEM SET DQL_STRICT_MODE = false")` (v5 default)

Authentication:
- Remove `DittoAuthenticationDelegate` conformance and class
- Remove `ditto.delegate = MyAuthDelegate()` assignment
- Set `ditto.auth?.expirationHandler` closure after `Ditto.open(config:)`
- Handler signature is `@Sendable (_ ditto: Ditto, _ timeUntilExpiration: TimeInterval) async -> Void`
- Use `timeUntilExpiration == 0` check for initial auth vs `> 0` for refresh
- Use `.development` provider for playground/test tokens

Sync:
- Replace `try ditto.startSync()` with `try ditto.sync.start()`
- Replace `ditto.stopSync()` with `ditto.sync.stop()`
- Replace `ditto.isSyncActive` with `ditto.sync.isActive`

Observers:
- Replace `collection.observeLocal { }` with `store.registerObserver(query:arguments:handler:)`
- Call `item.dematerialize()` after extracting data from `DittoQueryResultItem`
- Use `handlerWithSignalNext:` for back-pressure control on expensive operations
- Cleanup with `observer.cancel()`

Data Operations:
- Replace all `.collection("x").find(...)` chains with `store.execute(query:arguments:)` DQL
- Use parameterized queries with `:paramName` — never string interpolation
- Replace `.upsert()` with `INSERT INTO ... DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE`
- Replace `.update { }` closures with `UPDATE SET` DQL
- Replace `.remove()` with `DELETE FROM`
- Replace `.evict()` with `EVICT FROM`

Removed Platform Support

Breaking Change: v5 removes support for the following platforms. If your app targets one of these, you cannot upgrade to v5 while shipping on that platform — drop the platform target or stay on v4.

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

Check this before starting the rest of the migration. If you have concerns about this change, please reach out to Ditto customer support.

DittoObjC Removal

In v4 when adding the DittoSwift package, it would add in the DittoObjC package product dependencies. In v5, DittoObjC is no longer a separate product — it’s bundled into DittoSwift. This means that you no longer need to add the DittoObjC package product dependencies to your project and you need to remove the DittoObjC package product dependencies from your project in order to get the project to build. These are the following places the DittoObjC package product dependencies are used:

PBXBuildFile section — removed the DittoObjC in Frameworks entry
PBXFrameworksBuildPhase — removed DittoObjC in Frameworks from the files array
PBXNativeTarget.packageProductDependencies — removed the DittoObjC reference
XCSwiftPackageProductDependency — removed the entire DittoObjC dependency entry

Ditto Instance Initialization

v5 separates initialization into four distinct phases for better clarity and control:

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

// 2. Initialize (async)
let ditto = try await Ditto.open(config: config)

// 3. Authenticate
ditto.auth?.expirationHandler = { expiredDitto, timeUntilExpiration in
    expiredDitto.auth?.login(token: "your-token", provider: .development) { clientInfo, error in
        if let error = error {
            print("Ditto auth failed: \(error), client info: \(String(describing: clientInfo)), time until expiration: \(timeUntilExpiration)s")
        }
    }
}

// 4. Start sync
try ditto.sync.start()

let ditto = Ditto(
    identity: .onlinePlayground(
        appID: "your-app-id",
        token: "your-token",
        enableDittoCloudSync: false,
        customAuthURL: URL(string: "REPLACE_ME_WITH_YOUR_URL")
    )
)

ditto.updateTransportConfig { config in
    config.connect.webSocketURLs.insert("wss://...")
}
try? ditto.store.execute(query: "ALTER SYSTEM SET DQL_STRICT_MODE = false")
ditto.disableSyncWithV3()

try? ditto.startSync()

These changes provide:

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
Ditto.open() returns a non-optional Ditto instance

Initialization Migration Steps

Replace Configuration and Initialization

Replace Ditto(identity:) constructor with Ditto.open(config:).

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

let ditto = Ditto(
    identity: .onlinePlayground(
        appID: "your-app-id",
        token: "your-token",
        enableDittoCloudSync: false,
        customAuthURL: URL(string: "REPLACE_ME_WITH_YOUR_URL")
    )
)

Key changes:

Use DittoConfig instead of DittoIdentity
appID → databaseID
.onlinePlayground → .server(url:)
.offlinePlayground → .smallPeersOnly(privateKey: nil)
Add try await for async initialization
Remove updateTransportConfig, disableSyncWithV3(), and DQL strict mode queries

Update Authentication

Set authentication handler separately after initialization.

// Set handler after Ditto.open()
// The handler is async and receives the Ditto instance as its first parameter
ditto.auth?.expirationHandler = { expiredDitto, timeUntilExpiration in
        // Initial auth
        expiredDitto.auth?.login(
            token: "your-token",
            provider: .development
        ) { clientInfo, error in
            if let error = error {
                print("Ditto auth failed: \(error), client info: \(String(describing: clientInfo))")
            }
        }
}

// Auth mixed with identity
let ditto = Ditto(
    identity: .onlinePlayground(
        appID: "...",
        token: "...",  // Token in identity
        enableDittoCloudSync: false,
        customAuthURL: URL(...)
    )
)

Key changes:

Authentication now uses expirationHandler closure
The handler signature is @Sendable (_ ditto: Ditto, _ timeUntilExpiration: TimeInterval) async -> Void
Handler called when auth required (timeUntilExpiration == 0) or token expiring
Use .development provider for playground tokens
Custom auth: extend DittoAuthenticationProvider with a static property, or use DittoAuthenticationProvider("your-provider")

Start Sync

Start sync after initialization.

try ditto.sync.start()

try? ditto.startSync()

Key changes:

Namespace change from ditto.startSync() to ditto.sync.start()

Auth Handler: Swift 6 Actor Isolation Requirement

If your DittoManager (or whatever class holds the Ditto instance) is an actor, the expirationHandler closure is @Sendable and executes off the actor. Any access to actor-isolated state inside a Task { } block requires await:

// BROKEN — Swift 6 strict concurrency error
ditto.auth?.expirationHandler = { expiredDitto, timeUntilExpiration in
    if let error = someError {
        Task {
            self.myActorIsolatedProperty = error  // ← error: actor-isolated
        }
    }
}

// FIXED
ditto.auth?.expirationHandler = { expiredDitto, timeUntilExpiration in
    if let error = someError {
        Task {
            await self.myActorIsolatedProperty = error  // ← correct
        }
    }
}

Additional Changes

DQL Strict Mode Behavior Change

Breaking Change: v5 defaults to DQL_STRICT_MODE=false, which fundamentally changes how DQL queries behave.

v4 default: Objects treated as REGISTER (whole-object replacement)
v5 default: Objects treated as MAP (field-level merging)

This affects the behavior of all DQL SELECT, INSERT, and UPDATE operations.

Choose the appropriate migration path based on your current v4 configuration:

Currently Using DQL with DQL_STRICT_MODE=true (v4 default)

If you’re currently using the v4 default (DQL_STRICT_MODE=true), you must explicitly set strict mode to true in v5 before starting sync or executing any queries.

Failing to set strict mode will cause objects to merge at the field level instead of replacing entirely, which can result in unexpected data behavior and perceived data loss.

To migrate to DQL_STRICT_MODE=false (the new v5 default), contact Ditto Customer Support for guidance.

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

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

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

Currently Using DQL with DQL_STRICT_MODE=false

If you explicitly set DQL_STRICT_MODE=false in v4, no changes are required.v5 uses DQL_STRICT_MODE=false as the default, so your existing DQL queries will behave identically. You can upgrade freely.Recommended: Remove the explicit ALTER SYSTEM SET DQL_STRICT_MODE = false statement entirely — the v5 default already matches your intent, so the line is now redundant.

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

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

let ditto = Ditto(
    identity: .onlinePlayground(
        appID: "your-app-id",
        token: "your-token",
        enableDittoCloudSync: false,
        customAuthURL: URL(string: "REPLACE_ME_WITH_YOUR_URL")
    )
)

// You explicitly set this in v4
try? ditto.store.execute(query: "ALTER SYSTEM SET DQL_STRICT_MODE = false")

try? ditto.startSync()

Currently Using Legacy Query Builder

The Legacy Query Builder has been removed in v5. All queries must be converted to DQL before upgrading.Good news: Legacy Query Builder functionality has 1:1 support with DQL_STRICT_MODE=false (the v5 default), making migrations straightforward.Migration Steps:

In v4: Set DQL_STRICT_MODE=false after initialization:

let ditto = Ditto(
    identity: .onlinePlayground(
        appID: "your-app-id",
        token: "your-token",
        enableDittoCloudSync: false,
        customAuthURL: URL(string: "REPLACE_ME_WITH_YOUR_URL")
    )
)

// Set DQL_STRICT_MODE to false for Query Builder compatibility
try? ditto.store.execute(query: "ALTER SYSTEM SET DQL_STRICT_MODE = false")

try? ditto.startSync()

Convert all queries from Legacy Query Builder to DQL See the Swift Legacy→DQL Migration Guide for detailed conversion examples.
Upgrade to v5 No DQL configuration changes required—v5 defaults to DQL_STRICT_MODE=false.

For additional guidance or questions, contact Ditto Customer Support.

Default Persistence Directory

v5 includes the database ID in the default directory name: ditto-{databaseID} instead of ditto. This is for only new databases created in v5. v5 does not migrate existing databases to the new structure. Provide custom persistence directory:

let config = DittoConfig(
    databaseID: "your-database-id",
    connect: .server(url: URL(...)),
    persistenceDirectory: URL(fileURLWithPath: "/app/sandbox/ditto")  // custom path to save the database
)

Observer Changes

v4 and v5 both use callback-based observers. The core registerObserver API pattern is the same in both versions, returning a DittoStoreObserver that you retain and call .cancel() on for cleanup.

var observer: DittoStoreObserver?

observer = try ditto.store.registerObserver(
    query: "SELECT * FROM cars WHERE color = :color",
    arguments: ["color": "red"]
) { result in
    let cars = result.items.compactMap { item -> Car? in
        let car = Car(item.jsonData())
        item.dematerialize()  // Free native memory — do not use item after this
        return car
    }
    DispatchQueue.main.async { self.cars = cars }
}

// Cleanup
deinit {
    observer?.cancel()
}

var observer: DittoStoreObserver?

observer = ditto.store.registerObserver(
    query: "SELECT * FROM cars WHERE color = :color",
    arguments: ["color": "red"]
) { result in
    DispatchQueue.main.async {
        self.cars = result.items.compactMap { Car($0.jsonData()) }
    }
}

deinit {
    observer?.cancel()
}

Key changes:

v5 adds Codable argument overloads for registerObserver
Call item.dematerialize() after extracting data from DittoQueryResultItem to free native memory
The observer lifecycle pattern (retain, .cancel(), cleanup) is the same as v4

Back Pressure (Signal Next)

The standard registerObserver automatically signals readiness for the next callback after your handler returns. For handlers that need time to process results — such as expensive rendering or batch operations — use registerObserver(query:arguments:deliverOn:handlerWithSignalNext:) to control when the next callback is delivered.

Coalescing behavior: While your handler is processing, Ditto coalesces any intermediate changes. When you call signalNext(), you receive a single callback with the latest state — not every intermediate change.

// Standard observer — signalNext called automatically after handler returns
let observer = try ditto.store.registerObserver(
    query: "SELECT * FROM cars WHERE color = :color",
    arguments: ["color": "blue"]
) { result in
    updateUI(result.items)
    // signalNext() called automatically here
}

// Back-pressure observer — you control when the next callback fires
let observer = try ditto.store.registerObserver(
    query: "SELECT * FROM cars WHERE color = :color",
    arguments: ["color": "blue"],
    handlerWithSignalNext: { result, signalNext in
        Task {
            await expensiveRenderOperation(result.items)
            signalNext()  // Ready for next update
        }
    }
)

When to use signal next:

Processing updates is computationally expensive
You’re performing async work (network calls, heavy rendering) on each update
Query results change very frequently and you want to process only the latest state

DittoDiskUsageItem Property Names (v5, Unchanged)

DiskUsageItem was renamed to DittoDiskUsageItem, however, the property names are unchanged in v5:

.path: String — unchanged
.sizeInBytes: Int — unchanged
.childItems: [DittoDiskUsageItem] — unchanged (type renamed, property name same)

`DittoConnection` Property Renames

v4.14	v5.0
`connection.peerKeyString1`	`connection.peer1`
`connection.peerKeyString2`	`connection.peer2`
`connection.approximateDistanceInMeters`	REMOVED — no replacement

DittoPeer Property Renames (v5)

v4.14	v5.0
`peer.peerKeyString`	`peer.peerKey`
`peer.osV2: DittoPeerOS?`	`peer.os: DittoPeerOS?`
`peer.isConnectedToDittoCloud`	`peer.isConnectedToDittoServer`

Breaking: DittoConnection Conformances Cause Swift 6 `filter` Ambiguity

In v5, DittoConnection gains Identifiable, Equatable, Hashable, and Sendable conformances. In Swift 6, Foundation.filter(_:Predicate) takes precedence over Sequence.filter(_:) when the element type conforms to these protocols, causing an unexpected compile error. Error: trailing closure passed to parameter of type 'Predicate<DittoConnection>' Fix: Annotate the closure parameter type explicitly:

// BROKEN in Swift 6
connections.filter { $0.peer1 == localKey }

// FIXED
connections.filter { (conn: DittoConnection) in conn.peer1 == localKey }

Remove Retroactive `Sendable` Conformances

v5 declares Sendable in-module for its public types, including Ditto, DittoQueryResult, DittoTransactionCompletionAction, and DittoStoreObserver. If your v4-era code added its own retroactive conformance to satisfy Swift 6 strict concurrency, it now conflicts with the SDK’s declaration and fails to compile: Error: conformance of 'X' to protocol 'Sendable' was already stated in the type's module 'DittoSwift' Fix: Delete the retroactive shim:

// REMOVE — v5 already declares this conformance
extension DittoStoreObserver: @retroactive @unchecked Sendable {}

DittoLogger Changes

DittoLogger retains the same class name in both v4 and v5. The key changes are:

v5 marks DittoLogger as final and Sendable for Swift concurrency safety
DittoLogger.enabled is renamed to DittoLogger.isEnabled — DittoLogger.enabled = false becomes DittoLogger.isEnabled = false. Leaving the old name produces a compile error: type 'DittoLogger' has no member 'enabled'
DittoLogger.setLogFile() is removed in v5 (was deprecated in v4 — use export(to:) instead)

API Changes

v4.14	v5.0
`ditto.startSync()`	`ditto.sync.start()`
`ditto.stopSync()`	`ditto.sync.stop()`
`ditto.isSyncActive`	`ditto.sync.isActive`
`ditto.observePeers(_:)` / `observePeersV2(_:)`	`ditto.presence.observe(didChangeHandler:)`
`ditto.activated`	`ditto.isActivated`
`peerKeyString`	`peerKey`
`isConnectedToDittoCloud`	`isConnectedToDittoServer`
`Ditto(identity:)`	`Ditto.open(config:)` (async) or `Ditto.openSync(config:)`
`ditto.siteID`	Not a standalone property — access via `ditto.presence.graph.localPeer`
`ditto.appID`	`ditto.config.databaseID`
`DiskUsage` class	`DittoDiskUsage` class
`ditto.diskUsage` (typed `DiskUsage`)	`ditto.diskUsage` (now typed `DittoDiskUsage`)
`DiskUsage.exec: DiskUsageItem`	`DittoDiskUsage.item: DittoDiskUsageItem`
`DiskUsage.DiskUsageObserverHandle` (nested)	`DittoDiskUsageObserver` (standalone class)
`DiskUsage.observe(eventHandler:)` returns `DiskUsageObserverHandle`	`DittoDiskUsage.observe(eventHandler:)` returns `DittoDiskUsageObserver`
`DiskUsageItem`	`DittoDiskUsageItem`
`DittoSwiftError` typealias	Removed — use `DittoError` directly
`DittoError.migrationError(reason:)`	Removed
`MigrationErrorReason` enum	Removed
`DittoSmallPeerInfo.syncScope: DittoSmallPeerInfoSyncScope`	DQL: `ALTER SYSTEM SET sync_scope = '...'`
`DittoSmallPeerInfoSyncScope` enum	Removed — configure via DQL
`DittoSmallPeerInfo.metadataJSONString`	`DittoSmallPeerInfo.metadataJSONData`
`DittoSmallPeerInfo.setMetadataJSONString(_:)`	`DittoSmallPeerInfo.setMetadataJSONData(_:)`
`DittoLogger.enabled: Bool`	`DittoLogger.isEnabled: Bool` — renamed
`DittoLogger.setLogFile()`	Removed — use `export(to:)` instead

WebSocket Sync Default Changed

DittoHTTPListenConfig.webSocketSync default changed from true to false. If your app relied on the v4 default, you must now explicitly enable it.

Sync Subscription Changes

DittoSync.subscriptions is now computed rather than a stored Swift Set. Do not cache this collection — query it fresh when needed. The same applies to DittoStore.observers.

APIs Removed

These v4 APIs were removed.

Removed API	Notes
`Ditto.transportDiagnostics()` / `DittoTransportDiagnostics`	Low-level transport debug info removed
`Ditto.runGarbageCollection()`	GC is now handled automatically
`Ditto.disableSyncWithV3()`	v3 protocol support fully dropped
`Ditto.isHistoryTrackingEnabled` / history tracking initializer	History tracking removed entirely
`DittoIdentity.manual(certificateConfig:)`	Manual certificate identity removed
`DittoConnection.approximateDistanceInMeters`	Peer distance estimation removed
`DittoHTTPListenConfig.staticContentPath`	Static HTTP content serving removed
`DittoStore.queriesHash(queries:)`	Query set hashing removed
`DittoStore.queriesHashMnemonic(queries:)`	Query mnemonic hashing removed
`DittoConnectionPriority` enum	Connection priority control removed
`DittoTransportSnapshot` struct	Removed with transport diagnostics
`DittoRemotePeer` struct (deprecated)	Use `DittoPeer` in `DittoPresenceGraph`
`DittoAddress` struct	Removed
`DittoExperimental.jsonByTranscoding(cbor:)`	CBOR-to-JSON utility removed
`DittoLogger.setLogFile()`	Use `export(to:)` instead

New APIs in v5

Ditto.open(config:): async throws -> Ditto — async factory method
Ditto.openSync(config:): throws -> Ditto — synchronous factory alternative
ditto.config: DittoConfig — read the config used to open this instance
ditto.isActivated: Bool — replaces ditto.activated
DittoStore.newAttachment(data: Data, metadata:) — create attachment from in-memory Data (v4 was file path only)
DittoStore.registerObserver(query:arguments: some Codable, ...) — overloads accepting Codable query arguments
DittoSync.registerSubscription(query:arguments: some Codable) — overload accepting Codable arguments
DittoDiskUsageObserver — standalone observer class (was nested DiskUsage.DiskUsageObserverHandle)
DittoDiskUsageItem — renamed from DiskUsageItem
DittoSyncSubscription.queryArgumentsCBORData / .queryArgumentsJSONData / .id — new properties for introspection
DittoConnection now conforms to Identifiable, Equatable, Hashable, and Sendable
All public types now final and Sendable for Swift concurrency
DittoConfig and DittoConfigConnect now conform to Sendable and Codable

Migration Checklist

Initialization

Replace Ditto(identity:) with Ditto.open(config:)
Create DittoConfig with databaseID and connect mode
Add try await for async initialization
Update .onlinePlayground → .server(url:)
Update .offlinePlayground → .smallPeersOnly(privateKey: nil)
Remove updateTransportConfig calls
Remove disableSyncWithV3() calls
Set DQL_STRICT_MODE=true BEFORE starting sync if maintaining v4 behavior
Update startSync() → sync.start()

Authentication

Set expirationHandler closure after initialization
Use .development provider for playground tokens
Remove authentication from identity configuration

Observers

Call item.dematerialize() after extracting data from DittoQueryResultItem to free native memory
If processing is expensive, use handlerWithSignalNext: for back-pressure control
v5 adds Codable argument overloads — adopt where convenient

Data Operations

Replace all .collection("x").find(...) chains with store.execute() DQL
Use parameterized queries with :paramName — never string interpolation
Replace .upsert() with INSERT INTO ... ON ID CONFLICT DO UPDATE
Replace .update {} closures with UPDATE SET DQL
Replace .remove() with DELETE FROM
Replace .evict() with EVICT FROM
Replace .observeLocal {} with store.registerObserver() callback
Replace .subscribe() with sync.registerSubscription()
Replace counter?.increment(by:) with UPDATE APPLY ... PN_INCREMENT BY

Breaking Changes

Verification

Build compiles with zero errors
No deprecated API warnings
Observers update UI immediately
Authentication works before sync starts
No memory leaks on navigation
No memory leaks (Instruments: Allocations, Leaks)

Common Pitfalls

DQL_STRICT_MODE silent change: Not setting DQL_STRICT_MODE=true when your v4 app used the default. Objects that were replaced whole will now merge at field level — causes unexpected data merging.
Forgetting try await: Ditto.open(config:) is async. Not awaiting it causes a compile error.
Storing DittoQueryResultItem outside callback: These hold native memory. Always call dematerialize() and extract your model before the callback returns.
String interpolation in queries: Never "SELECT * FROM cars WHERE color = '\(color)'". Always use arguments: ["color": color].
Counter initialization: Don’t put DittoCounter() or 0 in insert documents. Counters are created on first PN_INCREMENT. Inserting 0 creates a REGISTER, not a COUNTER.
Missing ON ID CONFLICT: INSERT fails if document _id already exists without a conflict clause.
Not checking timeUntilExpiration in auth handler: Handler is called for both initial auth (0) and token refresh (>0). Handle both cases.

Overview & Setup

SDKs

Accessing Data

Syncing Data

Authentication and Authorization

Managing the Mesh

Deploying your App

Swift V4→V5 API Migration Guide

Overview

AI Agent Prompt

Removed Platform Support

DittoObjC Removal

Ditto Instance Initialization

Auth Handler: Swift 6 Actor Isolation Requirement

Additional Changes

DQL Strict Mode Behavior Change

Default Persistence Directory

Observer Changes

Back Pressure (Signal Next)

DittoDiskUsageItem Property Names (v5, Unchanged)

`DittoConnection` Property Renames

DittoPeer Property Renames (v5)

Breaking: DittoConnection Conformances Cause Swift 6 `filter` Ambiguity

Remove Retroactive `Sendable` Conformances

DittoLogger Changes

API Changes

WebSocket Sync Default Changed

Sync Subscription Changes

APIs Removed

New APIs in v5

Migration Checklist

Initialization

Authentication

Observers

Data Operations

Breaking Changes

Verification

Common Pitfalls

​Overview

​AI Agent Prompt

​Removed Platform Support

​DittoObjC Removal

​Ditto Instance Initialization

​Auth Handler: Swift 6 Actor Isolation Requirement

​Additional Changes

​DQL Strict Mode Behavior Change

​Default Persistence Directory

​Observer Changes

​Back Pressure (Signal Next)

​DittoDiskUsageItem Property Names (v5, Unchanged)

​DittoConnection Property Renames

​DittoPeer Property Renames (v5)

​Breaking: DittoConnection Conformances Cause Swift 6 filter Ambiguity

​Remove Retroactive Sendable Conformances

​DittoLogger Changes

​API Changes

​WebSocket Sync Default Changed

​Sync Subscription Changes

​APIs Removed

​New APIs in v5

​Migration Checklist

​Initialization

​Authentication

​Observers

​Data Operations

​Breaking Changes

​Verification

​Common Pitfalls

Overview

AI Agent Prompt

Removed Platform Support

DittoObjC Removal

Ditto Instance Initialization

Auth Handler: Swift 6 Actor Isolation Requirement

Additional Changes

DQL Strict Mode Behavior Change

Default Persistence Directory

Observer Changes

Back Pressure (Signal Next)

DittoDiskUsageItem Property Names (v5, Unchanged)

`DittoConnection` Property Renames

DittoPeer Property Renames (v5)

Breaking: DittoConnection Conformances Cause Swift 6 `filter` Ambiguity

Remove Retroactive `Sendable` Conformances

DittoLogger Changes

API Changes

WebSocket Sync Default Changed

Sync Subscription Changes

APIs Removed

New APIs in v5

Migration Checklist

Initialization

Authentication

Observers

Data Operations

Breaking Changes

Verification

Common Pitfalls