C++ 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 C++ application from v4 to v5. Focus on these critical changes:

INITIALIZATION:
Replace deprecated Ditto() constructor with Ditto::open(config) using builder pattern.
- Create DittoConfig with set_database_id and set_connect
- Identity::OnlinePlayground(app_id, token, cloud_sync, url) → DittoConfig::default_config().set_database_id(app_id).set_connect(DittoConfig::Connect::server(url))
- Identity::OfflinePlayground(app_id) → DittoConfig::default_config().set_database_id(app_id).set_connect(DittoConfig::Connect::small_peers_only())
- Identity::SharedKey(app_id, key) → DittoConfig::default_config().set_database_id(app_id).set_connect(DittoConfig::Connect::small_peers_only(key))
- Identity::Manual(cert) → No v5 equivalent — consult Ditto support
- Ditto::open(config) returns std::shared_ptr<Ditto>
- Remove disable_sync_with_v3, DQL strict mode workarounds
- IMPORTANT: If v4 app used default (strict=true), set DQL_STRICT_MODE=true BEFORE starting sync
- Remove Ditto::close() calls — use shared_ptr lifetime management
- Convenience shortcuts: set_server_connect(url) and set_small_peers_only_connect(key)
- Running update_transport_config is no longer needed to update a websocket_urls when using a Big Peer as this is automatically set by the SDK from the auth server URL.  

AUTHENTICATION:
Set set_expiration_handler lambda after Ditto::open().
- Handler signature: std::function<void(Ditto &ditto, uint32_t sec_remaining)>
- Access auth via ditto.get_auth()-> (not ditto.auth())
- get_auth() returns nullptr for non-authenticated configs — always null-check
- Handler called when sec_remaining == 0 (initial auth) or > 0 (token expiring)
- Use Authenticator::get_development_provider() for playground tokens
- Login: ditto.get_auth()->login(token, provider, [](std::unique_ptr<std::string> client_info, std::unique_ptr<DittoError> error) { ... })
- New: Authenticator::get_status(), observe_status(callback), logout(cleanup)

SYNC:
- ditto->start_sync() → ditto->get_sync().start()
- ditto->stop_sync() → ditto->get_sync().stop()
- ditto->get_is_sync_active() → ditto->get_sync().is_active()

PRESENCE:
- ditto->observe_peers(cb) → ditto->get_presence().observe(cb)
- peer.peer_key_string → peer.peer_key
- peer.is_connected_to_ditto_cloud → peer.is_connected_to_ditto_server
- connection.peer_key_string1/2 → connection.peer1/2
- connection.approximate_distance_in_meters → REMOVED, no replacement
- New: Presence::graph(), peer_metadata(), set_peer_metadata(), set_connection_request_handler()

COLLECTION API → DQL:
All collection APIs are removed. Replace with get_store().execute() using DQL.
- collection.find("color == 'blue'").exec() → ditto->get_store().execute("SELECT * FROM cars WHERE color = :color", {{"color", "blue"}})
- collection.find_by_id(id).exec() → ditto->get_store().execute("SELECT * FROM cars WHERE _id = :id", {{"id", id}})
- collection.upsert(value) → ditto->get_store().execute("INSERT INTO cars DOCUMENTS (:doc) ON ID CONFLICT DO UPDATE", {{"doc", value}})
- collection.find_by_id(id).update(...) → ditto->get_store().execute("UPDATE cars SET color = :color WHERE _id = :id", {{"color", "green"}, {"id", id}})
- collection.find_by_id(id).remove() → ditto->get_store().execute("DELETE FROM cars WHERE _id = :id", {{"id", id}})
- collection.find_by_id(id).evict() → ditto->get_store().execute("EVICT FROM cars WHERE _id = :id", {{"id", id}})
- Always use parameterized queries with :paramName — NEVER use string concatenation

WRITE TRANSACTIONS:
- Store::write(fn) with WriteTransaction → REMOVED
- Replace with Store::transaction(fn), execute_transaction(fn), or transaction_returning<T>(fn)
- TransactionCompletionAction::commit / rollback controls outcome

