Preparing 5.2.0 release

greenrobot · greenrobot · commit 6d091bfd4b14 · 2026-03-06T20:02:55.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,21 @@
 ObjectBox C and C++ API Changelog
 =================================
 
+5.2.0 (2026-03-06)
+------------------
+* Admin: new "Counts and Sizes" view (via Status page) to give an overview over all types their object counts and sizes
+* Admin: refresh button for the data view
+* Admin: fix reload via browser to stay on the page
+* Admin: schema view to display flags as text
+* (Minor) performance improvements of HNSW vector search on Linux ARM targets
+
+### Sync
+
+* Sync protocol version 10
+* Update client sync filters variables when online
+* Clients report errors to the server
+* Add OBXSyncFlags_SkipInvalidTxOps
+ 
 5.1.0 (2026-01-19)
 ------------------
 * Fix for deleting transactions in non-owner threads with open relation cursors
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -55,7 +55,7 @@ else ()
 
     function(defineObjectBoxLib VARIANT)
         # Configuration updated for each release
-        set(DL_VERSION 5.1.0)
+        set(DL_VERSION 5.2.0)
 
         # Platform detection and other setup
         set(DL_URL https://github.com/objectbox/objectbox-c/releases/download)
diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@ box.put({.text = "Buy milk"});
 
 See [ObjectBox C and C++ docs](https://cpp.objectbox.io/) for API details.
 
-**Latest version: 5.1.0** (2026-01-19).
+**Latest version: 5.2.0** (2026-03-06).
 See [changelog](CHANGELOG.md) for more details.
 
 ## Table of Contents:
diff --git a/download.sh b/download.sh
@@ -44,7 +44,7 @@ tty -s || quiet=true
 
 # Note: optional arguments like "--quiet" shifts argument positions in the case block above
 
-version=${1:-5.1.0}
+version=${1:-5.2.0}
 os=${2:-$(uname)}
 arch=${3:-$(uname -m)}
 echo "Base config: OS ${os} and architecture ${arch}"
diff --git a/doxygen/Changelog.md b/doxygen/Changelog.md
@@ -3,6 +3,21 @@
 ObjectBox C and C++ API Changelog
 =================================
 
+5.2.0 (2026-03-06)
+------------------
+* Admin: new "Counts and Sizes" view (via Status page) to give an overview over all types their object counts and sizes
+* Admin: refresh button for the data view
+* Admin: fix reload via browser to stay on the page
+* Admin: schema view to display flags as text
+* (Minor) performance improvements of HNSW vector search on Linux ARM targets
+
+### Sync
+
+* Sync protocol version 10
+* Update client sync filters variables when online
+* Clients report errors to the server
+* Add OBXSyncFlags_SkipInvalidTxOps
+ 
 5.1.0 (2026-01-19)
 ------------------
 * Fix for deleting transactions in non-owner threads with open relation cursors
diff --git a/doxygen/Doxyfile b/doxygen/Doxyfile
@@ -38,7 +38,7 @@ PROJECT_NAME           = "ObjectBox C and C++ API"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "5.1.0"
+PROJECT_NUMBER         = "5.2.0"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
diff --git a/examples/c-tasks-lowlevel/CMakeLists.txt b/examples/c-tasks-lowlevel/CMakeLists.txt
@@ -17,7 +17,7 @@ if (NOT TARGET objectbox) # Using "if" in case a (potential) parent project alre
     FetchContent_Declare(
             objectbox
             GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git
-            GIT_TAG v5.1.0 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
+            GIT_TAG v5.2.0 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
     )
     FetchContent_MakeAvailable(objectbox)
 
diff --git a/examples/c-tasks/CMakeLists.txt b/examples/c-tasks/CMakeLists.txt
@@ -17,7 +17,7 @@ if (NOT TARGET objectbox) # Using "if" in case a (potential) parent project alre
     FetchContent_Declare(
             objectbox
             GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git
-            GIT_TAG v5.1.0 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
+            GIT_TAG v5.2.0 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
     )
     FetchContent_MakeAvailable(objectbox)
 
diff --git a/examples/tasks/CMakeLists.txt b/examples/tasks/CMakeLists.txt
@@ -17,7 +17,7 @@ if (NOT TARGET objectbox) # Using "if" in case a (potential) parent project alre
     FetchContent_Declare(
             objectbox
             GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git
-            GIT_TAG v5.1.0 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
+            GIT_TAG v5.2.0 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
     )
     FetchContent_MakeAvailable(objectbox)
 
diff --git a/examples/vectorsearch-cities/CMakeLists.txt b/examples/vectorsearch-cities/CMakeLists.txt
@@ -17,7 +17,7 @@ if (NOT TARGET objectbox) # Using "if" in case a (potential) parent project alre
     FetchContent_Declare(
             objectbox
             GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git
-            GIT_TAG v5.1.0 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
+            GIT_TAG v5.2.0 # For latest versions, check https://github.com/objectbox/objectbox-c/releases
     )
     FetchContent_MakeAvailable(objectbox)
 
diff --git a/include/objectbox-sync.h b/include/objectbox-sync.h
@@ -34,7 +34,7 @@
 #include "objectbox.h"
 
 #if defined(static_assert) || defined(__cplusplus)
-static_assert(OBX_VERSION_MAJOR == 5 && OBX_VERSION_MINOR == 1 && OBX_VERSION_PATCH == 0,  // NOLINT
+static_assert(OBX_VERSION_MAJOR == 5 && OBX_VERSION_MINOR == 2 && OBX_VERSION_PATCH == 0,  // NOLINT
               "Versions of objectbox.h and objectbox-sync.h files do not match, please update");
 #endif
 
@@ -212,6 +212,9 @@ typedef enum {
     /// Enables debug logging of TX log processing.
     /// For now, this only has an effect on SyncClients (Sync Server has extensive debug logs already).
     OBXSyncFlags_DebugLogTxLogs = 16,
+
+    /// Skips invalid (put object) operations in the TX log instead of failing.
+    OBXSyncFlags_SkipInvalidTxOps = 32,
 } OBXSyncFlags;
 
 //----------------------------------------------
@@ -284,17 +287,27 @@ OBX_C_API obx_err obx_sync_close(OBX_sync* sync);
 /// Adds or replaces a sync filter variable value for the given name to the sync client.
 /// Eventually existing values for the same name are replaced.
 /// Client filter variables can be used in server-side sync filters to filter out objects that do not match the filter.
-/// Filter variables must be added before login, e.g. before obx_sync_start() or setting credentials.
+/// Filter variables can be set in two states:
+///  1) Added before login, e.g. before obx_sync_start() or setting credentials (no "apply" activation required).
+///  2) After a login, updates to sync filter variables are staged and are "pending" until
+///     obx_sync_filter_variables_apply() is called.
 /// @param name non-NULL name of the filter variable
 /// @param value non-NULL value of the filter variable
 OBX_C_API obx_err obx_sync_filter_variables_put(OBX_sync* sync, const char* name, const char* value);
 
 /// Removes a previously added sync filter variable value.
+/// If used after login, see obx_sync_filter_variables_put() for notes about obx_sync_filter_variables_apply().
 OBX_C_API obx_err obx_sync_filter_variables_remove(OBX_sync* sync, const char* name);
 
 /// Removes all previously added sync filter variable values.
+/// If used after login, see obx_sync_filter_variables_put() for notes about obx_sync_filter_variables_apply().
 OBX_C_API obx_err obx_sync_filter_variables_remove_all(OBX_sync* sync);
 
+/// Applies all pending filter variable updates (from put/remove filter variables calls).
+/// If the client is connected, sends the updated variables to the server.
+/// If the client is not connected, the updated variables will be included in the next login message.
+OBX_C_API obx_err obx_sync_filter_variables_apply(OBX_sync* sync);
+
 /// Sets credentials to authenticate the client with the server.
 /// Any credentials that were set before are replaced;
 /// if you want to pass multiple credentials, use obx_sync_credentials_add() instead.
diff --git a/include/objectbox-sync.hpp b/include/objectbox-sync.hpp
@@ -21,14 +21,15 @@
 #include "objectbox-sync.h"
 #include "objectbox.hpp"
 
-static_assert(OBX_VERSION_MAJOR == 5 && OBX_VERSION_MINOR == 1 && OBX_VERSION_PATCH == 0,  // NOLINT
+static_assert(OBX_VERSION_MAJOR == 5 && OBX_VERSION_MINOR == 2 && OBX_VERSION_PATCH == 0,  // NOLINT
               "Versions of objectbox.h and objectbox-sync.hpp files do not match, please update");
 
 namespace obx {
 
 /// Credentials for logging into a Sync Server that are passed to SyncClient.
 /// Typically created using a factory method, e.g. `SyncCredentials::none()` or `SyncCredentials::jwtIdToken(...)`.
 class SyncCredentials {
+    friend SyncBuilder;
     friend SyncClient;
     friend SyncServer;
     OBXSyncCredentialsType type_;
@@ -289,44 +290,7 @@ class SyncClient : public Closable {
     using Guard = std::lock_guard<std::mutex>;
 
 public:
-    /// Creates a sync client associated with the given store and options
-    /// (server URLs, credentials, optional certificate paths).
-    /// This does not initiate any connection attempts yet: call start() to do so.
-    SyncClient(Store& store, const std::vector<std::string>& serverUrls, const SyncCredentials& creds,
-               const std::vector<std::string>& certPaths = {})
-        : store_(store) {
-        std::vector<const char*> urlPointers;  // Convert serverUrls to a vector of C strings for the C API
-        urlPointers.reserve(serverUrls.size());
-        for (const std::string& serverUrl : serverUrls) {
-            urlPointers.emplace_back(serverUrl.c_str());
-        }
-
-        std::vector<const char*> certPointers;
-        certPointers.reserve(certPaths.size());
-        for (const std::string& certPath : certPaths) {
-            certPointers.emplace_back(certPath.c_str());
-        }
-
-        cSync_ = obx_sync_certs(store.cPtr(), urlPointers.data(), urlPointers.size(), certPointers.data(),
-                                certPointers.size());
-
-        internal::checkPtrOrThrow(cSync_, "Could not initialize sync client");
-        try {
-            setCredentials(creds);
-        } catch (...) {
-            closeNonVirtual();  // free native resources before throwing
-            throw;
-        }
-    }
-
-    /// Creates a sync client associated with the given store and options
-    /// (server URL, credentials, optional certificate paths).
-    /// This does not initiate any connection attempts yet: call start() to do so.
-    SyncClient(Store& store, const std::string& serverUrl, const SyncCredentials& creds,
-               const std::vector<std::string>& certPaths = {})
-        : SyncClient(store, std::vector<std::string>{serverUrl}, creds, certPaths) {}
-
-    /// Creates a sync client associated with the given store and options.
+    /// Creates a sync client associated with the given store and an existing C sync client.
     /// This does not initiate any connection attempts yet: call start() to do so.
     /// @param cSync an initialized sync client. You must NOT call obx_sync_close() yourself anymore.
     SyncClient(Store& store, OBX_sync* cSync) : store_(store), cSync_(cSync) {
@@ -411,9 +375,13 @@ class SyncClient : public Closable {
         internal::checkErrOrThrow(err);
     }
 
-    /// Adds or replaces a sync filter variable value to the sync client.
-    /// Client filter variables can be used in server-side sync filters to filter out objects that do not match the
-    /// filter. Filter variables must be added before login, e.g. before obx_sync_start() or setting credentials.
+    /// Adds or replaces a sync filter variable value for the given name to the sync client.
+    /// Eventually existing values for the same name are replaced.
+    /// Client filter variables can be used in server-side sync filters to filter out objects that do not match the filter.
+    /// Filter variables can be set in two states:
+    ///  1) Added before login, e.g. before obx_sync_start() or setting credentials (no "apply" activation required).
+    ///  2) After a login, updates to sync filter variables are staged and are "pending" until
+    ///     obx_sync_filter_variables_apply() is called.
     /// @param name non-NULL name of the filter variable
     /// @param value non-NULL value of the filter variable
     void putFilterVariable(const char* name, const char* value) {
@@ -445,6 +413,14 @@ class SyncClient : public Closable {
     /// Removes a previously added sync filter variable value.
     void removeFilterVariable(const std::string& name) { removeFilterVariable(name.c_str()); }
 
+    /// Applies all pending filter variable updates (from put/remove filter variables calls).
+    /// If the client is connected, sends the updated variables to the server.
+    /// If the client is not connected, the updated variables will be included in the next login message.
+    void applyFilterVariables() {
+        obx_err err = obx_sync_filter_variables_apply(cPtr());
+        internal::checkErrOrThrow(err);
+    }
+
     /// Triggers a reconnection attempt immediately.
     /// By default, an increasing backoff interval is used for reconnection attempts.
     /// But sometimes the user of this API has additional knowledge and can initiate a reconnection attempt sooner.
@@ -797,24 +773,28 @@ class SyncClient : public Closable {
     }
 };
 
+class SyncBuilder;
+
 /// <a href="https://objectbox.io/sync/">ObjectBox Sync</a> makes data available on other devices.
 /// Start building a sync client using client() and connect to a remote server.
 class Sync {
 public:
     static bool isAvailable() { return obx_has_feature(OBXFeature_Sync); }
 
+    /// @deprecated Use Sync::client(store).url(serverUrl).credentials(creds).build() instead.
     /// Creates a sync client associated with the given store and configures it with the given options.
     /// This does not initiate any connection attempts yet: call SyncClient::start() to do so.
     /// Before start(), you can still configure some aspects of the sync client, e.g. its "request update" mode.
     /// @note While you may not interact with SyncClient directly after start(), you need to hold on to the object.
     ///       Make sure the SyncClient is not destroyed and thus synchronization can keep running in the background.
     static std::shared_ptr<SyncClient> client(Store& store, const std::string& serverUrl,
-                                              const SyncCredentials& creds) {
-        std::lock_guard<std::mutex> lock(store.syncClientMutex_);
-        if (store.syncClient_) throw IllegalStateException("Only one sync client can be active for a store");
-        store.syncClient_.reset(new SyncClient(store, serverUrl, creds));
-        return std::static_pointer_cast<SyncClient>(store.syncClient_);
-    }
+                                              const SyncCredentials& creds);
+
+    /// Creates a SyncBuilder to configure and build a sync client for the given store.
+    /// Use the builder's fluent API to add URLs, certificates, credentials, and flags, then call build().
+    /// @param store the store to sync; a store can only have one sync client associated with it.
+    /// @return a SyncBuilder instance for configuring the sync client
+    static SyncBuilder client(Store& store);
 
     /// Adopts an existing OBX_sync* sync client, taking ownership of the pointer.
     /// @param cSync an initialized sync client. You must NOT call obx_sync_close() yourself anymore.
@@ -826,6 +806,91 @@ class Sync {
     }
 };
 
+/// Builder for creating and configuring a SyncClient.
+/// Use Sync::client(store) to obtain a builder, then configure it using the fluent API and call build().
+class SyncBuilder {
+    friend class Sync;
+
+    Store& store_;
+    OBX_sync_options* opt_;
+    SyncCredentials creds_{SyncCredentials::none()};
+    bool credsSet_ = false;
+
+    explicit SyncBuilder(Store& store) : store_(store), opt_(obx_sync_opt(store.cPtr())) {
+        internal::checkPtrOrThrow(opt_, "Could not create sync options");
+    }
+
+public:
+    /// Can't be copied, single owner of C resources is required (to avoid double-free during destruction)
+    SyncBuilder(const SyncBuilder&) = delete;
+
+    SyncBuilder(SyncBuilder&& source) noexcept
+        : store_(source.store_), opt_(source.opt_), creds_(std::move(source.creds_)), credsSet_(source.credsSet_) {
+        source.opt_ = nullptr;
+    }
+
+    ~SyncBuilder() {
+        if (opt_) obx_sync_opt_free(opt_);
+    }
+
+    /// Adds a server URL; at least one URL must be added before calling build().
+    /// Passing multiple URLs allows high availability and load balancing (i.e. using a ObjectBox Sync Server Cluster).
+    /// A random URL is selected for each connection attempt.
+    SyncBuilder& url(const std::string& url) {
+        internal::checkErrOrThrow(obx_sync_opt_add_url(opt_, url.c_str()));
+        return *this;
+    }
+
+    /// Adds an SSL certificate path.
+    /// This allows to pass SSL certificate paths referring to the local file system.
+    /// Example use cases are using self-signed certificates in a local development environment and custom CAs.
+    SyncBuilder& certificatePath(const std::string& path) {
+        internal::checkErrOrThrow(obx_sync_opt_add_cert_path(opt_, path.c_str()));
+        return *this;
+    }
+
+    /// Sets sync flags to adjust sync behavior; see OBXSyncFlags for available flags.
+    /// Combine multiple flags using bitwise OR.
+    SyncBuilder& flags(uint32_t flags) {
+        internal::checkErrOrThrow(obx_sync_opt_flags(opt_, flags));
+        return *this;
+    }
+
+    /// Sets credentials to authenticate the client with the server.
+    /// Alternatively, you can set credentials on the SyncClient after build().
+    SyncBuilder& credentials(const SyncCredentials& creds) {
+        creds_ = creds;
+        credsSet_ = true;
+        return *this;
+    }
+
+    /// Builds and returns the configured SyncClient.
+    /// This does not initiate any connection attempts yet: call SyncClient::start() to do so.
+    /// Before start(), you should configure credentials via credentials() or SyncClient::setCredentials().
+    /// @note The builder is consumed by this call and must not be used afterwards.
+    /// @throws IllegalStateException if a sync client is already active for the store
+    std::shared_ptr<SyncClient> build() {
+        OBX_VERIFY_STATE(opt_);
+        std::lock_guard<std::mutex> lock(store_.syncClientMutex_);
+        if (store_.syncClient_) throw IllegalStateException("Only one sync client can be active for a store");
+        OBX_sync* cSync = obx_sync_create(opt_);
+        opt_ = nullptr;  // obx_sync_create() always frees the options
+        internal::checkPtrOrThrow(cSync, "Could not create sync client");
+        store_.syncClient_ = std::make_shared<SyncClient>(store_, cSync);
+        if (credsSet_) {
+            static_cast<SyncClient*>(store_.syncClient_.get())->setCredentials(creds_);
+        }
+        return std::static_pointer_cast<SyncClient>(store_.syncClient_);
+    }
+};
+
+inline SyncBuilder Sync::client(Store& store) { return SyncBuilder(store); }
+
+inline std::shared_ptr<SyncClient> Sync::client(Store& store, const std::string& serverUrl,
+                                                const SyncCredentials& creds) {
+    return SyncBuilder(store).url(serverUrl).credentials(creds).build();
+}
+
 inline std::shared_ptr<SyncClient> Store::syncClient() {
     std::lock_guard<std::mutex> lock(syncClientMutex_);
     return std::static_pointer_cast<SyncClient>(syncClient_);
diff --git a/include/objectbox.h b/include/objectbox.h
diff --git a/include/objectbox.hpp b/include/objectbox.hpp

Original file line number	Diff line number	Diff line change
`@@ -17,7 +17,7 @@ if (NOT TARGET objectbox) # Using "if" in case a (potential) parent project alre`
`17`	`17`	`FetchContent_Declare(`
`18`	`18`	`objectbox`
`19`	`19`	`GIT_REPOSITORY https://github.com/objectbox/objectbox-c.git`
`20`		`- GIT_TAG v5.1.0 # For latest versions, check https://github.com/objectbox/objectbox-c/releases`
	`20`	`+ GIT_TAG v5.2.0 # For latest versions, check https://github.com/objectbox/objectbox-c/releases`
`21`	`21`	`)`
`22`	`22`	`FetchContent_MakeAvailable(objectbox)`
`23`	`23`