ObjectBox Swift 5.2.1 (aka 5.3.0-beta.1)

Author: greenrobot

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Notable changes to the ObjectBox Swift library.
 
+## 5.2.1 - 2026-03-24
+
+- Make SyncChange properties accessible
+- Update ObjectBox database to version `5.3.0-2026-03-23`.
+
 ## 5.2.0 - 2026-01-27
 
 - Queries: add inequality comparisons for floating point properties

Source/fetch_dependencies.command

@@ -26,28 +26,62 @@ else
   build_params=""
 fi
 
-# Skips building/fetching, only copy header files and print details
-if [ "${1:-}" == "--verify-only" ]; then
-    verify_only=true
-    shift
-else
-    verify_only=false
-fi
-
-# Never builds and downloads release from objectbox-swift-spec-staging GitHub repo instead
-if [ "${1:-}" == "--staging" ]; then
-    staging_repo=true
-    shift
-else
-    staging_repo=false
-fi
-
+# Copies objectbox headers from the given source dir into our Swift source tree, renaming them and adjusting includes.
+# Note: not using `sed -i` so it can run on Linux too.
+updateHeaders() {
+  local src_dir="$1"
+  local c_header_dir="ios-framework/CommonSource/Internal"
+  cp "$src_dir/objectbox.h" "${c_header_dir}/objectbox-c.h"
+  cp "$src_dir/objectbox-sync.h" "${c_header_dir}/objectbox-c-sync.h"
+  sed 's/#include "objectbox.h"/#include "objectbox-c.h"/' "${c_header_dir}/objectbox-c-sync.h" > "${c_header_dir}/objectbox-c-sync.h.tmp"
+  mv "${c_header_dir}/objectbox-c-sync.h.tmp" "${c_header_dir}/objectbox-c-sync.h"
+  echo "Headers updated in ${c_header_dir} from ${src_dir}"
+}
+
+verify_only=false
+staging_repo=false
+update_headers_only=false
 # Clean by default: after an update, there were issues with standard C includes not found and cleaning helped
 clean_build=true
-if [ "${1:-}" == "--dirty" ]; then
-  clean_build=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --verify-only)
+      verify_only=true
+      ;;
+    --staging)
+      staging_repo=true
+      ;;
+    --dirty)
+      clean_build=false
+      ;;
+    --update-headers-only)
+      update_headers_only=true
+      ;;
+    --help|-h|\?|-\?)
+      echo "Usage: $(basename "$0") [OPTIONS]"
+      echo ""
+      echo "Builds or downloads the ObjectBox C static library and updates headers."
+      echo ""
+      echo "Options:"
+      echo "  --verify-only          Skip building/fetching, only copy headers and verify libs"
+      echo "  --staging              Download from the staging repo instead of building"
+      echo "  --dirty                Skip cleaning the build directory before building"
+      echo "  --update-headers-only  Only update header files from the code repo (no build/download)"
+      echo "  --help, -h, ?, -?      Show this help message"
+      echo ""
+      echo "Environment variables:"
+      echo "  OBX_SKIP_STATIC_C_TESTS  Set to skip C library tests during build"
+      echo "  OBX_FEATURES             Set to enable additional features (e.g. VectorSearch)"
+      exit 0
+      ;;
+    *)
+      echo "Unknown parameter: $1"
+      exit 1
+      ;;
+  esac
   shift
-fi
+done
 
 # macOS does not have realpath and readlink does not have -f option, so do this instead:
 my_dir=$( cd "$(dirname "$0")" ; pwd -P )
@@ -58,9 +92,11 @@ dest_dir="${my_dir}/external/objectbox-static"
 
 if [ "$verify_only" = true ]; then
   echo "Skipping fetch, only verifying"
-else
-
-if [ -d "$code_dir" ] && [ "$staging_repo" != "true" ]; then # Do we have an existing code repo? Then build it...
+elif [ "$update_headers_only" = true ]; then
+  echo "Updating header files only from $code_dir"
+  updateHeaders "$code_dir/objectbox-c/include"
+  exit 0
+elif [ -d "$code_dir" ] && [ "$staging_repo" != "true" ]; then # Do we have an existing code repo? Then build it...
     pushd "$code_dir" # note: this also "fixed" building into cbuild dir in "our" objectbox-swift dir
 
     echo "-----------------------------------------"
@@ -166,13 +202,9 @@ else # Download static public release and unzip into $dest
         rm "${archive_path}"
     fi
 fi
-fi # verify_only
 
 # Update the header file actually used by our Swift sources
-c_header_dir="ios-framework/CommonSource/Internal"
-cp "$dest_dir/objectbox.h" "${c_header_dir}/objectbox-c.h"
-cp "$dest_dir/objectbox-sync.h" "${c_header_dir}/objectbox-c-sync.h"
-sed -i '' 's/#include "objectbox.h"/#include "objectbox-c.h"/' "${c_header_dir}/objectbox-c-sync.h"
+updateHeaders "$dest_dir"
 
 # Print versions for allow verification of built libs (is it the one we expect?)
 echo "============================================================================================"

Source/ios-framework/CommonSource/Internal/objectbox-c-sync.h