LIVE QUERIES → STORE OBSERVERS:
- collection.find("...").observe_local([](auto docs, auto event) { ... }) → ditto->get_store().register_observer("SELECT ...", args, [](QueryResult result) { ... })
- observer->cancel() to stop (same as v4)
- v4 handler: (std::vector<Document>, LiveQueryEvent) → v5 handler: (QueryResult)

SUBSCRIPTIONS:
- collection.find("color == 'red'").subscribe() → ditto->get_sync().register_subscription("SELECT * FROM cars WHERE color = :color", {{"color", "red"}})

BACK PRESSURE:
- StoreObservationHandlerWithNextSignal → StoreObservationHandlerWithSignalNext
- NextSignal → SignalNext (std::function<void()>)
- Standard observer auto-signals; use SignalNext overload for manual control

LOGGING:
- Log:: → Logger:: (all static methods)
- Log::Callback (raw function pointer) → Logger::Callback (std::function)
- Log::set_custom_log_cb → Logger::set_custom_log_cb
- Log::set_log_file(path) → REMOVED (continuous file logging gone; use Logger::set_custom_log_cb() for ongoing file output)
- Log::disable_log_file() → REMOVED
- Log::export_to_file(path) → Logger::export_to_file(path) (one-time dump, NOT a set_log_file replacement)
- Log::set/get_emoji_log_level_headings_enabled → removed

DISK USAGE:
- DiskUsageChild → DiskUsageItem
- DiskObserverContext → DiskUsageObserver
- DiskUsage::exec() → DiskUsage::item()

TRANSPORT CONFIG:
- update_transport_config still works in v5
- HttpListenConfig::static_content_path → REMOVED
- All other fields unchanged

DITTO CLASS:
- Ditto() deprecated constructors → removed (use Ditto::open(config))
- Ditto::close() → removed (use shared_ptr lifetime)
- Ditto::get_sdk_version() → Ditto::get_version()
- ditto_semver_version() → ditto::internal::ditto_semver_version() (use Ditto::get_version() instead)
- Identity class hierarchy → removed (use DittoConfig)

CONTAINERS:
- store.observers (public field) → removed, use store.get_observers() (returns std::unordered_set)
- Sync::subscriptions (public field) → removed, use Sync::get_subscriptions() (returns SyncSubscriptionSet = std::unordered_set)

REMOVED APIs (no replacement):
- Ditto::close() — shared_ptr lifetime management
- Ditto::disable_sync_with_v3() — v3 protocol dropped
- Log emoji headings — removed
- Log::set_log_file/disable_log_file — continuous file logging removed (use Logger::set_custom_log_cb() for ongoing file output; Logger::export_to_file() is one-time only)
- Identity class hierarchy — replaced by DittoConfig
- Identity::Manual — no equivalent
- LiveQueryEvent::hash()/hash_mnemonic() — query hashing removed
- DocumentIdPath/AbstractDocumentPath — removed with legacy collection API
- Connection::approximate_distance_in_meters — peer distance estimation removed
- HttpListenConfig::static_content_path — static content serving removed
- 38 legacy headers removed (Collection, Document, LiveQuery, WriteTransaction, etc.)

BEFORE (V4):
```cpp
auto ditto = Ditto(
    Identity::OnlinePlayground(
        "your-app-id",
        "your-token",
        false,
        "https://your-server.ditto.live"
    )
);
ditto.update_transport_config([](auto& config) {
    config.connect.websocket_urls.insert("wss://...");
});
ditto.get_store().execute("ALTER SYSTEM SET DQL_STRICT_MODE = false", {});
ditto.disable_sync_with_v3();
ditto.start_sync();
```

AFTER (V5):
```cpp
auto config = DittoConfig::default_config()
    .set_database_id("your-database-id")
    .set_connect(DittoConfig::Connect::server("https://your-server.ditto.live"));

auto ditto = Ditto::open(config);

ditto->get_auth()->set_expiration_handler([](Ditto &ditto, uint32_t sec_remaining) {
    ditto.get_auth()->login(
        "your-token",
        Authenticator::get_development_provider(),
        [](std::unique_ptr<std::string> client_info, std::unique_ptr<DittoError> error) {
            if (error) {
                std::cout << "Authentication failed: " << error->what() << std::endl;
            }
        }
    );
});

ditto->get_sync().start();
```

CHECKLIST:
- Replace Ditto() deprecated constructor with Ditto::open(config)
- Create DittoConfig with builder pattern
- Set set_expiration_handler for authentication (ditto->get_auth()->)
- Remove disable_sync_with_v3, DQL strict mode
- Replace observe_peers(cb) with get_presence().observe(cb)
- Replace peer_key_string with peer_key
- Replace is_connected_to_ditto_cloud with is_connected_to_ditto_server
- Replace connection.peer_key_string1/2 with connection.peer1/2
- Remove approximate_distance_in_meters usage
- Replace Log:: with Logger::
- Replace StoreObservationHandlerWithNextSignal with StoreObservationHandlerWithSignalNext
- Replace NextSignal with SignalNext
- Replace start_sync() → get_sync().start(), stop_sync() → get_sync().stop()
- Replace get_sdk_version() with get_version()
- Remove Ditto::close() calls
- Replace DiskUsageChild with DiskUsageItem, DiskUsage::exec() with item()
- Replace Store::write() with Store::transaction() or execute_transaction()
- Remove HttpListenConfig::static_content_path references

Work through the codebase systematically. Show me each file's changes.

​

Ditto Instance Initialization

// 1. Configure
auto config = DittoConfig::default_config()
    .set_database_id("your-database-id")
    .set_connect(DittoConfig::Connect::server("https://your-server.ditto.live"));

// 2. Initialize
auto ditto = Ditto::open(config);

// 3. Authenticate
ditto->get_auth()->set_expiration_handler([](Ditto &ditto, uint32_t sec_remaining) {
    ditto.get_auth()->login(
        "your-token",
        Authenticator::get_development_provider(),
        [](std::unique_ptr<std::string> client_info, std::unique_ptr<DittoError> error) {
            if (error) {
                std::cout << "Authentication failed: " << error->what() << std::endl;
            } else {
                std::cout << "Authentication successful" << std::endl;
            }
        }
    );
});

// 4. Start sync
ditto->get_sync().start();

• Clear separation of connection, initialization, and authentication concerns
• Builder pattern for flexible configuration
• No workarounds needed (DQL strict mode, v3 sync disable)
• Type-safe configuration with compile-time validation

auto config = DittoConfig::default_config()
    .set_database_id("your-database-id")
    .set_connect(DittoConfig::Connect::server("https://your-server.ditto.live"));

auto ditto = Ditto::open(config);
ditto->get_sync().start();

// Set handler after Ditto::open()
// Handler signature: void(Ditto &ditto, uint32_t sec_remaining)
ditto->get_auth()->set_expiration_handler([](Ditto &ditto, uint32_t sec_remaining) {
        ditto.get_auth()->login(
            "your-token",
            Authenticator::get_development_provider(),
            [](std::unique_ptr<std::string> client_info, std::unique_ptr<DittoError> error) {
                if (error) {
                    std::cout << "Authentication failed: " << error->what() << std::endl;
                } else {
                    std::cout << "Authentication successful" << std::endl;
                }
            }
        );
});

​

Additional Changes

​

DQL Strict Mode Behavior Change

auto config = DittoConfig::default_config()
    .set_database_id("your-database-id")
    .set_connect(DittoConfig::Connect::server("https://your-server.ditto.live"));
auto ditto = Ditto::open(config);

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

// Now safe to start sync
ditto->get_sync().start();

auto config = DittoConfig::default_config()
    .set_database_id("your-database-id")
    .set_connect(DittoConfig::Connect::server("https://your-server.ditto.live"));