@@ -34,7 +34,7 @@
 #include "objectbox-c.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 == 3 && OBX_VERSION_PATCH == 0,  // NOLINT
               "Versions of objectbox.h and objectbox-sync.h files do not match, please update");
 #endif
 
@@ -287,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.

Source/ios-framework/CommonSource/Internal/objectbox-c.h

@@ -52,7 +52,7 @@ extern "C" {
 /// When using ObjectBox as a dynamic library, you should verify that a compatible version was linked using
 /// obx_version() or obx_version_is_at_least().
 #define OBX_VERSION_MAJOR 5
-#define OBX_VERSION_MINOR 1
+#define OBX_VERSION_MINOR 3
 #define OBX_VERSION_PATCH 0  // values >= 100 are reserved for dev releases leading to the next minor/major increase
 
 //----------------------------------------------
@@ -113,6 +113,11 @@ OBX_C_API bool obx_version_is_at_least(int major, int minor, int patch);
 /// @see obx_version() and obx_version_is_at_least() for integer based versions
 OBX_C_API const char* obx_version_string(void);
 
+/// Return the (runtime) version of the library to be printed.
+/// The format is "YYYY-MM-DD" (e.g. "2026-02-16") and thus can be compared lexicographically.
+/// @see obx_version() and obx_version_is_at_least() for integer based versions.
+OBX_C_API const char* obx_version_date_string(void);
+
 /// Return the version of the ObjectBox core to be printed (currently also contains a version date and features).
 /// The format may change in any future release; only use for information purposes.
 OBX_C_API const char* obx_version_core_string(void);
@@ -191,22 +196,18 @@ OBX_C_API bool obx_has_feature(OBXFeature feature);
 // Utilities
 //----------------------------------------------
 
-/// Log level as passed to obx_log_callback.
+/// Log level used by obx_log_level_set(), obx_log_level_get(), and obx_log_callback().
+/// @note Values were changed in version 5.3 (previously 10/20/30/40/50 for Verbose..Error);
+///       update your code if you relied on the old numeric values.
 typedef enum {
-    /// Log level for verbose messages (not emitted at the moment)
-    OBXLogLevel_Verbose = 10,
-
-    /// Log level for debug messages (may be limited to special debug builds)
-    OBXLogLevel_Debug = 20,
-
-    /// Log level for info messages
-    OBXLogLevel_Info = 30,
-
-    /// Log level for warning messages
-    OBXLogLevel_Warn = 40,
-
-    /// Log level for error messages
-    OBXLogLevel_Error = 50,
+    OBXLogLevel_All = 0,      ///< Enable all log output.
+    OBXLogLevel_Trace = 1,    ///< Most detailed; typically only for short-term investigations.
+    OBXLogLevel_Verbose = 2,  ///< Very detailed; not printed by default.
+    OBXLogLevel_Debug = 3,    ///< Detailed output useful during development/debugging.
+    OBXLogLevel_Info = 4,     ///< Informational messages (default for release builds).
+    OBXLogLevel_Warn = 6,     ///< Noteworthy issues that are not necessarily errors.
+    OBXLogLevel_Error = 8,    ///< Only for "bad things happened" (e.g. internal errors).
+    OBXLogLevel_None = 10,    ///< Disable all log output.
 } OBXLogLevel;
 
 /// Callback for logging, which can be provided to store creation via options.
@@ -224,13 +225,27 @@ OBX_C_API size_t obx_db_file_size(char const* directory);
 /// Enable (or disable) debug logging for ObjectBox internals.
 /// This requires a version of the library with the DebugLog feature.
 /// You can check if the feature is available with obx_has_feature(OBXFeature_DebugLog).
+/// @Deprecated: prefer obx_log_level_set() with OBXLogLevel_Debug / OBXLogLevel_Info.
 OBX_C_API obx_err obx_debug_log(bool enabled);
 
-/// Checks if debug logs are enabled for ObjectBox internals. This depends on the availability of the DebugLog feature.
+/// Checks if debug logs are enabled for ObjectBox internals.
+/// This depends on the availability of the DebugLog feature.
 /// If the feature is available, it returns the current state, which is adjustable via obx_debug_log().
-/// Otherwise, it always returns false for standard release builds (or true if you are having a special debug version).
+/// Otherwise, it always returns false for standard release builds
+/// (or true if you are having a special debug version).
+/// @Deprecated: Prefer obx_log_level_get() and compare against OBXLogLevel_Debug.
 OBX_C_API bool obx_debug_log_enabled();
 
+/// Sets the runtime log level for ObjectBox internals.
+/// Log messages below the given level will not be printed (provided they are compiled into the library).
+/// @note Without the DebugLog feature, log messages at debug level and below are not compiled in;
+///       use obx_has_feature(OBXFeature_DebugLog) to check.
+OBX_C_API obx_err obx_log_level_set(OBXLogLevel log_level);
+
+/// Gets the current runtime log level for ObjectBox internals.
+/// @returns One of the OBXLogLevel values.
+OBX_C_API OBXLogLevel obx_log_level_get();
+
 /// Gets the number, as used by ObjectBox, of the current thread.
 /// This e.g. allows to "associate" the thread with ObjectBox logs (each log entry contains the thread number).
 OBX_C_API int obx_thread_number();
@@ -619,6 +634,21 @@ typedef enum {
     /// If a date property has this flag (max. one per entity type), the date value specifies the time by which
     /// the object expires, at which point it MAY be removed (deleted), which can be triggered by an API call.
     OBXPropertyFlags_EXPIRATION_TIME = 65536,
+
+    /// Marks a Long (64-bit integer) property as the sync clock, a "hybrid logical clock" to resolve Sync conflicts.
+    /// These clock values allow "last write wins" conflict resolution.
+    /// There can be only one sync clock per sync entity type; which is also recommended for basic conflict resolution.
+    /// For new objects, initialize a property value to 0 to reserve "a slot" in the object data.
+    /// ObjectBox Sync will update this property automatically on put operations.
+    /// As a hybrid clock, it combines a wall clock with a logical counter to compensate for some clock skew effects.
+    OBXPropertyFlags_SYNC_CLOCK = 131072,
+
+    /// Marks a Long (64-bit integer) property as the "sync precedence" to customize Sync conflict resolution.
+    /// Developer-assigned precedence values are then used to resolve conflicts via "higher precedence wins".
+    /// Defining and assigning precedence values are completely in the hands of the developer (the ObjectBox user).
+    /// There can be only one sync precedence per sync entity type.
+    /// Typically, it is combined with a sync clock, with the latter being the tie-breaker for equal precedence values.
+    OBXPropertyFlags_SYNC_PRECEDENCE = 262144,
 } OBXPropertyFlags;
 
 /// A property type of an external system (e.g. another database) that has no default mapping to an ObjectBox type.

Source/ios-framework/CommonSource/Store.swift

@@ -43,7 +43,7 @@ public class Store: CustomDebugStringConvertible {
     internal(set) public var directoryPath: String
 
     /// The version of this ObjectBox Swift SDK.
-    public static var version = "5.2.0"
+    public static var version = "5.3.0"
 
     /// Pass this together with a String identifier as the directory path to use
     /// a file-less in-memory database.

Source/ios-framework/CommonSource/Sync/SyncClient.swift

@@ -4,6 +4,7 @@
 /// The sync client will start trying to connect after start() is called.
 public protocol SyncClient: AnyObject {
 
+    /// If `true`, listener callbacks are dispatched to the main thread. Default is `false`.
     var callListenersInMainThread: Bool { get set }
 
     /// Sets a listener to observe login events. Replaces a previously set listener.
@@ -73,10 +74,14 @@ public protocol SyncClient: AnyObject {
 
     /// Sets credentials to authenticate the client with the server.
     /// Build credentials using e.g. `SyncCredentials.makeSharedSecret(secret)`.
+    ///
+    /// If the client was waiting for credentials (e.g. after a failed login), this can trigger a reconnection attempt.
     func setCredentials(_ credentials: SyncCredentials) throws
 
     /// Sets multiple credentials to authenticate the client with the server.
     /// Build credentials using e.g. `SyncCredentials.makeSharedSecret(secret)`.
+    ///
+    /// If the client was waiting for credentials (e.g. after a failed login), this can trigger a reconnection attempt.
     func setCredentials(_ credentials: [SyncCredentials]) throws
 
     /// Once the sync client is configured, you can "start" it to initiate synchronization.
@@ -130,9 +135,11 @@ public protocol SyncClient: AnyObject {
     ///  app logic.
     func outgoingMessagesCount(limit: UInt) throws -> UInt
 
-    /// Experimental/Advanced API: requests a sync of all previous changes from the server.
-    /// - Returns true if the request was likely sent (e.g. the sync client is in "logged in" state)
-    /// - Returns false if the request was not sent (and will not be sent in the future).
+    /// Experimental/Advanced API: quickly brings the database up-to-date in a single transaction,
+    /// without transmitting all the history. Good for initial sync of new clients.
+    ///
+    /// - Returns `true` if the request was likely sent (e.g. the sync client is in "logged in" state)
+    /// - Returns `false` if the request was not sent (and will not be sent in the future).
     @discardableResult
     func fullSync() throws -> Bool
 

Source/ios-framework/CommonSource/Sync/SyncCredentials.swift

@@ -5,7 +5,8 @@
 import Foundation
 
 /// Credentials for authenticating the client when connecting to a sync server/peer.
-/// E.g. use `SyncCredentials.makeSharedSecret(secret)`.
+///
+/// Create credentials using factory methods like `SyncCredentials.makeSharedSecret(secret)`.
 public class SyncCredentials {
     var type: SyncCredentialsType
     var data: Data?
@@ -33,7 +34,7 @@ public class SyncCredentials {
         return SyncCredentials(type: SyncCredentialsType.sharedSecret, data: data)
     }
 
-    /// Authenticate with a pre-shared key. The given string will be UTF-8 encoded.
+    /// Authenticate with a pre-shared secret. The given string will be UTF-8 encoded.
     public static func makeSharedSecret(_ string: String) -> SyncCredentials {
         return makeSharedSecret(string.data(using: .utf8)!)
     }