auto ditto = Ditto::open(config);

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

​

Default Persistence Directory

auto config = DittoConfig::default_config()
    .set_database_id("your-database-id")
    .set_connect(DittoConfig::Connect::server("https://your-server.ditto.live"))
    .set_persistence_directory("/app/data/ditto");  // Old v4 path

​

Observer Changes

// Standard observer — signal_next called automatically after handler returns
auto observer = ditto->get_store().register_observer(
    "SELECT * FROM cars WHERE color = :color",
    {{"color", "blue"}},
    [](QueryResult result) {
        process_results(result);
        // signal_next called automatically here
    }
);

// Cleanup: cancel explicitly or let shared_ptr go out of scope
observer->cancel();

• v5 adds introspection methods to StoreObserver: get_query(), get_query_arguments(), get_query_arguments_cbor_data(), get_query_arguments_json_string()
• Container type changed: store.get_observers() returns std::unordered_set (v4 returned std::set)
• The deprecated store.observers public field is removed — use store.get_observers()

​

Back Pressure (SignalNext)

// Standard observer — signal_next called automatically after handler returns
auto observer = ditto->get_store().register_observer(
    "SELECT * FROM cars WHERE color = :color",
    {{"color", "blue"}},
    [](QueryResult result) {
        process_results(result);
        // signal_next called automatically here
    }
);

// Back-pressure observer — you control when the next callback fires
StoreObservationHandlerWithSignalNext handler = [](QueryResult result, SignalNext signal_next) {
    process_results(result);
    // ... do expensive work ...
    signal_next();  // Ready for next update — must call this
};

auto observer = ditto->get_store().register_observer(
    "SELECT * FROM cars WHERE color = :color",
    {{"color", "blue"}},
    handler
);

• SignalNext = std::function<void()> (renamed from v4’s NextSignal)
• StoreObservationHandlerWithSignalNext = std::function<void(QueryResult, SignalNext)> (renamed from v4’s StoreObservationHandlerWithNextSignal)

​

Presence API Changes

// Observe presence changes
auto observer = ditto->get_presence().observe([](const PresenceGraph &graph) {
    for (const auto &peer : graph.remote_peers) {
        std::cout << "Peer: " << peer.peer_key << std::endl;
    }
});

// Get current presence graph
auto graph = ditto->get_presence().graph();

// Set peer metadata
ditto->get_presence().set_peer_metadata({{"role", "sensor"}});

• Presence::graph() — get current PresenceGraph immediately
• Presence::peer_metadata() / set_peer_metadata(json) — get/set arbitrary peer metadata
• Presence::peer_metadata_json_string() / set_peer_metadata_json_string(str) — JSON string variants
• Presence::set_connection_request_handler(handler) — control which peers can connect

​

DiskUsage API Changes

​

Transport Config Changes

// Transport config still works in v5
ditto->update_transport_config([](TransportConfig &config) {
    config.peer_to_peer.bluetooth_le.enabled = true;
    config.peer_to_peer.lan.enabled = true;
});

​

Transaction API Changes

#include <Transaction.hpp>

// Basic transaction
auto result = ditto->get_store().transaction(
    [](Transaction &txn) -> TransactionCompletionAction {
        txn.execute("INSERT INTO cars DOCUMENTS (:doc)", {{"doc", car_data}});
        txn.execute("UPDATE inventory SET count = count - 1 WHERE _id = :id", {{"id", inv_id}});
        return TransactionCompletionAction::commit;
    }
);

// Convenience: void-returning lambda (auto-commits on return, rolls back on throw)
ditto->get_store().execute_transaction([](Transaction &txn) {
    txn.execute("INSERT INTO cars DOCUMENTS (:doc)", {{"doc", car_data}});
});

// Return a value from a transaction
auto car_id = ditto->get_store().transaction_returning<std::string>(
    [](Transaction &txn) -> std::string {
        auto result = txn.execute("INSERT INTO cars DOCUMENTS (:doc)", {{"doc", car_data}});
        return result.mutated_document_ids()[0].dump();
    }
);

• Store::write(fn) with WriteTransaction — removed
• WriteTransaction, ScopedWriteTransaction, WriteTransactionResult, UpdateResult — removed
• DQL-based Store::transaction() and Store::execute_transaction() are the replacement
• New: Store::transaction_returning<T>() — return a value from a transaction
• TransactionOptions available: set_read_only(bool), set_hint(string)

​

API Renames

​

Log → Logger Rename

// v4
Log::set_minimum_log_level(LogLevel::Debug);
Log::set_custom_log_cb([](LogLevel level, std::string msg) {
    std::cout << msg << std::endl;
});

// v5
Logger::set_minimum_log_level(LogLevel::Debug);
Logger::set_custom_log_cb([](LogLevel level, const std::string& msg) {
    std::cout << msg << std::endl;
});

​

Header Count Reduced

​

Ditto Lifetime Management

​

APIs Removed Without Replacement

​

Legacy Collection API — Completely Removed

​

New APIs in v5

​

Ditto

• Ditto::get_version() — replaces get_sdk_version()
• Ditto::get_presence() — returns Presence & for presence operations

​

Logger

• Logger class — replaces Log; callback type is now std::function
• Logger::export_to_file(path) — one-time export of accumulated logs; returns std::future<uint64_t> (bytes written as gzip-compressed JSON lines). Renamed from Log::export_to_file() — not a replacement for the removed Log::set_log_file().

​

Sync

• ditto->get_sync().start() / .stop() / .is_active() — sync lifecycle on Sync object
• SyncSubscriptionHash / SyncSubscriptionEq — hash/eq helpers for subscription unordered_set
• SyncSubscriptionSet type alias — unordered_set of SyncSubscription shared_ptrs
• SyncSubscription::get_query() / get_query_arguments() / get_query_arguments_cbor_data() / get_query_arguments_json_string() — introspect registered subscription

​

Store & Observers

• StoreObservationHandlerWithSignalNext / SignalNext — renamed from NextSignal variants
• StoreObserverHash / StoreObserverEq — hash/eq helpers for observer unordered_set
• StoreObserver::get_query() / get_query_arguments() / get_query_arguments_cbor_data() / get_query_arguments_json_string() — introspect registered observer
• Store::execute_transaction() — convenience transaction with auto-commit
• Store::transaction_returning<T>() — transaction that returns a value

​

Authentication

• Authenticator::get_status() — returns current AuthenticationStatus
• Authenticator::observe_status(callback) — observe authentication status changes
• Authenticator::logout(cleanup) — log out with optional cleanup callback

​

Presence

• Presence::observe(cb) — replaces Ditto::observe_peers()
• Presence::graph() — get current PresenceGraph immediately
• Presence::peer_metadata() / set_peer_metadata(json) — get/set arbitrary peer metadata
• Presence::peer_metadata_json_string() / set_peer_metadata_json_string(str) — JSON string variants
• Presence::set_connection_request_handler(handler) — control incoming peer connections

​

DiskUsage

• DiskUsageItem — renamed from DiskUsageChild
• DiskUsageObserver — renamed from DiskObserverContext
• DiskUsage::item() — renamed from DiskUsage::exec()

​

Configuration

• DittoConfig::set_server_connect(url) — convenience shortcut for set_connect(Connect::server(url))
• DittoConfig::set_small_peers_only_connect(key) — convenience shortcut for set_connect(Connect::small_peers_only(key))

​

Migration Checklist

​

Initialization

• Replace deprecated Ditto() constructor with Ditto::open(config)
• Create DittoConfig with set_database_id and set_connect
• Update Identity::OnlinePlayground → DittoConfig::Connect::server(...)
• Update Identity::OfflinePlayground → DittoConfig::Connect::small_peers_only()
• Update Identity::SharedKey → DittoConfig::Connect::small_peers_only("your-shared-key")
• Remove disable_sync_with_v3() calls
• Set DQL_STRICT_MODE=true BEFORE starting sync if maintaining v4 behavior

​

Authentication

• Set set_expiration_handler lambda after initialization
• Handler receives Ditto &ditto, uint32_t sec_remaining
• Access auth inside handler via ditto.get_auth()->login(...)
• Use Authenticator::get_development_provider() for playground tokens
• Remove authentication from identity configuration
• Null-check get_auth() — returns nullptr for non-authenticated configs

​

Sync

• Update start_sync() → get_sync().start()
• Update stop_sync() → get_sync().stop()
• Update get_is_sync_active() → get_sync().is_active()

​

Data Operations

• Replace all collection-based queries with DQL via get_store().execute()
• 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 .observe_local() with get_store().register_observer()
• Replace .subscribe() with get_sync().register_subscription()
• Replace Store::write(fn) with Store::transaction() or Store::execute_transaction()

​

Presence

• Update observe_peers(cb) → get_presence().observe(cb)
• Update peer_key_string → peer_key
• Update peer_key_string1/2 → peer1/2
• Update is_connected_to_ditto_cloud → is_connected_to_ditto_server
• Remove approximate_distance_in_meters usage (no replacement)

​

Logging

• Replace Log:: with Logger:: throughout codebase
• Update Log::Callback stored variables: raw function pointer → std::function
• Update Log::set_custom_log_cb → Logger::set_custom_log_cb
• Remove Log::set_log_file(path) calls — continuous file logging removed. Use Logger::set_custom_log_cb() if you need ongoing file output.
• Remove Log::disable_log_file() calls
• Remove Log::set_emoji_log_level_headings_enabled() calls

​

DiskUsage

• Update DiskUsageChild → DiskUsageItem
• Update DiskUsage::exec() → DiskUsage::item()

​

Breaking Changes

• Set set_persistence_directory if maintaining v4 directory structure
• Replace StoreObservationHandlerWithNextSignal → StoreObservationHandlerWithSignalNext
• Replace NextSignal → SignalNext type alias
• Replace store.observers field access with store.get_observers() (now returns unordered_set)
• Replace Sync::subscriptions field access with Sync::get_subscriptions() (now returns unordered_set)
• Remove Ditto::close() calls — manage lifetime via shared_ptr
• Replace get_sdk_version() with get_version()
• Audit header includes — header count reduced from 86 to 50 (38 removed, 2 added)
• If processing is expensive, use StoreObservationHandlerWithSignalNext overload for back-pressure control
• Remove HttpListenConfig::static_content_path references

​

Verification

• Build compiles with zero errors
• No deprecated API warnings
• Observers update data immediately
• Authentication works before sync starts
• No memory leaks

​

Common Pitfalls

1. 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.
2. Wrong auth accessor: Using ditto->auth() instead of ditto->get_auth(). Inside the expiration handler, the Ditto & reference requires ditto.get_auth()->login(...) (note: . for the reference, -> for the shared_ptr).
3. Null auth pointer: get_auth() returns nullptr for small_peers_only configurations without a server. Always null-check before calling methods on the result.
4. String interpolation in queries: Never build queries with string concatenation. Always use parameterized queries: execute("SELECT * FROM cars WHERE color = :color", {{"color", "blue"}}).
5. Counter initialization: Don’t put 0 in insert documents for counter fields. Counters are created on first PN_INCREMENT. Inserting 0 creates a REGISTER, not a COUNTER.
6. Missing ON ID CONFLICT: INSERT fails if document _id already exists without a conflict clause.
7. Log::Callback type change: v4 used a raw function pointer (void(*)(LogLevel, std::string)). v5 uses std::function<void(LogLevel, const std::string&)>. Code storing callbacks as function pointers must be updated.
8. shared_ptr lifetime: Ditto::open() returns shared_ptr<Ditto>. The instance is destroyed when all copies go out of scope. Do not call close() — it was removed.
9. Observer container type: store.get_observers() now returns std::unordered_set instead of std::set. Code that depends on ordered iteration must be updated.